Skip to content

tes3spell⚓︎

A spell game object.

This type inherits the following: tes3object, tes3baseObject

Properties⚓︎

alwaysSucceeds⚓︎

A flag that determines if casting the spell will always succeed.

Returns:

  • result (boolean)

autoCalc⚓︎

Determines if the magicka cost for the spell is autocalculated, and if the spell may be automatically assigned to NPCs if they are skillful enough to cast it.

Returns:

  • result (boolean)

basePurchaseCost⚓︎

Calculates the base cost to purchase the spell. This value is not adjusted by mercantile skills.

Returns:

  • result (number)

blocked⚓︎

The blocked state of the object.

Returns:

  • result (boolean)

castType⚓︎

The spell's cast type. Maps to tes3.spellType constants.

Returns:

deleted⚓︎

Read-only. The deleted state of the object.

Returns:

  • result (boolean)

disabled⚓︎

Read-only. The disabled state of the object.

Returns:

  • result (boolean)

effects⚓︎

Read-only. An array-style table of the tes3effect data on the object.

Returns:

Example: Determining if a spell is hostile

The following function returns true if the spell contains at least one hostile effect. This criterion can be considered subjective, but that rule is also used by the game to determine if a use of the spell on an NPC is considered an offense.

--- @param magicSource tes3spell|tes3enchantment|tes3alchemy
local function isSpellHostile(magicSource)
    for _, effect in ipairs(magicSource.effects) do
        if (effect.object.isHarmful) then
            -- If one of the spell's effects is harmful, then
            -- `true` is returned and function ends here.
            return true
        end
    end
    -- If no harmful effect was found then return `false`.
    return false
end

flags⚓︎

A bit field for the spell's flags.

Returns:

  • result (number)

id⚓︎

Read-only. The unique identifier for the object.

Returns:

  • result (string)

isActiveCast⚓︎

Read-only. True if the spell is actively cast. If false, the spell's effects are always passively affecting the owner.

Returns:

  • result (boolean)

isLocationMarker⚓︎

True if this object is an editor marker for a gameplay location. These include travel, intervention, prison, door, and interior north markers. Markers are invisible in-game.

Returns:

  • result (boolean)

magickaCost⚓︎

The magicka used when attempting to cast this spell. For an auto-calculated spell, it is updated when the spell is created or loaded.

Returns:

  • result (number)

modified⚓︎

The modification state of the object since the last save.

Returns:

  • result (boolean)

name⚓︎

The name of the spell.

Returns:

  • result (string)

nextInCollection⚓︎

The next object in parent collection's list.

Returns:

objectFlags⚓︎

Read-only. The raw flags of the object.

Returns:

  • result (number)

objectType⚓︎

Read-only. The type of object. Maps to values in tes3.objectType.

Returns:

owningCollection⚓︎

The collection responsible for holding this object.

Returns:

persistent⚓︎

The persistent flag of the object.

Returns:

  • result (boolean)

playerStart⚓︎

A flag that determines if the spell may be assigned to the player at character generation if the player has enough skill to cast it.

Returns:

  • result (boolean)

previousInCollection⚓︎

The previous object in parent collection's list.

Returns:

scale⚓︎

The object's scale. The value range is (0, 10).

Returns:

  • result (number)

sceneCollisionRoot⚓︎

The scene graph node for this object's physics collision, if its mesh has a root collision node.

Returns:

sceneNode⚓︎

The scene graph node for this object.

Returns:

sourceless⚓︎

The soruceless flag of the object.

Returns:

  • result (boolean)

sourceMod⚓︎

Read-only. The filename (including the extension) of the mod that owns this object. It has nil value if the object was anything other than loaded from an ESP or ESM file.

Returns:

  • result (string)

supportsLuaData⚓︎

If true, references of this object can store temporary or persistent lua data.

Returns:

  • result (boolean)

value⚓︎

Read-only. The calculated base price of the spell. This is the magickaCost of the spell multiplied by the fSpellValueMult GMST.

Returns:

  • result (number)

Methods⚓︎

__tojson⚓︎

Serializes the object to json.

local string = myObject:__tojson()

Returns:

  • string (string)

calculateCastChance⚓︎

Calculates the chance that a caster can cast a given spell.

local result = myObject:calculateCastChance({ checkMagicka = ..., caster = ... })

Parameters:

  • params (table)
    • checkMagicka (boolean): Default: true. Determines if the caster's magicka should be taken into account during the calculation.
    • caster (tes3reference, tes3mobileActor): The caster to perform the calculation against.

Returns:

  • result (number)

createCopy⚓︎

Creates a copy of this object.

local newObject = myObject:createCopy({ id = ..., addToObjectList = ..., sourceless = ... })

Parameters:

  • params (table)
    • id (string): Optional. The new object's ID. If one is not provided, a randomly generated one will be used.
    • addToObjectList (boolean): Default: true. If true, the object will be added to the data handler. If this is false, the new object may not have a randomly generated ID. Do not use this without knowing the implications.
    • sourceless (boolean): Default: false. If true, the object will be made sourceless, and will not be serialized to the save game. If the object is copied outside of a save game, the object will always be sourceless.

Returns:

getActiveEffectCount⚓︎

Gets the number of active effects in the spell effect table.

local result = myObject:getActiveEffectCount()

Returns:

  • result (integer)

getAutoCalcMagickaCost⚓︎

Calculates and returns the magicka cost as if this spell was an autoCalc spell. It only returns the magicka value and does not update the spell's magickaCost.

local result = myObject:getAutoCalcMagickaCost()

Returns:

  • result (number)

getFirstIndexOfEffect⚓︎

Gets the first index of an effect ID in the spell effect table. Returns -1 if provided effect doesn't exist in the spell

local index = myObject:getFirstIndexOfEffect(effectId)

Parameters:

Returns:

  • index (integer): Returns 0-based index. Because Lua's arrays are 1-based, to index the spell's effects array with the return value add 1.

getLeastProficientEffect⚓︎

Returns the effect of the spell that a given actor is least proficient with.

local effect = myObject:getLeastProficientEffect(actor)

Parameters:

Returns:

  • effect (tes3effect, nil): The least proficient effect, or nil if the spell has no valid effects.

getLeastProficientSchool⚓︎

Returns the school of the least proficient effect on the spell, for a given actor.

local schoolID = myObject:getLeastProficientSchool(actor)

Parameters:

Returns: