Initial commit

.local/SPEC.md

@@ -0,0 +1,213 @@
+# Functional Specification — PvE Arena
+
+Target: Minecraft Java 1.21.1, NeoForge. Server-first multiplayer PvE arena, initially designed for up to ~4 simultaneous participants.
+
+## 1. Core principles
+- One arena is required for V1, but core code SHOULD avoid an irreversible singleton design.
+- A placed **Arena Controller** is the spatial reference for the arena.
+- Arena geometry is builder-owned. The mod manages combat/session rules, not arena construction.
+- Coordinates for arena points are stored relative to the controller.
+- Player-facing flow MUST be intuitive and MUST NOT require player commands.
+- Admin commands/tools MAY be used for setup and content editing.
+- Vanilla and modded items/entities are referenced by registry IDs. Unknown IDs invalidate only the affected definition.
+
+## 2. Arena Controller and bounds
+The controller stores/configures:
+- asymmetric 3D bounding box (`x-`, `x+`, `y-`, `y+`, `z-`, `z+`);
+- lobby/hall location;
+- participant entry/ready location(s);
+- respawn location;
+- exit location;
+- boss spawn;
+- tagged mob spawn points (`GROUND`, `WATER`, optional future tags);
+- water baseline/max level;
+- optional environment/redstone hooks.
+
+Admin MUST be able to visualize bounds and configured points using temporary client-visible effects/particles. Bounds MUST be adjustable without rebuilding the arena.
+
+Spawn validation MUST reject points that cannot fit the entity's actual dimensions (including scale), are obstructed, lack appropriate support/fluid, or are dangerously close to a participant. The director retries another compatible point.
+
+## 3. Session lifecycle
+Nominal states:
+`IDLE -> REGISTRATION -> CLASS_SELECTION -> READY -> COUNTDOWN -> WAVES -> BOSS -> VICTORY -> CLEANUP -> IDLE`
+
+Exceptional endings:
+`DEFEAT`, `ABORTED`, `SERVER_RECOVERY` -> `CLEANUP`.
+
+Flow:
+1. Player registers.
+2. Original player state is durably snapshotted.
+3. Only after successful persistence, arena-controlled inventory/state is applied.
+4. Player enters hall and chooses an unlocked class.
+5. Player enters ready area and marks Ready.
+6. When all registered participants are ready, registration closes and countdown starts.
+7. Waves run.
+8. Final boss encounter runs.
+9. Victory/defeat/abort cleans all arena entities/environment and restores players.
+
+Late joining after countdown is forbidden.
+
+## 4. Inventory safety
+This is a hard requirement.
+- Persist recovery data BEFORE clearing/changing the player's original inventory.
+- Snapshot at minimum: main inventory, hotbar, armor, offhand; include other player state only if implementation deliberately modifies it.
+- On normal exit/elimination: remove arena kit, restore original snapshot, then mark recovery complete.
+- On disconnect/crash: remove player from active session. If restoration cannot happen while offline, restore automatically on next login.
+- On server restart with an unfinished session: cancel/recover the session. Online participants are moved outside and restored; offline participants are restored on next login.
+- A failed snapshot MUST prevent arena entry and MUST NOT clear inventory.
+- Restoration logic MUST be designed to avoid both loss and duplication.
+
+## 5. Classes
+Classes are JSON-defined and include:
+- ID/display name;
+- required reputation rank;
+- armor slots, offhand and inventory;
+- optional descriptive metadata.
+
+Item definitions MUST support full `ItemStack` data/components so vanilla or modded items can retain enchantments, custom name/lore, dyes, banner/shield patterns, armor trims, attributes and other registered data components.
+
+Admin editing:
+- `addItemFromHand` (or equivalent) copies the full held stack into the class JSON.
+- Captured stack quantity MUST equal held quantity for stackable items.
+- Captured damage/durability MUST be normalized to fully repaired.
+- Capture MUST NOT consume the admin's held item.
+- Armor/offhand slot capture commands SHOULD exist.
+- JSON remains the source of truth; in-game editing updates the JSON and revalidates/reloads the class.
+- `/arena class give <class> [player]` gives a copy of the complete class kit for testing/display (e.g. armor racks), without registering a session.
+
+Class choice locks when the player becomes Ready. Multiple players MAY choose the same class unless later configured otherwise.
+
+On participant death with lives remaining:
+- arena kit does not drop;
+- consumed items are NOT restocked;
+- durability/remaining stack counts are preserved;
+- player respawns in the arena respawn zone with the same remaining kit state.
+
+## 6. Reputation and ranks
+- Reputation is permanent, per-player progression keyed by UUID.
+- Currency is separate and spendable.
+- Ranks are JSON-defined thresholds, e.g. Recruit/Fighter/Veteran/Champion.
+- Classes SHOULD require a rank ID rather than duplicate numeric thresholds.
+- Average reputation/rank of the starting group determines the session's configured wave-count tier. This is frozen at session start and never recalculated after disconnect/elimination.
+- Reputation is earned per validated wave.
+- In clear-to-progress mode, wave N validates when its required mobs are defeated.
+- In timed-pressure mode, wave N validates when wave N+2 is reached; victory validates any remaining pending waves.
+- Eliminated players keep reputation already earned.
+
+## 7. Lives and modes
+Keep "mode" separate from wave power/budget.
+
+Default modes:
+### Clear-to-progress (easy-style)
+- Lives are individual.
+- Next wave begins after all required arena mobs for current wave are defeated.
+- Wave validation occurs on clear.
+
+### Timed-pressure (hard-style)
+- Lives are shared by the team.
+- Each wave starts after a configured timer even if previous-wave enemies remain.
+- Wave N reputation validates when N+2 is reached.
+
+Exact life counts/timers/multipliers are configurable balancing values.
+
+When a player has no applicable life remaining, they are eliminated:
+- removed from session participation;
+- teleported outside;
+- original inventory restored.
+Remaining participants continue. Defeat occurs when no active participants remain (subject to mode rules).
+
+## 8. Wave Director
+Wave difficulty is budget/score-driven, not encoded as `easy/hard` on themes.
+
+Each theme JSON defines:
+- ID/display name;
+- selection weight;
+- mob/variant pool;
+- each entry: cost, weight, optional min/max, compatible spawn tags;
+- optional environmental requirement such as water level.
+
+For each wave:
+1. Determine target score/budget from wave progression, player-count scaling and configurable session scaling.
+2. Select a valid theme.
+3. A theme used recently is excluded for the next 5 waves by default (`themeCooldown`, configurable).
+4. If too few themes exist, gracefully relax cooldown using least-recently-used fallback.
+5. Compose mobs until near target budget while respecting weights/min/max.
+6. Spawn progressively through validated compatible spawn points.
+
+Player-count scaling SHOULD primarily increase mob budget/count. Health scaling MAY increase modestly and MUST be separately configurable; avoid turning normal mobs into excessive HP sponges.
+
+At wave start, participants receive a Title:
+- title: `Vague <N>`
+- subtitle: theme display name.
+Action bar MAY show useful mode-specific status (remaining enemies or next-wave timer).
+
+## 9. Mob variants, equipment, mounts
+Mob definitions MAY include equipment/full item stack components and configurable registered attributes such as max health, attack damage, armor, movement and `minecraft:scale`.
+
+Composite spawns MUST support vehicles/passengers (e.g. spider jockey, mounted skeleton). Treat a composite as one director selection with one total cost. Limit nesting depth.
+
+Third-party registered entity IDs MAY be used without a compile-time dependency. Missing entity/item/attribute IDs invalidate the affected definition with diagnostics, not server startup.
+
+## 10. Bosses
+- Wither MAY be the default boss but is not mandatory.
+- Boss definitions are data-driven and MAY reference vanilla or modded registered entities.
+- Pseudo-bosses MAY apply name, scale, attributes, equipment, boss bar and optional adds/minions.
+- Third-party boss compatibility is best-effort; arena containment and cleanup still apply.
+- Boss rewards scale with completed session/wave tier.
+- Optional boss mods must never become required dependencies.
+
+## 11. Arena isolation and protection
+During an active session, the arena bounding box is a logical sealed boundary.
+- Participants cannot leave except through arena-controlled teleport/exit.
+- Non-participant players cannot enter.
+- Arena mobs cannot leave; outside mobs cannot enter.
+- Projectiles/effects must not cross the boundary in either direction where technically interceptable; unsafe crossing projectiles should be cancelled/removed.
+- Arena mobs SHOULD NOT target non-participants.
+- Endermen cannot move arena blocks and cannot teleport outside.
+- Explosions can retain combat effects but MUST NOT destroy arena blocks.
+- Participants cannot place or break arena blocks.
+- Existing arena interactions remain usable where safe: ladders, slime blocks, doors/trapdoors/buttons, wind charges, etc.
+- Arena mobs SHOULD drop no normal loot/XP unless explicitly configured.
+- All session-spawned entities (mobs, mounts, passengers, minions, relevant projectiles) are tagged/tracked by session and cleaned on end/recovery.
+- Spectator stands may exist immediately outside the bounding box; spectators must not influence combat.
+
+## 12. Water environment
+No dynamic obstacle system in V1. Builders own obstacles.
+
+Themes MAY request temporary arena flooding by 0..N block layers above a configured water baseline.
+- Only safe/replaceable positions may be temporarily filled.
+- Never overwrite permanent arena geometry blindly.
+- Track every modified position needed for exact restoration.
+- Water MAY rise/fall progressively for presentation.
+- Restore on theme transition as designed, session end, abort and recovery.
+- Recovery MUST handle server restart without leaving permanent unintended flooding.
+- `WATER` spawn points become eligible when appropriate.
+
+## 13. Cobblemon and other integrations
+Cobblemon support is OPTIONAL.
+- If absent, arena works normally.
+- If present, arena rules can allow or block Pokémon use/sending/battling during a session.
+- Integration code must be isolated and written only against verified APIs for the installed target version.
+
+EasyNPC is OPTIONAL presentation/integration only. Core registration/readiness/session behavior must work without it.
+Create is NOT a dependency. Builders may use Create/redstone around the arena independently.
+
+## 14. Rewards and forfeit
+- Currency reward is equal per qualifying starting participant; do not create a pot that grows for survivors when teammates are eliminated.
+- Default: currency is awarded on final victory; amount depends on completed wave/session tier and configurable scaling.
+- Reward item/currency can be configured in-game from a held ItemStack and persisted in configuration.
+- Reputation is progression-based as described above.
+- Collective forfeit is available through an in-chat vote among active participants.
+- Default vote: absolute majority; solo = immediate. Duration/config is configurable.
+- Successful forfeit -> ABORTED -> cleanup, exit and inventory restoration; no victory currency.
+
+## 15. Validation philosophy
+Provide useful startup/reload/admin diagnostics for:
+- missing registry IDs;
+- malformed class/theme/boss definitions;
+- impossible min/max/cost values;
+- missing required arena points;
+- invalid bounds/spawn points;
+- incompatible boss size warning.
+
+Invalid content should be disabled locally whenever safe instead of crashing the server.