Skip to content

Item

The Item class represents a persistent asset or configuration within a project. Items define what something is, for example a mesh, material, particles' emitter configuration , or other reusable resource. They are stored data, not live objects in the running scene.

Items can be used to create or configure SceneGraph Objects, which are the actual instances that appear and behave in the scene during runtime. However, not all SceneGraph Objects necessarily originate from Items.

The Item class provides methods to create, delete, find, and modify these assets by name, ID, or field values. It allows you to retrieve and update item properties such as colors, numbers, enums, giving you full control over project data and configurations.

Item vs Scene Object

  • Item: a stored asset or configuration — something that exists persistently in your project (for example, a saved mesh, material, or emitter setup).
  • Scene Object (SceneObject): a live object in the scene — it represents what’s currently visible or active during runtime (for example, an SgSphere placed in the scene).

Usage

To use this class, add the following require at the top of your script:

local Item = require 'engine/item'

Reference

findByName

findByName(name)

Find an object by name and return it

Parameters

  • name (string)

Returns

  • Object

findById

findById(id)

Find an object by its id and return it

Parameters

  • id (string)

Returns

  • Object

create

static create(self, itemType, attributes)

Create a new item of specified type from scratch without an underlying item.

Parameters

  • self
  • itemType (string): type of item to create.
  • attributes (table): the attributes to use to create the item. Leave nil to use defaults.

Returns

  • Promise: promise resolving to the created item

delete

delete()

Delete an item. The item is only deleted if it is not referenced anymore. Furthermore, even after the last reference of the item is gone, the garbage collector will remove it only after a certain period of time of no reference.

getId

getId()

Return the ID of an item

Returns

  • string

getName

getName()

Return the name of an item

Returns

  • string

getType

getType()

Return the type of an item

Returns

  • string

createMaterial

createMaterial(attributes)

Create a new material from scratch without an underlying item.

Parameters

  • attributes (table): the attributes to use to create the material. Leave nil to use defaults.

Returns

  • Material: created material

set

set(name, value)

Set a field of the item to a new value

Parameters

  • name (string)
  • value (string)

get

get(name)

Get an item field's value

Parameters

  • name (string): name of the field

setFieldValue

setFieldValue(name, value)

Set a field of the item to a new value

Parameters

  • name (string)
  • value (string)

setFieldColorValue

setFieldColorValue(name, value)

Set a field of the item to a new color value

Parameters

  • name (string)
  • value (Color)

setFieldNumberValue

setFieldNumberValue(name, value)

Set a field of the item to a new number value

Parameters

  • name (string)
  • value (number)

setFieldEnumValue

setFieldEnumValue(name, value, refEnum)

Set a field of the item to a new enum value

Parameters

  • name (string)
  • value (number)
  • refEnum (table): reference enum table to verify value against

setFieldBooleanValue

setFieldBooleanValue(name, value)

Set a field of the item to a new boolean value

Parameters

  • name (string)
  • value (boolean)

getFieldValue

getFieldValue(name)

Get an item field's value

Parameters

  • name (string): name of the field

getFieldColorValue

getFieldColorValue(name)

Get the value of an item's field as color value

Parameters

  • name

Returns

  • Color: of the field

getFieldNumberValue

getFieldNumberValue(name)

Get the value of an item's field as number value

Parameters

  • name

Returns

  • number: of the field

getFieldEnumValue

getFieldEnumValue(name)

Get the value of an item's field as string value

Parameters

  • name

Returns

  • string: of the field

getFieldBooleanValue

getFieldBooleanValue(name)

Get the value of an item's field as boolean value

Parameters

  • name

Returns

  • boolean: of the field

getLinkItem

getLinkItem(name)

Get a link of the item to a new value

Parameters

  • name (string): name of the link field

Returns

  • number: of the linked item or nil if not set

setLinkItem

setLinkItem(name, item)

Set a link from the item

Parameters

  • name (string): name of the link field
  • item (string): value can be either an item ID or an Item object