Equipment computation

DataSheetLang can derive equipment entries from item definitions and optionally compute equipment stats in a deterministic way.

This page focuses on what you need to use the feature safely. The exact balancing weights used by our project are intentionally not published.

If you only need commands, see CLI.
For presets, see Presets.

---

What equipment computation does

When enabled, the tool can:

• derive missing equipment metadata from item data (equipment ID, part, type, etc.)
• compute a set of stats based on level, grade, power tier, and optional rank boosts
• allow explicit overrides for any derived or computed values

This is useful for large-scale tuning: instead of hand-editing thousands of rows, you adjust tiers/formulas and recompute consistently.

---

1) Inline equipment block (most common)

Attach an equipment block to an item create operation:

items:
  create:
    - id: 99001
      name: "Dreadspire Axe"
      level: 65
      rareGrade: "Unique"
      combatItemType: "EQUIP_WEAPON"
      combatItemSubType: "AXE"

      equipment:
        computed: true

computed: true enables stat computation with default inputs.

---

2) Equipment block structure

equipment:
  preset: preset_name        # Optional: equipment preset reference
  computed: true             # Optional: shorthand for compute: {}

  compute:                   # Optional: computation parameters
    formula: "standard"      # Formula name (default: "standard")
    powerTier: 5             # Power tier 1–16 (default: derived)
    rank: 0                  # Rank boost (default: 0)

  override:                  # Optional: explicit value overrides (always win)
    equipmentId: 900099001
    part: "Weapon"
    type: "AXE"

    # Computed stats (examples; exact set depends on category)
    maxAtk: 600
    impact: 100

    # Pass-through values (examples)
    countOfSlot: 4
    balance: 50
    atkRate: 1.0
    defRate: 1.0
    impactRate: 1.0
    balanceRate: 1.0

Shorthand

computed: true is equivalent to:

compute: {}

(with defaults).

---

3) Value derivation (metadata)

When computation is enabled, these values are derived automatically:

Value	Derived from	Override
equipmentId	900000000 + itemId	override.equipmentId
part	item combatItemSubType mapping	override.part
type	item combatItemSubType mapping	override.type
level	item level	(not overrideable)
grade	item rareGrade	(not overrideable)

Part / type mapping

The item combatItemSubType determines classification:

Weapons

SubType	Part	Type
DUAL	Weapon	DUAL
LANCE	Weapon	LANCE
TWOHAND	Weapon	TWOHAND
AXE	Weapon	AXE
CIRCLE	Weapon	CIRCLE
BOW	Weapon	BOW
STAFF	Weapon	STAFF
ROD	Weapon	ROD
CHAIN	Weapon	CHAIN
BLASTER	Weapon	BLASTER
GAUNTLET	Weapon	GAUNTLET
SHURIKEN	Weapon	SHURIKEN
GLAIVE	Weapon	GLAIVE

Armor

SubType	Part	Type
BODY_ARMOR, BODY_MAIL	BODY	MAIL
BODY_LEATHER	BODY	LEATHER
BODY_ROBE	BODY	ROBE
HAND_ARMOR, HAND_MAIL	HAND	MAIL
HAND_LEATHER	HAND	LEATHER
HAND_ROBE	HAND	ROBE
FEET_ARMOR, FEET_MAIL	FEET	MAIL
FEET_LEATHER	FEET	LEATHER
FEET_ROBE	FEET	ROBE

Accessories

SubType	Part	Type
RING	FINGER	RING
NECKLACE	NECK	NECKLACE
EARRING	EAR	EARRING
BROOCH	BROOCH	BROOCH
BELT	BELT	BELT
UNDERWEAR	UNDERWEAR	UNDERWEAR
ACCESSORYHAIR	ACCESSORYHAIR	ACCESSORYHAIR
ACCESSORYFACE	ACCESSORYFACE	ACCESSORYFACE
RELIC	RELIC	RELIC
HOLYTHING	HOLYTHING	HOLYTHING

---

4) Stat formulas (how to set up)

Stat computation uses a named formula (default: "standard") with a project-specific configuration file.

What you need to know

• Commands that compute stats require a --formulas <file> input.
• The file format is stable, but the exact weights are project-controlled.
• If you are not part of the balancing team, you typically receive this file (you don’t invent values).

File format: stat-formulas.yaml

Create a stat-formulas.yaml file with the required structure:

stat-formulas.yaml

sigmoid:
  maximumValue: <number>
  growthRate: <number>
  growthSteepness: <number>

modifiers:
  statBoostByGrade: <number>
  statBoostByRank: <number>
  statBoostByPowerTier: <number>

Notes:

• All values are numeric.
• Keep this file under version control (it defines your balancing rules).
• If your project provides this file centrally, do not fork it lightly.

Selecting a formula

In YAML, you can choose a formula name:

equipment:
  computed: true
  compute:
    formula: "standard"

If you omit it, "standard" is used.

---

5) Merge order (preset → computed → override)

When you combine presets, computation, and overrides:

1. Preset values provide a baseline
2. Computed values fill in computed stats
3. Override values always win

Precedence:

final = override ?? computed ?? preset

---

6) Power tiers

Power tiers are validated as an integer range:

• 1–16

Power tier can come from:

• compute.powerTier inline
• tier mapping during bulk regeneration (recommended for large sets)

---

7) Bulk regeneration (recompute many items)

Regenerate equipment stats from existing XML files:

dsl regenerate equipment   --path ./datasheets   --tiers gear-tiers.yaml   --formulas stat-formulas.yaml   --seed 100000

Options

Option	Description	Default
--path	DataSheet directory	Required
--tiers	tier mapping file	Required
--formulas	formula config file	Required
--seed	starting equipment ID	100000
--dry-run	preview without writing	false

Tier mapping file (gear-tiers.yaml)

Maps item IDs to power tiers:

gear-tiers.yaml

tiers:
  - itemIds: [13001, 13002, 13003]
    powerTier: 1

  - itemIds: [13101, 13102]
    powerTier: 5

  - range:
      start: 14000
      end: 14999
    powerTier: 10

---

8) Explain command (debug computation)

Debug equipment computation for a specific item:

dsl explain my-spec.yaml 99001 --formulas stat-formulas.yaml

Typical output includes:

• derived values (part/type/level/grade)
• formula name used
• computed stats
• final merged values

---

9) Validation errors

Common computation-related errors include:

• invalid power tiers
• missing/invalid formulas file
• unknown formula name

See: Error codes.