Ritsus Offhand Key

A lightweight client-side mod that adds a dedicated, customizable keybind to use your offhand item. Hold the key to keep using the offhand (e.g., hold up a shield), release to stop—smooth, responsive, and multiplayer-safe.

Features

Dedicated offhand key: Bind any key or mouse button (default: Mouse Button 4) to trigger offhand use independently of right-click.
Hold-to-use behavior: Press-and-hold to continuously use offhand items like shields or bows; release to cancel.
Smart item check: Only triggers when the offhand item actually supports right-click use (no wasted inputs on inert items).
Stable input handling: Uses reliable raw mouse polling to minimize “input drops” during intense combat.
Client-side only: No server component required; works fine on vanilla or modded servers.
Configurable in-game: Rebind the key from Minecraft’s Controls menu.

How it works

On press: Starts using the offhand item if it supports right-click (e.g., shield, bow, potion, food).
While held: Continues to request offhand use each tick for consistent “held” behavior, ensuring shields stay raised and bows keep charging even under heavy input load.
On release: Cleanly stops offhand use if it’s currently active.

This mirrors the “press-and-hold” feel of vanilla right-click, but for your offhand and on a separate key.

Requirements and compatibility

Loader: Forge
Minecraft: 1.20.1
Side: Client-only (does not need to be installed on a server)
Multiplayer: Compatible; sends standard use/release actions just like vanilla input.
Conflicts:
- Controls overlap: If another mod uses the same key, both may trigger. Rebind in Controls.
- Input hooks: Mods that intercept or override offhand usage may alter behavior.

Installation and setup

Install Forge 1.20.1.
Drop the JAR into your mods folder.
Launch the game and go to Options → Controls → Key Binds.
Rebind “Use Offhand Item” to your preferred key or mouse button (default: Mouse Button 4).

Tip: If your mouse software maps side buttons to “Back/Forward,” switch them to a “Generic Button” so the game receives raw input.

FAQ

What items does it work with? Shields, bows/crossbows (charging), potions (drinking/throwing), food (eating), and other right‑clickable items. The mod checks whether the item actually consumes a right-click action before attempting use.
Can I keep attacking with the main hand? Yes. The offhand key is independent of left/right click and WASD; you can attack, jump, and sneak while holding the offhand key.
Is there server-side logic? No. It’s fully client-side and behaves like normal input. Works on vanilla and modded servers.
The shield flickers with my mouse side button. Ensure your mouse software isn’t mapping the button to navigation (Back/Forward). Set it to a generic button and rebind in-game.

Permissions and license

License: MIT (recommended). Feel free to fork, modify, and include in modpacks.
Modpacks: Allowed without permission.
Attribution: Appreciated but not required.

Add a LICENSE file to your repository if you publish the source (e.g., on GitHub).

Changelog template

v1.0.0
- Initial release
- Offhand keybind (default: Mouse Button 4)
- Hold-to-use behavior
- Smart right-click item detection
- Raw mouse polling for stable input

v1.0.1

focuses on stability and compatibility improvements.
This update ensures the mod no longer interferes with vanilla right-click behavior and adds input stability handling to prevent offhand use from being interrupted by brief input drops.

v1.1.0

Added support for offhand use in the air and on blocks (e.g., torch placement).
Entity interactions (e.g., villagers, animals) are currently disabled by default in the code and can be re‑enabled by uncommenting the relevant section.
Improved server‑side packet handling for more reliable block placement.
Added extension points for modded item handling.

v1.2.0

Allowed main‑hand actions to be performed while holding an off‑hand action (e.g., blocking with a shield while placing blocks).
Improved hold‑type detection for more consistent behavior across shields, bows, tridents, and block‑placement items.
Standardized 4‑tick cooldown for block‑placement‑type items to match vanilla mechanics.
Added automatic off‑hand resume after main‑hand actions.
Various code clean‑ups and stability fixes.
Off‑hand food item long‑press behavior is under development and may still be interrupted in certain cases.

v1.2.1/v1.2.2

Long press-related fixes