Initial commit

.local/ARCHITECTURE.md

@@ -0,0 +1,81 @@
+# 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.