Chest Instance Engine v1.0.0-rc0.0.1

Hytale Chest Instance Engine (CIE)​

Dynamic instanced reward chest system for Hytale servers. Designed for modular integration with ArenaWavesEngine and other gameplay systems.

Click to expand...

Overview​

• Clean architecture
• High server-side performance
• Gson/ConfigHandle-based configuration
• Instanced chest logic (per-player or shared)
• Modular reward system

Dependencies​

Core Features​

Chest Configuration System​

Supports multiple chest definitions Fully driven by Gson/ConfigHandle configuration Designed for extensibility Supports multiple chest definitions Fully driven by Gson/ConfigHandle configuration Designed for extensibility

Chest Array Structure​

• id → Unique identifier
• name → Display name for the chest
• description → Description for the chest
• mode → PER_PLAYER | SHARED
• expiresAt → Auto-despawn date-time (ISO-8601 UTC, e.g. "2026-12-31T23:59:59Z")
• position → Position where the chest should be spawned (x, y, z)
• rotation → Rotation of the chest in the world (x, y, z)
• world → Optional world name where the chest should be spawned
• chestItemId → Hytale item ID for the chest block model (default: Furniture_Dungeon_Chest_Legendary_Large)
• usePlayerWhitelist → When true, only players assigned via assign-profile can open the chest
• lootPools → List of named reward pools (e.g. DEFAULT, TOP_10, TOP_1)

Loot Pool Configuration​

{
  "id": "auto-uuid",
  "poolName": "DEFAULT",
  "items": [
    {
      "itemId": "Gold_Coin",
      "minAmount": 200,
      "maxAmount": 350,
      "chance": 100
    }
  ]
}

• itemId → Hytale item identifier
• minAmount → Minimum quantity (>= 1)
• maxAmount → Maximum quantity (>= minAmount)
• chance → Probability percentage (0–100) that this item will be generated

Config Example​

{
  "chests": [
    {
      "Id": "awe_boss_reward_chest",
      "Name": "AWE Boss Reward Chest",
      "Description": "Baú único no mundo com loot individual por participante",
      "Position": { "x": 120.0, "y": 64.0, "z": -45.0 },
      "Rotation": { "x": 0.0, "y": 180.0, "z": 0.0 },
      "Mode": "PER_PLAYER",
      "World": "Overworld",
      "ExpiresAt": "2026-12-31T23:59:59Z",
      "ChestItemId": "Furniture_Dungeon_Chest_Legendary_Large",
      "UsePlayerWhitelist": true,
      "LootPools": [
        {
          "PoolName": "DEFAULT",
          "Items": [
            { "ItemId": "Gold_Coin", "MinAmount": 200, "MaxAmount": 350, "Chance": 100 }
          ]
        },
        {
          "PoolName": "TOP_10",
          "Items": [
            { "ItemId": "Gold_Coin", "MinAmount": 350, "MaxAmount": 600, "Chance": 100 }
          ]
        },
        {
          "PoolName": "TOP_1",
          "Items": [
            { "ItemId": "Gold_Coin", "MinAmount": 800, "MaxAmount": 1200, "Chance": 100 }
          ]
        }
      ]
    }
  ]
}

Note: The config uses UPPER_CAMEL_CASE field names (Gson FieldNamingPolicy.UPPER_CAMEL_CASE).

Click to expand...

Instance Modes​

PER_PLAYER Mode​

• Each player gets their own unique loot when they open the chest
• Items are not shared between players
• Player access is controlled by whitelist (usePlayerWhitelist)

SHARED Mode​

• All players share the same chest instance
• Items are consumed by the first player to open it

Expiration System​

• Instances automatically expire at expiresAt (ISO-8601 timestamp)
• Expiration is scheduled on spawn and rescheduled on plugin restart
• Background daemon runs every 5 minutes to clean up stale instances

Player Whitelist & Loot Profiles​

When usePlayerWhitelist = true: Only players explicitly assigned via assign-profile can open the chest Each player is assigned a named loot pool profile (e.g. TOP_1, TOP_10, DEFAULT) Profile also carries a percentage multiplier (lootPercentage) used in item quantity generation When usePlayerWhitelist = false: Any player can open the chest Loot pool is selected randomly if no profile is assigned

Integration With ArenaWavesEngine​

1. Arena emits completion event
2. /cie spawn is called with trigger + percentage
3. /cie assign-profile is called per player with their profile
4. Instanced chest is spawned in the world
5. Each player opens and receives their own loot
6. Chest expires automatically

Recommended AWE integration flow​

AWE placeholders commonly used with CIE commands​

Commands​

Note: If a chest instance already exists at the target position, spawn is blocked with an error message.

Click to expand...

Note: assign-profile retries up to 10 times with 200ms delay to handle race conditions when called immediately after spawn.

Click to expand...

Permissions​

🖥 Admin UI​

Left Panel​

• Search box to filter definitions by name
• Scrollable list of all chest definitions
• "Add" button to create a new definition (requires EDIT permission)
• "Delete" button per definition row

Right Panel — 3 Tabs​

General Tab​

Loot Pools Tab​

Instances Tab​

Target Audience​

• Hytale mod developers
• Server owners with custom gameplay systems
• Developers using ArenaWavesEngine
• Modular gameplay system creators

Bundle Strategy​

• Complete arena gameplay loop
• Performance-based rewards
• Instanced chest system
• Fully configurable loot profiles
• High replayability system