Class View.DisplayItem

Represents a Display Item.

Functions

DisplayItem(name, objectID, [pos], [rot], [scale], [meshBits]) Create a DisplayItem object.
GetItemByName(name) Get a DisplayItem by its name.
RemoveItem(name) Remove a DisplayItem by its name.
ClearAllItems() Clear all DisplayItems.
IsNameInUse(name) Check if a given name is used by a DisplayItem.
IsObjectIDInUse(Slot) Check if an object ID is in use by a DisplayItem.
SetAmbientLight(color) Set the ambient color for all DisplayItems.
SetCameraPosition(pos, [disableInterpolation]) Set the camera location.
SetTargetPosition(pos, [disableInterpolation]) Set the camera target location.
SetFOV([fov], [disableInterpolation]) Set the field of view for DisplayItems.
GetAmbientLight() Get the ambient color of the display items.
GetCameraPosition() Get the camera position.
GetTargetPosition() Get the position of the camera target.
GetFOV() Get field of view angle for DisplayItems.
ResetCamera() Reset the camera position, camera target position, and field of view.

Class

DisplayItem:Remove() Remove the Display Item.
DisplayItem:Exists() Test if a Display Item exists.
DisplayItem:SetObjectID(objectID) Change the DisplayItem's object ID.
DisplayItem:SetPosition(pos, [disableInterpolation]) Set the DisplayItem's position.
DisplayItem:SetRotation(rot, [disableInterpolation]) Set the DisplayItem's rotation.
DisplayItem:SetScale(scale, [disableInterpolation]) Set the DisplayItem's scale.
DisplayItem:SetColor(color, [disableInterpolation]) Set the DisplayItem's color.
DisplayItem:SetMeshBits(meshBits) Set the packed MeshBits for the Display Item (for advanced users).
DisplayItem:SetMeshVisible(meshIndex, isVisible) Make the specified mesh visible or invisible.
DisplayItem:SetJointRotation(meshIndex, rot, [disableInterpolation]) Set the DisplayItem's joint rotation.
DisplayItem:SetVisible(isVisible) Set the DisplayItems's visibility.
DisplayItem:SetFrame(animNumber, frameNumber) Set the frame number from an animation.
DisplayItem:GetObjectID() Retrieve the object ID from a DisplayItem.
DisplayItem:GetPosition() Get the DisplayItem's position.
DisplayItem:GetRotation() Get the DisplayItem's rotation.
DisplayItem:GetScale() Get the DisplayItem's visual scale.
DisplayItem:GetColor() Get the DisplayItem's color.
DisplayItem:GetMeshVisible(index) Get the visibility state of a specified mesh in the DisplayItem.
DisplayItem:GetJointRotation(meshIndex) Get the DisplayItem's joint rotation.
DisplayItem:GetVisible() Get the DisplayItem's visibility state.
DisplayItem:GetAnim() Get the active animation number.
DisplayItem:GetFrame() Get the current frame number of the active animation.
DisplayItem:GetEndFrame() Get the end frame number of the DisplayItems's active animation.
DisplayItem:GetBounds() Get the projected 2D bounding box of the DisplayItem.


Functions

DisplayItem(name, objectID, [pos], [rot], [scale], [meshBits])
Create a DisplayItem object.

Parameters:

  • name string Lua name of the display item.
  • objectID ObjID Slot object ID.
  • pos Vec3 Position in 3D display space. Default: Vec3(0, 0, 0).
  • rot Rotation Rotation on the XYZ axes. Default: Rotation(0, 0, 0).
  • scale Vec3 Visual scale. Default: Vec3(1, 1, 1).
  • meshBits int Packed meshbits. Optional.

Returns:

    DisplayItem A new DisplayItem object.

Usage:

    local item = TEN.View.DisplayItem("My name", -- name
TEN.Objects.ObjID.PISTOLS_ITEM, -- object ID)
GetItemByName(name)
Get a DisplayItem by its name.

Parameters:

  • name string Unique DisplayItem name.

Returns:

    DisplayItem DisplayItem reference.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
RemoveItem(name)
Remove a DisplayItem by its name.

Parameters:

  • name string Unique DisplayItem.

Usage:

    local item = TEN.View.DisplayItem.RemoveItem("My name")
ClearAllItems()
Clear all DisplayItems.

Usage:

    TEN.View.DisplayItem.ClearAllItems()
IsNameInUse(name)
Check if a given name is used by a DisplayItem.

Parameters:

Returns:

    bool True if the name is used and a DisplayItem with a given name is present, false otherwise.

Usage:

    local test = TEN.View.DisplayItem.IsNameInUse("My name")
print(test)
IsObjectIDInUse(Slot)
Check if an object ID is in use by a DisplayItem. Only the first first matching DisplayItem will be checked and true will be returned immediately if found.

Parameters:

  • Slot ObjID object ID to find.

