Wave Defense Mod - v0.2.44

Wave Defense is a PvE/PvP Forge mod for Minecraft 1.20.1 and Java 17. It lets server owners build configurable arena locations with mob waves, team PvP, shops, loot events, portals, boundaries, HUD panels, and in-game admin editors.

Status

Version 0.2.44 — stable after seven audit passes and full tester review (43 screenshots).

Completed in this workspace:

• Architecture: Decomposed WaveManager (3 748 lines) into 11 focused sub-managers; LocationSession value object; ListEditorScreen<T> base class; CoordinateInputField compound widget; LocationSerializer / NbtHelper data layer.
• PvE runtime: Fixed totalWaves persistence, victoryLingerTicks countdown, dead-mob cleanup, waveStartMobCount inflation, PlayerBackup restore (armor/offhand/effects). Activated waveEffect, pointsReward, completionCommand, firstWaveDelaySec.
• PvP runtime: Fixed premature ENDED state, dmTeamKills accumulation, BR simultaneous death draw, BR environment death tracking, rebalance during BUY phase, double-point award, PvP teammates HUD sync.
• Networking: SellItemPacket now carries shopPointIndex; all server responses use Component.translatable().
• Data safety: LocationManager writes a .bak copy on save; restores from backup on corrupt primary file.
• Spawn correctness: Mob dimension fixed (no longer tied to player's current dimension); unloaded-chunk guard prevents stalled waves.
• i18n: Full localization — 224 keys per language, 8 language files (EN · UK · DE · FR · ES · PL · PT-BR · ZH-CN), zero hardcoded player-visible strings.
• § corruption fix: All ?[color] substitutions and \\u00A7x literal-escape auto-keys corrected across all 8 lang files and 3 Java GUI files.
• GUI audit (52 screens): Scissor clipping, scroll behavior, hidden-widget click filtering, two-click delete confirmations (waves, rewards, PvP spawns), Cancel buttons, per-slot loot "from hand" buttons, stable effect-picker width, standardized button heights.
• Layout fixes: Import/Export header overlap, Completion Rewards item frame padding, tooltip black-box bug, LocationEditor footer overlap, mob spawn scroll Y offset, PvP mode unlock button.
• Config screen: In-game configuration via Mods menu → Wave Defense → Config (all wavedefense-common.toml settings, five tabs, saves on close).

Still to do:

• Clean generated notes, old summaries, corrupted files, and root-level prototype files.
• Run full in-game testing for PvE waves and 2+ player PvP sessions.

Installation

1. Install Forge 1.20.1 (47.2.0+ recommended).
2. Copy the built wavedefense-0.2.44.jar into the mods/ folder.
3. Start the client or dedicated server.

Key Bindings

Main Features

PvE Wave Defense

• Configurable locations with player spawn, optional scatter radius, and mob spawn points.
• Configurable waves with mob type, count, equipment, effects, spawn chance, and scaling.
• Optional delay before the first wave and between later waves.
• Point system for kills, starting points, purchases, sales, rewards, and completion bonuses.
• Inventory backup and restore on entry/exit.
• Starting items and completion rewards.
• Global shop mode or point-based shop mode.
• Loot spawn points with event triggers.
• Optional auto-activation zone with countdown and particles.
• Optional location boundary with timer, damage, teleport-back, or instant surrender modes.
• Optional portal system for penalty waves.
• TextDisplay info panels for wave, timer, mob count, players, and points.

PvP Modes

PvP locations use team spawn points and per-location PvP settings.

Supported sub-modes:

• Standard: team rounds with buy phase, countdown, active phase, win/loss points, and round count.
• Deathmatch: respawns during the match and victory by kill target.
• Battle Royale: random spawn assignment, shrinking border, border particles, and last-player-wins flow.

PvP settings include:

• team spawn points with optional spawn radius;
• minimum player count;
• friendly fire;
• team auto-balance;
• wait effects;
• starting points;
• kill points and death penalty;
• round start delay;
• round start/win/loss points;
• Deathmatch kill target;
• Battle Royale border radius, shrink interval, particles, and border damage.

Admin Editors

The mod is designed to be configured in game through GUI screens:

• location editor;
• PvP location editor;
• wave list editor;
• wave mob editor;
• wave trigger editor;
• mob selection;
• starting items;
• completion rewards;
• shop editor;
• shop item editor;
• shop availability trigger editor;
• shop point editor;
• loot spawn editor;
• import/export screens;
• HUD editor.
• player PvP team selection screen.

Current UI direction for 0.2.43+:

• fewer long unstructured forms;
• grouped sections for Basic, Spawns, Waves, Shop, Loot, Boundary, Portal, HUD, and PvP;
• consistent scroll behavior across all large screens;
• no clicks on hidden scrolled-out widgets;
• better player shop browsing with list and tile/grid modes;
• parity between useful PvE location settings and PvP location settings;
• clearer PvP team selection with scrollable cards for locations with many teams.

Shop System

The shop supports:

• multiple item stacks per shop entry;
• buy and sell price;
• category;
• optional NBT matching for sell checks;
• availability triggers;
• global shop items;
• per-point shop items;
• import/export through NBT files.

Player-facing UI:

• tile/grid view with item icons, compact prices, category filtering, and clear buy/sell actions;
• classic list view remains available from the same shop screen.

Trigger System

Triggers are used by waves, loot, shops, and location events.

Examples:

• wave events: WAVE_START, WAVE_END, WAVE_N, WAVE_COMPLETE;
• timers: TIMER_60, TIMER_120, TIMER_300, TIMER_CUSTOM;
• mob events: MOB_KILL, MOBS_KILLED_N, MOBS_REMAINING_LOW;
• player events: PLAYER_JOIN, PLAYER_DEATH, PLAYER_ENTER_ZONE, PLAYER_HAS_ITEM;
• PvP events: ROUND_START, ROUND_END, BUY_PHASE, MATCH_START, MATCH_END, TEAM_WIPE, KILL_STREAK_3;
• shop events: SHOP_LOCATION_START, SHOP_WAVE_START, SHOP_WAVE_N, SHOP_PLAYER_HAS_ITEM.

Commands

Configuration

In-game (recommended)

Open the Mods menu → select Wave Defense → click Config.
A five-tab GUI covers every setting without editing any file manually:

Changes are written to disk immediately on Save & Close.

File (manual)

Common config file:

config/wavedefense-common.toml

Architecture

Core runtime:

WaveDefenseMod
  WaveManager
    WaveContext
    LocationSession
    SessionManager
    MobSpawnManager
    TriggerEvaluator
    PvpRoundManager
    BattleRoyaleManager
    BoundaryManager
    PortalManager
    ZoneActivationManager
    InfoPanelManager

Data layer:

Location
LocationManager
LocationSerializer
NbtHelper
WaveConfig
WaveMob
WaveTrigger
ShopItem
ShopPoint
LootSpawn
PvpSpawnPoint

Networking:

PacketHandler
network/packets/*

Client UI:

gui/*
events/HudOverlay
events/KeyBindings

Build

Use Java 17:

$env:JAVA_HOME='C:\Program Files\Java\jdk-17'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
.\gradlew.bat build

Quick verification:

$env:JAVA_HOME='C:\Program Files\Java\jdk-17'
$env:Path="$env:JAVA_HOME\bin;$env:Path"
.\gradlew.bat compileJava test

Cleanup Notes

The repository currently contains older implementation summaries, generated build/run artifacts, root-level prototype files, and at least one corrupted Java file. Those should be cleaned in a separate pass after gameplay and GUI behavior are stable.

Known cleanup candidates:

• root-level summary markdown files that are no longer useful;
• root-level prototype Java files outside src/main/java;
• src/main/java/com/wavedefense/audit/WaveDefenseAuditLog.java.corrupted;
• stale generated files in build/ and run/ if they were accidentally included in source control.

License

MIT.