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)

Numeric properties display a drag handle when you hover over their input field. You can increase/decrease their value, by dragging the handle right/left or up/down respectively.

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 is provided as the first parameter to either a property-specific function or the generic gui.get() and gui.set() functions:

-- Get the color of the button
local node = gui.get_node("button")
local color = gui.get_color(node)
local same_color = gui.get(node, "color")
gui.set(node, "color.x", 1)

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 have property-specific getter and setter functions, such as gui.get_position() and gui.set_position(). The built-in properties listed below can alternatively be read and written with gui.get(node, property) and gui.set(node, property, value). Other node values may still require their dedicated functions. Material constants on GUI nodes also use the generic functions. To address one component of a vector property, append its name, for example gui.set(node, "color.x", 1).

The generic and property-specific functions do not always use identical value types. gui.get() returns a vector4 for the complete position, scale, size, and euler properties, while the corresponding property-specific functions return a vector3. gui.set() accepts either a vector3 or vector4 for those properties. The generic rotation property uses a quaternion; use euler when setting rotation in degrees.

• position (or gui.PROP_POSITION)
• rotation (or gui.PROP_ROTATION)
• euler (or gui.PROP_EULER)
• 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)
• leading (or gui.PROP_LEADING)
• tracking (or gui.PROP_TRACKING)
• 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