LockboxKey

Overview

Gacha.xml defines lockbox key entries: mappings between key items and the gacha lockbox items they can open, with a configurable open multiplier.

Version Support

Version	Status
v92	Full
v90	-
v86	-

---

DSL Support

Entity: lockboxKeys Operations: create, update, delete, upsert File Organization: Regional variants (Gacha_JP.xml, Gacha_KR.xml, Gacha_NAEU.xml, etc.)

---

Quick Recipes

Create

spec:
  version: "1.0"

lockboxKeys:
  create:
    - itemTemplateId: 300001
      lockboxTemplateId: "200001"

Creates a lockbox key that opens gacha item 200001. The multiple attribute defaults to 1.

Create with Custom Multiplier

spec:
  version: "1.0"

lockboxKeys:
  create:
    - itemTemplateId: 300002
      lockboxTemplateId: "200001"
      multiple: 10

Creates a lockbox key that opens gacha item 200001 ten times per use.

Update

spec:
  version: "1.0"

lockboxKeys:
  update:
    - itemTemplateId: 300001
      changes:
        lockboxTemplateId: "200002"

Changes which gacha item this key opens.

Update Multiplier

spec:
  version: "1.0"

lockboxKeys:
  update:
    - itemTemplateId: 300001
      changes:
        multiple: 5

Changes the open multiplier for an existing key.

Delete

spec:
  version: "1.0"

lockboxKeys:
  delete:
    - 300001
    - 300002

Removes lockbox key entries by their itemTemplateId.

Upsert

spec:
  version: "1.0"

lockboxKeys:
  upsert:
    - itemTemplateId: 300003
      lockboxTemplateId: "200001"
      multiple: 1

Creates the lockbox key if itemTemplateId 300003 doesn’t exist, or leaves the existing entry unchanged if it does.

---

Properties Reference

LockboxKey

Property	Type	Since	Required	Description
itemTemplateId	int	v92	Yes	Key item template ID (primary key)
lockboxTemplateId	string	v92	Yes	Item template ID of the gacha lockbox this key opens
multiple	int	v92	No	Number of times the lockbox is opened per key use. Defaults to 1

---

XML Structure

LockboxKey uses flat nesting within the shared Gacha root:

Gacha
└── LockboxKey (itemTemplateId, lockboxTemplateId, multiple)

Example XML:

<Gacha>
  <LockboxKey itemTemplateId="300001" lockboxTemplateId="200001" multiple="1" />
  <LockboxKey itemTemplateId="300002" lockboxTemplateId="200001" multiple="10" />
</Gacha>

---

Common Pitfalls

• Shared XML File: LockboxKey and GachaItem share the same Gacha.xml file. Both entity types coexist as sibling elements under the <Gacha> root.

• Regional Variants: Gacha uses regional file variants (Gacha_JP.xml, Gacha_KR.xml, Gacha_NAEU.xml, etc.). Ensure you’re modifying the correct regional file for your target deployment.

• lockboxTemplateId Is a String: Unlike most ID fields, lockboxTemplateId is a string type in the XML schema. Always quote the value in YAML.

• Default Multiple: The multiple attribute defaults to 1 on create. This means one key opens the lockbox once. Only specify multiple when a different value is needed.

• Cross-Reference to GachaItem: The lockboxTemplateId should reference a valid GachaItem’s itemTemplateId that has isLockbox: true. The DSL does not validate this cross-reference at compile time.