Spell data

Spell Engine owns spell definitions, binding pools and item assignments; IsekaiExpansion adds a separate astral-energy map. This page is checked against Spell Engine 1.10.7+1.20.1 and covers the active-spell, projectile, visual and item formats used by this integration.

Where the files live

Same-path spell/assignment resources are selected by data-pack priority, not merged field by field. Energy files merge by iteration order without an explicit sort; avoid defining a spell’s energy in multiple files. The bundled spell reference directories are examples outside the live spell/ path and do not register their nested examples as playable spells.

Minimal example

This reduced form of the bundled arcane-blast reference uses direct damage and aimed targeting, with no required external item or sound. Save it at a live spell path in your pack; the existing reference folder itself is not loaded as a spell.

{
  "school": "spell_power:arcane",
  "active": {
    "cast": {}
  },
  "target": {
    "type": "AIM",
    "aim": {}
  },
  "deliver": {
    "type": "DIRECT"
  },
  "impacts": [
    {
      "action": {
        "type": "DAMAGE",
        "damage": {}
      }
    }
  ]
}

Fields

Defaults below apply when a field is omitted, not when an explicit null is supplied. The dependency’s JSON model is permissive; a default of null can still be unusable for the selected execution branch.

Casting, targeting, impacts and costs

Other action kinds are STATUS_EFFECT, FIRE, SPAWN, SUMMON, TELEPORT, COOLDOWN, AGGRO, DISRUPT, IMMUNITY, VELOCITY and CUSTOM. Each requires its own branch-specific payload. Passive triggers, modifiers, charge bonuses and those payloads are owned by the versioned Spell Engine schema; they are not extra IsekaiExpansion fields.

Projectile and meteor layout

Projectile and meteor launch settings are separate from the projectile’s flight data. The model rows beginning models[] are relative to client_data.composite_model.models[].

Flight motion, collision perks, entity placement, cloud/melee delivery and model animation transforms extend this shape in the same versioned schema. Do not transplant fields from the older flat projectile format.

Shared animation, sound and particle objects

Paths here are relative shapes: animation and sound can occur at cast/release/impact sites; particles[] names one particle-group list entry. Continuous cast particles are a list, while impact/release effects use a visuals bundle.

The particle format also defines lifetime, opacity, scaling, attachment and batch geometry controls. Model effects define transforms and timed animations. These are dependency formats; use the linked release when extending beyond the fields above.

Item assignments and pools

This assignment uses a subset of the bundled staff’s spells:

{
  "spell_container": {
    "access": "CONTAINED",
    "pool": "isekaiexpansion:tier1",
    "spell_ids": [
      "isekaiexpansion:healing"
    ]
  }
}

Resolution is per-stack saved data, then assignment, then item default, then fallback. An assignment containing a container also suppresses the item’s default choice unless the assignment supplies a choice. Explicit per-stack choice data still wins. A container with NONE access can store spells for equipment-source provision without acting as a casting resolver itself.

A pool uses the registry-tag format:

{
  "values": [
    "isekaiexpansion:healing",
    "isekaiexpansion:clarity"
  ]
}

Astral energy

The bundled healing entry is:

{
  "isekaiexpansion:healing": 12
}

There is no wrapper or metadata field. Other keys are other spell-ID strings. Final costs also use scroll, talent, origin and airborne modifiers; channels pay per successful delivery.

Full example

This adds binding, a timed cast, casting particles, release animation and cooldown. The cast duration is 1 second and cooldown is 3 seconds.

{
  "school": "spell_power:arcane",
  "tier": 1,
  "range": 24,
  "learn": {},
  "active": {
    "cast": {
      "duration": 1,
      "animation": {
        "id": "spell_engine:one_handed_projectile_charge"
      },
      "particles": [
        {
          "id": "spell_engine:magic_spell",
          "appearance": {
            "color": 4278190335,
            "motion": "FLOAT"
          },
          "batch": {
            "shape": "CIRCLE",
            "count": 4,
            "min_speed": 0.05,
            "max_speed": 0.1
          }
        }
      ]
    }
  },
  "target": {
    "type": "AIM",
    "aim": {}
  },
  "deliver": {
    "type": "DIRECT"
  },
  "impacts": [
    {
      "action": {
        "type": "DAMAGE",
        "damage": {
          "spell_power_coefficient": 1
        }
      }
    }
  ],
  "release": {
    "animation": {
      "id": "spell_engine:one_handed_projectile_release"
    }
  },
  "cost": {
    "cooldown": {
      "duration": 3
    }
  }
}

To channel, set cast type to CHANNEL and provide its channel object with a positive total delivery count. For custom delivery, set delivery type to CUSTOM and its custom handler to an installed handler ID. Data alone cannot create a new custom handler.

Validation

Spell definitions use the dependency’s generic JSON decoder. Unknown fields are ignored; missing fields retain model defaults. There is no uniform schema-wide range clamp or validation that every referenced asset, school, handler and nested object exists. Wrong structural types can fail decoding; unknown enum strings or explicit nulls can survive as null and fail later when the selected branch executes. An empty object is therefore not a useful spell even if decoding succeeds. Use finite numbers, valid installed identifiers and the exact uppercase enum values.

Assignment files require an object containing spell_container or spell_choice. Empty text, a non-object root, a bare container or a wrapper whose members both fail decoding is warned about and skipped. Members decode independently: a valid choice can survive a bad container. An explicit empty container is accepted to override and disable an item’s default. Unknown fields are ignored; invalid access enum spelling fails that member. On startup the assignment map is replaced by successfully parsed entries.

Energy application clears the old map first. An empty object contributes nothing. Empty keys and nonpositive values log errors and skip that entry. Values use integer conversion rather than strict integer validation; author integer JSON numbers. A conversion exception logs and stops the rest of that file, preserving entries already inserted; other files continue. Spell IDs are not parsed or checked by this loader, so misspellings can silently remain unused.

Reloading

Treat spell definitions as world-registry data and item assignments as server-start data in this pinned dependency version: restart/reopen the world after changing them. The dependency synchronises the spell registry and assignment data when clients join. Resource images, models and animations still need the matching client resource pack.

IsekaiExpansion energy files reload with server data, but the resolved energy map is currently sent to clients only on join. Reconnect after /reload to refresh client energy checks and tooltips. This differs from formats such as emoji data that explicitly broadcast after successful reload.

Related

Spell integration covers custom handlers, payment and saved item data. Elements explains the player-facing schools.