gunfigterarusil/wave-defense-mod

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