TIDE - Ticrom's Integrated Dungeon Engine

A room-based dungeon engine plugin for Hytale servers. Supports solo and party play with configurable rooms, enemies, boss fights, economy integration, leaderboards, and a real-time HUD.

Dependencies

Plugin	Required	Purpose
HytaleServer	Yes	Core server API
HyUI	Yes	HUD and interactive page rendering
RPGLeveling	No	Enemy level assignment (enemies spawn at default level without it)
CivicCoreEconomy	No	Economy (entry fees, rewards)
PartyPro	No	Party system integration
MultipleHUD	No	Multiple HUD support

Building

./gradlew build

The output JAR will be in build/libs/TDE-3.0.0.jar.

Installation

1. Place TDE-3.0.0.jar in your server's plugin directory
2. Ensure all required dependency plugins are installed
3. Start the server - a default config will be generated
4. Use the admin commands below to set up your dungeons

Dungeon Setup Guide

Step 1: Define a Dungeon in Config

The plugin generates a default dungeon (sewers) on first run. To create your own, edit the config and add a new entry to the Dungeons array:

{
  "Id": "my_dungeon",
  "Enabled": true,
  "DisplayName": "The Dark Catacombs",
  "Description": "Ancient catacombs filled with undead",
  "EntryFee": 100.0,
  "CompletionReward": 500.0,
  "CooldownSeconds": 300,
  "PartyAllowed": true,
  "RewardMode": "ALL",
  "PartyDeathPolicy": "FAIL_ALL",
  "Rooms": []
}

Step 2: Set Entrance and Exit Locations

Stand at the desired entrance location in-game and run:

/dungeonadmin --action=setentrance --dungeon=my_dungeon

Stand at the desired exit location and run:

/dungeonadmin --action=setexit --dungeon=my_dungeon

Both commands capture your current position and world.

Step 3: Define Rooms in Config

Add rooms to the dungeon's Rooms array. Each room needs an ID, display name, order, and enemy definitions:

{
  "Id": "entrance_hall",
  "DisplayName": "Entrance Hall",
  "Order": 1,
  "BossRoom": false,
  "Required": true,
  "Enemies": [
    { "EnemyType": "Skeleton", "Count": 5, "Scale": 1.0, "RpgLevel": 0 }
  ]
}

The last room (or any room marked BossRoom: true) triggers dungeon completion when cleared.

Step 4: Set Room Bounds

Room bounds define the AABB (axis-aligned bounding box) that triggers combat when a player enters. Use the two-point selection tool:

1. Stand at one corner of the room and run:

   /dungeonadmin --action=setroom --dungeon=my_dungeon --room=entrance_hall
   

2. Stand at the opposite corner and run the same command again.

The plugin will compute the bounding box and set the enemy spawn center to the room's center.

Step 5: Reload and Test

/dungeonadmin --action=reload
/dungeonadmin --action=info --dungeon=my_dungeon

Verify all rooms have bounds set, then test with:

/dungeonadmin --action=start --dungeon=my_dungeon --player=YourName

Player Commands

/dungeon

Usage	Description
/dungeon	Show usage and list available dungeons
/dungeon --action=start --id=<dungeonId>	Start a dungeon (solo or party)
/dungeon --action=leaderboard --id=<dungeonId>	View the dungeon leaderboard GUI
/dungeon --action=accept	Accept a party dungeon invitation
/dungeon --action=decline	Decline a party dungeon invitation

When starting a dungeon while in a party, a ready check is sent to all online party members with an interactive Accept/Decline GUI. The dungeon begins once all members respond or the timeout expires.

Admin Commands

/dungeonadmin

Requires the dungeonadmin permission.

Usage	Description
/dungeonadmin --action=start --dungeon=ID --player=NAME	Force-start a dungeon for a player
/dungeonadmin --action=stop --player=NAME	Stop a player's active session
/dungeonadmin --action=reload	Reload the configuration file
/dungeonadmin --action=status	Show plugin status (active sessions, economy, debug)
/dungeonadmin --action=list	List all configured dungeons
/dungeonadmin --action=info --dungeon=ID	Show detailed dungeon info (rooms, bounds, settings)
/dungeonadmin --action=setentrance --dungeon=ID	Set dungeon entrance to your position
/dungeonadmin --action=setexit --dungeon=ID	Set dungeon exit to your position
/dungeonadmin --action=setroom --dungeon=ID --room=ID	Set room bounds (two-point selection)
/dungeonadmin --action=resetcooldown --player=NAME [--dungeon=ID]	Reset a player's cooldown
/dungeonadmin --action=resetdaily [--player=NAME]	Reset daily session limits
/dungeonadmin --action=leaderboard --dungeon=ID	View the dungeon leaderboard
/dungeonadmin --action=debug	Show debug mode status

Configuration Reference

Global Settings

Key	Default	Description
PluginEnabled	true	Enable/disable the plugin
DebugMode	false	Verbose logging for troubleshooting

Economy & Rewards

Key	Default	Description
EconomyEnabled	true	Enable economy integration (requires CivicCoreEconomy)
DefaultEntryFee	100.0	Default entry fee (overridable per dungeon)
DefaultCompletionReward	500.0	Default completion reward (overridable per dungeon)

Cooldowns & Limits

Key	Default	Description
DefaultCooldownSeconds	300	Cooldown between dungeon runs (5 minutes)
MaxSessionsPerDay	5	Maximum dungeon runs per player per day
MaxConcurrentSessions	1	Maximum concurrent sessions server-wide

Teleportation

Key	Default	Description
TeleportEnabled	true	Enable teleportation to entrance/exit
DungeonWorld	"dungeons"	World name where dungeons are located
ReturnWorld	"world"	Fallback world for exit teleportation
ReturnX/Y/Z	0/64/0	Fallback exit coordinates

