Systems

Loot Chests

lootchest is a framework blocktype (BlockLootChest + the LootChest block entity): an animated cache that, after a short opening effect, rolls a weighted loot table for the player who opened it. Access can be per player or shared, gated by a key item, limited to one open and/or put on cooldown.


Blocktype

The blocktype ships with the framework (assets/alegacyvsquest/blocktypes/lootchest.json, creative tab alegacyvsquest-actionitems, item lootchest-*-north). The variant group body selects the model:

BodyModelDefault open animation
scorchedwoodchestopen-lid
leathersatchelopen-shake
ashdauburnopen-lid
bluedauburnopen-spin

The three animations open-lid, open-shake and open-spin exist in all three shapes. Any other body state falls back to the chest shape and the block-level default animation open-lid.

Packs add bodies (for example paintings in albase) with a JSON patch on the body group:

{
  "op": "add",
  "path": "/variantgroups/0/states/-",
  "value": "painting-stariy",
  "file": "alegacyvsquest:blocktypes/lootchest.json"
}

Where the loot config comes from

The block entity keeps its own copy of the config, saved with the block:

  • When a chest is placed the first time, the config is initialised from the block attributes (the same field names as below, including entries; lootMode and accessMode are read as numbers: 0/1 and 0/1/2 in enum order). attributesByType can override per variant, as the shipped blocktype does for openAnimation.
  • After that the stored copy wins. Server admins edit it in-world: sneak + right-click on the chest with the controlserver privilege opens the config dialog (LootChestConfigGui); saving needs the same privilege.

The shipped blocktype sets only the effect defaults (openLoopSound = alegacyvsquest:sounds/lootchest_open, finishSound = alegacyvsquest:sounds/lootchest_get, particleType = glow) and the animation. It has no loot entries: a chest without entries answers "The cache is empty".

Config fields

{
  "entries": [
    { "itemCode": "game:gear-rusty", "minStack": 1, "maxStack": 3, "weight": 50 },
    { "itemCode": "mypack:relic", "minStack": 1, "maxStack": 1, "weight": 5 }
  ],
  "lootMode": "Direct",
  "itemLimit": 2,
  "oneTime": false,
  "cooldownSeconds": 86400,
  "accessMode": "PerPlayer",
  "keyItemCode": "mypack:crypt-key",
  "consumeKeyItem": true,
  "achievementTriggerCode": "mypack:crypt-looted",
  "achievementDirectUnlock": "mypack:crypt-raider",
  "effect": {
    "sound": "game:sounds/block/chestopen",
    "openLoopSound": "mypack:sounds/chest-hum",
    "openLoopSoundVolume": 1.0,
    "finishSound": "game:sounds/effect/rewardsound",
    "particleType": "glow",
    "particleColor": [255, 200, 100, 255],
    "durationSeconds": 10
  },
  "openAnimation": "open-lid",
  "openAnimationSpeed": 1.0
}
FieldDefaultDescription
entries[]emptyLoot table. Each entry: itemCode (item or block code; unknown codes are silently skipped), minStack (1), maxStack (1), weight (1). Stack size is a random value from minStack to maxStack; negative weights count as 0
lootModeDirectDirect: items go to the player's inventory, whatever does not fit is dropped at the chest. Chest: items spawn as item entities above the chest
itemLimit0How many distinct entries are rolled per open (weighted, without repeats). 0 = all entries
oneTimefalseEach player (or the chest, in Global) can open it only once. Ignored in PerPlayerOnceGlobalCooldown (that mode is always once per player)
cooldownSeconds0Cooldown after an open, in real seconds
accessModePerPlayerPerPlayer: opened/cooldown tracked per player. Global: one opened flag and one cooldown for everybody. PerPlayerOnceGlobalCooldown: each player can open only once, but a shared cooldown applies between any two opens
keyItemCodenoneShort code of a key item (domain:path, compared case-insensitively). Only the hotbar is searched
consumeKeyItemtrueTake one key item on open
achievementTriggerCodenoneIf set, the framework event lootchest is published for the player after the loot is granted
achievementDirectUnlocknoneAchievement id unlocked for the player after the loot is granted
effect.soundgame:sounds/block/chestopenPlayed at the chest when the effect starts — only if no openLoopSound is set
effect.openLoopSoundnoneLooping sound while the opening effect runs; it replaces effect.sound
effect.openLoopSoundVolume1Volume of the loop
effect.finishSoundgame:sounds/effect/rewardsoundPlayed when the loot is handed out
effect.particleTypeglowglow, smoke, sparks or portal (client particle style)
effect.particleColor[255,200,100,255]Four integers (needs 4 values in block attributes)
effect.durationSeconds10Length of the opening effect; the loot is granted when it ends. 0 = loot is granted immediately with no effect or animation
openAnimationopen-lidShape animation code
openAnimationSpeed1Animation speed

Opening sequence

  • Server checks access (opened flag / cooldown) and the key; a failure sends a chat notice (already opened, cooldown with remaining seconds, "You need a key item").
  • The key is consumed (if set) and the open is registered immediately — the cooldown starts and oneTime is spent now, even if the player walks away during the effect.
  • The opening player's client plays the sound, animation and particles for durationSeconds (the effect packet is sent to the opener only).
  • After that the finish sound plays and the loot is granted to the player who opened it, followed by the achievement hooks.

Tips

  • PerPlayer + cooldownSeconds: 86400 = a daily chest for every player.
  • PerPlayerOnceGlobalCooldown suits contested world chests: everybody gets one loot, but not in the same minute.
  • itemLimit: 1 turns the table into a "pick one prize" roll.
  • Pair keyItemCode with a quest reward item to gate access.

Press ESC to close