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" | "sound" | "none" (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)
config.description	string	❌	HTML description text set on the created world item (default: "")
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.

Opening Styles: "video" plays a fullscreen video overlay with sound; "confetti" triggers a confetti animation with sound; "sound" plays only the sound effect with no visual animation; "none" is completely silent with no sound and no animation.

Example

await MysteryBox.CreateBox({
  config: {
    name: "Treasure Chest",
    rarity: "rare",
    mode: "raffle",
    openingStyle: "sound",
    raffleCount: 1,
    raffleMaximum: 1,
    description: "<p>A chest filled with wonders. Only the worthy may claim its contents.</p>"
  },
  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 }
  ]
});