Skip to content

tes3cell⚓︎

An exterior or interior game area.

This type inherits the following: tes3baseObject

Properties⚓︎

activators⚓︎

Read-only. One of the three reference collections for a cell.

Returns:

actors⚓︎

Read-only. One of the three reference collections for a cell.

Returns:

Example: Converting reference list to array style table

An example is given of a general function that can be used to convert a tes3referenceList to simple array which can be looped over with standard ipairs().

-- This function loops over the references inside the
-- tes3referenceList and adds them to an array-style table
---@param list tes3referenceList
---@return tes3reference[]
local function referenceListToTable(list)
    local result = {}
    local i = 1
    if list.size == 0 then
        return {}
    end
    local ref = list.head

    while ref.nextNode do
        result[i] = ref
        i = i + 1
        ref = ref.nextNode
    end

    -- Add the last reference
    result[i] = ref

    return result
end

-- Usage:
local list = tes3.player.cell.actors

-- The references is now a simple array style table
-- that can be looped over with regular ipairs()
local references = referenceListToTable(list)

for i, ref in ipairs(references) do
    -- Do something with the reference
    tes3ui.log(ref.id)
end
Example: Generic iterator function

In this more involved example, we used the corouting API from the Lua standard library to construct a generic iterator function. The iterReferenceList() function can then be used directly inside a for loop.

--- This is a generic iterator function used
--- to loop over a tes3referenceList
---@param list tes3referenceList
---@return fun(): tes3reference
local function iterReferenceList(list)
    local function iterator()
        local ref = list.head

        if list.size ~= 0 then
            coroutine.yield(ref)
        end

        while ref.nextNode do
            ref = ref.nextNode
            coroutine.yield(ref)
        end
    end
    return coroutine.wrap(iterator)
end

-- Usage:
local list = tes3.player.cell.actors
for ref in iterReferenceList(list) do
    -- Do something with the reference
    tes3ui.log(ref.id)
end

ambientColor⚓︎

The cell's ambient color. Only available on interior cells.

Returns:

behavesAsExterior⚓︎

If true, the cell behaves as an exterior instead of an interior for certain properties. Only available on interior cells.

Returns:

  • result (boolean)

blocked⚓︎

The blocked state of the object.

Returns:

  • result (boolean)

cellFlags⚓︎

A numeric representation of the packed bit flags for the cell, typically accessed from other properties.

Returns:

  • result (number)

deleted⚓︎

Read-only. The deleted state of the object.

Returns:

  • result (boolean)

disabled⚓︎

Read-only. The disabled state of the object.

Returns:

  • result (boolean)

displayName⚓︎

The name of the cell as displayed on the in-game UI. For exterior cells without an assigned name, this is the region name.

Returns:

  • result (string)

editorName⚓︎

The name of the cell as displayed in the Construction Set. For exterior cells, this includes the cell coordinates.

Returns:

  • result (string)

fogColor⚓︎

The cell's fog color. Only available on interior cells.

Returns:

fogDensity⚓︎

The cell's fog density. Only available on interior cells.

Returns:

  • result (number)

gridX⚓︎

The cell's X grid coordinate. Only available on exterior cells.

Returns:

  • result (number)

gridY⚓︎

The cell's Y grid coordinate. Only available on exterior cells.

Returns:

  • result (number)

hasMapMarker⚓︎

Read-only. If true, the cell will be marked on the player's map. This does not take into account if the player has been to that cell.

Returns:

  • result (boolean)

hasWater⚓︎

If true, the cell has water. Only applies to interior cells.

Returns:

  • result (boolean)

id⚓︎

Read-only. The unique identifier for the object.

Returns:

  • result (string)

isInterior⚓︎

If true, the cell is an interior.

Returns:

  • result (boolean)

isOrBehavesAsExterior⚓︎

Read-only. true if the cell is not an interior or if it behaves as an exterior.

Returns:

  • result (boolean)

landscape⚓︎

Read-only. Access to the cell's landscape object. It's only available on exterior cells.

Returns:

modified⚓︎

The modification state of the object since the last save.

Returns:

  • result (boolean)

name⚓︎

The name and id of the cell. See also displayName and editorName.

Returns:

  • result (string)

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:

pathGrid⚓︎

Read-only. Access to the cell's pathgrid. Not all cells have a pathgrid. The property is unaccessible on unloaded cells.

Returns:

persistent⚓︎

The persistent flag of the object.

Returns:

  • result (boolean)

pickObjectsRoot⚓︎

The scenegraph node containing player-interactable objects from this cell.

Returns:

region⚓︎

The region associated with the cell. Only available on exterior cells, or interior cells that behave as exterior cells.

Returns:

restingIsIllegal⚓︎

If true, the player may not rest in the cell.

Returns:

  • result (boolean)

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)

staticObjectsRoot⚓︎

The scenegraph node containing static non-player-interactable objects from this cell.

Returns:

statics⚓︎

Read-only. One of the three reference collections for a cell.

Returns:

sunColor⚓︎

The cell's sun color. Only available on interior cells.

Returns:

supportsLuaData⚓︎

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

Returns:

  • result (boolean)

waterLevel⚓︎

The water level in the cell. In extirior cells, water level is 0, while the interior cells can have custom water, usually set in the Construction Set, or don't have water at all. In that case, this property will be nil.

Returns:

  • result (number, nil)

Methods⚓︎

__tojson⚓︎

Serializes the object to json.

local string = myObject:__tojson()

Returns:

  • string (string)

isPointInCell⚓︎

Determines if a given X/Y coordinate falls in the given cell. This will always be true for interior cells.

local inCell = myObject:isPointInCell(x, y)

Parameters:

  • x (number): The X position to test.
  • y (number): The Y position to test.

Returns:

  • inCell (boolean): true, if the point is found in the cell.

iterateReferences⚓︎

Used in a for loop, iterates over objects in the cell.

local iterator = myObject:iterateReferences(filter)

Parameters:

  • filter (integer, integer[]): Optional. The TES3 object type to filter results by. If you need multiple filters, just pass them as a table, e.g. { tes3.objectType.npc, tes3.objectType.creature }. Those are stored in tes3.objectType namespace.

Returns: