> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borntocraftstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Loot Chest Trigger

> Action entry that manually activates a loot chest on demand — for secret rewards, boss drops, and conditional chests.

Action entry that manually triggers a specific loot chest at runtime. Used in combination with `DungeonLootChestEntry` when `manualMode: true`.

## Trigger Modes

| Mode          | Behavior                                                                     |
| ------------- | ---------------------------------------------------------------------------- |
| `ONCE`        | Chest spawns once per session. Subsequent triggers are ignored (default).    |
| `REPEATABLE`  | Chest can be triggered multiple times.                                       |
| `CONDITIONAL` | Chest only triggers if `triggerCriteria` are met (evaluated per activation). |

## Configuration

<ResponseField name="loot_chest_trigger" type="Map" required>
  Configuration for the loot chest trigger action.

  <Expandable title="Properties">
    <ResponseField name="chestEntry" type="Ref<DungeonLootChestEntry>">
      The loot chest entry to activate. Must have `manualMode: true`.
    </ResponseField>

    <ResponseField name="triggerMode" type="Enum" default="ONCE">
      `ONCE`, `REPEATABLE`, or `CONDITIONAL`.
    </ResponseField>

    <ResponseField name="triggerCriteria" type="List<Criteria>">
      Criteria checked when `triggerMode` is `CONDITIONAL`. All must pass.
    </ResponseField>

    <ResponseField name="triggerSound" type="String">
      Sound played when the chest is triggered (e.g., `ENTITY_ENDERMAN_TELEPORT`). Empty = no sound.
    </ResponseField>

    <ResponseField name="triggerDelay" type="Int" default="0">
      Delay in ticks before the chest appears after triggering.
    </ResponseField>

    <ResponseField name="triggerParticle" type="String">
      Particle effect shown at the chest location when triggered (e.g., `PORTAL`). Empty = none.
    </ResponseField>

    <ResponseField name="broadcastMessage" type="String">
      Message broadcast to all online players when this chest is triggered. Supports `{player}` and `{chest}`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

```yaml theme={null}
# The chest definition (manualMode = true)
dungeon_loot_chest:
  id: "secret_treasure"
  dungeonInstance: "ancient_temple"
  location: {x: 50, y: 70, z: 30, world: "dungeon_temple"}
  manualMode: true
  lootTable:
    - item: NETHERITE_INGOT
      dropChance: 50

# The trigger — fired when boss dies (via onEnd/onEnter triggers)
action:
  type: loot_chest_trigger
  id: "boss_treasure_trigger"
  chestEntry: "secret_treasure"
  triggerMode: ONCE
  triggerSound: "ENTITY_ENDERMAN_TELEPORT"
  triggerParticle: "PORTAL"
  broadcastMessage: "<gold>{player} unlocked the secret treasure!"
```