GachaItem

Overview

Gacha.xml defines gacha item entries: loot box configurations specifying the item that opens the box, mail delivery metadata, and nested reward tables for both fixed (guaranteed) and random (probability-based) drops.

Version Support

Version	Status
v92	Full
v90	-
v86	-

This entity supports an inline workflow:

1. Inline item — define the gacha box’s ItemTemplate entry within a gachaItems.create or gachaItems.upsert operation using the item: block

---

DSL Support

Entity: gachaItems Operations: create, update, delete, upsert Inline blocks:

• item: — creates/updates ItemTemplate.xml and StrSheet_Item.xml with gacha-specific defaults File Organization: Regional variants (Gacha_JP.xml, Gacha_KR.xml, Gacha_NAEU.xml, etc.)

---

Quick Recipes

Create with Inline Item Block (Recommended)

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200001
      title: "Summer Event Box"
      sender: "Event Manager"
      memo: "Thank you for participating!"
      # Inline item block - automatically creates ItemTemplate + StrSheet_Item entries
      item:
        # Tier 3: Required user input (2 fields)
        icon: "Icon_Items_Lootbox_Summer"
        rareGrade: 3  # 0=Common, 1=Uncommon, 2=Rare, 3=Superior, 4=Mythic

        # Tier 2: Optional overrides (defaults applied if omitted)
        tradable: true          # Default: false
        boundType: "Equip"      # Default: "None"
        combatItemType: "LOCKBOX"  # Default: "GACHA"
      fixedRewards:
        - itemTemplateId: 50001
          count: 10

Creates gacha item 200001 with an automatically generated ItemTemplate entry (ID 200001) and StrSheet_Item entry (using the gacha’s title as the string value). The system applies 15 hard defaults (Tier 1) and 13 soft defaults (Tier 2), requiring only 2 user inputs for the item block.

Create (Traditional Approach)

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200001
      title: "Summer Event Box"
      sender: "Event Manager"
      memo: "Thank you for participating!"

Creates a gacha item with mail delivery metadata. The aniTime attribute defaults to 0 (structural default). Use this approach when the ItemTemplate entry already exists or is managed separately.

Create with Fixed Rewards

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200001
      title: "Starter Box"
      sender: "System"
      memo: "Welcome gift"
      fixedRewards:
        - itemTemplateId: 50001
          count: 10
        - itemTemplateId: 50002
          count: 5
          notifyLevel: world

Creates a gacha item with guaranteed reward entries. Each fixed reward specifies an item and quantity.

Create with Random Rewards

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200002
      title: "Lucky Box"
      sender: "Event Manager"
      memo: "Try your luck!"
      randomRewardMax: 3
      randomRewardMin: 1
      randomRewards:
        - rewards:
            - itemTemplateId: 60001
              probability: 0.7
              min: 1
              max: 5
            - itemTemplateId: 60002
              probability: 0.25
              min: 1
              max: 1
            - itemTemplateId: 60003
              probability: 0.05
              min: 1
              max: 1
              notifyLevel: world
              notify: true

Creates a gacha item with a random reward group. The player receives between randomRewardMin and randomRewardMax random draws from the reward table.

Create with Class/Race-Filtered Rewards

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200003
      title: "Class Box"
      sender: "System"
      memo: "Class-specific rewards"
      fixedRewards:
        - itemTemplateId: 70001
          count: 1
          class: WARRIOR
          race: human
          gender: male
      randomRewards:
        - class: ARCHER
          rewards:
            - itemTemplateId: 70010
              probability: 0.5
              min: 1
              max: 1
            - itemTemplateId: 70011
              probability: 0.5
              min: 1
              max: 1
        - class: LANCER
          rewards:
            - itemTemplateId: 70020
              probability: 1.0
              min: 1
              max: 1

Both fixed rewards and random reward groups support class, race, and gender filters. Only matching characters receive these rewards.

Create with equal probability rewards

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200004
      title: "Crystal Box"
      sender: "Crystal System"
      memo: "Equal chance crystal box"
      randomRewards:
        - equalProbability: true
          rewards:
            - itemTemplateId: 8100
            - itemTemplateId: 8114
            - itemTemplateId: 8142

