Learn how to import 3D models to use in a scene
3D models are imported into decentraland in glTF format. There are a number of supported features that these models can include. This section goes over ways to make them compatible with Decentraland and best practices.
See Scene content guide for information on how you can configure a 3D model in a Decentraland scene to set its position, scale, activate its animations, etc.
Keep in mind that all models, their shaders and their textures must be within the parameters of the scene limitations.
All 3D models in Decentraland must be in glTF format. glTF (GL Transmission Format) is an open project by Khronos providing a common, extensible format for 3D assets that is both efficient and highly interoperable with modern web technologies.
glTF models can have either a .gltf or a .glb extension. glTF files are human-readable, you can open one in a text editor and read it like a JSON file. This is useful, for example, to verify that animations are properly attached and to check for their names. glb files are binary, so they’re not readable but they are considerably smaller in size, which is good for the scene’s performance.
We recommend using .gltf while you’re working on a scene, but then switching to .glb when uploading it.
The following aspects of a 3D model can either be embedded in a glTF file or referenced externally:
Note: Animations must be embedded inside the glTF file to use in Decentraland.
Blender doesn’t support exporting to glTF by default, but you can install a plugin to enable it.
scripts/addons/io_scene_gltf2folder under the
scripts/addonsfolder in your Blender installation.
Note: If you have another glTF 2.0 exporter installed, disable it. Only one can be enabled at a time.
When exporting 3D models that include multiple animations, make sure that all animations are embedded in the model. To do this, open the NLA editor and click Stash to add each animation to the model.
We recommend using the following export settings when exporting models with animations:
3D Studio Max doesn’t support exporting to glTF by default, but you can install a plugin to enable it.
Maya doesn’t support exporting to glTF by default, but you can install a plugin to enable it.
Note: As an alternative, you can try this other plugin too.
Unity doesn’t support exporting to glTF by default, but you can install a plugin to enable it.
Download the plugin from this link.
Note: As an alternative, you can try this other plugin too.
SketchUp doesn’t support exporting to glTF by default, but you can install a plugin to enable it.
Download the plugin from this link.
A quick and easy way to preview the contents of a glTF model before importing it into a scene is to use the Babylon.js Sandbox. Just drag and drop the glTF file (and its .bin file if applicable) into the canvas to view the model.
In the sandbox you can also view the animations that are embedded in the model, select which to display by picking it out of a dropdown menu.
Compared to the older OBJ format, which supports only vertices, normals, texture coordinates, and basic materials, glTF provides a more powerful set of features that includes:
Note: .obj models are supported in Decentraland scenes as a legacy feature, but will likely not be supported for much longer.
Compared to COLLADA, the supported features are very similar. However, because glTF focuses on providing a “transmission format” rather than an editor format, it is more interoperable with web technologies.
Consider this analogy: the .PSD (Adobe Photoshop) format is helpful for editing 2D images, but images must then be converted to .JPG for use on the web. In the same way, COLLADA may be used to edit a 3D asset, but glTF is a simpler way of transmitting it while rendering the same result.
Not all shaders can be used in models that are imported into Decentraland. Make sure you use one of the following:
Standard materials: any shaders are supported, for example diffuse, specular, transparency, etc.
Tip: When using Blender, these are the materials supported by Blender Render rendering.
PBR (Physically Based Rendering) materials: This shader is extremely flexible, as it includes properties like diffuse, roughness, metalness and emission that allow you to configure how a material interacts with light.
Tip: When using Blender, you can use PBR materials by setting Cycles rendering and adding the Principled BSDF shader. Note that none of the other shaders of the Cycles renderer are supported.
See entity interfaces for a full list of all the properties that can be configured in a material.
Textures can be embedded into the exported glTF file or referenced from an external file. Both ways are supported.
Texture sizes must use width and height numbers (in pixels) that match the following numbers:
1, 2, 4, 8, 16, 32, 64, 128, 256, 512
This sequence is made up of powers of two:
f(x) = 2 ^ x. 512 is the maximum number we allow for a texture size. This is a fairly common requirement among other rendering engines, it’s there due internal optimizations of the graphics processors.
The width and height don’t need to have the same number, but they both need to belong to this sequence.
The recommended size for textures is 512x512, we have found this to be the optimal size to be transported through domestic networks and to provide reasonable loading/quality experiences.
Examples of other valid sizes:
32x32 64x32 512x256 512x512
Although textures of arbitrary sizes work in the alpha release, the engine displays an alert in the console. We will enforce this restriction in coming releases and invalid texture sizes will cease to work.
Note: After referencing a file for a texture that won’t be embedded, make sure that file won’t be moved or renamed, as otherwise the reference to the file will be lost. The file must also be inside the scene folder so that it’s uploaded together with the scene.
To enable collisions between a 3D model and users of your scene, you must create a new object to serve as a collider. Without a collider, users are able to walk through models as if they weren’t there. For performance reasons, colliders usually have a much simpler geometry than the model itself.
Colliders currently don’t affect how models and entities interact with each other, they can always overlap. Colliders only affect how the model interacts with the user’s avatar.
For an object to be recognized by a Decentraland scene as a collider, all it needs is to be named in a certain way. The object’s name must include the the suffix “_collider” at the end.
For example, to create a collider for a tree, you can create a simple box object surrounding its trunk. Users of the scene won’t see this box, but it will block their path.
In this case, we can name the box “BoxTree_collider” and export both the tree and the box as a single _gltf model. The _collider tag alerts the Decentraland world engine that the box object belongs to the collection of colliders, making the _collider mesh invisible.
Whenever a player views the tree model in your scene, they will see the complex model for your tree. However, when they walk into your tree, they will collide with the box, not the tree.
Stairs are a very common use-case for collider objects. In order for users to climb stairs, there must be a corresponding _collider object that the users are able to step on.
We recommend using a ramp object for your stair colliders, this provides a much better experience when walking up or down. When they climb up your stairs, it will appear as a smooth ascent or descent, instead of requiring them to “jump” up each individual step.
Using a ramp object also avoids creating unnecessary geometry, saving room for other more complicated models. Keep in mind that collider geometry is also taken into account when calculating the scene limitations
Name the ramp object something similar to stairs_collider. It must end in _collider.
Overlay the ramp object to the stairs so that they occupy the same space.
Now when users view the stairs in your scene, they’ll see the more elaborate model of the stairs, but when they climb them, they’ll collide with the ramp.
Note: Remember that each scene is limited to log2(n+1) x 10000 triangles, where n is the number of parcels in your scene.
When duplicating collider objects, pay attention to their names. Some programs append a _1 to the end of the filename to avoid duplicates, for example tree_collider_1. Objects that are named like this will be interpreted by the Decentraland World Engine as normal objects, not colliders.
dcl startand then click
c. This draws blue lines that delimit all colliders in place.
3D models can be animated in a Decentraland scene using skeletal animations. All animations of a 3D model must be embedded inside its glTF file, you can’t reference animations in separate files.
Currently, other forms of animations that aren’t based on armatures are not supported.
There’s no specific rule about the names animations must have. You can verify the names of the animations in an exported model by opening the contents of a .gltf file with a text editor. Typically, an animation name is comprised of its armature name, an underscore and its animation name. For example
You can include any number of animations in a glTF model. All animations in a glTF model are disabled by default when loading the model into a Decentraland scene. See Scene content guide for instructions on how to activate and handle animations in a scene.
Note: There currently isn’t a way to change the frame rate of an animation displayed in your scene, the speed is fixed to a default setting. To change an animation’s speed, you must change the number of frames.
In a Decentraland scene, you can use
weight to blend several animations or to make an animation more subtle.
Tip: Instead of creating your own animations, you can also download generic animations and apply them to your model. For example, for 3D characters with human-like characteristics, you can download free or paid animations from Mixamo.
You can use a tool like Blender to create animations for a 3D model.
Create an armature, following the shape of your model and the parts you wish to move. You do this by adding an initial bone and then extruding all other bones from the vertices of that one. Bones in the armature define the points that can be articulated. The armature must be positioned overlapping the mesh.
Make both the armature and the mesh child assets of the same object.
Check that the mesh moves naturally when rotating its bones in the ways you plan to move it. If parts of the mesh get stretched in undesired ways, use weight paint to change what parts of the model are affected by each bone in the armature.
Note: There’s a reported bug with Babylon.js that prevents some faces of a mesh from being rendered when they’re not related to any bone in the armature. So if you paint some faces with weight 0 and then animate the model, you might see these faces dissappear. To solve this, we recommend making sure that each face is related to at least one bone of the armature and painted with a weight of at least 0.01.
Move the armature to a desired pose, all bones can be rotated or scaled. Then lock the rotation and scale of the bones you wish to control with this animation.
Switch to a different frame in the animation, position the armature into a new pose and lock it again. Repeat this process for all the key frames you want to set to describe the animation.
By default all frames in between the ones you defined will transition linearly from one pose to the next. You can also configure these transitions to behave exponentially, ease-in, bounce, etc.
To export a model with several embedded animations in Blender, you must create multiple actions from the Dope-Sheet.
You can also edit the animation from the Dope-Sheet view, for example you can adjust the distance between two key frames.
To preview the different actions, open the Action Editor (only accessible once you’re in the Dope Sheet).
In order to export multiple animations, you need to stash all the actions using the NLA Editor. We recommend opening the NLA editor on a separate editor tab while keeping the Dope sheet also open.
In the NLA Editor, select each action that you want to embed in the glTF model and click Stash.
When adding the model to your Decentraland scene, you must activate animations by configuring the gltf-model entity. See Scene content guide for instructions.