API

Developers

You can create a Mystery Box programmatically using a macro or script, without opening any UI.

await MysteryBox.CreateBox({ config, items })

Parameters

Parameter	Type	Required	Description
config.name	string	✅	The name of the Mystery Box
config.rarity	string	❌	"common" | "uncommon" | "rare" | "legendary" (default: "common")
config.mode	string	❌	"percentage" | "raffle" (default: "percentage")
config.openingStyle	string	❌	"video" | "confetti" (default: "video")
config.raffleCount	number	❌	How many items are drawn in raffle mode (default: 1)
config.raffleMaximum	number	❌	Maximum number of items that can be drawn (default: 1)
items	array	✅	Array of { uuid, chance } objects. chance defaults to 100 if omitted

Note: This function is GM-only and must be called with await. It creates the box configuration and a matching world Item automatically.

Example

await MysteryBox.CreateBox({
  config: {
    name: "Treasure Chest",
    rarity: "rare",
    mode: "percentage",
    openingStyle: "video",
    raffleCount: 1,
    raffleMaximum: 1
  },
  items: [
    { uuid: "Compendium.daggerheart.loot.Item.QGYPNBIufpBguwjC", chance: 70 },
    { uuid: "Compendium.daggerheart.loot.Item.v4PIoCCEjeE3acys",  chance: 100 },
    { uuid: "Compendium.daggerheart.loot.Item.gsUDP90d4SRtLEUn",   chance: 100 }
  ]
});