# 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.