Arena Waves Engine v1.5.3

Arena Waves Engine 1.5.3​

Overview​

Arena Waves Engine 1.5.3 introduces advanced affix integration with Mob Affix Engine, and critical stability improvements. Server administrators can now configurable player scaling, and seamless loot integration via Chest Instance Engine.

For Server Owners & Modders​

New Features​

• Mob Affix Integration (MAE) — Dynamic Difficulty
  • Configure affix effects via new AffixDefinition in enemy definitions
  • AWE automatically forwards effect stat payloads to Mob Affix Engine via awe-effect-stats command dispatch
  • Mobs gain dynamic stat modifications (HP scaling, damage multipliers, special effects)
  • Victim effects now execute with correct command format (--chance and --every flags)
  • Enables challenging, dynamic enemy progression throughout the arena session
• Wave Player Scaling
  • Waves now support per-player difficulty scaling through WavePlayerScalingConfig
  • Configure scaling behavior per wave: enemy health, damage, or spawn count based on player count
  • Ensure balanced progression for solo vs. squad sessions
• Wave Timed-Out Title
  • Players receive visual feedback when the WAITING_CLOSE timeout expires
  • Improves UX for players unfamiliar with timeout mechanics
• TIMER Wave Trigger Mode
  • Introduce wave trigger configuration with TIMER mode for automatic wave completion
  • TIMER mode: wave completes automatically after configured duration
  • COMBAT mode: wave completes when all enemies defeated (existing)
• CIE Integration — Completion Profile Flow
  • Arena completion now integrates with Chest Instance Engine for per-player reward profiles
  • Reward chests assign completion-based loot profiles based on performance
  • Squad sessions can distribute different rewards per player
  • Fully persistent via CIE's instance storage

Changes & Improvements​

• Result Flow (WAITING_CLOSE Lifecycle)
  • Final wave completion now executes result actions in correct sequence:
    1. Compute result state (COMPLETED or FAILED)
    2. Remove arena portal/marker from map
    3. Execute result commands (Events.Completed or Events.Failed)
    4. Open leaderboard/results page
    5. Transition to WAITING_CLOSE (grace period for post-combat interactions)
  • CIE integration now works reliably at arena completion
  • Reward chests spawn before session close (correct order)
• Database Migrations (Automatic)
  • Three new migrations run automatically on startup:
    • Migration_202603231211_AddingCurrentWaveSpawnProgress — Wave progress tracking
    • Migration_202603251256_AddingResultState — Result state persistence
  • No manual action required from server administrators

Bug Fixes​

• Victim Effect Command Format — Fixed --chance and --every flag handling in effect commands
• Portal Cleanup — Fixed portal/map marker not being removed on result flow
• Test Coverage— Resolved all 13 test failures and added comprehensive test suite:
  • WaitingClearStateHandlerTest (329 lines) — Chunk load validation
  • SessionStartingHandlerAutoJoinTest (201 lines) — Auto-join flow coverage
  • InviteManagerTest (85 lines) — Invite system validation
  • JoinSessionServiceTest (125 lines) — Multi-player join scenarios
  • Enhanced CommandExecutorServiceTest (257 lines of updates)

Configuration Updates​

New Config Fields​

Field	Type	Default	Description
WavePlayerScaling	Object	null	Per-player difficulty scaling configuration (health, damage, spawn count multipliers)
AffixDefinition	Object	null	Mob affix configuration for dynamic stat modifications via Mob Affix Engine
WaveTrigger.TriggerMode	Enum	COMBAT	Wave completion trigger mode (COMBAT = all enemies defeated, TIMER = auto-complete after duration)
WaveTrigger.DurationSeconds	Integer	—	Duration in seconds for TIMER mode waves

JSON Configuration Example (New Fields):

Code:

