QuickCast PvP

QuickCast PvP is a lightweight, high-performance client-side Fabric mod for Minecraft 26.3 (“Wilderness Bound”). It enables players to bind keys or mouse buttons to instantly select, cast/use/place, and restore items from their hotbar in a single seamless action within 1–2 client ticks.

Designed specifically for competitive PvP environments, QuickCast PvP introduces no custom packet types, respects all vanilla cooldown and reach constraints, and operates with monotonic nanosecond precision to prevent desynchronization or misfires.

Features

• Three Independent Actions:
• Quick Ender Pearl: Default binding Mouse Middle Click (Button 3).
• Quick Wind Charge: Default unbound.
• Quick End Crystal: Default unbound.
• Smart Hotbar Search:
• Scans hotbar slots 0–8 in sequential order for target items (Items.ENDER_PEARL, Items.WIND_CHARGE, Items.END_CRYSTAL).
• Off-hand is strictly untouched and never inspected.
• 1-Tick Slot Switch & Restore State Machine:
• Switches to the matching item slot and triggers vanilla use (useItem or useItemOn).
• Under RESTORE mode, reverts to your original slot on the subsequent client tick.
• Player Input Preservation: If you manually scroll or press a hotbar number key while a restore is pending, the mod detects the change and cancels the restore, never fighting your manual inputs.
• Trigger Modes (Press vs Hold-and-Release):
• PRESS: Executes immediately upon keydown.
• HOLD_AND_RELEASE: Primes on keydown and casts upon keyup. Automatically cancels after a 3-second safety window or if you manually switch hotbar slots while holding.
• Latency-Aware Safety Guard:
• Configurable ping ceiling (highPingGuardMs, default 250 ms, 0 = disabled).
• Protects against slot desync on unstable connections by preventing casts when real-time latency (PlayerInfo.getLatency()) exceeds your limit.
• Automatically bypasses latency checks on the local integrated-server client (singleplayer or LAN host).
• Keybind Conflict Detection:
• Scans all vanilla and modded KeyMapping entries at startup and runtime.
• Logs warnings to console, notifies the player once via action bar if a conflict occurs, and displays real-time warning banners in the YACL config screen.
• Crystal Placement Validation:
• Supports TRY_PLACE (direct server-side validation) and PLACE_AT_CROSSHAIR_IF_POSSIBLE (client-side pre-check verifying Obsidian/Bedrock, top face, air above, and entity bounding box clearance).
• Flexible Feedback & Low-Stock Alerts:
• Multiple feedback styles: NONE, ACTION_BAR, TITLE, SOUND, or ALL.
• Configurable low-stock alert (lowStockWarningThreshold, default 1 item, 0 = disabled) warning you when hotbar supply is running low.
• Monotonic Cooldowns & Overrides:
• Uses System.nanoTime() for lag-immune timing.
• Configurable global cooldown (default 120 ms, slider 0–2000 ms).
• Rapid key repeat protection on misses (50 ms cooldown) prevents hotbar scanning spam when out of items.
• Per-action cooldown overrides (cooldownOverrideMs, -1 = inherit global).
• Profile Management:
• Save, load, and switch between named configuration profiles stored in .minecraft/config/quickcastpvp/profiles/<name>.json.
• Manage profiles in-game through the YACL config screen or via chat commands (/quickcastpvp profile [save|load|list]).
• Typing & Screen Protection:
• allowWhileScreenOpen: When false, any open GUI blocks casting. When true, non-text screens (e.g. inventory) allow casting while ChatScreen and active text boxes (EditBox) remain strictly protected.
• In-Game Configuration:
• Powered by YetAnotherConfigLib (YACL v3).
• Integrates seamlessly with Mod Menu if installed.
• Accessible via /quickcastpvp config command or a dedicated rebindable keybind.
• Schema v2 with automatic backward-compatible migration from v1.0.0 configurations.

