🎯 DiolezHitregistry — Ghost Hit Elimination & PvP Desync Fix

Feel every swing land. No more ghost hits. No more rubber-band deaths.
Client-side combat prediction for Minecraft 1.21 (Fabric) — zero server-side dependencies.

---

❓ What Problem Does This Solve?

You've felt it before. You swing on a player, the hit animation plays, particles fly — and nothing happens. Their health doesn't move. You didn't deal damage. The server didn't agree.

That's a ghost hit — caused by the gap between what your client sees and what the server processes. It gets worse the higher your ping is.

DiolezHitregistry eliminates this feeling entirely.

---

✨ Features

⚔️ Ghost Hit Elimination

Every swing instantly applies a visual health reduction to your target. If the server confirms the hit — perfect, it already looks right. If the server rejects it due to lag or tick desync — the health bar smoothly fades back to the real value. No jarring snap. No confusion.

🧠 Combat Prediction & Reconciliation

The mod timestamps every attack the moment you swing and tracks a live round-trip time estimate from your current ping. It uses this to calibrate a tolerance window — giving the server enough time to respond before deciding a hit was a ghost. On 150ms+ connections, this window automatically widens to absorb lag spikes.

🔧 Utility Desync Fixes

All of these actions are predicted immediately and rolled back gracefully if the server disagrees:

• 🟣 Ender pearls — arc and trajectory appear instantly on throw
• 🏹 Bow & crossbow — projectile predicted on release
• 🍗 Food & potions — consume animation plays without waiting for server
• 🧱 Block placement — block appears in world before server acknowledgement
• 🎒 Hotbar switching — slot change is instant, rolled back if server denies

📊 Live RTT Calibration

The mod continuously measures your actual ping and uses it to dynamically tune prediction windows — no manual configuration needed. It works well at 20ms and still feels great at 300ms+.

🐛 Debug Overlay (Optional)

Enable a developer HUD that shows in real-time:

• Estimated RTT and tick-boundary crossing risk
• Visual HP vs real HP on your current target
• Prediction status (pending / confirmed / rolled back)
• Entity position error (how far the server-side target is from what you see)

---

⚙️ Configuration

Config file is auto-created at: .minecraft/config/hitregistry.json

| Option | Default | Description |
|---|---|---|
| enabled | true | Master on/off toggle |
| combatPredictionEnabled | true | Toggle hit prediction |
| utilityPredictionEnabled | true | Toggle utility desync fixes |
| hitExpiryTicks | 20 | How long to wait for server confirmation before treating as ghost hit |
| latencyCompensationTicks | 2 | Extra ticks added to the window for high-ping servers |
| predictionStrength | 0.85 | How aggressively visual damage is predicted (0.0–1.0) |
| rollbackLerpSpeed | 0.3 | How fast visual HP snaps back on rollback |
| pearlPredictionEnabled | true | Ender pearl desync fix |
| projectilePredictionEnabled | true | Bow/crossbow desync fix |
| itemUsePredictionEnabled | true | Food/potion desync fix |
| blockPlacementPredictionEnabled | true | Block placement desync fix |
| utilityRollbackDelayMs | 400 | ms to wait before rolling back an unconfirmed utility action |
| debugLogging | false | Verbose console logging |
| debugOverlay | false | Enable HUD debug panel |

🔴 High Ping (150ms+) Recommended Settings

{
  "hitExpiryTicks": 30,
  "latencyCompensationTicks": 5,
  "predictionStrength": 0.90,
  "utilityRollbackDelayMs": 600
}

🟢 Strict Server / Anti-Cheat Sensitive Settings

{
  "hitExpiryTicks": 12,
  "latencyCompensationTicks": 1,
  "predictionStrength": 0.70,
  "utilityRollbackDelayMs": 300
}

---

🛡️ Anti-Cheat Compatibility

This mod is designed from the ground up to be invisible to anti-cheat systems.

| What this mod does | Safe? |
|---|---|
| Apply visual health reduction before server confirms | ✅ Purely cosmetic — never touches the entity's real health value |
| Lerp visual health back on rollback | ✅ Client-side rendering only |
| Timestamp and track pending actions | ✅ No network interaction |
| Inject into vanilla methods | ✅ Read-only, post-execution — never cancels anything |
| Send extra attack packets | ❌ Never — would trigger hit-rate limiters |
| Modify outgoing packet timing | ❌ Never — server-side manipulation = ban |
| Alter entity positions | ❌ Never — position spoofing = instant Grim ban |
| Cancel incoming server packets | ❌ Never — would desync the client |

Compatible with: Grim Anticheat, Vulcan, NoCheatPlus, Matrix, and all standard server anti-cheats.
All prediction logic is purely visual. The server always remains authoritative.

---

❓ FAQ

Q: Does this work on servers I don't own?
A: Yes. It's 100% client-side. No server mod or plugin required.

Q: Will this get me banned?
A: No. The mod never sends extra packets, never modifies outgoing attack packets, and never alters any authoritative server state. All changes are visual-only on your own client.

Q: Does it work in singleplayer?
A: Yes, though at 0ms local latency, ghost hits don't occur naturally — so you won't see much difference there.

Q: Why does the health bar sometimes snap a little before correcting?
A: That's the rollback lerp. When the server contradicts a prediction, the visual HP smoothly returns to the real value. You can adjust rollbackLerpSpeed in the config to make it faster or slower.

Q: Can I disable specific features?
A: Yes. Every feature has its own toggle in hitregistry.json. You can run combat prediction only, utility prediction only, or mix and match.

Q: Is this the same as reach or kill-aura mods?
A: Absolutely not. This mod does not extend your reach, automate attacks, or alter hitboxes. It only improves visual feedback and desync recovery for actions you take yourself.

---

📦 Installation

1. Install Fabric Loader for Minecraft 1.21
2. Install Fabric API
3. Drop DiolezHitregistry-1.0.0.jar into your .minecraft/mods/ folder
4. Launch — config is created automatically on first run

---

⚠️ Known Limitations

True zero-latency PvP is physically impossible over a network. Here's what we simulate and why each limit exists:

• Invincibility frames (iFrames): After being hit, entities have a server-side 10-tick invincibility window. The client can't know exact iFrame state for other players, so some hits during this window may appear as ghost hits locally even when they're valid server-side.

• Bow draw power: Draw state is tracked server-side. Projectile velocity prediction may be slightly off if the bow wasn't fully drawn.

• Armour & enchantment precision: The damage estimator uses visible attributes only and applies a 10% conservative reduction. Actual server damage (post-armour toughness, Protection enchants) will differ slightly, causing a small visual correction when the server responds.

• Packet batching: Some server configs batch health sync packets, delaying rollback triggers by an extra tick or two.

---

🔗 Source Code

Full source code with architecture documentation and inline comments explaining every design decision is included in the project.

Built with: Fabric API · Fabric Mixins · Java 21 · Minecraft 1.21 Yarn Mappings

---

Made by Diolez