Party Settings

Key	Default	Description
PartyEnabled	true	Enable party dungeon support (requires PartyPro)
PartyReadyCheckSeconds	20	Timeout for party invitation responses
MaxPartySize	4	Maximum party members allowed in a dungeon

HUD & Leaderboard

Key	Default	Description
HudEnabled	true	Enable the in-game dungeon HUD
LeaderboardEnabled	true	Enable leaderboard recording
LeaderboardSize	10	Number of entries to keep per dungeon

Messages

All player-facing messages are customizable. Available placeholders vary by message:

Key	Default	Placeholders
MessagePrefix	[Dungeon]	-
MessageDungeonStarted	Entering the dungeon... Good luck!	-
MessageRoomTriggered	Enemies incoming! Clear the room!	-
MessageRoomCleared	Room cleared!	-
MessageBossDefeated	BOSS DEFEATED!	-
MessageDungeonCompleted	CONGRATULATIONS! You completed the dungeon!	-
MessageDungeonFailed	Dungeon failed. You cleared %rooms% room(s).	%rooms%
MessageOnCooldown	You must wait %time% before trying again!	%time%
MessageInsufficientFunds	You need %amount% to enter this dungeon!	%amount%
MessageRewardReceived	+%amount% (Reward)	%amount%
MessageDailyLimitReached	You've reached your daily limit of %limit% sessions!	%limit%
MessagePartyInviteReceived	%player% wants to start '%dungeon%'...	%player%, %dungeon%
MessagePartyMemberLeft	%player% has left the dungeon.	%player%

Dungeon Configuration

Per-Dungeon Settings

Key	Description
Id	Unique identifier (used in commands)
Enabled	Whether the dungeon is available to players
DisplayName	Name shown in HUD and messages
Description	Flavor text
EntryFee	Cost to enter (-1 to use global default)
CompletionReward	Reward for completing (-1 to use global default)
CooldownSeconds	Cooldown after completion (-1 to use global default)
PartyAllowed	Whether parties can enter this dungeon
RewardMode	How party rewards are distributed (see below)
PartyDeathPolicy	What happens when a party member dies (see below)
CompletionCommands	Console commands to run on completion
FailureCommands	Console commands to run on failure

Completion/Failure Command Placeholders: %player%, %dungeon%, %rooms%, %kills%

Reward Modes

Mode	Description
ALL	Every party member gets the full reward
DIVIDE	Reward is split equally among active members
LEADER	Only the party leader receives the reward
STARTER	Only the player who initiated the dungeon receives the reward
RANDOM	One random party member receives the reward

Party Death Policies

Policy	Description
FAIL_ALL	If any member dies, the entire dungeon fails for everyone
REMOVE_INDIVIDUAL	Only the dead player is removed; the party continues

Room Configuration

Key	Description
Id	Unique identifier within the dungeon
DisplayName	Name shown in HUD and messages
Order	Room sequence number (determines progression order)
BossRoom	If true, clearing this room completes the dungeon
Required	If true, this room must be cleared for completion
MinX/Y/Z	Bounding box minimum corner (set via /dungeonadmin setroom)
MaxX/Y/Z	Bounding box maximum corner
SpawnCenterX/Y/Z	Where enemies spawn (auto-calculated by setroom)

Enemy Configuration

Key	Description
EnemyType	NPC role name (e.g., Skeleton, Skeleton_Burnt_Archer)
Count	Number of this enemy to spawn
Scale	Size multiplier (1.0 = normal, 2.0 = double size for bosses)
RpgLevel	RPG level assignment (0 = default)

How It Works

1. Player runs /dungeon --action=start --id=sewers
2. Entry fee is charged, player is teleported to the dungeon entrance
3. The 1-second tick system monitors player position
4. When a player enters an uncleared room's bounding box, enemies spawn
5. The HUD updates in real-time showing progress, combat info, and stats
6. Clearing all enemies in a room marks it as cleared
7. Clearing the boss room (or all required rooms) completes the dungeon
8. Rewards are given, the leaderboard is updated, and the player is teleported to the exit
9. If the player dies, the dungeon fails with partial rewards based on rooms cleared

Architecture

TDEPlugin                    # Plugin entry point, service wiring
  command/
    DungeonCommand           # Player commands (/dungeon)
    DungeonAdminCommand      # Admin commands (/dungeonadmin)
  config/
    TDEConfig                # Global configuration
    DungeonDefinition        # Per-dungeon settings
    RoomDefinition           # Room bounds, enemies, boss flag
    EnemySpawnDefinition     # Enemy type, count, scale, level
    RewardMode               # Party reward distribution modes
    PartyDeathPolicy         # Party death handling
  model/
    DungeonSession           # Active session state and tracking
  system/
    DungeonSystem            # Core game loop (1s tick)
    SpawnSystem              # NPC spawning and death tracking
    DamageTrackingSystem     # Damage attribution
    PlayerTrackingSystem     # Player state monitoring
  service/
    SessionService           # Session lifecycle management
    RewardService            # Economy rewards and fees
    CooldownService          # Per-dungeon cooldowns
    TeleportService          # World teleportation
    EconomyService           # CivicCoreEconomy integration
    LeaderboardService       # Top scores per dungeon
  party/
    PartyAdapter             # Party plugin abstraction
    PartyProBridge           # PartyPro integration
    PartyAdapterFactory      # Plugin detection
    PartyDungeonEventListener # Party event hooks
    ReadyCheck               # Invitation state management
  event/
    DungeonEventHandler      # Disconnect handling
  ui/
    HudManager               # Real-time dungeon HUD
    InviteHudManager         # Interactive party invite pages

License

Proprietary - Hytale Together