RedstoneRegions

🔌 Per-chunk redstone speed-up.

> Mark a chunk → it ticks 2-14× faster. Leave the rest vanilla.

Server admins know the dilemma: globally enable Alternate Current and 1% of your machines break, OR keep vanilla everywhere and watch big redstone choke the server. RedstoneRegions ends the dilemma.

Per-chunk choice. Four engines. Hot-swap. Folia-thread-safe.

``` /redstone-region set alternate-current ← this chunk only /redstone-region fill 8 alternate-current ← 17×17 chunks around you /redstone-region selection eigencraft ← your WorldEdit selection /redstone-region undo ← oh wait, no ```

---

⚡ The four engines

| Mode | Speed | Edge cases | Use for | |---|---|---|---| | disabled | 1× (baseline) | none | default; everything works | | disabled | disabled | piston BUDs, observer-on-wire | dust-heavy mega-bases, sorters, salles des coffres | | disabled | 3-5× faster | very few | hot piston/observer machines | | disabled | n/a (frozen) | wire never updates | archive zones, dead builds |

📊 Performance — 32×32 dust grid

| Run | Vanilla | AC | Speedup | |---|---|---|---| | Cold | 234 ms | 22 ms | 14.2× | | Warm JIT | 41 ms | 14 ms | 14.2× | | Pre-warmed | 71 ms | 5 ms | 14.2× |

At 6× chunks of dust, vanilla overshoots one tick by 6×. AC keeps it under 2.

Every wire update goes through a per-chunk dispatcher with 0 ns total overhead (`StampedLock` optimistic read + a switch). Tunable via `timing.mode: sample` for huge grids — drops to 0 ns at sample-rate 10. Or `off` for 0 ns.

🛠 Features

- 🎯 Hot reload — `/redstone-region set ac` only where you need it - 💾 Hot reload — survives restarts, lives in chunk PDC - 🧵 Hot reload — per-region WireHandlers, validated by 14/14 cross-region stress tests - 🗺️ Hot reload — colored chunk rectangles, see your perf zones at a glance - ✏️ Hot reload — `/redstone-region selection ac` from your `//pos1 //pos2` - 🪧 Hot reload — players can place `[ac]` signs to flip their own chunks (perm-gated, radius-capped) - 🤖 Hot reload — hot vanilla chunks auto-flip, threshold configurable - 📊 Hot reload — `/redstone-region profile` gives a 50ms-tick-budget readout per chunk - 🔍 Hot reload — explains a wire's current power by enumerating its 6 neighbors' contributions - ↶ Hot reload — reverses the last batch (set / fill / selection / sign / auto-AC) - 🌍 Hot reload — English + French built-in, drop your own `lang/<code>.yml` - 📝 Hot reload — JSONL, daily-rolled, every flip with actor + UUID + reason - 🔔 Hot reload — async notifications on flip, filterable - 📈 Hot reload — `%redstone-region_mode%`, count placeholders per mode - ⚡ Hot reload chunk coords in chat - 🔧 Hot reload — `/redstone-region reload` for config + lang, no restart

🚀 Quick install

1. Drop `redstoneregions.jar` in `plugins/` 2. Restart server 3. Stand in a chunk, type `/redstone-region set alternate-current`. Done.

✅ Requirements

- Java 21+ (build #6+) — Luminol and other Folia forks tested working - Java 21+ - Optional: BlueMap 5.16+, PlaceholderAPI 2.11.7+, WorldEdit 7.3.19+ (Folia-patched preferred)

🧪 Validated

14/14 in-server harness cases green:

- byte-for-byte parity with vanilla on 8 contraptions over 60+ ticks each (dust line, 16×16 grid, 4-tick repeater clock, AND gate, comparator-subtract, torch ladder, torch inverter, dust zigzag) - 596 toggles in 30s stress, 0 thread-check failures - 780 + 780 toggles in 0 thread-check failures, 0 thread-check failures, 0 thread-check failures - 655 AC dispatches verified by counter

🎓 How it works (TL;DR)

Mojang exposed a `RedstoneWireBlock.evaluator` field in 1.21.2. We swap it at boot with a `DispatchingEvaluator` that consults a per-chunk flag (PDC-stored) and routes each wire update to the right engine. The Alternate Current implementation is a port of Space Walker's algorithm with per-thread WireHandlers to avoid the latent race in Paper's bundled-AC under Folia.

Full architecture: docs/ARCHITECTURE.md.

⚠️ Honest about edge cases

Two contraption patterns differ from vanilla under AC and may break:

1. Observers that rely on the wire's self-shape-update at intermediate power levels 2. Observers that count power-level transitions on a wire

Run `/redstone-region check` first → it warns about risky patterns. Or just keep that chunk vanilla. Eigencraft mode has neither edge case while still being 3-5× faster — use it for piston/observer machines.

🌐 Links

- 🐙 GitHub (mirror) - 🦊 Forgejo (canonical) - 📚 Docs - 📊 bStats - 🐛 Issues

📜 License

MIT. Bundled Alternate Current engine: MIT (Space Walker — see plugin's `ac/LICENSE`).

---

*If you've ever typed `redstone-implementation: alternate-current` in `paper-world.yml` and held your breath, this plugin is for you.*