Skip to content

tes3reference⚓︎

A reference is a sort of container structure for objects. It holds a base object, as well as various variables associated with that object that make it unique.

For example, many doors may share the same base object. However, each door reference might have a different owner, different lock/trap statuses, etc. that make the object unique.

This type inherits the following: tes3object, tes3baseObject

Properties⚓︎

activationReference⚓︎

The current reference, if any, that this reference will activate.

Returns:

attachments⚓︎

Read-only. A table with friendly named access to all supported attachments.

Returns:

baseObject⚓︎

Read-only. This is similar to the object field, but is guaranteed to provide the base-most object. If object is an actor clone, the base actor will be given instead.

Returns:

blocked⚓︎

The blocked state of the object.

Returns:

  • result (boolean)

bodyPartManager⚓︎

Read-only. Access to the reference's body part manager, if available. Typically this is only available on NPC references.

Returns:

cell⚓︎

Read-only. The cell that the reference is currently in.

Returns:

context⚓︎

Read-only. Access to the script context for this reference and its associated script.

Returns:

Example: Checking reference's script variables

Companions usually have a mwscript script with variable named companion set to 1. This can be used to determine if a reference is player's companion or not. Note that companion share functionality was added to Morrowind in Tribunal expansion. In vanilla game it is used by Tribunal companions. Also, companion mods usually use this feature. But note that all the followers (during certain parts of their quests) from base Morrowind don't have companion share.

--- This function returns `true` if the reference
--- has a variable companion set to 1 in its script.
---@param reference tes3reference
---@return boolean
local function hasCompanionShare(reference)

    -- Any local script variable inside `tes3scriptContext`
    -- objects can be read as if it were a normal Lua table
    -- (`reference.context` is of `tes3scriptContext` type)
    local companion = reference.context.companion
    -- or:
    -- local companion = reference.context["companion"]

    -- In addition, local script variables can be accessed from the tes3npc object:
    -- myNpc.script.context.somVarName

    -- To change the variable value, do an assignment:
    -- reference.context.companion = 0

    return (
        companion and
        companion == 1 or
        false
    )
end
Example: Checking if an actor is a follower

In this example we provide a way to check if a certain actor is currently player's follower. This function can also be useful besides the one from previous example, since not all of the followers have companion share enabled.

local followPackage = {
    [tes3.aiPackage.follow] = true,
    -- Depending on your needs, you can also include player's escortees.
    -- In the base game, AiEscort package is quite rare. Only White Guar
    -- has that package and with player as the targetActor.
    [tes3.aiPackage.escort] = true,
}

--- This function returns `true` if a given mobile has
--- follow ai package with player as its target
---@param mobile tes3mobileNPC|tes3mobileCreature
---@return boolean isFollower
local function isFollower(mobile)
    local planner = mobile.aiPlanner
    if not planner then
        return false
    end

    local package = planner:getActivePackage()
    if not package then
        return false
    end

    if followPackage[package.type] then
        local target = package.targetActor

        if target.objectType == tes3.objectType.mobilePlayer then
            return true
        end
    end
    return false
end

--- With the above function we can build a function that
--- creates a table with all of the player's followers
---@return tes3reference[] followerList
local function getFollowers()
    local followers = {}

    for _, mobile in pairs(tes3.mobilePlayer.friendlyActors) do
        ---@cast mobile tes3mobileNPC|tes3mobileCreature
        if isFollower(mobile) then
            table.insert(followers, mobile.reference)
        end
    end

    return followers
end

data⚓︎

A generic lua table that data can be written to, and synced to/from the save. All information stored must be valid for serialization to json. For item references, this is the same table as on the tes3itemData structure. To store data that doesn't get serialized to/from the save, use tempData.

There is a guide available here on using this table.

Returns:

  • result (table)

deleted⚓︎

Read-only. The deleted state of the object.

Returns:

  • result (boolean)

destination⚓︎

Read-only. Returns the travel destination node for this reference, or nil. This can be used to determine where a given door links to.

Returns:

disabled⚓︎

Read-only. The disabled state of the object.

Returns:

  • result (boolean)

facing⚓︎

Convenient access to the z-component of the reference's orientation in range of [-PI, PI] for actors and [0, 2PI] radians for all the other references. The North is facing of 0. Setting the facing sets the reference as modified.

Returns:

  • result (number)

forwardDirection⚓︎

Read-only. The normalized forward or Y direction vector of the reference.

Returns:

hasNoCollision⚓︎

Sets the no-collision flag on this reference, and recalculates collision groups. Use the setNoCollisionFlag() function to manage collision group recalculation instead.

Returns:

  • result (boolean)

id⚓︎

Read-only. The unique identifier for the object.

Returns:

  • result (string)

isDead⚓︎

Read-only. Returns true if the object is dead, false if they are alive, or nil if that couldn't be determined.

Returns:

  • result (boolean, nil)

isEmpty⚓︎

Friendly access onto the reference's empty inventory flag.

Returns:

  • result (boolean)

isLeveledSpawn⚓︎

Read-only. If true, this reference was created as a result of a leveled spawn.

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)

isRespawn⚓︎

Read-only. If true, the references respawn flag is set.

Returns:

  • result (boolean)

itemData⚓︎

Gets or sets the attached itemData for this reference. If set to nil, the item data will be unhooked but not deleted.

Returns:

leveledBaseReference⚓︎

Read-only. If this reference is a leveled spawn, this is the leveled creature spawn reference. If this reference wasn't the result of a leveled spawn, the value is nil.

Returns:

light⚓︎

Read-only. Direct access to the scene graph light, if a dynamic light is set.

Returns:

lockNode⚓︎

Read-only. Quick access to the reference's lock node, if any. Doors or containers that aren't locked nor trapped have this property set to nil.

Returns:

mesh⚓︎

The path to the object's mesh.

Returns:

  • result (string)

mobile⚓︎

Read-only. Access to the attached mobile object, if applicable.

Returns:

modified⚓︎

The modification state of the object since the last save.

Returns:

  • result (boolean)

nextInCollection⚓︎

The next object in parent collection's list.

Returns:

nextNode⚓︎

Read-only. The next reference in the parent reference list.

Returns:

nodeData⚓︎

Read-only. Redundant access to this object, for iterating over a tes3referenceList.

Returns:

object⚓︎

Read-only. The object that the reference is for, such as a weapon, armor, or actor.

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:

orientation⚓︎

Access to the reference's orientation, in XYZ Euler angles in radians in [0, 2 PI] except for actors. For actors, the Z angle is in range [-PI, PI] radians. Changing the orientation marks the reference as modified.

Returns:

owningCollection⚓︎

The collection responsible for holding this object.

Returns:

persistent⚓︎

The persistent flag of the object.

Returns:

  • result (boolean)

position⚓︎

Access to the reference's position. Setting the position sets the reference as modified.

For actors, the axes are:

  • X right - left(+)
  • Y front - back(+)
  • Z down - up(+)

Returns:

previousInCollection⚓︎

The previous object in parent collection's list.

Returns:

previousNode⚓︎

Read-only. The previous reference in the parent reference list.

Returns:

rightDirection⚓︎

Read-only. The normalized right or X direction vector of the reference.

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⚓︎

Read-only. The scene graph node that the reference uses for rendering.

Returns:

sourceFormId⚓︎

No description yet available.

Returns:

  • result (number)

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)

sourceModId⚓︎

No description yet available.

Returns:

  • result (number)

stackSize⚓︎

Access to the size of a stack, if the reference represents one or more items.

Returns:

  • result (number)

startingOrientation⚓︎

Read-only. Access to the reference's original orientation. Note that this value is invalid for NPCs and creatures.

Returns:

startingPosition⚓︎

Read-only. Access to the reference's original position. Note that this value is invalid for NPCs and creatures.

Returns:

supportsLuaData⚓︎

If true, this reference can store temporary or persistent lua data.

Returns:

  • result (boolean)

targetFormId⚓︎

No description yet available.

Returns:

  • result (number)

targetModId⚓︎

No description yet available.

Returns:

  • result (number)

tempData⚓︎

As with the data field, a generic lua table that data can be written to. No information in this table will persist into saves. For item references, this is the same table as on the tes3itemData structure.

There is a guide available here on using this table.

Returns:

  • result (table)

upDirection⚓︎

Read-only. The normalized up or Z direction vector of the reference.

Returns:

Methods⚓︎

__tojson⚓︎

Serializes the object to json.

local string = myObject:__tojson()

Returns:

  • string (string)

activate⚓︎

Causes this reference to activate another. This will lead them to go through doors, pick up items, etc.

