81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 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.
|