Skip to content

niCamera⚓︎

Object that represent a camera. Position and orientation is determined by parent properties. This enables the cameras to be attached to scene graph objects and follow them automatically, as they move.

This type inherits the following: niAVObject, niObjectNET, niObject

Properties⚓︎

alphaProperty⚓︎

Convenient access to this object's alpha property. Setting this value to be nil will erase the property, while setting it to a valid alpha property will set (or replace) it.

Returns:

appCulled⚓︎

A flag indicating if this object is culled. When culled, it will not render, and raycasts ignore it.

Returns:

  • result (boolean)

controller⚓︎

Read-only. The first controller available on the object.

Returns:

cullingPlanes⚓︎

The culling planes of the camera: near, far, left, right, top, and bottom.

Returns:

extraData⚓︎

Read-only. The first extra data available on the object.

Returns:

flags⚓︎

Flags, dependent on the specific object type.

Returns:

  • result (number)

fogProperty⚓︎

Convenient access to this object's fog property. Setting this value to be nil will erase the property, while setting it to a valid fog property will set (or replace) it.

Returns:

lodAdjust⚓︎

The level-of-detail adjustment value for the camera. This value is used by NiLODNode objects to multiply the distance between the object whose LOD is being computed and the camera. A higher value will lower the LOD of the objects drawn by the camera.

Returns:

  • result (number)

materialProperty⚓︎

Convenient access to this object's material property. Setting this value to be nil will erase the property, while setting it to a valid material property will set (or replace) it.

Returns:

name⚓︎

The human-facing name of the given object.

Returns:

  • result (string)

parent⚓︎

Read-only. The object's parent. It may not have one if it is not attached to the scene.

Returns:

port⚓︎

The port on the backbuffer of the camera. Represents the rectangular portion of the rendering backbuffer to which the camera's view rectangle is drawn (purely 2D mapping). These values are called port settings. The ordering: X - left, Y - right, Z - top and W - bottom. All port settings must be in the unit interval [0, 1]. The left edge of the backbuffer is 0.0, the right edge is 1.0. The top edge of the backbuffer is 1.0, the bottom edge is 0.0.

Returns:

properties⚓︎

Read-only. The list of properties attached to this niAVObject.

Returns:

refCount⚓︎

Read-only. The number of references that exist for this object. When this value reaches zero, the object will be deleted.

Returns:

  • result (number)

renderer⚓︎

Read-only. The renderer of the camera.

Returns:

rotation⚓︎

The object's local rotation matrix.

Returns:

RTTI⚓︎

Read-only. The runtime type information for this object. This is an alias for the .runTimeTypeInformation property.

Returns:

runTimeTypeInformation⚓︎

Read-only. The runtime type information for this object.

Returns:

scale⚓︎

The object's local uniform scaling factor.

Returns:

  • result (number)

scene⚓︎

Read-only. The scene of the camera.

Returns:

stencilProperty⚓︎

Convenient access to this object's stencil property. Setting this value to be nil will erase the property, while setting it to a valid stencil property will set (or replace) it.

Returns:

texturingProperty⚓︎

Convenient access to this object's texturing property. Setting this value to be nil will erase the property, while setting it to a valid texturing property will set (or replace) it.

Returns:

translation⚓︎

The object's local translation vector.

Returns:

velocity⚓︎

The object's local velocity.

Returns:

vertexColorProperty⚓︎

Convenient access to this object's vertex coloring property. Setting this value to be nil will erase the property, while setting it to a valid vertex coloring property will set (or replace) it.

Returns:

viewDistance⚓︎

The view distance of the camera.

Returns:

  • result (number)

worldBoundOrigin⚓︎

The world coordinates of the object's bounds origin.

Returns:

worldBoundRadius⚓︎

The radius of the object's bounds.

Returns:

  • result (number)

worldDirection⚓︎

Defines the X-axis of the camera.

Returns:

worldRight⚓︎

Defines the Z-axis of the camera.

Returns:

worldToCamera⚓︎

The world-to-camera transform matrix in row-major order.

Returns:

worldTransform⚓︎

The object's transformations in the world space.

Returns:

worldUp⚓︎

Defines the Y-axis of the camera.

Returns:

zBufferProperty⚓︎

Convenient access to this object's z-buffer property. Setting this value to be nil will erase the property, while setting it to a valid z-buffer property will set (or replace) it.

Returns:

Methods⚓︎

addExtraData⚓︎

Appends an extra data to the object.

myObject:addExtraData(extraData)

Parameters:

attachProperty⚓︎