myObject:activate(reference)

Parameters:

clearActionFlag⚓︎

Unsets a bit in the reference's action data attachment

myObject:clearActionFlag(flagIndex)

Parameters:

clone⚓︎

Clones a reference for a base actor into a reference to an instance of that actor. For example, this will force a container to resolve its leveled items and have its own unique inventory. Also, marks the new cloned reference as modified.

local cloned = myObject:clone()

Returns:

  • cloned (boolean): Returns true if the reference was successfully cloned. Returns false if the reference was already cloned or can't be cloned.

delete⚓︎

Disables the reference, removes all its attachments, resets its scale, marks it as modified, and sets the reference to be deleted, trigerring referenceDeactivated event.

myObject:delete()

deleteDynamicLightAttachment⚓︎

Deletes the dynamic light attachment, if it exists. This will automatically detach the dynamic light from affected nodes.

myObject:deleteDynamicLightAttachment(removeLightFromParent)

Parameters:

  • removeLightFromParent (boolean): Default: false. If true, the dynamic light is removed from its parent node as well.

detachDynamicLightFromAffectedNodes⚓︎

Removes the dynamic light from any affected scene graph nodes, but will not delete the associated attachment.

myObject:detachDynamicLightFromAffectedNodes()

disable⚓︎

Hides the reference, detaches all dynamic lights and sounds, and stops any mobile simulation. Sets the reference as modified implicitly.

local success = myObject:disable()

Returns:

  • success (boolean): If true, the reference was successfully disabled.

enable⚓︎

Shows the reference, reattaches all dynamic lights and sounds, and restarts any mobile simulation if the player is close enough. Sets the reference as modified implicitly.

local success = myObject:enable()

Returns:

  • success (boolean): If true, the reference was successfully enabled.

getAngleTo⚓︎

Calculates the angle from this reference's current facing to the target reference.

local angle = myObject:getAngleTo(reference)

Parameters:

  • reference (tes3reference): The reference to calculate the angle to.

Returns:

  • angle (number): The angle to the given reference in radians.

getAttachedDynamicLight⚓︎

Fetches the dynamic light attachment.

local result = myObject:getAttachedDynamicLight()

Returns:

getOrCreateAttachedDynamicLight⚓︎

Fetches the dynamic light attachment. If there isn't one, a new one will be created with the given light and value.

If no light is supplied as an argument, a point light of radius 512 will be automatically created.

If the light is not attached to any part of the scene graph yet, the point light will be placed as a child of the "attachLight" subnode of the model, or a child of the model if "attachLight" is not found.

local result = myObject:getOrCreateAttachedDynamicLight(light, phase)

Parameters:

Returns:

onCloseInventory⚓︎

A function that tells the game that an inventory has been closed, if you are simulating inventory operations. It has the capability of un-cloning an inventory if it has not been modified. Typically not used outside of specific purposes.

local result = myObject:onCloseInventory()

Returns:

  • result (boolean)

setActionFlag⚓︎

Sets a bit in the reference's action data attachment.

myObject:setActionFlag(flagIndex)

Parameters:

setDynamicLighting⚓︎

Sets the dynamic lighting state of the reference using the global data handler.

myObject:setDynamicLighting()

setNoCollisionFlag⚓︎

Sets if this reference has active collision. This is preferable to changing the hasNoCollision property, if you are manipulating multiple objects at once and do not want to constantly recalculate collision groups.

myObject:setNoCollisionFlag(hasNoCollision, updateCollisions)

Parameters:

  • hasNoCollision (boolean): If true, the reference no longer has collision.
  • updateCollisions (boolean): Default: true. If true, collision groups for the active cells are recalculated.

testActionFlag⚓︎

Returns the flag's value in the reference's action data attachment.

local result = myObject:testActionFlag(flagIndex)

Parameters:

Returns:

  • result (boolean)

updateEquipment⚓︎

Causes the reference, if of an actor, to update the reference's bodyparts with the currently equipped ones.

myObject:updateEquipment()

updateLighting⚓︎

Updates the lighting of the reference using the global data handler.

myObject:updateLighting()

updateSceneGraph⚓︎

Updates the reference's local rotation matrix, propagates position changes to the scene graph, and sets the reference's modified flag. You need to call this if the orientation or position was manually modified.

myObject:updateSceneGraph()