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

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.