Each reward receives equal probability. Probabilities are truncated to 2 decimal places with the remainder assigned to the first entry (0.34, 0.33, 0.33 in this example). Since min and max default to 1, they can be omitted for single-item rewards.

Create with Both Reward Types

spec:
  version: "1.0"

gachaItems:
  create:
    - itemTemplateId: 200004
      title: "Premium Box"
      sender: "Cash Shop"
      memo: "Premium loot box"
      randomRewardMax: 2
      isLockbox: true
      fixedRewards:
        - itemTemplateId: 50001
          count: 100
      randomRewards:
        - rewards:
            - itemTemplateId: 60001
              probability: 0.8
              min: 1
              max: 3
            - itemTemplateId: 60002
              probability: 0.2
              min: 1
              max: 1

A gacha item can have both fixed and random rewards. Fixed rewards are always granted; random rewards are drawn from the probability table.

Update

spec:
  version: "1.0"

gachaItems:
  update:
    - itemTemplateId: 200001
      changes:
        title: "Updated Title"
        randomRewardMax: 5

Updates scalar attributes on an existing gacha item.

Update Reward Tables

spec:
  version: "1.0"

gachaItems:
  update:
    - itemTemplateId: 200001
      changes:
        fixedRewards:
          - itemTemplateId: 50001
            count: 20
          - itemTemplateId: 50003
            count: 10

Updates the entire fixed reward collection using replace-all semantics.

Replace-all semantics

When you specify fixedRewards or randomRewards in an update, the entire collection is replaced. Any rewards not included in the update will be removed. Always include all rewards you want to preserve.

Delete

spec:
  version: "1.0"

gachaItems:
  delete:
    - 200001
    - 200002

Removes gacha item entries by their itemTemplateId.

Upsert

spec:
  version: "1.0"

gachaItems:
  upsert:
    - itemTemplateId: 200005
      title: "New or Existing Box"
      sender: "System"
      memo: "Upserted"
      fixedRewards:
        - itemTemplateId: 50001
          count: 5

Creates the gacha item if itemTemplateId 200005 doesn’t exist, or leaves the existing entry unchanged if it does.

Upsert with Inline Item

spec:
  version: "1.0"

gachaItems:
  upsert:
    - itemTemplateId: 200006
      title: "Seasonal Loot Box"
      sender: "Event Manager"
      memo: "Limited edition"
      item:
        icon: "Icon_Items_Lootbox_Seasonal"
        rareGrade: 3
        name: "eventItem"
        maxStack: 500
      fixedRewards:
        - itemTemplateId: 50001
          count: 5

Creates a new gacha item and its ItemTemplate/StrSheet_Item entries if ID 200006 doesn’t exist, or replaces them completely if they do exist.

---

Properties Reference

GachaItem (Root Entry)

Property	Type	Since	Required	Description
itemTemplateId	int	v92	Yes	Item template ID that opens this gacha box (primary key)
title	string	v92	No	Mail subject line when rewards are delivered
sender	string	v92	No	Mail sender name
memo	string	v92	No	Mail body text
aniTime	int	v92	No	Animation time in milliseconds. Defaults to 0
randomRewardMax	int	v92	No	Maximum number of random reward draws. Defaults to 1
randomRewardMin	int	v92	No	Minimum number of random reward draws
isLockbox	bool	v92	No	Whether this gacha requires a lockbox key to open
isLimitedGacha	bool	v92	No	Whether this gacha has a limited availability window
limitedGacahId	int	v92	No	ID linking to the limited gacha schedule
item	object	v92	No	Inline item block for auto-creating the gacha box’s ItemTemplate and StrSheet_Item entries. See Item (Inline Block).
fixedRewards	list	v92	No	List of guaranteed reward entries
randomRewards	list	v92	No	List of random reward groups

FixedReward (Nested)