Installation Requirements

• Minecraft: 26.3 (“Wilderness Bound”)
• Fabric Loader: >= 0.19.5
• Java: 25
• Required Dependencies:
• Fabric API (0.161.0+26.3 or newer)
• YetAnotherConfigLib (YACL) (3.9.6+26.3-fabric or newer)
• Optional Dependencies:
• Mod Menu (21.0.0-beta.1 or newer) for access via the “Mods” screen.

Drop quickcastpvp-1.0.3.jar and required dependencies into your .minecraft/mods directory.

Configuration Reference

Configuration is stored at .minecraft/config/quickcastpvp.json (Schema v2).

{
  "configVersion": 2,
  "pearl": {
    "enabled": true,
    "cooldownOverrideMs": -1,
    "triggerMode": "PRESS"
  },
  "windCharge": {
    "enabled": true,
    "cooldownOverrideMs": -1,
    "triggerMode": "PRESS"
  },
  "endCrystal": {
    "enabled": true,
    "cooldownOverrideMs": -1,
    "triggerMode": "PRESS",
    "crystalPlaceMode": "TRY_PLACE"
  },
  "afterUseBehavior": "RESTORE",
  "requireHotbarOnly": true,
  "cooldownMs": 120,
  "highPingGuardMs": 250,
  "feedbackStyle": "ACTION_BAR",
  "lowStockWarningThreshold": 1,
  "allowWhileScreenOpen": false
}

Config Options Table

| Field | JSON Path | Default | Range / Options | Description |
|—|—|—|—|—|
| Config Version | configVersion | 2 | Integer | Internal schema version for automatic migrations. |
| Pearl Enabled | pearl.enabled | true | true, false | Enables or disables Quick Ender Pearl. |
| Pearl Cooldown Override | pearl.cooldownOverrideMs | -1 | -1 – 2000 ms | Specific cooldown for pearls. -1 inherits global cooldown. |
| Pearl Trigger Mode | pearl.triggerMode | PRESS | PRESS, HOLD_AND_RELEASE | Cast on key press vs key release. |
| Wind Charge Enabled | windCharge.enabled | true | true, false | Enables or disables Quick Wind Charge. |
| Wind Charge Cooldown Override | windCharge.cooldownOverrideMs | -1 | -1 – 2000 ms | Specific cooldown for wind charges. -1 inherits global cooldown. |
| Wind Charge Trigger Mode | windCharge.triggerMode | PRESS | PRESS, HOLD_AND_RELEASE | Cast on key press vs key release. |
| End Crystal Enabled | endCrystal.enabled | true | true, false | Enables or disables Quick End Crystal. |
| End Crystal Cooldown Override | endCrystal.cooldownOverrideMs | -1 | -1 – 2000 ms | Specific cooldown for crystals. -1 inherits global cooldown. |
| End Crystal Trigger Mode | endCrystal.triggerMode | PRESS | PRESS, HOLD_AND_RELEASE | Cast on key press vs key release. |
| Crystal Placement Mode | endCrystal.crystalPlaceMode | TRY_PLACE | TRY_PLACE, PLACE_AT_CROSSHAIR_IF_POSSIBLE | TRY_PLACE sends the placement interaction to the server whenever looking at any block. PLACE_AT_CROSSHAIR_IF_POSSIBLE validates Obsidian/Bedrock, top face, and entity clearance locally first. |
| After-Use Behavior | afterUseBehavior | RESTORE | RESTORE, KEEP_NEW_SLOT | RESTORE returns to your original hotbar slot on the next tick. KEEP_NEW_SLOT leaves the cast item selected. |
| Require Hotbar Only | requireHotbarOnly | true | true (greyed out) | Restricts search to hotbar slots 0–8. (See Known Limitations). |
| Global Cooldown | cooldownMs | 120 | 0 – 2000 ms | Monotonic cooldown between successful quickcast actions. |
| High Ping Guard | highPingGuardMs | 250 | 0 – 1000 ms | Maximum latency (ms) before quickcast aborts to prevent slot desync. 0 disables. Bypassed on local singleplayer/LAN. |
| Feedback Style | feedbackStyle | ACTION_BAR | NONE, ACTION_BAR, TITLE, SOUND, ALL | Presentation method for casting notifications. |
| Low Stock Threshold | lowStockWarningThreshold | 1 | 0 – 8 | Warns if remaining hotbar count is at or below this threshold after casting. 0 disables. |
| Allow While Screen Open | allowWhileScreenOpen | false | true, false | When true, allows casting while non-text GUIs (e.g. inventory) are open. Chat and text fields are always protected. |

