# gunfigterarusil/wave-defense-mod architecture

> Architecture diagram of the GitHub repository gunfigterarusil/wave-defense-mod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gunfigterarusil/wave-defense-mod
- Repository: https://github.com/gunfigterarusil/wave-defense-mod

## Overview

#### Purpose and Runtime
Wave Defense is a server-authoritative Minecraft Forge mod for Minecraft 1.20.1 on Java 17. It provides configurable arena “locations” supporting PvE waves and several PvP modes, with in-game player/admin UI, persistent arena definitions, and client/server synchronization. Mod bootstrap and lifecycle wiring begin in `src/main/java/com/wavedefense/WaveDefenseMod.java`; Forge metadata is in `src/main/resources/META-INF/mods.toml`.

#### Entry Points and Interaction Surface
Forge events drive server ticks, player lifecycle, HUD, and keybindings through `src/main/java/com/wavedefense/events/EventHandler.java`, `src/main/java/com/wavedefense/events/ClientEventHandler.java`, and `src/main/java/com/wavedefense/events/KeyBindings.java`. Commands expose operational entry points for menus, teleporting, kicking, and reloads in `src/main/java/com/wavedefense/commands/WaveDefenseCommand.java` and `src/main/java/com/wavedefense/commands/WaveDefenseAdminCommands.java`.

#### Location Data and Persistence
`Location` is the aggregate configuration for an arena: mode, wave/PvP settings, spawn points, shops, loot, boundaries, portals, capture points, and panels. `LocationManager` owns indexed location lookup, loading, concurrent section-level merges, debounced/atomic saves, and backup recovery. Serialization is isolated from runtime logic.
- `src/main/java/com/wavedefense/data/Location.java`
- `src/main/java/com/wavedefense/data/LocationManager.java`
- `src/main/java/com/wavedefense/data/LocationSerializer.java`

#### Session and PvE Wave Orchestration
`WaveManager` is the central runtime coordinator. A player/group enters a `LocationSession`; session state is held separately from durable location configuration. `SessionManager` manages session lifecycle, while `MobSpawnManager`, `TriggerEvaluator`, autoscaling, and contextual state advance each arena during ticks. The flow is: configured location → session creation/join → wave scheduling/spawn/trigger evaluation → completion, abandonment grace period, or cleanup/restoration.
- `src/main/java/com/wavedefense/wave/WaveManager.java`
- `src/main/java/com/wavedefense/wave/LocationSession.java`
- `src/main/java/com/wavedefense/wave/MobSpawnManager.java`

#### PvP, Spatial Rules, and Arena Services
PvP sessions branch into round-based, deathmatch, capture-point, and battle-royale behaviors. PvP managers apply team state, round transitions, respawns, scoring, and winners; BR controls the shrinking arena. Boundary, portal, zone activation, capture points, and info panels are independent services invoked by the session/wave loop rather than embedded in data models.
- `src/main/java/com/wavedefense/wave/PvpRoundManager.java`
- `src/main/java/com/wavedefense/wave/BattleRoyaleManager.java`
- `src/main/java/com/wavedefense/wave/BoundaryManager.java`

#### Network Boundary and Client State
`PacketHandler` defines the client/server packet channel. Client UI sends intent packets—purchases, joins/leaves, readiness, and admin mutations—while the server validates, mutates authoritative state, and sends sync packets for location, player, shop, PvP, stats, teammate, and capture-point state. `PacketRateLimiter` protects selected client-to-server paths. Client cache/managers decouple rendering from packet arrival.
- `src/main/java/com/wavedefense/network/PacketHandler.java`
- `src/main/java/com/wavedefense/network/PacketRateLimiter.java`
- `src/main/java/com/wavedefense/gui/ClientPlayerDataManager.java`

#### UI and Configuration
Client-only screens provide the operational product surface: unified location editing, wave/shop configuration, import/export, player menus, and match views. HUD rendering consumes synchronized state and local interpolation. Shared config and game-rule abstractions control global defaults and limits.
- `src/main/java/com/wavedefense/gui/AdminMenuScreen.java`
- `src/main/java/com/wavedefense/gui/universal/UniversalLocationEditor.java`
- `src/main/java/com/wavedefense/events/HudOverlay.java`