Returns:

    bool True if ObjectID is used by a DisplayItem, false if not.

Usage:

    local isUsed = TEN.View.DisplayItem.IsObjectIDInUse(TEN.Objects.ObjID.PISTOLS_ITEM)
print(isUsed)
SetAmbientLight(color)
Set the ambient color for all DisplayItems.

Parameters:

  • color Color New ambient color for all DisplayItems.

Usage:

    TEN.View.DisplayItem.SetAmbientLight(TEN.Color(128, 200, 255))
SetCameraPosition(pos, [disableInterpolation])
Set the camera location. This single camera is used for all DisplayItems.

Parameters:

  • pos Vec3 New camera position.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    TEN.View.DisplayItem.SetCameraPosition(TEN.Vec3(0, 0, 1024))
SetTargetPosition(pos, [disableInterpolation])
Set the camera target location.

Parameters:

  • pos Vec3 New target camera position.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    TEN.View.DisplayItem.SetTargetPosition(TEN.Vec3(0, 0, 1024))
SetFOV([fov], [disableInterpolation])
Set the field of view for DisplayItems.

Parameters:

  • fov float Field of fiew angle in degrees (clamped to [10, 170]). Default: 80.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    TEN.View.DisplayItem.SetFOV(80)
GetAmbientLight()
Get the ambient color of the display items.

Returns:

    Color Ambient color.

Usage:

    local color = TEN.View.DisplayItem.GetAmbientLight()
GetCameraPosition()
Get the camera position. This single camera is used for all DisplayItems.

Returns:

    Vec3 Camera position for all DisplayItems.

Usage:

    local camPos = TEN.View.DisplayItem.GetCameraPosition()
GetTargetPosition()
Get the position of the camera target.

Returns:

    Vec3 The camera target position for all of the DisplayItems..

Usage:

    local targetPosition = TEN.View.DisplayItem.GetTargetPosition()
GetFOV()
Get field of view angle for DisplayItems.

Returns:

    float Current FOV angle in degrees.

Usage:

    local fieldOfView = TEN.View.DisplayItem.GetFOV()
ResetCamera()
Reset the camera position, camera target position, and field of view.

Usage:

    local targetPosition = TEN.View.DisplayItem.ResetCamera()

Class

Methods for DisplayItem instances.

Quick Reference: Return Values

MethodReturns on SuccessReturns on Failure
Existstrue/falseNever fails
GetObjectIDObjects.ObjIDnil
GetPositionVec3nil
GetRotationRotationnil
GetScalenumbernil
GetColorColornil
GetMeshVisibletrue/falsefalse
GetJointRotationRotationnil
GetVisibletrue/falsefalse
GetAnimnumbernil
GetFramenumbernil
GetEndFramenumbernil
GetBounds{Vec2, Vec2}nil

Best Practices

1. Always Check Existence

Before using a DisplayItem, always verify it exists to avoid nil errors:

local item = TEN.View.DisplayItem.GetItemByName("myItem")
if item:Exists() then
    local pos = item:GetPosition()
    if pos then  -- Double check for safety
        print("Position:", pos.x, pos.y, pos.z)
    end
end


2. Handle nil Returns Gracefully

Methods that can fail return nil. Use one of the following patterns:

local item = TEN.View.DisplayItem.GetItemByName("My name")

-- Pattern 1: if-check (recommended)
local pos = item:GetPosition()
if pos then
    print("Position:", pos.x, pos.y, pos.z)
end

-- Pattern 2: default value
local pos = item:GetPosition()
if not pos then
    pos = TEN.Vec3(0, 0, 0)
end

-- Pattern 3: early return (useful in functions)
local function updateItem(name)
    local item = TEN.View.DisplayItem.GetItemByName(name)
    if not item:Exists() then return end

    local pos = item:GetPosition()
    if not pos then return end

    -- Safe to use pos here
    item:SetPosition(pos + TEN.Vec3(0, 10, 0))
end


3. Common Mistakes Not checking if item exists:

local pos = item:GetPosition()
print(pos.x)  -- ERROR if the item doesn't exist.

Always check first:

if item:Exists() then
    local pos = item:GetPosition()
    if pos then print(pos.x) end
end
DisplayItem:Remove()
Remove the Display Item.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:Remove()
DisplayItem:Exists()
Test if a Display Item exists.

Returns:

    bool true if the Display Item exists, false otherwise.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("M name")
local test = item:Exists()
print(test)
DisplayItem:SetObjectID(objectID)
Change the DisplayItem's object ID.

Parameters:

  • objectID ObjID New slot object ID.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetObjectID(TEN.Objects.ObjID.BIGMEDI_ITEM)
DisplayItem:SetPosition(pos, [disableInterpolation])
Set the DisplayItem's position.

Parameters:

  • pos Vec3 New position.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetPosition(TEN.Vec3(0, 200, 1024))
DisplayItem:SetRotation(rot, [disableInterpolation])
Set the DisplayItem's rotation.

