Item¶

The Item class represents an item within a scene, providing methods to create, delete, find, and manipulate items by name, ID, and field values. The class supports operations such as retrieving item properties, and setting various field values including colors, numbers, enums, and booleans. This class is essential for managing scene objects dynamically, enabling users to interact with the scene’s items programmatically through a structured set of functions tailored for different data types and use cases.

Inherits from¶

Object

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

create(type, attributes)¶

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

Parameters:

• type (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

setFieldValue(name, value)¶

Set a field of the item to a new value

Parameters:

• name (str)

• value (str)

setFieldColorValue(name, value)¶

Deprecated since version 25.09: Use setFieldValue 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 setFieldValue 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)¶

Get an item field’s value

Parameters:

name (str) – name of the field

getFieldColorValue()¶

Deprecated since version 25.09: Use getFieldValue 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 getFieldValue 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 getFieldValue 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 getFieldValue 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)¶

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

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