Property	Type	Since	Required	Description
itemTemplateId	int	v92	Yes	Reward item template ID
count	int	v92	Yes	Quantity of the reward item
name	string	v92	No	Display name for the reward
class	CharacterClass	v92	No	Character class filter
race	Race	v92	No	Character race filter
gender	Gender	v92	No	Character gender filter
notifyLevel	NotifyLevel	v92	No	Notification broadcast level

RandomRewardGroup (Nested)

Property	Type	Since	Required	Description
class	CharacterClass	v92	No	Character class filter for the entire group
race	Race	v92	No	Character race filter for the entire group
gender	Gender	v92	No	Character gender filter for the entire group
equalProbability	bool	v92	No	When true, auto-distributes probability equally among entries without explicit probability. Entries with explicit values keep theirs; remaining probability is split among the rest, truncated to 2 decimal places.
rewards	list	v92	Yes	List of reward entries with probabilities

RandomRewardEntry (Nested in RandomRewardGroup)

Property	Type	Since	Required	Description
itemTemplateId	int	v92	Yes	Reward item template ID
probability	decimal	v92	No	Drop probability (0.0 to 1.0). Required unless equalProbability: true is set on the parent group
min	int	v92	No	Minimum drop quantity. Defaults to 1
max	int	v92	No	Maximum drop quantity. Defaults to 1
name	string	v92	No	Display name for the reward
notifyLevel	NotifyLevel	v92	No	Notification broadcast level
notify	bool	v92	No	Whether to send a notification when this reward is drawn

Item (Inline Block)

Defines the gacha box’s ItemTemplate entry inline during create/upsert operations. When specified, automatically creates/updates the corresponding ItemTemplate entry and StrSheet_Item entry with gacha-specific defaults.

Every gacha item has a 1:1 relationship with an Item in ItemTemplate.xml. Analysis of 4,975 gacha items shows that 12 attributes are 100% constant and 13 more have 85-99% dominant values, leaving only 2 fields that truly vary (icon and rareGrade).

Three-Tier Default System:

• Tier 1 (Hard Defaults): 15 attributes with 100% constant values (auto-applied, non-overridable). Includes boundType: None, artisanable: false, dismantlable: false, enchantEnable: false, etc.
• Tier 2 (Soft Defaults): 13 attributes with high-frequency defaults (auto-applied, user-overridable). See properties marked below.
• Tier 3 (Required Input): 2 attributes users must provide.

Tier 3 - Required User Input:

Property	Type	Since	Required	Description
icon	string	v92	Yes	Icon asset path for the gacha box item
rareGrade	int	v92	Yes	Rarity grade: 0=Common, 1=Uncommon, 2=Rare, 3=Superior, 4=Mythic

Tier 2 - Optional Overrides (Defaults Applied if Omitted):

Property	Type	Since	Default	Description
itemId	int	v92	<itemTemplateId>	Item template ID (defaults to gacha’s itemTemplateId if not specified)
name	string	v92	"premium_gacha"	Internal item name identifier
combatItemType	string	v92	"GACHA"	Combat item type. Default is appropriate for gacha items.
combatItemSubType	string	v92	"service"	Combat item subtype
category	string	v92	"service"	Item category
boundType	string	v92	"None"	Item binding type (None, Equip, EquipToItem, Loot)
level	int	v92	1	Required level to use this item
maxStack	int	v92	1000	Maximum stack size
sellPrice	int	v92	0	Sell price at NPC vendors
storeSellable	boolean	v92	false	Whether sellable in player stores
warehouseStorable	boolean	v92	true	Whether storable in personal warehouse
tradable	boolean	v92	false	Whether the item can be traded
destroyable	boolean	v92	true	Whether the item can be destroyed by players
guildWarehouseStorable	boolean	v92	false	Whether storable in guild warehouse

Tier 1 - Auto-Applied Hard Defaults (Non-Overridable):

15 attributes including dismantlable: false, obtainable: true, requiredEquipmentType: "NO_COMBAT", searchable: "True", enchantEnable: false, changeLook: false, extractLook: false, changeColorEnable: false, artisanable: false, relocatable: true, rank: 0, requiredGuildMaster: false, coolTimeGroup: 0, divide: 0, conversion: false. These are applied automatically and cannot be overridden.

