arena-of-shinuwa/.local/TODO.md

Implementation Plan

Do one phase at a time. Keep the project compiling after every phase.

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