## QuickCast PvP

**QuickCast PvP** is a lightweight **client-side Fabric** mod for **Minecraft Java** designed for PvP: press **Middle Mouse Button** to instantly perform a selected quick action (Ender Pearl / Wind Charge / End Crystal).  
After the action, the mod can automatically **restore your previous hotbar slot** (default), so you can keep your combo flow without manual switching.

This mod only runs logic when you press the keybind (no heavy tick spam).

---

## Features

- **Middle-click quickcast** for:
  - **Ender Pearl** (use/throw)
  - **Wind Charge** (use/throw)
  - **End Crystal** (attempt placement at your crosshair target)
- **Hotbar search (0..8)** → temporary slot switch → action → optional restore
- **After-use behavior**
  - `RESTORE` (default): return to previous slot
  - `KEEP_NEW_SLOT`: stay on the used item slot
- **Cooldown** (default `120ms`) to prevent spam
- Optional **chat feedback**
- Optional **allowWhileScreenOpen** (works while inventory/menu is open)
- Optional **Mod Menu + Cloth Config** config screen

---

## How it works

When you press **Middle Mouse Button**, the mod:
1. Reads your selected `defaultAction` (Pearl / Wind Charge / Crystal)
2. Searches for the required item in your **hotbar**
3. If found: switches to that slot and triggers a client interaction (use/place)
4. By default, switches back to your **previous hotbar slot**
5. If not found: does nothing (or shows an optional chat message)

**Important:** End Crystal placement is **server-validated** (obsidian/bedrock rules, space, permissions, etc.). This mod only attempts the placement.

---

## Configuration

Config file:
- `.minecraft/config/quickcastpvp.json`

Options:
- `defaultAction`: `ENDER_PEARL | WIND_CHARGE | END_CRYSTAL`
- `afterUseBehavior`: `RESTORE | KEEP_NEW_SLOT`
- `restorePreviousSlot`: `true/false`
- `cooldownMs`: integer (default `120`)
- `showChatFeedback`: `true/false`
- `allowWhileScreenOpen`: `true/false`
- `crystalPlaceMode`: `TRY_PLACE | PLACE_AT_CROSSHAIR_IF_POSSIBLE`
- `requireHotbarOnly`: `true/false`
  - **Note (v1.0.0):** `requireHotbarOnly=false` (inventory-to-hotbar swap) is **not implemented yet** and will fall back to hotbar-only.

If you install **Mod Menu** and **Cloth Config**, you can edit these settings in-game.

---

## Requirements

- Minecraft
- Loader: **Fabric**
- **Fabric API**: required
- Environment: **Client-side**

---

## Links

- Source / Issues: https://github.com/modclaim/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 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

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.