---

Enum Types

CharacterClass

Value	Since
ARCHER	v92
ASSASSIN	v92
BERSERKER	v92
ELEMENTALIST	v92
ENGINEER	v92
FIGHTER	v92
GLAIVER	v92
LANCER	v92
PRIEST	v92
SLAYER	v92
SORCERER	v92
SOULLESS	v92
WARRIOR	v92

Race

Value	Since
aman	v92
baraka	v92
castanic	v92
highElf	v92
human	v92
popori	v92

Gender

Value	Since
male	v92
female	v92

NotifyLevel

Value	Since
guard	v92
world	v92

---

XML Structure

Gacha uses 3-level nesting for gacha items:

Gacha
└── GachaItem (itemTemplateId, title, sender, memo, aniTime, randomRewardMax, randomRewardMin, isLockbox, isLimitedGacha, limitedGacahId?)
    ├── FixedReward
    │   └── Reward (itemTemplateId, count, name?, class?, race?, gender?, notifyLevel?)
    └── RandomReward (class?, race?, gender?)
        └── Reward (itemTemplateId, probability, min, max, name?, notifyLevel?, notify?)

Example XML:

<Gacha>
  <GachaItem itemTemplateId="200001" title="Summer Box" sender="System" memo="Welcome" aniTime="0" randomRewardMax="2">
    <FixedReward>
      <Reward itemTemplateId="50001" count="10" />
      <Reward itemTemplateId="50002" count="5" notifyLevel="world" />
    </FixedReward>
    <RandomReward>
      <Reward itemTemplateId="60001" probability="0.7" min="1" max="5" />
      <Reward itemTemplateId="60002" probability="0.3" min="1" max="1" />
    </RandomReward>
  </GachaItem>
</Gacha>

---

Common Pitfalls

• Shared XML File: GachaItem and LockboxKey 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.

• Replace-All for Nested Rewards: The DSL does not support granular add/remove for individual rewards. When updating fixedRewards or randomRewards, the entire collection is replaced. Include all rewards you want to preserve.

• FixedReward vs RandomReward XML Ambiguity: Both fixed and random rewards use the XML element name Reward, but they appear under different parent elements (FixedReward vs RandomReward). The DSL distinguishes them via fixedRewards and randomRewards properties.

• limitedGacahId Typo: The attribute name limitedGacahId preserves the original XML schema typo (missing ‘c’ in “Gacha”). Use this exact spelling in DSL files.

• Inline Item Required Fields: When using the item: block, only 2 fields are required: icon and rareGrade. Omitting either will cause a YamlParseException.MissingField error.

• Inline Item String Value: The StrSheet_Item entry uses the gacha’s title as its string value, falling back to the inline block’s name if title is not specified.

• Three-Tier Default System: When using inline item blocks:

  • Tier 1 (15 fields): Automatically applied, non-overridable (e.g., dismantlable: false, obtainable: true)
  • Tier 2 (13 fields): Automatically applied with defaults, but user-overridable (e.g., combatItemType: "GACHA", name: "premium_gacha")
  • Tier 3 (2 fields): User must provide icon and rareGrade

  Total: 30 item attributes set with only 2 required user inputs (93% reduction in authoring effort).

• ItemId Defaults to itemTemplateId: When using the item: block, if you don’t specify itemId, it automatically defaults to the gacha’s itemTemplateId. Only specify itemId explicitly if the item ID must differ from the gacha ID.

• RareGrade Range: The rareGrade field in inline item blocks must be 0-4 (0=Common, 1=Uncommon, 2=Rare, 3=Superior, 4=Mythic). Other values will cause an InvalidEnum error.

• Smart Defaults: aniTime defaults to 0 on create. randomRewardMax defaults to 1 when not specified. These defaults apply only during create operations, not updates.

• Probability Sum: Random reward probabilities within a group should sum to 1.0. The game client selects rewards based on cumulative probability.

• Enum Casing: CharacterClass values are uppercase (WARRIOR, ARCHER). Race and Gender values are camelCase (highElf, male). NotifyLevel values are lowercase (guard, world).