Initial commit

.local/TODO.md

@@ -0,0 +1,132 @@
+# Implementation Plan
+
+Do one phase at a time. Keep the project compiling after every phase.
+
+- [x] **Phase 0 — Bootstrap**
+  - Confirm exact NeoForge/Minecraft/Java versions and mappings from the project.
+  - Create minimal mod entrypoint/config/logging.
+  - Establish packages and basic test setup.
+  - No gameplay yet.
+  - Completed: `arena` entrypoint, server config/startup logging, `com.shinuwa.arena`
+    and `config` packages; removed template gameplay/client examples.
+  - Versions confirmed: Minecraft 1.21.1, NeoForge 21.1.235, Java 21
+    (local JDK 21.0.8), NeoGradle 7.1.38, Gradle 9.2.1,
+    NeoForm 1.21.1-20240808.144430, Parchment 1.21.1 / 2024.11.17.
+  - Validation: `./gradlew build test --offline` succeeded; 3 JUnit 5.11.4
+    configuration tests passed. Rebuilt and inspected `arena-1.0.0.jar`:
+    correct metadata, no template content, only Minecraft/NeoForge dependencies.
+  - README documents build instructions and dedicated/integrated server smoke
+    tests. Full server/client startup remains a manual check, not executed here.
+
+- [ ] **Phase 1 — Data model + content loading**
+  - Resource IDs, ranks, class definitions, themes, mob variants, bosses, balance/progression.
+  - JSON loading/reload and validation diagnostics.
+  - Add example built-in/default data.
+  - Unit-test pure validators where practical.
+
+- [ ] **Phase 2 — Arena Controller + admin setup**
+  - Controller block/block entity.
+  - Relative asymmetric bounding box.
+  - Configurator/admin commands for bounds and points.
+  - Particle visualization of bounds/points.
+  - Tagged spawn points and validation diagnostics.
+  - Export/import arena definition if cleanly supportable.
+
+- [ ] **Phase 3 — Inventory recovery foundation**
+  - Durable snapshot-before-clear transaction.
+  - Restore and idempotency.
+  - Restore-on-login for disconnected/offline players.
+  - Interrupted-session recovery marker.
+  - Test failure paths before adding full sessions.
+
+- [ ] **Phase 4 — Session state machine**
+  - Registration, class selection, ready, countdown, active, victory/defeat/abort, cleanup.
+  - Starting roster/config freeze.
+  - Disconnect = remove participant + pending restoration.
+  - Server restart = cancel/recover.
+  - No waves yet; use simple admin-driven state transitions for tests.
+
+- [ ] **Phase 5 — Classes + reputation**
+  - Class unlock by JSON rank.
+  - Full kit application.
+  - Death handling: no drops, preserve remaining kit state, respawn if life remains.
+  - Elimination restores original inventory.
+  - `addItemFromHand`/slot capture writes JSON, preserves components/count, repairs durability.
+  - `/arena class give`.
+  - Reputation persistence/ranks.
+
+- [ ] **Phase 6 — Wave Director**
+  - Budget-driven composition.
+  - Theme weights, 5-wave default cooldown + graceful fallback.
+  - Entry cost/weight/min/max.
+  - Player-count budget scaling and modest configurable health scaling.
+  - Deterministic tests with seeded RNG.
+  - Wave Title/subtitle.
+
+- [ ] **Phase 7 — Spawning + advanced mob variants**
+  - Spawn-point validation.
+  - Equipment/components/attributes/scale.
+  - Vehicles/passengers with nesting limit.
+  - Session entity tagging/tracking.
+  - Modded registry entity support without compile dependency.
+
+- [ ] **Phase 8 — Modes, lives, progression**
+  - Clear-to-progress individual lives.
+  - Timed-pressure shared lives.
+  - N+2 reputation validation for timed mode.
+  - Wave count tier from frozen group average reputation.
+  - Action bar status.
+  - Defeat conditions.
+
+- [ ] **Phase 9 — Arena isolation**
+  - Block break/place protection.
+  - Explosion terrain protection.
+  - Entity/player boundary entry/exit.
+  - Enderman restrictions.
+  - Projectile crossing.
+  - Targeting isolation.
+  - Loot/XP suppression.
+  - Cleanup of all tracked arena entities.
+  - Verify spectator stands outside bounds cannot influence session.
+
+- [ ] **Phase 10 — Boss system + rewards**
+  - Data-driven vanilla/modded boss EntityType.
+  - Pseudo-boss attributes/scale/equipment/boss bar/adds.
+  - Victory detection.
+  - Equal per-player victory currency, scaled by completed tier.
+  - Held-item currency configuration.
+  - Idempotent payout.
+
+- [ ] **Phase 11 — Water environment**
+  - Configurable baseline/max.
+  - Safe temporary fill for requested layers.
+  - Progressive batched rise/fall.
+  - Exact transactional restoration.
+  - Crash/restart recovery.
+  - WATER spawn integration.
+
+- [ ] **Phase 12 — Player UX + forfeit**
+  - Intuitive registration/class/ready UX; no player commands required.
+  - Participant/class/ready recap.
+  - In-chat forfeit vote and timeout.
+  - Polish titles/action bar/errors.
+  - Accessibility/readability pass.
+
+- [ ] **Phase 13 — Optional Cobblemon integration**
+  - Verify actual target Cobblemon API first.
+  - Optional adapter only.
+  - Configurable allow/block Pokémon use/battles during arena session.
+  - Test startup with Cobblemon absent and present.
+
+- [ ] **Phase 14 — Optional EasyNPC bridge**
+  - Only if useful and actual API is verified.
+  - NPC may initiate/open arena services but must not own core logic.
+  - Test startup with EasyNPC absent.
+
+- [ ] **Phase 15 — Hardening/release**
+  - Multiplayer tests (1–4 players).
+  - Disconnect/reconnect, kill server mid-session, abort, repeated cleanup.
+  - Duplication/loss tests.
+  - Invalid JSON/mod removed between restarts.
+  - Performance profiling with high mob counts.
+  - Admin documentation and example configs.