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:
| Body | Model | Default open animation |
|---|---|---|
scorchedwood | chest | open-lid |
leather | satchel | open-shake |
ashdaub | urn | open-lid |
bluedaub | urn | open-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, includingentries;lootModeandaccessModeare read as numbers:0/1and0/1/2in enum order).attributesByTypecan override per variant, as the shipped blocktype does foropenAnimation. - After that the stored copy wins. Server admins edit it in-world: sneak + right-click on the chest with the
controlserverprivilege 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
}| Field | Default | Description |
|---|---|---|
entries[] | empty | Loot 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 |
lootMode | Direct | Direct: 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 |
itemLimit | 0 | How many distinct entries are rolled per open (weighted, without repeats). 0 = all entries |
oneTime | false | Each player (or the chest, in Global) can open it only once. Ignored in PerPlayerOnceGlobalCooldown (that mode is always once per player) |
cooldownSeconds | 0 | Cooldown after an open, in real seconds |
accessMode | PerPlayer | PerPlayer: 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 |
keyItemCode | none | Short code of a key item (domain:path, compared case-insensitively). Only the hotbar is searched |
consumeKeyItem | true | Take one key item on open |
achievementTriggerCode | none | If set, the framework event lootchest is published for the player after the loot is granted |
achievementDirectUnlock | none | Achievement id unlocked for the player after the loot is granted |
effect.sound | game:sounds/block/chestopen | Played at the chest when the effect starts — only if no openLoopSound is set |
effect.openLoopSound | none | Looping sound while the opening effect runs; it replaces effect.sound |
effect.openLoopSoundVolume | 1 | Volume of the loop |
effect.finishSound | game:sounds/effect/rewardsound | Played when the loot is handed out |
effect.particleType | glow | glow, smoke, sparks or portal (client particle style) |
effect.particleColor | [255,200,100,255] | Four integers (needs 4 values in block attributes) |
effect.durationSeconds | 10 | Length of the opening effect; the loot is granted when it ends. 0 = loot is granted immediately with no effect or animation |
openAnimation | open-lid | Shape animation code |
openAnimationSpeed | 1 | Animation 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
oneTimeis 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.PerPlayerOnceGlobalCooldownsuits contested world chests: everybody gets one loot, but not in the same minute.itemLimit: 1turns the table into a "pick one prize" roll.- Pair
keyItemCodewith a quest reward item to gate access.