Gem data

Gem resources control which bonuses can be rolled and where they fit. The server loads all gem families as one snapshot: an invalid resource keeps the previous snapshot active.

Where the files live

Except global settings, these paths are relative to data/<namespace>/; any namespace can contribute definitions. Global settings are read only from data/isekaiexpansion/gem_system/settings.json.

gem_system/settings.json
gem_attributes/random_roll/*.json
gem_attributes/fixed_attributes/*.json
gem_attributes/element_attributes/*.json
gem_attributes/skill_attributes/*.json
socket_profiles/*.json
curses/*.json
gem_consumables/*.json

Each file contains one object. A higher-priority pack replaces a resource with the same namespaced path; definitions at different paths are still checked for duplicate IDs, attributes and item ownership. Global settings use the highest resource, not a field-by-field merge. A socket profile’s ID is its namespaced path below socket_profiles/, without .json.

Minimal example

Save this as data/example/socket_profiles/iron_sword.json. It gives an iron sword an unlocked attribute socket and outranks the bundled melee profile. The explicit priority prevents the example being hidden by that existing profile; it is optional to the parser.

{
  "priority": 120,
  "match": {
    "items": [
      "minecraft:iron_sword"
    ]
  },
  "sockets": [
    {
      "kind": "ATTRIBUTE",
      "min_item_level": 0
    }
  ]
}

Fields

Use actual JSON numbers and booleans. Missing required fields or numeric conversion failures reject the reload. Unknown fields are ignored except the explicitly removed keys under Validation. The table calls out intentional fallbacks for wrong container types.

Global settings

Random and fixed attributes

Value formatting and difficulty scaling

Element and skill gems

Socket profiles

Curses

Consumables

Enumerations and formulas

Weapon restrictions accept none, sword, rapier, greatsword, glaive, dagger, lance, scythe, axe, halberd, spear, mace, hammer, wand, staff, katana, chakram, gauntlet, boomerang, bow, crossbow, gun, magigun. Matching ignores case and surrounding whitespace. Unknown names reject the reload.

Formulas produce a multiplier, then the operation’s rounding format applies to base × multiplier. Variables areaLv and level both hold area level; base and value both hold the unscaled attribute value. Formula bands differ from the requirement-map keys:

A missing band falls back to default. Missing formulas, non-finite results and evaluation errors use multiplier 1; evaluation errors log at use, not reload. The bundled exp4j dependency evaluates formulas. Formula keys and expressions cross the network with limits of 64 and 512 characters respectively; stay within those limits even though loading does not enforce them. Scaling applies to random and fixed attributes, not element or skill gems.

Consumable actions

All IDs below use the isekaiexpansion: namespace. Action fields belong inside data.

Eligibility is checked before rolling and consuming, against both branches. The chosen branch runs in order; successful earlier mutations are not rolled back if a later action does nothing. A successful roll with no applied action does not consume. A failed roll can consume under ALWAYS even with an empty failure branch. An empty target is never eligible. Registration alone does not add an eligibility rule for a new code action.

Curse attribute values and status durations scale by the stored multiplier. Incoming damage becomes damage × (1 + sum(value × curse multiplier)); status amplifiers do not scale. Multiple curses providing the same effect take the greatest duration and amplifier, combine ambient with OR, and particle/icon visibility with AND.

Full example

Save this as data/example/gem_attributes/random_roll/attack_damage.json after replacing or removing any other active random definition for this attribute. It follows the bundled random files’ structure; different filenames do not permit duplicate attribute IDs.

{
  "attribute": "minecraft:generic.attack_damage",
  "domain": "OFFENSE",
  "weight": 1,
  "damage_categories": [
    "MELEE"
  ],
  "operations": [
    {
      "name": "ADDITION",
      "min": 1,
      "max": 2,
      "format": {
        "decimals": 2
      },
      "difficulty_scaling": {
        "formula": "1 + areaLv * 0.02",
        "min_multiplier": 1,
        "max_multiplier": 2
      }
    }
  ]
}

Validation

• Malformed, empty or non-object file: records a resource error and rejects the gem snapshot. Required arrays must be nonempty where specified.
• Unknown registry ID: gem items, attributes, schools, effects and triggerable skills reject the reload. Profile and requirement item/tag filters validate syntax only; an absent optional-mod item remains a non-match.
• Duplicate definition: random attribute IDs, same-family definition IDs, same-family item IDs and cross-family fixed/element/skill item reuse reject the reload. Equal-priority profiles are allowed and sort by ID.
• Invalid range: finite, probability and positive checks reject rather than clamp. Some integer fields use numeric conversion; supply integers explicitly. Difficulty weight maps additionally reject fractional values and duplicate keys differing only in case.
• Removed fields: insert.cost_curve rejects; use insert.crack_chance_on_fail. Element extras rejects; use typed element fields.
• Conditional compatibility: Fabric’s fabric:load_conditions is checked before gem fields. A failing condition excludes the file; failing settings conditions use defaults. Condition syntax belongs to Fabric. Passing conditions do not relax registry validation.

Unknown action-data keys are normally ignored; set_socket_state copies unrecognized keys into saved state. Wrong optional action-data types can bypass readers and fall back rather than fail. JSON action data becomes NBT: booleans become bytes, integral in-range numbers become integers, other numbers become doubles, and null becomes an empty string. Use homogeneous arrays.

A restriction translates as gem_requirement.<namespace>.<path>, with path slashes changed to dots. Removing its definition leaves existing gems with that ID unable to match equipment; it does not remove the restriction.

Reloading

Resources load on the server resource reload. Joining sends the active snapshot; a successful data-pack reload broadcasts it to connected clients. Replacement clears the item-to-profile cache. A gem-local validation failure retains its previous snapshot; this is not a transaction across unrelated reload listeners.

Existing item NBT remains separate. Reloading does not reroll stored random values. It can change compatibility, fixed-definition values and the profile selected for an item. Reducing a profile’s socket count can discard excess saved slots when a mutating operation normalizes the item; inspect occupied equipment before making that change.

Related

Gems and sockets explains the player loop. Gem runtime covers item NBT, integration and verification.