#### External Integrations and Operations
The mod optionally integrates with Mine and Slash and Tacz through compatibility adapters, avoiding mandatory dependencies. Operational resilience includes scheduled player backups and TPS/health monitoring. Localization assets serve all player-visible text.
- `src/main/java/com/wavedefense/compat/MineAndSlashCompat.java`
- `src/main/java/com/wavedefense/compat/TaczCompat.java`
- `src/main/java/com/wavedefense/backup/WaveDefenseBackupSystem.java`

Main entry points: [`src/main/java/com/wavedefense/wave/WaveManager.java`](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/WaveManager.java) (Wave manager), [`src/main/java/com/wavedefense/network/PacketHandler.java`](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/network/PacketHandler.java) (Packet channel), [`src/main/java/com/wavedefense/data/LocationManager.java`](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/LocationManager.java) (Location manager), [`src/main/java/com/wavedefense/WaveDefenseMod.java`](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/WaveDefenseMod.java) (Mod bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forge["Forge integration"]
  node_mod{{"Mod bootstrap<br/>Forge mod entry"}}
  node_events["Server event handler<br/>Forge events<br/>[EventHandler.java]"]
  node_client_events["Client events and keys<br/>Forge client events"]
  node_commands["Player commands<br/>command handlers"]
  node_admin_commands["Admin commands<br/>command handlers"]
end

subgraph group_server["Authoritative server"]
  node_location["Location definition<br/>arena aggregate<br/>[Location.java]"]
  node_location_manager[("Location manager<br/>persistent location store")]
  node_location_serializer["Location serializer<br/>serialization"]
  node_wave_manager{{"Wave manager<br/>runtime coordinator<br/>[WaveManager.java]"}}
  node_location_session["Location session<br/>runtime session state"]
  node_mob_spawns["Mob spawn manager<br/>PvE spawning"]
  node_pvp_rounds["PvP round manager<br/>PvP modes"]
  node_battle_royale["Battle royale manager<br/>PvP mode"]
  node_arena_services["Arena services<br/>spatial gameplay services"]
  node_packet_handler["Packet channel<br/>network boundary<br/>[PacketHandler.java]"]
  node_rate_limiter["Packet rate limiter<br/>network protection"]
end

subgraph group_client["Client UI and state"]
  node_client_cache["Client player cache<br/>synchronized client state"]
  node_admin_ui["Admin UI<br/>client screen"]
  node_location_editor["Location editor<br/>client editor"]
  node_hud["HUD overlay<br/>client rendering<br/>[HudOverlay.java]"]
end

subgraph group_operations["Operations and integrations"]
  node_backup["Backup system<br/>operational resilience"]
  node_mine_slash["Mine and Slash adapter<br/>optional compatibility"]
  node_tacz["Tacz adapter<br/>optional compatibility<br/>[TaczCompat.java]"]
end

node_mod -->|"registers"| node_events
node_mod -->|"registers"| node_client_events
node_mod -->|"initializes"| node_packet_handler
node_commands -->|"operates"| node_wave_manager
node_admin_commands -->|"mutates and reloads"| node_location_manager
node_events -->|"server ticks"| node_wave_manager
node_location_manager -->|"loads and saves through"| node_location_serializer
node_location_manager -->|"owns definitions"| node_location
node_wave_manager -->|"reads configuration"| node_location_manager
node_wave_manager -->|"creates and advances"| node_location_session
node_wave_manager -->|"orchestrates PvE"| node_mob_spawns
node_wave_manager -->|"routes PvP sessions"| node_pvp_rounds
node_pvp_rounds -->|"uses for BR mode"| node_battle_royale
node_wave_manager -->|"invokes"| node_arena_services
node_packet_handler -->|"guards intents with"| node_rate_limiter
node_packet_handler -->|"validated session intent"| node_wave_manager
node_packet_handler -->|"validated admin changes"| node_location_manager
node_admin_ui -->|"sends intents"| node_packet_handler
node_location_editor -->|"sends edits"| node_packet_handler
node_packet_handler -->|"syncs state"| node_client_cache
node_client_cache -->|"supplies match state"| node_hud
node_client_events -->|"renders"| node_hud
node_backup -.->|"backs up player state"| node_wave_manager
node_mine_slash -.->|"optional integration"| node_wave_manager
node_tacz -.->|"optional integration"| node_wave_manager

click node_mod "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/WaveDefenseMod.java"
click node_events "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/EventHandler.java"
click node_client_events "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/ClientEventHandler.java"
click node_commands "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/commands/WaveDefenseCommand.java"
click node_admin_commands "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/commands/WaveDefenseAdminCommands.java"
click node_location "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/Location.java"
click node_location_manager "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/LocationManager.java"
click node_location_serializer "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/LocationSerializer.java"
click node_wave_manager "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/WaveManager.java"
click node_location_session "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/LocationSession.java"
click node_mob_spawns "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/MobSpawnManager.java"
click node_pvp_rounds "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/PvpRoundManager.java"
click node_battle_royale "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/BattleRoyaleManager.java"
click node_arena_services "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/BoundaryManager.java"
click node_packet_handler "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/network/PacketHandler.java"
click node_rate_limiter "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/network/PacketRateLimiter.java"
click node_client_cache "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/ClientPlayerDataManager.java"
click node_admin_ui "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/AdminMenuScreen.java"
click node_location_editor "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/universal/UniversalLocationEditor.java"
click node_hud "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/HudOverlay.java"
click node_backup "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/backup/WaveDefenseBackupSystem.java"
click node_mine_slash "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/compat/MineAndSlashCompat.java"
click node_tacz "https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/compat/TaczCompat.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mod,node_events,node_client_events,node_commands,node_admin_commands toneBlue
class node_location,node_location_manager,node_location_serializer,node_wave_manager,node_location_session,node_mob_spawns,node_pvp_rounds,node_battle_royale,node_arena_services,node_packet_handler,node_rate_limiter toneAmber
class node_client_cache,node_admin_ui,node_location_editor,node_hud toneMint
class node_backup,node_mine_slash,node_tacz toneRose
```

## Components

### Forge integration

- [Mod bootstrap](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/WaveDefenseMod.java): Forge mod entry · Registers lifecycle wiring and mod services. · `src/main/java/com/wavedefense/WaveDefenseMod.java`
- [Server event handler](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/EventHandler.java): Forge events · Drives ticks and player lifecycle events. · `src/main/java/com/wavedefense/events/EventHandler.java`
- [Client events and keys](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/ClientEventHandler.java): Forge client events · Drives HUD and keybinding interaction. · `src/main/java/com/wavedefense/events/ClientEventHandler.java`
- [Player commands](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/commands/WaveDefenseCommand.java): command handlers · Opens menus and supports arena operations. · `src/main/java/com/wavedefense/commands/WaveDefenseCommand.java`
- [Admin commands](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/commands/WaveDefenseAdminCommands.java): command handlers · Provides administrative mutation and reload operations. · `src/main/java/com/wavedefense/commands/WaveDefenseAdminCommands.java`

### Authoritative server

- [Location definition](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/Location.java): arena aggregate · Durable arena mode, rules, geometry, shops, and panels. · `src/main/java/com/wavedefense/data/Location.java`
- [Location manager](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/LocationManager.java): persistent location store · Indexes, merges, loads, and atomically saves arena definitions. · `src/main/java/com/wavedefense/data/LocationManager.java`
- [Location serializer](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/data/LocationSerializer.java): serialization · Keeps durable format conversion outside runtime logic. · `src/main/java/com/wavedefense/data/LocationSerializer.java`
- [Wave manager](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/WaveManager.java): runtime coordinator · Coordinates authoritative arena sessions and progression. · `src/main/java/com/wavedefense/wave/WaveManager.java`
- [Location session](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/LocationSession.java): runtime session state · Separates active player or group state from location configuration. · `src/main/java/com/wavedefense/wave/LocationSession.java`
- [Mob spawn manager](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/MobSpawnManager.java): PvE spawning · Schedules and spawns wave mobs. · `src/main/java/com/wavedefense/wave/MobSpawnManager.java`
- [PvP round manager](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/PvpRoundManager.java): PvP modes · Handles teams, rounds, scoring, respawns, and winners. · `src/main/java/com/wavedefense/wave/PvpRoundManager.java`
- [Battle royale manager](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/BattleRoyaleManager.java): PvP mode · Controls shrinking-arena behavior. · `src/main/java/com/wavedefense/wave/BattleRoyaleManager.java`
- [Arena services](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/wave/BoundaryManager.java): spatial gameplay services · Applies boundaries, portals, zones, capture points, and panels. · `src/main/java/com/wavedefense/wave/BoundaryManager.java`
- [Packet channel](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/network/PacketHandler.java): network boundary · Routes validated client intents and server sync packets. · `src/main/java/com/wavedefense/network/PacketHandler.java`
- [Packet rate limiter](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/network/PacketRateLimiter.java): network protection · Protects selected client-to-server packet paths. · `src/main/java/com/wavedefense/network/PacketRateLimiter.java`

### Client UI and state

- [Client player cache](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/ClientPlayerDataManager.java): synchronized client state · Decouples client rendering from packet arrival. · `src/main/java/com/wavedefense/gui/ClientPlayerDataManager.java`
- [Admin UI](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/AdminMenuScreen.java): client screen · Provides operational arena administration. · `src/main/java/com/wavedefense/gui/AdminMenuScreen.java`
- [Location editor](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/gui/universal/UniversalLocationEditor.java): client editor · Edits unified arena configuration. · `src/main/java/com/wavedefense/gui/universal/UniversalLocationEditor.java`
- [HUD overlay](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/events/HudOverlay.java): client rendering · Renders synchronized match state. · `src/main/java/com/wavedefense/events/HudOverlay.java`

### Operations and integrations

- [Backup system](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/backup/WaveDefenseBackupSystem.java): operational resilience · Schedules player backups. · `src/main/java/com/wavedefense/backup/WaveDefenseBackupSystem.java`
- [Mine and Slash adapter](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/compat/MineAndSlashCompat.java): optional compatibility · Integrates without a mandatory dependency. · `src/main/java/com/wavedefense/compat/MineAndSlashCompat.java`
- [Tacz adapter](https://github.com/gunfigterarusil/wave-defense-mod/blob/main/src/main/java/com/wavedefense/compat/TaczCompat.java): optional compatibility · Integrates without a mandatory dependency. · `src/main/java/com/wavedefense/compat/TaczCompat.java`

## Connections

- Mod bootstrap → Server event handler: registers
- Mod bootstrap → Client events and keys: registers
- Mod bootstrap → Packet channel: initializes
- Player commands → Wave manager: operates
- Admin commands → Location manager: mutates and reloads
- Server event handler → Wave manager: server ticks
- Location manager → Location serializer: loads and saves through
- Location manager → Location definition: owns definitions
- Wave manager → Location manager: reads configuration
- Wave manager → Location session: creates and advances
- Wave manager → Mob spawn manager: orchestrates PvE
- Wave manager → PvP round manager: routes PvP sessions
- PvP round manager → Battle royale manager: uses for BR mode
- Wave manager → Arena services: invokes
- Packet channel → Packet rate limiter: guards intents with
- Packet channel → Wave manager: validated session intent
- Packet channel → Location manager: validated admin changes
- Admin UI → Packet channel: sends intents
- Location editor → Packet channel: sends edits
- Packet channel → Client player cache: syncs state
- Client player cache → HUD overlay: supplies match state
- Client events and keys → HUD overlay: renders
- Backup system → Wave manager: backs up player state
- Mine and Slash adapter → Wave manager: optional integration
- Tacz adapter → Wave manager: optional integration