{
  "Id": "default_arena_map_affix_reward",
  "Name": "Default arena map mob affix with reward",
  "Description": "Any description for default arena map",
  "Spawn": { "X": 0.0, "Y": 0.0, "Z": 0.0 },
  "CleanupTimeoutSeconds": 300,
  "CompletionThreshold": 0.0,
  "WavePlayerScaling": { "HpMultiplierPerPlayer": 2.0 },
  "Events": {
    "Started": [],
    "Completed": [
      {
        "Command": "cie spawn awe_boss_reward_chest --trigger {session} --percentage {completionPercentage} --position {spawnPosition} --expiresAt {closeTimeout}",
        "PerPlayer": false,
        "RunAsConsole": true
      },
      {
        "Command": "cie assign-profile {session} {player} {profile}",
        "PerPlayer": true,
        "RunAsConsole": true
      }
    ],
    "Failed": [],
    "Stopped": []
  },
  "Waves": [
    {
      "Interval": 10,
      "Enemies": [
        {
          "EnemyType": "Skeleton",
          "Count": 3,
          "Radius": 8.0,
          "Scale": 1.0,
          "Speed": 1.0,
          "PlayerHeadRotation": { "X": 0.0, "Y": 0.0, "Z": 0.0 },
          "PosOffset": { "X": 0.0, "Y": 0.0, "Z": 0.0 },
          "HeadRotation": { "X": 0.0, "Y": 0.0, "Z": 0.0 },
          "BodyRotation": { "X": 0.0, "Y": 0.0, "Z": 0.0 },
          "RandomRotation": true,
          "FacingRotation": false,
          "FlockSize": 1,
          "Frozen": false,
          "RandomModel": false,
          "BypassScaleLimits": true,
          "SpawnOnGround": true,
          "NonRandom": false,
          "Affix": {
            "EntityStatType": [
              { "Name": "Health", "Multiplier": 2.0, "CalculationType": "MULTIPLICATIVE" },
              { "Name": "Damage", "Multiplier": 5.0, "CalculationType": "MULTIPLICATIVE" }
            ],
            "EntityEffectStatus": [
              { "Name": "Immune", "Duration": 5.0, "Chance": 1.0, "Every": 10.0, "EntityStatType": [] },
              { "Name": "Thorns_T5", "Duration": 999.0, "Chance": 1.0, "EntityStatType": [] }
            ],
            "VictimEntityEffectStatus": [
              { "Name": "Burn", "Duration": 10.0, "Chance": 0.5, "EntityStatType": [] },
              { "Name": "Slow", "Duration": 10.0, "Chance": 1.0, "EntityStatType": [] }
            ]
          }
        }
      ],
      "Trigger": {
        "Condition": "ALL_DEAD",
        "TimerSeconds": 0
      }
    }
  ]
}

Dependencies​

Dependency	Version	Type	Notes
Hytale Server	2026.03.26-89796e57b	Required	Server API
HyDB	1.0	Required	SQLite database for session/wave persistence
HyUI	0.9.4	Required	HTML/page rendering for results and maps
MultipleHUD	1.0.6	Required	HUD management and session display
ChestInstanceEngine (CIE)	1.0.0-rc0.0.1	Optional	Reward chest workflow on arena completion
MobAffixEngine (MAE)	1.0.0-rc0.1.0	Optional	Dynamic mob stat scaling and affix effects

Server Admin Action:

• Required dependencies ship with AWE; no separate installation needed
• Install CIE and MAE separately only if you want reward chests or affix effects

Arena Waves Engine 1.5.2​

Overview​

This release introduces auto-join for the session starter, persists wave spawn progress to the database, improves NPC spawn spread consistency, and overhauls command documentation in the README.

For Server Owners & Modders​

New Features​

• Auto-Join Starter Player
  • When a player starts an arena session with a configured tp.playerPosition, they are now automatically joined into the session — no separate /awe join needed.
  • This works for both the /awe start --waveMapId <id> command and the UI selection flow.
  • If tp.playerPosition is not configured (or set to 0,0,0), behavior is unchanged — the player starts the arena but is not teleported.

Changes & Improvements​

• NPC Spawn Spread Now Applies to All Counts
  • Previously, when only 1 NPC spawned per entry, it was placed exactly at the configured position with no radius offset. Now all NPCs (including single spawns) use the configured radius for random spread.
  • This makes spawn behavior more consistent and less predictable for players.
• Wave Spawn Progress Persisted to Database
  • currentWaveSpawnProgress is now saved to the database instead of being held only in memory.
  • On a server restart mid-session, spawn progress is preserved and the wave resumes where it left off.
  • A database migration runs automatically on first start (Migration_202603231211).
• HUD Enemy List Visible During Spawning
  • The enemy progress bar in the Active Session HUD now displays during both SPAWNING and WAITING_CLEAR states (previously only WAITING_CLEAR).
  • Players can see remaining enemies as they spawn, not just after all have appeared.
