213 lines
11 KiB
Markdown
213 lines
11 KiB
Markdown
# 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.
|