Spells and abilities

Spell script structure

Each spell has a Lua file in scripts/actions/spells/ organized by spell school. Spells expose standard handler functions.

-- scripts/actions/spells/black/blizzard.lua (actual source)
---@type TSpell
local spellObject = {}

spellObject.onMagicCastingCheck = function(caster, target, spell)
    return 0  -- 0 means the spell can be cast
end

spellObject.onSpellCast = function(caster, target, spell)
    return xi.spells.damage.useDamageSpell(caster, target, spell)
end

return spellObject

Spell handler reference

Handler	Signature	When called
`onMagicCastingCheck`	`(caster, target, spell)`	Validates whether the spell can be cast; return 0 to allow, non-zero to deny
`onSpellCast`	`(caster, target, spell)`	Main spell execution; return the damage dealt

Damage spell calculations

scripts/globals/spells/damage_spell.lua contains xi.spells.damage, used for all direct-damage magic (Black, White, Dark, Ninjutsu). Damage parameters are stored in a table indexed by spell ID:

-- Structure: [spellId] = { StatUsed, bonusMacc, npcPower, npcMultiplier,
--                          pcPower, inflexionPoint, M0, M50, M100, M200, M300, M400, M500 }
[xi.magic.spell.FIRE   ] = { xi.mod.INT,  0,   35, 1,   55,  46, 1.4, 1, 0, 0, 0, 0, 0 },
[xi.magic.spell.FIRE_II] = { xi.mod.INT, 10,  133, 1,  160, 155, 2.4, 1.7, 1, 0, 0, 0, 0 },
[xi.magic.spell.FIRE_III]= { xi.mod.INT, 20,  295, 1.5, 290, 320, 3.1, 2.7, 1.85, 1, 0, 0, 0 },
-- ...

Call xi.spells.damage.useDamageSpell(caster, target, spell) to run the full pipeline including:

Base power lookup from the parameter table
Stat modifier (INT/MND) application
Magic accuracy vs. magic evasion (resist rate from magic_hit_rate.lua)
Day/weather bonus (damage_multipliers.lua)
Magic burst multiplier (magicburst.lua)
Stoneskin, Phalanx, One For All absorption
Final HP adjustment

Cure spells

Cure calculations live in scripts/globals/magic.lua:

-- Get the caster's raw cure power
getCurePower(caster, isBlueMagic)
-- power = floor(MND/2) + floor(VIT/4) + HealingMagicSkill

-- Apply all potency modifiers to a base cure amount
getCureFinal(caster, spell, basecure, minCure, isBlueMagic)
-- Applies: CURE_POTENCY, CURE_POTENCY_II, day/weather, RAPTURE, DIVINE_SEAL

Enfeebling and enhancing spells

Helper modules in scripts/globals/spells/ cover other spell families:

File	Covers
`enfeebling_spell.lua`	Slow, Paralyze, Blind, etc.
`enhancing_spell.lua`	Protect, Shell, Haste, etc.
`enfeebling_song.lua`	Bard enfeebling songs
`enhancing_song.lua`	Bard enhancing songs
`enhancing_ninjutsu.lua`	Ninjutsu enhancing buffs
`enhancing_teleport.lua`	Teleport/Warp spells
`absorb_spell.lua`	Absorb-TP, Absorb-STR, etc.

Blue magic

scripts/globals/bluemagic.lua provides xi.spells.blue with calculation routines for Blue Mage spells. Blue magic spells can be physical or magical and reuse the mob skill calculation pipeline.

-- TP modifier enum (currently unused in most spells)
xi.spells.blue.tpMod =
{
    NONE          = 0,
    CRITICAL      = 1,
    DAMAGE        = 2,
    ACC           = 3,
    ATTACK        = 4,
    DURATION      = 5,
    EFFECT_CHANCE = 6,
}

Blue magic physical spells use WSC alpha scaling based on the caster’s level:

-- alpha calculation (level-dependent WSC multiplier)
-- level <= 60: ceil(100 - level/6) / 100
-- level <= 75: ceil(100 - (level-40)/2) / 100
-- level  > 75: 0.83

Individual blue magic spell scripts live in scripts/actions/spells/blue/ and call into xi.spells.blue helpers.

Job abilities

scripts/globals/ability.lua provides xi.ability.adjustDamage(), which applies universal modifiers to job ability damage:

xi.ability.adjustDamage = function(dmg, attacker, skill, target, skilltype, skillparam, shadowbehav)
    -- Handles: perfect dodge, all_miss, shadows, anticipate, third_eye
    -- Returns adjusted damage
end

Individual job ability scripts live in scripts/actions/abilities/ and return a table with:

local abilityObject = {}

abilityObject.onAbilityCheck = function(player, target, ability)
    -- Return 0 to allow, non-zero message ID to deny
    return 0
end

abilityObject.onUseAbility = function(player, target, ability)
    -- Execute ability effect
end

return abilityObject

Ninjutsu

Ninjutsu tools are checked and consumed automatically by the C++ core. Ninjutsu spell scripts follow the same structure as regular spells but may reference scripts/globals/spells/enhancing_ninjutsu.lua for buff ninjutsu.

Spell object API

The spell object passed to all spell handlers is a CLuaSpell (bound in src/map/lua/lua_spell.cpp).

spell:getID()         -- spell ID constant
spell:getElement()    -- elemental constant (xi.element.FIRE, etc.)
spell:getSkillType()  -- magic skill type
spell:getTP()         -- TP cost
spell:getMP()         -- MP cost
spell:getTargetID()   -- target entity ID
spell:isMagicBurst()  -- boolean
spell:setTotalDamage(dmg)
spell:setCasterAnimationPacket(anim)

Lua Scripting Overview

Interaction Framework

Game Systems

Spell script structure

Spell handler reference

Damage spell calculations

Cure spells

Enfeebling and enhancing spells

Blue magic

Job abilities

Ninjutsu

Spell object API

​Spell script structure

​Spell handler reference

​Damage spell calculations

​Cure spells

​Enfeebling and enhancing spells

​Blue magic

​Job abilities

​Ninjutsu

​Spell object API

Spell script structure

Spell handler reference

Damage spell calculations

Cure spells

Enfeebling and enhancing spells

Blue magic

Job abilities

Ninjutsu

Spell object API