# Architecture — NeoForge 1.21.1 Arena

This document fixes responsibilities, not exact Java package names.

## Modules/components
### ArenaManager
Owns registered arena definitions/controllers and active sessions. V1 may enforce one active arena, but APIs should accept arena/session IDs.

### ArenaDefinition / ArenaControllerBlockEntity
Persistent spatial configuration: relative bounds, locations, tagged spawn points, water baseline/max, presentation/config metadata. Controller is the coordinate origin.

### ArenaSession
Runtime state machine. Holds immutable starting roster/config snapshot plus mutable participant states, wave state, lives, tracked entities, environment transaction and reward progress.

### ParticipantState
UUID, class, ready/eliminated status, remaining arena kit state, reputation progress, recovery reference.

### InventoryRecoveryService
Durable, idempotent recovery snapshots. Owns save-before-clear, restore-on-exit/login, unfinished-session recovery and anti-duplication state transitions. Keep this isolated and heavily tested.

### ContentRepository
Loads/reloads/validates JSON definitions: classes, ranks, themes, mob variants, bosses, progression/balance config. Registry-aware validation produces diagnostics and disabled-definition lists.

### ItemStackCodec / CaptureService
Uses Minecraft's supported ItemStack serialization/data-component mechanisms for target version. In-game capture normalizes durability only, preserves stack count and other components, then writes canonical JSON.

### WaveDirector
Pure-ish deterministic logic where possible. Inputs: wave index, target budget, eligible themes, recent theme history, player scaling, RNG seed. Output: planned composition. Does not directly spawn entities.

### SpawnService
Turns planned entries into entities at validated tagged spawn points. Supports equipment, attributes, scale, vehicles/passengers and session tagging.

### ArenaIsolationService
Event-driven boundary/protection rules: entry/exit, teleport containment, block break/place, explosions, endermen, targeting, projectile crossing, loot/XP, interaction rules.

### EnvironmentService
Transactional temporary water modifications and restoration. Persist enough recovery information to undo interrupted flooding.

### Reward/ReputationService
UUID reputation/ranks, wave validation, victory currency, admin configuration.

### Presentation/UI
Titles/action bar, intuitive registration/class/ready screens or interactions. Player commands are not required. Admin commands remain separate.

### Optional integrations
Separate compatibility adapters loaded only when the mod is present:
- Cobblemon: block/allow Pokémon actions according to arena rule.
- EasyNPC: optional hooks/commands/API bridge if verified and useful.
No Create dependency.

## Persistence
Use NeoForge/Minecraft-supported persistent data facilities appropriate to 1.21.1. Do not invent ad-hoc unsafe serialization when native codecs/registries are available.

Persist at least:
- controller/arena definition;
- reputation/ranks data as appropriate;
- inventory recovery records;
- enough active-session recovery marker to detect an interrupted session;
- temporary environment restoration data while modifications exist.

## State machine invariants
- Only registered participants may enter participant states.
- Inventory snapshot success precedes inventory clearing.
- Starting roster, average reputation tier, wave count and mode are frozen at countdown start.
- Session-created entities carry session identity.
- Cleanup is idempotent: running it twice must not duplicate rewards/items or damage the world.
- Reward payout is idempotent.
- Recovery is safe after abrupt server termination.

## Data-driven compatibility
Use ResourceLocations/registries for Item, EntityType, Attribute, enchantment/data component references supported by the target APIs. A definition may reference another mod without compile-time linkage.

## Networking
Keep authority server-side. Client packets are requests/UI actions only; server validates class unlocks, readiness, arena membership, admin permissions and configuration changes.

## Performance
- Do not scan the entire arena every tick.
- Track session entities directly.
- Boundary checks should be event-driven where possible; low-frequency sanity checks may repair missed crossings.
- Water changes should be batched/throttled.
- Spawn validation should inspect only candidate locations/entity dimensions.