Note: Keybindings are stored in vanilla Minecraft’s options.txt and can be customized under Options > Controls > Key Binds > QuickCast PvP.

Commands

QuickCast PvP provides client-side commands:

• /quickcastpvp config — Opens the in-game configuration screen.
• /quickcastpvp profile save <name> — Saves active settings to .minecraft/config/quickcastpvp/profiles/<name>.json.
• /quickcastpvp profile load <name> — Loads settings from the specified profile and applies them immediately.
• /quickcastpvp profile list — Lists all available saved configuration profiles in chat.

Opening the Config Screen

1. Via Mod Menu: Open the Mods menu in-game, select QuickCast PvP, and click the Settings icon.
2. Via Command: Execute /quickcastpvp config in chat.
3. Via Keybind: Bind the “Open QuickCast Config” key under Controls > Key Binds.

Known Limitations & Design Constraints

• Hotbar Only (requireHotbarOnly = true): Searching the entire main inventory and swapping items into the hotbar via click-slot packets introduces network round-trip delays, container state ID updates, and desynchronization risks in intense PvP. To uphold the “No Fake Options” rule, this toggle is visibly disabled in the YACL menu with an explanatory tooltip and currently defaults strictly to hotbar-only.
• Vanilla Fair Play: QuickCast PvP does not alter vanilla attack cooldowns, item cooldowns, reach distances, or server packet validation. End Crystals placed on invalid blocks or occupied spaces will be rejected by the server according to vanilla mechanics.

Building from Source

To compile the mod from source:

git clone https://github.com/modclaim/quickcast-pvp.git
cd quickcastpvp
./gradlew build

The compiled artifact will be located at build/libs/quickcastpvp-1.0.3.jar.

Maintenance release 1.0.3

• Restores the previous hotbar slot on the next client tick, after giving vanilla use a full tick to synchronize. Pending casts cannot overwrite each other.
• Failed vanilla interactions use miss feedback/cooldown, restore the original slot and do not display a success or low-stock message.
• Held casts cancel when a blocking screen opens or the player becomes unavailable. On release, enabled settings, item identity, latency and the current crystal target are revalidated.
• Monotonic cooldowns support arbitrary clock origins and counter wraparound.
• Configuration/profile saves replace files atomically when supported. Invalid profiles cannot silently replace the active settings with defaults; corrupt active configurations are backed up.
• JDK 25 is selected through Gradle’s Java toolchain. Run ./gradlew clean build for regression tests and release JARs.

This artifact targets Minecraft 26.3 only. Historical ports in versions/ and platforms/ are separate sources and are not represented as tested by this release. A successful client interaction is a local prediction; multiplayer servers remain authoritative. No server-specific anticheat acceptance is claimed.

AI assisted this maintenance update, regression tests and documentation. The mod does not use an AI service at runtime.

Combined client smoke test

With the sibling fps booster and MoreEnchanted projects built, run ./gradlew runSmokeClient. The separate src/smokeclient harness opens both settings screens, captures screenshots, loads a copy of the regression world, exercises the real pearl keybind against the integrated server, checks server inventory consumption and slot restoration, then disconnects and closes. Test code is excluded from release JARs.