A Fabric client mod for Minecraft 1.20.1 built around Crystal PvP. Optimizes the crystal place/break loop, tracks combat in real time across 20+ metrics, coaches you through an AI integration, and includes a practice bot you can fight on a local server.
Originally started as a simple crystal speed tweak, then grew into... all of this.
The mod has three layers:
-
The engine -- rewrites the crystal interaction pipeline with latency-aware packet pacing, client-side entity prediction, and anti-shuffle. This is the part that actually makes crystals faster.
-
The analytics -- a zero-allocation per-tick tracking system that records everything during a fight: cycle speed distributions, totem swap quality grades, movement entropy, self-damage ratios, crystal efficiency, pressure timelines, anchor burst sequences, pearl boost detection, hitcrystal/dtap pattern recognition, and more. When the fight ends, all of this gets compiled into a structured report.
-
The coaching loop -- those reports feed into an AI provider (OpenAI, Gemini, or Claude) that understands CPVP mechanics at a deep level. It references specific tick numbers, damage values, and event sequences from your fight. Conversations persist as Markdown files so you can pick them up later.
On top of that there's a training bot, a network optimization stack, crystal rendering LOD, a media player widget, per-server config profiles, and a player discovery system. The GUI is an 11-tab Elementa-based settings panel with a glass-morphism aesthetic and way too many visual effects on the toast notifications.
- Optimized attack/place pipeline with latency-derived packet budgets
- Client-side entity prediction (crystals removed locally before server confirms)
- Anti-shuffle (pre-compensates stack decrement to prevent count flickering)
- Configurable keybinds for every combat-relevant item (crystals, obsidian, anchors, glowstone, gapples, pearls, sword, totem, etc.)
- Anchor anti-airplace safety with ghost block prediction
The analytics system uses parallel primitive arrays (SoA layout) and ring buffers to avoid any heap allocation during combat. String formatting and report generation only happen when the session ends.
Tracked subsystems:
- PlaceBreakCycleTracker -- place-to-break and break-to-place latency with quality grading (INSTANT/FAST/NORMAL/SLOW)
- CrystalEfficiencyTracker -- estimates per-crystal damage to enemies vs self using the vanilla explosion formula
- PositionalDamageTracker -- classifies incoming damage by source (self-crystal, enemy crystal, anchor, melee, other) and detects Y-level exposure
- MovementAnalyzer -- Shannon entropy of movement direction quantized into 8 octants, stationary time, strafe reversals, height changes
- TotemTracker -- pop detection, swap speed grading (GOOD/OK/NORMAL/BAD/FAILED), wrong-item detection, restock timeout tracking
- PressureCalculator -- rolling score that indicates who's dominating the fight at any moment, with event weights (+3 crystal attack, -6 own totem pop, etc.)
- AnchorTracker -- cycle state machine, burst sequence detection, per-second rate, glowstone error classification (minor: 2 charges, major: 3-4 charges), offhand violation tracking
- TacticsAnalyzer -- recognizes hitcrystal combos, D-taps, faceplaces, self-crystal placements, pearl flashes (I-frame abuse), anchor shield blocks, suicide anchors, elevated crystal play
- PearlBoostTracker -- detects pearl punching (crystal detonated near a thrown pearl for knockback boost), measures distance and classifies direction (chase/escape/reposition)
- EnemyPopTracker, HealTracker, ArmorTracker, HotbarTracker, PearlTracker, ObsidianTracker, CombatContext
Everything feeds into a CombatReport record with 70+ fields and a full dmesg-style event log. There's also a real-time debug overlay you can toggle in-game.
- Supports OpenAI (GPT-4o-mini), Google Gemini, and Anthropic Claude
- System prompt contains detailed reference data for every metric the analytics produce
- Multi-turn conversations -- ask follow-up questions about specific aspects of your fight
- Conversations saved as Markdown files with YAML frontmatter in
config/synergyst-chats/ - Can import external .md chat files
- Session list with continue/delete in the GUI
The bot is a real ServerPlayerEntity on the integrated server with a behavior tree driving its decisions:
ROOT (Selector)
P1: Survival (totem swap, surround, heal)
P2: Attack (dtap, hitcrystal, faceplace, anchor cycle, crystal cycle)
P3: Escape (pearl)
P4: Positioning (strafing, approach/retreat)
Four difficulty tiers:
| Tier | Cycle Speed | Totem Swap | Hitcrystal | D-tap | Error Rate |
|---|---|---|---|---|---|
| LT (Beginner) | 12-16t | 15-25t | 0% | 0% | 20% |
| MT (Intermediate) | 7-10t | 8-12t | 15% | 0% | 8% |
| HT1 (Advanced) | 4-6t | 4-7t | 60% | 10% | 3% |
| HT2 (Expert) | 2-4t | 2-4t | 90% | 45% | 0.5% |
The bot doesn't "pretend" to be bad at lower tiers -- it genuinely thinks slower, evaluates fewer positions, and makes real mistakes. Includes arena management, round auto-reset, difficulty recommendation based on win rate, and training history persistence.
Movement works through an overridden travel() method that processes velocity with full collision detection and vanilla physics (gravity, friction, step-up), since vanilla's LivingEntity.travel() skips server-side players.
- Netty flush consolidation handler
- TCP_NODELAY enforcement
- Packet prioritization (crystal interact/attack packets get immediate flush)
- Adaptive send rate with jitter-based throttling (hysteresis between 10ms and 18ms jitter)
- Network stats overlay with rolling ping graph, jitter, estimated packet loss, packets/sec
- Fast server list pinger -- raw TCP implementation of the Minecraft status protocol, bypasses vanilla's slow pipeline, SRV record resolution, TTL-based caching, configurable thread pool
- Three-tier crystal LOD: full vanilla geometry near, outer frame only at medium range (with interpolated animation slowdown), static core cube at far range
- Distance culling beyond LOD range
- Per-frame crystal density budget
- FPS-aware adaptive quality (automatically reduces LOD distance when FPS drops)
- Explosion particle throttle (per-window counter)
- Explosion flash intensity slider
- Anchor ghost block prediction (client-side block removal on detonation)
- Totem overlay duration reduction (configurable % of vanilla 2-second animation)
- Damage camera tilt suppression
- Combat FOV lock (fixed FOV during active combat sessions)
- Periodic inventory resync (forces server to re-confirm slots, fights ghost items)
- Offhand totem alert (red vignette + warning when no totem during combat)
- Armor durability HUD bars
Two modes:
- Spotify Web API -- requires Premium, uses PKCE OAuth flow, polls currently-playing endpoint
- Local Media Session -- no Premium needed, reads from any media player via Windows WinRT
GlobalSystemMediaTransportControlsSessionManager(PowerShell script) or Linux MPRIS2 (playerctl)
HUD widget with album art texture, track/artist/album text, animated progress bar with client-side interpolation between API polls, compact single-line mode.
- Per-server configuration presets with glob pattern auto-detection on join
- Profile inheritance chains (child overrides parent overrides base)
- Import/export as JSON files
- Keybind to cycle through profiles in-game
- Priority system for overlapping server patterns
Custom plugin channel (synergystcrystal:discovery) for detecting other mod users on the same server. Discovered players get a purple icon in the tab list and chat messages. Requires server-side relay (included as a ModInitializer entrypoint for Fabric servers). Protected CPVP servers enforce discovery being enabled -- attempting to connect with it disabled results in a formatted disconnect message.
Frosted-glass cards with:
- 24 easing functions for entry/exit animations
- Four screen corner positions with directional slide
- Layered background effects: aurora bands, bokeh glow, dust particles, shimmer sweep, exit flash, film grain, edge glow, chromatic fringe, edge vignette, accent glow bleed
- Full visual editor with live preview
- Palette presets (Midnight, Obsidian, Ember, Frost, Void)
- Trilingual random facts pool (~300 entries across Russian, English, German)
Elementa-based with 11 tabs (Modules, Visuals, Food, QoL, Profiles, Combat, Network, AI Coach, Rendering, Media, Bot Training). Features include modal dialogs, AI chat overlay with styled message bubbles, markdown rendering, collapsible sections, search/filter, staggered entrance animations, undo bars, unsaved changes detection, inline keybind capture, five color themes, UI scale slider.
./gradlew build
Requires Java 17+. Output goes to build/libs/.
- Fabric Loader >= 0.14.0
- Fabric API
- Minecraft 1.20.1
- Elementa (Essential)
- ModMenu (optional, for config screen in mod list)
config/
synergyst-crystal.json main config
synergyst-analytics/
history.json last 200 fight summaries
aggregate.json lifetime aggregate stats
synergyst-profiles/
default.json profile presets
*.json
synergyst-chats/
chat_*.md AI conversation files
synergyst-bot/
training_history.json bot session records
| Command | What it does |
|---|---|
/efc config |
Opens the settings GUI |
/efc counter toggle |
Toggles the CPS counter on the HUD |
/efc combat overlay |
Toggles the real-time combat debug overlay |
/synergyst crystals toggle |
Enables/disables the crystal optimization engine |
The crystal engine doesn't fabricate, duplicate, or modify packets. It controls the timing of vanilla interactions within the same tick. The network stack only affects flush timing, not packet content. All rendering changes and PvP fixes are purely client-side. That said, use at your own discretion on servers with strict anti-cheat policies.
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
Version 2, December 2004
Copyright (C) 2004 Sam Hocevar sam@hocevar.net
Everyone is permitted to copy and distribute verbatim or modified copies of this license document, and changing it is allowed as long as the name is changed.
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- You just DO WHAT THE FUCK YOU WANT TO.