Attaches a property to this object, without checking to see if the property or another of its type is already on the list. Property lists must not have more than one property of a given class (i.e. no two niTexturingProperty objects) attached at once, or else undefined behavior will result.

myObject:attachProperty(property)

Parameters:

clear⚓︎

This method clears the current render target of the camera's renderer. Uses flag values from ni.cameraClearFlags.

myObject:clear(flags)

Parameters:

clearTransforms⚓︎

Resets the object's local transform.

myObject:clearTransforms()

click⚓︎

This method renders the currently-attached scene graph to the active renderer.

myObject:click(something)

Parameters:

  • something (boolean): Default: false.

clone⚓︎

Creates a copy of this object.

local result = myObject:clone()

Returns:

copyTransforms⚓︎

Update object's local transform by copying from another source.

myObject:copyTransforms(source)

Parameters:

detachAllProperties⚓︎

Detaches all the properties on the object and returns them in the table.

local result = myObject:detachAllProperties()

Returns:

detachProperty⚓︎

Detaches and returns a property from the object which matches the given property type.

local result = myObject:detachProperty(type)

Parameters:

Returns:

getGameReference⚓︎

Searches for an niExtraData on this object to see if it has one that holds a related reference.

local reference = myObject:getGameReference(searchParents)

Parameters:

  • searchParents (boolean): Default: false. If true, all parent objects (if applicable) are also searched.

Returns:

getObjectByName⚓︎

Searches this node and all child nodes recursively for a node with a name that matches the argument.

local result = myObject:getObjectByName(name)

Parameters:

  • name (string)

Returns:

getProperty⚓︎

Gets an attached property by property type.

local result = myObject:getProperty(type)

Parameters:

Returns:

getStringDataStartingWith⚓︎

Searches for an niExtraData on this object to see if it has niStringExtraData that has its string start with the provided value argument.

local extra = myObject:getStringDataStartingWith(value)

Parameters:

  • value (string): The first niStringExtraData starting with this value will be returned.

Returns:

getStringDataWith⚓︎

Searches for an niExtraData on this object to see if it has niStringExtraData that has the provided value argument in its string field.

local extra = myObject:getStringDataWith(value)

Parameters:

  • value (string): The first niStringExtraData with this word will be returned.

Returns:

hasStringDataStartingWith⚓︎

Searches for an niExtraData on this object to see if it has niStringExtraData that has its string start with the provided value argument. Returns true if the value was found.

local result = myObject:hasStringDataStartingWith(value)

Parameters:

  • value (string): The value to search for.

Returns:

  • result (boolean)

hasStringDataWith⚓︎

Searches for an niExtraData on this object to see if it has niStringExtraData that contains the provided value argument in its string field. Returns true if the value was found.

local result = myObject:hasStringDataWith(value)

Parameters:

  • value (string): The value to search for.

Returns:

  • result (boolean)

isAppCulled⚓︎

Recursively checks if either the object or any of its parents are appCulled.

local result = myObject:isAppCulled()

Returns:

  • result (boolean)

isFrustumCulled⚓︎

Checks if the object is frustum culled for the given camera.

local result = myObject:isFrustumCulled(camera)

Parameters:

Returns:

  • result (boolean)

isInstanceOfType⚓︎

Determines if the object is of a given type, or of a type derived from the given type.

local result = myObject:isInstanceOfType(type)

Parameters:

Returns:

  • result (boolean)

isOfType⚓︎

Determines if the object is of a given type.

local result = myObject:isOfType(type)

Parameters:

Returns:

  • result (boolean)

lookAtWorldPoint⚓︎

Update the camera's local rotation so that it is looking at the given point, with an up vector as close as possible to the given up vector. Both parameters are assumed to be in world space.

local success = myObject:lookAtWorldPoint(point, up)

Parameters:

Returns:

  • success (boolean): It's false when the provided location is equal to the location of the camera. It's true on success.

prependController⚓︎

Add a controller to the object as the first controller.

myObject:prependController(controller)

Parameters:

propagatePositionChange⚓︎

Alias for update() method. Updates the world transforms of this node and its children, which makes changes visible for rendering. Use after changing any local rotation, translation, scale, bounds or after attaching and detaching nodes.

Tip

It's best to "batch up" calls to this method. For example, when transform of an object its parent and grandparent are all changed during the same frame, it is much more efficient to call this method only on the grandparent object after all transforms have been changed. Also, consider calling this function as low as possible on a scene graph.

myObject:propagatePositionChange({ time = ..., controllers = ..., bounds = ... })