• Improved Command Documentation (README)
  • All /awe commands now use detailed per-command sections with parameter tables (type, description, required/optional).
  • Invite and join commands updated to use --flag syntax (--sessionId, --player, --inviteCode).

Bug Fixes​

• None in this release.

Breaking Changes​

• Invite/Join command syntax updated: /awe invite <player> [sessionId] is now /awe invite <player> [--sessionId <sessionId>]. Similarly, /awe join now uses --player, --sessionId, --inviteCode flags. Update any scripts or documentation referencing the old positional syntax.

New Commands​

No new commands added. Existing commands updated:

Command	Change	Permission required
/awe invite <player> [--sessionId <id>]	sessionId is now a named flag	awe.invite
/awe join [--player <name>] [--sessionId <id>] [--inviteCode <code>]	All args are now named flags	awe.join

New Permissions​

No new permissions in this release.

Configuration Updates​

New Config Fields​

No new configuration fields for server admins.

Database Migration​

Migration	Description
Migration_202603231211	Adds currentWaveSpawnProgress column to the ArenaSession table. Runs automatically on server start.

Dependencies​

• Hytale Server: 2026.02.19-1a311a592 (unchanged)
• No dependency changes relevant for Server Admins.

Migration Guide​

1. Drop the new .jar into your plugins folder (replace the old one).
2. Start the server — the database migration runs automatically.
3. If you have scripts using /awe invite or /awe join with positional args, update them to use --sessionId, --player, --inviteCode flags.
4. No config file changes required.

What's Changed​

• feat: auto-join starter player when session starts with tp.playerPosition configured
• feat: persist currentWaveSpawnProgress to database (new migration)
• fix: NPC spawn spread now applies to single-count spawns
• fix: HUD enemy list visible during SPAWNING state
• refactor: extract JoinSessionService from JoinCommand (DRY)
• refactor: SessionStartingHandler broken into smaller focused methods
• docs: overhaul README command documentation with parameter tables
• test: add JoinSessionServiceTest and SessionStartingHandlerAutoJoinTest

Arena Waves Engine 1.5.1​

Overview​

This release brings an important hotfix for the /awe start command execution, resolving thread-safety issues that caused exceptions during arena initialization and pause actions.

For Server Owners & Modders​

Bug Fixes​

• /awe start command exception (Not in thread)
  • What was broken: Executing the /awe start command as a player caused instances of "start is not in thread" or "pauseAll not in thread" exceptions. This occurred because spawn logic and entity manipulation were not running inside the proper world tick thread.
  • How it's fixed: The execution of actions tied to /awe start (including SessionStarting and pause events) have been refactored and wrapped inside the target World execution thread (playerCurrentWorld.execute { ... }), guaranteeing correct thread safety.

What's Changed​

• fix: start is not in thread
• fix: pauseAll not in thread

Arena Waves Engine 1.5.0​

Executive Summary​

AWE 1.5.0 introduces a player invite system, console-initiated arenas, and a config structure change (spawn position relocated). Server Admins must update arena JSON configs — the Spawn field moves from inside Tp to the arena root. A database migration runs automatically.

Invite System​

Players can now invite others to join active arena sessions using short 4-character codes.

• /awe invite <player> [sessionId] — sends an invite with a unique code to the target player
• /awe join [player] [sessionId] [inviteCode] — accepts an invite and teleports into the arena
• If a player has exactly one pending invite, /awe join auto-accepts it
• If multiple invites are pending, all codes are listed for selection
• All pending invites for a session are automatically cleared when the session finishes

Important: Console execution of /awe join force-joins a player without requiring a code.

Click to expand...

Console-Initiated Arenas​

/awe start now works from both player and console — no separate command needed.

• /awe start <waveMapId> [world] — unified command for player and console
• When run from console, starts a session with no player owner; world parameter is optional if configured in Tp.World
• Useful for scheduled events, NPC triggers, or server-side automation

Spawn Position Relocated (Breaking Config Change)​

The Spawn field has moved from inside the Tp object to the arena map root level.

• Before (1.4.x): ArenaMaps[].Tp.Spawn
• After (1.5.0): ArenaMaps[].Spawn

Spawn resolution priority:

1. Tp.PlayerPosition (if configured and non-zero)
2. arenaDefinition.Spawn (new location)
3. Warning logged if neither is set

