Properties

Defold exposes properties for game objects, components and GUI nodes that can be read, set and animated. The following types of properties exist:

• System defined game object transforms (position, rotation and scale) and component specific properties (for example a sprite’s pixel size or a collision object’s mass)
• User defined script component properties defined in Lua scripts (see Script properties documentation for details)
• GUI node properties
• Shader constants defined in shaders and material files (see Material documentation for details)

Depending on where a property is found, you access it via a generic function, or a property-specific function. Many of the properties can be automatically animated. Animating properties through the built-in system is highly recommended over manipulating the properties yourself (inside an update() function), both for performance reasons as well as convenience.

Composite properties of type vector3, vector4 or quaternion also expose their sub-components (x, y, z and w). You can address the components individually by suffixing the name with a dot (.) and the name of the component. For example, to set the x-component of a game object’s position:

-- Set the x position of "game_object" to 10.
go.set("game_object", "position.x", 10)

The functions go.get(), go.set() and go.animate() take a reference as their first parameter and a property identifier as their second. The reference identifies the game object or component and can be a string, a hash or a URL. URLs are explained in detail in the addressing manual. The property identifier is a string or hash that names the property:

-- Set the x-scale of the sprite component
local url = msg.url("#sprite")
local prop = hash("scale.x")
go.set(url, prop, 2.0)

For GUI nodes, the node identifier is provided as the first parameter to the property specific function:

-- Get the color of the button
local node = gui.get_node("button")
local color = gui.get_color(node)

Game object and component properties

All game objects, and some component types have properties that can be read and manipulated in runtime. Read these values with go.get() and write them with go.set(). Depending on the property value type, you can animate the values with go.animate(). A small set of the properties are read only.

get

Can be read with go.get().

get+set

Can be read with go.get() and written with go.set(). Numerical values can be animated with go.animate().

GAME OBJECT PROPERTIES

SPRITE COMPONENT PROPERTIES

COLLISION OBJECT COMPONENT PROPERTIES

MODEL (3D) COMPONENT PROPERTIES

LABEL COMPONENT PROPERTIES

GUI node properties

GUI nodes also contain properties, but they are read and written through special getter and setter functions. For each property there exists one get- and one set- function. There is also a set of constants defined to use as reference to the properties when animating them. If you need to refer to separate property components you have to use the string name of the property, or a hash of the string name.

• position (or gui.PROP_POSITION)
• rotation (or gui.PROP_ROTATION)
• scale (or gui.PROP_SCALE)
• color (or gui.PROP_COLOR)
• outline (or gui.PROP_OUTLINE)
• shadow (or gui.PROP_SHADOW)
• size (or gui.PROP_SIZE)
• fill_angle (or gui.PROP_FILL_ANGLE)
• inner_radius (or gui.PROP_INNER_RADIUS)
• slice9 (or gui.PROP_SLICE9)

Note that all color values are encoded in a vector4 where the components correspond to the RGBA values:

x

The red color component

y

The green color component

z

The blue color component

w

The alpha component

GUI NODE PROPERTIES