Parameters:

  • rot Rotation New rotation.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetRotation(TEN.Rotation(0, 200, 1024))
DisplayItem:SetScale(scale, [disableInterpolation])
Set the DisplayItem's scale.

Parameters:

  • scale float New scale.
  • disableInterpolation bool Disable interpolation to allow snap movements. Default: false.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetScale(2))
DisplayItem:SetColor(color, [disableInterpolation])
Set the DisplayItem's color.

Parameters:

  • color Color New color.
  • disableInterpolation bool Disable interpoaltion to allow snap color changes. Default: false.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetColor(TEN.Color(128, 200, 255))
DisplayItem:SetMeshBits(meshBits)
Set the packed MeshBits for the Display Item (for advanced users).

Parameters:

  • meshBits int Packed MeshBits to be set.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetMeshBits(3)
DisplayItem:SetMeshVisible(meshIndex, isVisible)
Make the specified mesh visible or invisible. Used to show or hide a mesh in a DisplayItem.

Parameters:

  • meshIndex int Mesh index.
  • isVisible bool True to set visible, false to set invisible.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetMeshVisible(1, false)
DisplayItem:SetJointRotation(meshIndex, rot, [disableInterpolation])
Set the DisplayItem's joint rotation.

Parameters:

  • meshIndex int Joint index..
  • rot Rotation New rotation.
  • disableInterpolation bool Disables interpolation to allow for snap movements. Default: false.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetJointRotation(1, TEN.Rotation(0, 200, 0))
DisplayItem:SetVisible(isVisible)
Set the DisplayItems's visibility.

Parameters:

  • isVisible bool True to set visible, false to set invisible.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetVisible(true)
DisplayItem:SetFrame(animNumber, frameNumber)
Set the frame number from an animation. This will set the specified animation to the given frame. The number of frames in an animation can be seen under the heading "End frame" in the WadTool animation editor.

Parameters:

  • animNumber int Animation number to set.
  • frameNumber int Frame number to set.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
item:SetFrame(2, 10)
DisplayItem:GetObjectID()
Retrieve the object ID from a DisplayItem.

Returns:

    ObjID Slot object ID.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local objectID = item:GetObjectID()
end
DisplayItem:GetPosition()
Get the DisplayItem's position.

Returns:

    Vec3 Position.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local objectPosition = item:GetPosition()
end
DisplayItem:GetRotation()
Get the DisplayItem's rotation.

Returns:

    Rotation Rotation.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local objectRotation = item:GetRotation()
end
DisplayItem:GetScale()
Get the DisplayItem's visual scale.

Returns:

    float Visual scale.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local objectScale = item:GetScale()
end
DisplayItem:GetColor()
Get the DisplayItem's color.

Returns:

    Color Color.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
local objectColor = item:GetColor()
DisplayItem:GetMeshVisible(index)
Get the visibility state of a specified mesh in the DisplayItem.

Parameters:

  • index int Index of a mesh.

Returns:

    bool Visibility status.

Or

    bool False if the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local test = item:GetMeshVisible(1)
   print(test)
end
DisplayItem:GetJointRotation(meshIndex)
Get the DisplayItem's joint rotation.

Parameters:

  • meshIndex int Index of the joint to check.

Returns:

    Rotation Joint rotation.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local jointRotation = item:GetJointRotation(1)
end
DisplayItem:GetVisible()
Get the DisplayItem's visibility state.

Returns:

    bool Visibility state.

Or

    bool False if the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local test = item:GetVisible()
   print(test)
end
DisplayItem:GetAnim()
Get the active animation number. This corresponds to the number shown in the item's animation list in WadTool.

Returns:

    int Active animation number.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local animNumber = item:GetAnim()
end
DisplayItem:GetFrame()
Get the current frame number of the active animation.

Returns:

    int Current frame number of the active animation.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local frameNumber = item:GetFrame()
end
DisplayItem:GetEndFrame()
Get the end frame number of the DisplayItems's active animation. This is the "End Frame" set in WADTool for the animation.()

Returns:

    int End frame number of the active animation.

Or

    nil If the DisplayItem does not exist.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local endFrame = item:GetEndFrame()
end
DisplayItem:GetBounds()
Get the projected 2D bounding box of the DisplayItem. Projects the DisplayItem into display space and returns two Vec2 values.

Returns:

  1. Vec2 center Projected center position in display space percent.
  2. Vec2 size The projected width/height in display space percent.

Or

    nil If the DisplayItem does not exist or has no bounds.

Usage:

    local item = TEN.View.DisplayItem.GetItemByName("My name")
if item:Exists() then
   local bounds = item:GetBounds()
  if bounds then
       print("Center: ", bounds[1].x, bounds[1].y)
       print("Size: ", bounds[2].x, bounds[2].y)
     end
end
generated by TEN-LDoc (a fork of LDoc 1.4.6)