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 zero custom packets, 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 singleplayer and LAN worlds.
• 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.1.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/quickcastpvp/quickcastpvp.git
cd quickcastpvp
./gradlew build

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