Model component

Defold is at its core a 3D engine. Even when you work with 2D material only all rendering is done in 3D, but orthographically projected onto the screen. Defold allows you to utilize full 3D content by including 3D assets, or Models into your collections. You can build games in strictly 3D with only 3D assets, or you can mix 3D and 2D content as you wish.

Creating a model component

Model components are created just like any other game object component. You can do it two ways:

• Create a Model file by right-clicking a location in the Assets browser and select New... ▸ Model.
• Create the component embedded directly into a game object by right-clicking a game object in the Outline view and selecting Add Component ▸ Model.

With the model created you need to specify a number of properties:

Model properties

Apart from the properties Id, Position and Rotation the following component specific properties exist:

Scene

The glTF .gltf or .glb file that contains the model’s geometry. If the file contains morph targets, they are imported together with the scene. This property was previously named Mesh.

Mesh

An optional named mesh from the selected Scene. Leave this field empty to render the whole scene with its imported transforms. Select a mesh to render that mesh once in its local coordinates, without the glTF node transforms. Position, rotate and scale the model component or its game object to place the selected mesh.

Create GO Bones

Check this to create a game object for every bone of the model. You can use the game objects to attach other game objects such as weapons to hand bones and so on.

Skeleton

This property should refer to the glTF .gltf or .glb file that contains the skeleton to use for animation. Note that Defold requires a single root bone in your hierarchy.

Animations

Set this to the Animation Set File that contains the animations you want to use on the model.

Default Animation

This is the animation (from the animation set) that will be automatically played on the model.

In addition to the properties above there will also be a field to assign a material for every mesh of the model:

Material

Set this property to a material suitable for the model. Use a built-in gltf material for physically based rendering of glTF material properties, a built-in model material for general model shading, or your own custom material. See the material variants below and the PBR manual.

Depending on the material there will be one or more texture properties:

Texture

This property should point to the texture image that you want applied to the object. It can be a separate project asset or an embedded image exposed under a glTF or GLB file in the Assets pane.

Selecting a glTF or GLB Scene, or changing its Mesh selection, can offer to fill the material and texture bindings. Auto Fill replaces existing bindings with those from the source; Keep Current preserves your bindings while applying the new scene or mesh selection. See the model import workflow.

Editor manipulation

With the model component in place you are free to edit and manipulate the component and/or the encapsulating game object with the regular Scene Editor tools to move, rotate and scale the model to your liking.

Runtime manipulation

You can manipulate models in runtime through a number of different functions and properties (refer to the API docs for usage).

Runtime animation

Defold provides powerful support for controlling animation in runtime. More in the model animation manual:

local play_properties = { blend_duration = 0.1 }
model.play_anim("#model", "jump", go.PLAYBACK_ONCE_FORWARD, play_properties)

The animation playback cursor can be animated either by hand or through the property animation system:

-- set the run animation
model.play_anim("#model", "run", go.PLAYBACK_NONE)
-- animate the cursor
go.animate("#model", "cursor", go.PLAYBACK_LOOP_PINGPONG, 1, go.EASING_LINEAR, 10)

Models can also use glTF morph target animations. Morph target weights are animated with model.play_anim() like other model animations, and can be read or overridden at runtime using model.get_blend_weights() and model.set_blend_weights(). See the morph targets section in the model animation manual for details.

Changing properties

A model also has a number of different properties that can be manipulated using go.get() and go.set():

animation

The current model animation (hash) (READ ONLY). You change animation using model.play_anim() (see above).

cursor

The normalized animation cursor (number).

material

The model material (hash). You can change this using a material resource property and go.set(). Refer to the API reference for an example.

playback_rate

The animation playback rate (number).

textureN

The model textures where N is 0-15 (hash). You can read these properties with go.get() and change them using a texture resource property and go.set(). Defold supports at most 16 textures per draw, but the number usable by a shader may be lower on graphics adapters with a smaller texture-sampler limit.

Material

3D software commonly allows you to set properties on your object vertices, like coloring and texturing. This information goes into the glTF .gltf or .glb file that you export from your 3D software. Depending on the requirements of your game you will have to select and/or create appropriate and performant materials for your objects. A material combines shader programs with a set of parameters for rendering of the object.

The following built-in materials are available in /builtins/materials/:

The gltf materials provide built-in metallic/roughness lighting using the imported glTF material data. See the PBR manual for texture bindings, lights and custom shaders.

All of these built-in materials use local vertex space. For skinned models, local vertex space allows the vertex shader to perform skinning on the GPU using a bone-matrix texture; local vertex space is also required for model instancing. A custom material intended for GPU-skinned or instanced models should therefore use the Local vertex-space setting.

The bone-matrix cache uses an RGBA32F texture. If the active graphics adapter does not support that texture format, Defold cannot create an animated Model component that uses a local-space material. On OpenGL ES 2.0 and WebGL 1.0, support therefore depends on the adapter’s floating-point texture extension. For compatibility with an adapter that lacks it, use a custom world-space material, which uses CPU skinning and cannot use model instancing. The cache dimensions can be adjusted with the Model project settings.

If you need to create custom materials for your models, see the Material documentation for information. The Shader manual contains information on how shader programs work.

Material constants

The default model material has the following constants that can be changed using go.set() or go.animate() (refer to the Material manual for more details). Examples:

go.set("#model", "tint", vmath.vector4(1,0,0,1))
go.animate("#model", "tint", go.PLAYBACK_LOOP_PINGPONG, vmath.vector4(1,0,0,1), go.EASING_LINEAR, 2)

tint

The color tint of the model (vector4). The vector4 is used to represent the tint with x, y, z, and w corresponding to the red, green, blue and alpha tint.

Rendering

The default render script draws materials with the model tag, including the built-in model and glTF materials. To render them in a custom render script, create a matching predicate and draw it with a view and projection suitable for your scene. For instance:

  function init(self)
    self.model_pred = render.predicate({"model"})
    ...
  end

  function update()
    ...
    render.set_depth_mask(true)
    render.enable_state(graphics.STATE_DEPTH_TEST)
    render.set_projection(stretch_projection(-1000, 1000))  -- orthographic
    render.draw(self.model_pred)
    render.set_depth_mask(false)
    ...
  end

See the Render documentation for details on how render scripts work.