Parameters:

  • args (table): Optional.
    • time (number): Default: 0. This parameter is the time-slice for transformation and bounds updates
    • controllers (boolean): Default: false. Update object's controllers?
    • bounds (boolean): Default: true. Update object's bounds?

removeAllControllers⚓︎

Removes all controllers.

myObject:removeAllControllers()

removeAllExtraData⚓︎

Removes all extra data.

myObject:removeAllExtraData()

removeController⚓︎

Removes a controller from the object.

myObject:removeController(controller)

Parameters:

removeExtraData⚓︎

Removes a specific extra data from the object.

myObject:removeExtraData(extraData)

Parameters:

saveBinary⚓︎

Serializes the object, and writes it to the given file.

local success = myObject:saveBinary(path)

Parameters:

  • path (string): The path to write the file at, relative to the Morrowind installation folder.

Returns:

  • success (boolean): If true the object was successfully serialized.

setFlag⚓︎

Sets a given flag in the niObjectNET flag data. The specifics use of the flag is dependent on the real underlying type.

myObject:setFlag(state, index)

Parameters:

  • state (boolean)
  • index (number)

swapBuffers⚓︎

Causes the current backbuffer of the attached display to be drawn to the frontbuffer, by swapping the two.

myObject:swapBuffers()

update⚓︎

Updates the world transforms of this node and its children, which makes changes visible for rendering. Use after changing any local rotation, translation, scale, bounds or after attaching and detaching nodes.

Update Efficiency

It's best to "batch up" calls to this method. For example, when transform of an object its parent and grandparent are all changed during the same frame, it is much more efficient to call this method only on the grandparent object after all transforms have been changed. Also, consider calling this function as low as possible on a scene graph.

myObject:update({ time = ..., controllers = ..., children = ... })

Parameters:

  • args (table): Optional.
    • time (number): Default: 0. This parameter is passed to controllers. Only needed if controllers are being updated.
    • controllers (boolean): Default: false. Update controllers before updating transforms.
    • children (boolean): Default: true. Recursively updates the children of this node.

updateEffects⚓︎

Update all attached effects. This method must be called at or above any object when dynamic effects are attached or detached from it

myObject:updateEffects()

updateProperties⚓︎

Update all attached properties.

myObject:updateProperties()

windowPointToRay⚓︎

Given a screen space position, calculates the world position and outlook direction. This can be useful when trying to find a reference under a UI element, such as the cusor.

local origin, direction = myObject:windowPointToRay(point)

Parameters:

  • point (tes3vector2, number[]): The screen position to calculate a world ray for. Screen space is measured as ([-screenWidth/2, screenWidth/2], [-screenHeight/2, screenHeight/2]) with up-right being positive and an origin at the center of the screen. The screen size settings used are scaled by MGE XE UI scaling setting. These can be retrieved with tes3ui.getViewportSize.

Returns:

  • origin (tes3vector3): The world point that the given screen position looks out from.
  • direction (tes3vector3): The look direction of the camera from the given origin point.
Example: Sampling landscape texture under the crosshair/mouse cursor 
local function onEnterFrame()
    local cursor = tes3.getCursorPosition()
    local camera = tes3.worldController.worldCamera.cameraData.camera
    local position, direction = camera:windowPointToRay({ cursor.x, cursor.y })

    local hit = tes3.rayTest({
        position = position,
        direction = direction,
        -- Let's ray test agains terrain
        root = tes3.game.worldLandscapeRoot
    })
    if not hit or not hit.object then return end

    local texturingProperty = hit.object.texturingProperty
    if not texturingProperty then return end

    local baseMap = texturingProperty.maps[1]
    if not baseMap or not baseMap.texture then return end

    tes3.messageBox(baseMap.texture.fileName)
end

local function onLoaded()
    if event.isRegistered(tes3.event.enterFrame, onEnterFrame) then return end

    event.register(tes3.event.enterFrame, onEnterFrame)
end

event.register(tes3.event.loaded, onLoaded)

worldPointToScreenPoint⚓︎

Given a world coordinate position, calculates where that point relates to the screen space. Returns nil if the world point is ourside of camera's view.

local screenPosition = myObject:worldPointToScreenPoint(point)

Parameters:

  • point (tes3vector3): The world position to calculate screen position for.

Returns:

  • screenPosition (tes3vector2, nil): The screen space position. Screen space is measured as ([-screenWidth/2, screenWidth/2], [-screenHeight/2, screenHeight/2]) with up-right being positive and an origin at the center of the screen.