Important: You must update your arena JSON configs. Move the Spawn field out of Tp to the arena root.

Click to expand...

Before:

Code:

{
  "ArenaMaps": [{
    "Id": "my_arena",
    "Tp": {
      "Spawn": { "X": 100, "Y": 64, "Z": 200 },
      "World": "my_world"
    }
  }]
}

After:

Code:

{
  "ArenaMaps": [{
    "Id": "my_arena",
    "Spawn": { "X": 100, "Y": 64, "Z": 200 },
    "Tp": {
      "World": "my_world"
    }
  }]
}

Multi-Player Session Model​

Arena sessions are no longer tied to a single player owner.

• Removed owner, targetPlayer, and session-level savedPosition fields
• Each player now stores their own saved position independently (ArenaSessionPlayer.savedPosition)
• Database migration runs automatically (drops obsolete columns)

NPC Despawn Reliability​

Fixed NPC despawning when chunks are unloaded.

• Async despawn now uses CompletableFuture with guaranteed chunk loading
• 1-second timeout prevents indefinite hangs if chunk loading fails

Pause Command Fixes​

• /awe pause migrated from AbstractPlayerCommand to AbstractAsyncCommand for better async handling
• Fixed pauseAll logic in SessionPausedHandler

Commands​

Command	Description	Permission	Type
/awe invite <player> [sessionId]	Invite a player to an active arena session	miilhozinho.awe.invite	Player + Console
/awe join [player] [sessionId] [inviteCode]	Join an arena session via invite code	miilhozinho.awe.join	Player + Console
/awe start <waveMapId> [world]	Start an arena (now works from both Player and Console)	miilhozinho.awe.start	Player + Console

Permissions​

Permission	Description	New?
miilhozinho.awe.invite	Allows inviting players to arena sessions	Yes
miilhozinho.awe.join	Allows joining arena sessions via invite	Yes
miilhozinho.awe.start	/awe start now supports console execution (unified command)	Updated scope

Dependencies​

No relevant dependency changes for Server Admins.

Integrations & Placeholders​

No runtime AWE placeholder changes in this release.

Post-Update Checklist​

• Update arena JSON configs — move Spawn from Tp.Spawn to root-level Spawn for each arena map
• Server will auto-run database migration (drops owner, targetPlayer, savedPosition columns)
• Grant miilhozinho.awe.invite and miilhozinho.awe.join permissions to desired player groups
• Test /awe start <mapId> from server console
• Test invite flow: /awe invite <player> → target runs /awe join
• Verify NPC despawn behavior in arenas with chunk boundary edges

Config Hot-Reload​

This release introduces the ability to reload the Arena Waves Engine configuration from disk without restarting the server.

Previously, any change made to mods/Miilhozinho_ArenaWavesEngine/ArenaWavesEngine.json required a full server restart to take effect.
Starting from 1.4.2, the config is reloaded automatically in two situations:

• /awe start — config is read fresh from disk every time a new session is started, so the latest arena definitions are always used.
• /awe refresh — new admin command that explicitly triggers a reload on demand.

Running sessions are not affected. The reload only impacts future sessions started after the command is executed. Any arena currently in progress will continue with the configuration it was started
with.

Click to expand...

New Command​

Command	Description	Permission required
/awe refresh	Reloads the config file from disk instantly. No restart needed.	miilhozinho.awe.refresh

New Permission​

Permission	Description
miilhozinho.awe.refresh	Allows the player to execute /awe refresh

Arena Event Commands​

Arena Waves Engine now supports configurable lifecycle commands that fire automatically on
session events. Assign commands to any stage of the arena lifecycle and use placeholders
to inject real-time session data.

Configure the Events object within each ArenaMaps entry:

Event Stage	When it fires
Started	When the session starts (first wave begins)
Completed	When all waves are cleared successfully
Failed	When the session fails (players eliminated, etc.)
Stopped	When the session is manually stopped

Each command entry supports three fields:

Field	Type	Default	Description
Command	String	—	Command to execute (without leading /)
PerPlayer	Boolean	false	If true, runs once per active online player with {player} substituted
RunAsConsole	Boolean	false	If true, dispatches as console even with PerPlayer: true — required for privileged commands like /give

Dispatch modes​

PerPlayer	RunAsConsole	Behavior
false	—	Single execution as console
true	false	Once per online player, dispatched as that player (respects their permissions)
true	true	Once per online player, dispatched as console (for /give, /op, etc.)

Offline players are silently skipped when PerPlayer: true.

Click to expand...

Available Placeholders​

Placeholder	Description
{player}	Player username — only available with PerPlayer: true
{wave}	Current wave number (1-indexed)
{total_waves}	Total number of waves in the map
{session}	Session ID
{map}	Arena map ID
{map_name}	Arena map display name
{player_count}	Number of active players in the session
{kills}	Total enemies killed in the session
{damage}	Total damage dealt in the session
{duration}	Elapsed session time

JSON Example​

Code:

{
  "ArenaMaps": [
    {
      "Id": "my_arena",
      "Waves": [...],
      "Events": {
        "Started": [
          { "Command": "say Arena {map_name} has started!", "PerPlayer": false }
        ],
        "Completed": [
          { "Command": "say {player} survived all {total_waves} waves!", "PerPlayer": true, "RunAsConsole": false },
          { "Command": "give {player} reward_item 1", "PerPlayer": true, "RunAsConsole": true }
        ],
        "Failed": [
          { "Command": "say Arena failed at wave {wave} of {total_waves}.", "PerPlayer": false }
        ],
        "Stopped": [
          { "Command": "cleanup_arena {session}", "PerPlayer": false }
        ]
      }
    }
  ]
}

Permissions​

Arena Waves Engine uses a permission system to control access to its features. Here are all available permissions:

Permission	Description
miilhozinho.awe	Base permission for Arena Waves Engine
miilhozinho.awe.start	Permission to start arena sessions
miilhozinho.awe.pause	Permission to pause arena sessions
miilhozinho.awe.status	Permission to check arena session status
miilhozinho.awe.*	Wildcard permission for all Arena Waves Engine permissions

ArenaWavesEngine 1.2.0​

For Server Owners & Modders​

• New Damage HUD
  • Added a new HUD that displays damage information to players during arena sessions.
  • Players can now track their performance in real-time during battles.

• New Command Options
  • Added --player optional argument to /awe start command.
  • Admins can now start an arena for another player using /awe start --player <player> or /awe start --waveMapId <id> --player <playerUserName>.
• Arena Results Screen
  • Added a new end-game screen displayed when the arena finishes (Completed, Failed, or Paused).
  • Shows key statistics:
    • MVP - The most valuable player of the session
    • Player Count - Number of players in the session
    • Damage - Damage dealt by each player
    • Kills - Number of kills by each player

• Teleport System
  • Implemented a teleport system for arena players.
  • New configuration options added to ArenaMaps for teleport settings:

  • Field	Type	Default	Description
    Tp.World	String	""	(Optional) World name where players will be teleported when starting the arena. If not set, player stays in current world.
    Tp.Spawn.X/Y/Z	Double	0.0	(Optional) Fixed spawn coordinates when entering the arena. If not set, spawn will be relative to PlayerPosition.
    Tp.PlayerPosition.X/Y/Z	Double	0.0	Fixed player position relative to the target world.
    Tp.PlayerRotation.X/Y/Z	Double	0.0	Fixed player rotation (yaw/pitch/roll) relative to the target world.

  • JSON Example:
  
  
  JSON:

  {
    "ArenaMaps": [
      {
        "Id": "my_arena",
        "Waves":[ (...) ]
        "Tp": {
          "World": "my_world",
          "Spawn": {
            "X": 100.0,
            "Y": 64.0,
            "Z": 200.0
          },
          "PlayerPosition": {
            "X": 100.0,
            "Y": 65.0,
            "Z": 200.0
          },
          "PlayerRotation": {
            "X": 0.0,
            "Y": 180.0,
            "Z": 0.0
          }
        }
      }
    ]
  }

  • Note: Currently in development for instanced worlds (works only for non-instanced worlds in this version).
• JAR Size Optimization
  • The final JAR file has been optimized, resulting in a lighter mod.
  • Improves loading time and reduces memory usage.
• Translation System
  • Implemented an internationalization system.
  • Currently supports native languages: en-US and pt-BR.
  • To add a new language, create the translation file at: mods/YourCustomFolder/Server/Languages/your-language/ArenaWavesEngine.lang
  • Copy the default keys and translate them to your desired language.