open-hands-lib

Open Hands Lib

Per-hand melee cooldowns and mining for NeoForge content mods.

If you are not a mod developer, this is a dependency mod.

Install it only when another mod lists open_hands_lib as a required dependency. On its own it does not add items, blocks, or gameplay.

What is Open Hands Lib?

A NeoForge library that splits attack and mining logic across main hand and off hand. Each hand gets its own cooldown timer; your content mod decides when the system is active and which hand to use.

The library owns timers, mixins, and state. Your mod registers enable conditions and handles events — the library does not pick duelist logic for you.

Features

Combat (when enabled for a player)

• Independent cooldown per hand
• Attacks only land at full charge — partial swings are rejected on purpose
• Hand selection via ResolveAttackHandEvent (alternation, best weapon, etc.)
• Damage, enchantments, and weapon effects use the resolved hand
• Optional rules to attack with the main hand while the off hand is using an item

Combat activates when any registered condition is true (OR).

Mining (when enabled)

• Tool, harvest check, speed, and durability follow the resolved hand
• Hand selection via ResolveMiningHandEvent
• Per-block session cache until mining stops

Mining activates when any registered condition is true (OR).

Requirements

| | |
|—|—|
| Minecraft | 1.21.1 |
| Java | 21+ |
| Mod ID | open_hands_lib |
| Version | 0.1.1 |
| Author | Thow New Error |
| NeoForge | 21.1.219+ · Kotlin for Forge 5.9.0+ |
| Fabric | Loader 0.16.14+ · Fabric API · Fabric Language Kotlin |

Installation

1. Install NeoForge
2. Install Kotlin for Forge
3. Install Open Hands Lib and the content mod that depends on it

Do not rename the mod or swap the jar for an unofficial build in public modpacks.

For mod developers

Register when your gameplay should turn on, then listen for hand events:

OpenHandsLib.registerEnableCondition(
    ResourceLocation.fromNamespaceAndPath("your_mod", "dual_wield"),
) { player -> /* your check */ true }

NeoForge.EVENT_BUS.register(object {
    @SubscribeEvent
    fun onResolveAttackHand(event: ResolveAttackHandEvent) {
        event.hand = InteractionHand.MAIN_HAND
    }

    @SubscribeEvent
    fun onAttackHandCompleted(event: AttackHandCompletedEvent) {
        // alternation, etc.
    }
})

Mining: registerMiningEnableCondition + ResolveMiningHandEvent.

Public API

• mod.openhandslib.api.OpenHandsLib — entry point
• ResolveAttackHandEvent, AttackHandCompletedEvent, OpenHandsCombatStateClearEvent
• ResolveMiningHandEvent