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¶

class Item¶

module:

findByName(name)¶

Find an object by name and return it

Parameters:

name (str)

Return type:

Object

findById(id)¶

Find an object by its id and return it

Parameters:

id (str)

Return type:

Object

static create(itemType, attributes)¶

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

Parameters:

• itemType (str) – type of item to create.

• attributes (table) – the attributes to use to create the item. Leave nil to use defaults.

Returns:

a promise resolving to the created item

Return type:

Promise

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()¶

Return the ID of an item

Returns:

ID

Return type:

str

getName()¶

Return the name of an item

Returns:

Name

Return type:

str

getType()¶

Return the type of an item

Returns:

Type

Return type:

str

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:

the created material

Return type:

Material

set(name, value)¶

Set a field of the item to a new value

Parameters:

• name (str)

• value (str)

get(name)¶

Get an item field’s value

Parameters:

name (str) – name of the field

setFieldValue(name, value)¶

Deprecated since version 25.11: Use get which is the new shorter version

Set a field of the item to a new value

Parameters:

• name (str)

• value (str)

setFieldColorValue(name, value)¶

Deprecated since version 25.09: Use set which handle the correct type automatically.

Set a field of the item to a new color value

Parameters:

• name (str)

• value (Color)

setFieldNumberValue(name, value)¶

Deprecated since version ?.

Set a field of the item to a new number value

Parameters:

• name (str)

• value (number)

setFieldEnumValue(name, value, refEnum)¶

Deprecated since version 25.09: Use set which handle the correct type automatically.

Set a field of the item to a new enum value

Parameters:

• name (str)

• value (number)

• refEnum (table) – reference enum table to verify value against

setFieldBooleanValue(name, value)¶

Set a field of the item to a new boolean value

Parameters:

• name (str)

• value (boolean)

getFieldValue(name)¶

Deprecated since version 25.11: Use get which is the new shorter version

Get an item field’s value

Parameters:

name (str) – name of the field

getFieldColorValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

Returns:

value of the field

Return type:

Color

getFieldNumberValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

Returns:

value of the field

Return type:

number

getFieldEnumValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

Returns:

value of the field

Return type:

str

getFieldBooleanValue()¶

Deprecated since version 25.09: Use get which always returns the correct type.

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

Returns:

value of the field

Return type:

boolean

getLinkItem(name)¶

Deprecated since version 25.11: Use get which also handles items

Get a link of the item to a new value

Parameters:

name (str) – name of the link field

Returns:

handle of the linked item or nil if not set

Return type:

number

setLinkItem(name, item)¶

Deprecated since version 25.11: Use set which also handles items

Set a link from the item

Parameters:

• name (str) – name of the link field

• item (str) – value can be either an item ID or an Item object