Hello! Please choose your
desired language:
Dismiss

3D model considerations

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.

Supported 3D model formats

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:

  • Textures can either be embedded or referenced from an external image file.
  • Binary data about geometry, animations, and other buffer-related aspects of the model can either be embedded or referenced from an external .bin file.

Note: Animations must be embedded inside the glTF file to use in Decentraland.

Export to glTF from Blender

Blender doesn’t support exporting to glTF by default, but you can install a plugin to enable it.

  1. Download the Khronos Exporter
  2. To install the exporter, extract the .zip file, and then copy the scripts/addons/io_scene_gltf2 folder under the scripts/addons folder in your Blender installation.
  3. Activate the addon by opening User Preferences… in Blender. In the Add-ons tab, enable Import-Export: glTF 2.0 format. Don’t forget to click Save User Settings.

    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:

Blender export menu

Export to glTF from 3D Studio Max

3D Studio Max doesn’t support exporting to glTF by default, but you can install a plugin to enable it.

  1. Download the plugin from this link.
  2. Install the plugin by following these instructions.
  3. Export glTF files using the plugin by following these instructions.

Export to glTF from Maya

Maya doesn’t support exporting to glTF by default, but you can install a plugin to enable it.

  1. Install the plugin by following these instructions.
  2. Export glTF files using the plugin by following these instructions.

Note: As an alternative, you can try this other plugin too.

Export to glTF from Unity

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.

Export to glTF from SketchUp

SketchUp doesn’t support exporting to glTF by default, but you can install a plugin to enable it.

Download the plugin from this link.

Preview a glTF model

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.

Why we use glTF

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:

  • Hierarchical objects
  • Skeletal structure and animation
  • More robust materials and shaders
  • Scene information (light sources, cameras)

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.

Materials

Shader support

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.

The image below shows two identical models, created with the same colors and textures. The model on the left uses all PBR materials, some of them include metalness, transparency, and emissiveness. The model on the right uses all standard materials, some including transparency and emissiveness.

See entity interfaces for a full list of all the properties that can be configured in a material.

Transparent and emissive materials

You can set a material to be transparent. Transparent materials can be seen through to varying degrees, depending on their alpha. To do this, activate the transparency property of the material and then set its alpha to the desired amount. An alpha of 1 will make the material completely opaque, an alpha of 0 will make it invisible.

You can also make a material emissive. Emissive materials cast their own light. Note that when rendered, they don’t actually illuminate nearby objects in the scene, they just seem to have a blurred glow around them.

The image below shows two identical models created with standard materials. The one on the left uses only opaque materials, the one on the right uses both transparent and emissive materials in some of its parts.

Textures

Textures can be embedded into the exported glTF file or referenced from an external file. Both ways are supported.

Texture size constraints

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.

How to swap a material

Suppose you’ve imported a 3D model that uses a material that’s not supported by Decentraland. You can easily change this material while still keeping the same texture and its mapping.

Model without valid material

To swap the material:

  1. Check the current material’s settings to see what texture files are being used and how they are configured.
  2. Delete the current material from the mesh.

  3. Create a new material.

    New default basic material

    Tip: If you’re using Blender and are on the Blender Render tab, it creates a basic material by default, which is supported by Decentraland.

  4. Open the Textures settings and create a new texture, importing the same image file that the original material used.

    New default basic texture

  5. The texture should be mapped to the new material just as it was mapped to the old material.

    Model with valid material

Best practices for materials

  • If your scene includes multiple models that use the same texture, reference the texture as an external file instead of having it embedded in the 3D model. Embedded textures get duplicated for each model and add to the scene’s size.

    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.

  • Read this article for a detailed overview of a full art pipeline that uses PBR textures in glTF models.
  • Find free, high quality PBR textures in cgbookcase.

Meshes

3D models have a mesh composed of triangular faces. These faces meet each other on edges (the lines along which they touch) and vertices (the points where their corners join).

Smooth geometries

You can configure a mesh to be smooth. This tells the engine to render its shape as if there was an infinite number of intermediate faces rounding it off. This setting can greatly help you reduce the number of triangles needed to make a shape appear to be rounded.

The image below shows two identical models with the same materials. They differ in that the one on the right has most of its geometry set to smooth.

Note how you can see distinct faces on all of the cylindrical shapes of the model on the left, but not on the model on the right.

This setting can be configured separately over individual faces, edges and vertices of a model. One same model could have some of its faces or edges set to smooth and others to sharp

Best practices for geometries

  • Be mindful of how many faces you add to your 3D models, as more faces make its rendering more demanding. See scene limitations for the limits imposed by a scene.
  • Make sure there are no hidden faces that can’t be seen but that add to the triangle count.
  • For shapes that should have rounded sides, set them to be smooth rather than adding additional faces.
  • Make sure the normals of all faces are facing outwards instead of inwards. If there are faces in your model that seem not to be there when you render it, this is most likely the cause.

Colliders

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.

Entity tree

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.

Entity tree

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.

How to add a collider to a staircase

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

  1. Create a new object in the shape of a ramp that resembles the size and proportions of the original stairs.

    Staircase mesh and collider side by side

  2. Name the ramp object something similar to stairs_collider. It must end in _collider.

  3. Overlay the ramp object to the stairs so that they occupy the same space.

    Overlaid mesh and collider

  4. Export both objects together as a single glTF model.

    Exported 3D model with invisible collider

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.

Best practices with colliders

  • Always use the smallest number of triangles possible when creating colliders. Avoid making a copy of a complex object to use as a collider. Simple colliders guarantee a good user-experience in and keep your scene within the triangle limitations.
  • Collider objects shouldn’t have any material, as users of your scene will never see it. Colliders are invisible to users.

    Note: Remember that each scene is limited to log2(n+1) x 10000 triangles, where n is the number of parcels in your scene.

  • All collider objects names must end with _collider. For example, tree_collider.
  • If you use a plane as a collider, it will only block in one direction. If you want colliders to block from both sides, for example for a wall, you need to create two planes with their normals facing in opposite directions.

  • 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.

  • To view the limits of all collider meshes in a Decentraland scene, launch your scene preview with dcl start and then click c. This draws blue lines that delimit all colliders in place.

Animations

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 myArmature_animation1.

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.

How to create an animation

You can use a tool like Blender to create animations for a 3D model.

  1. 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.

    Armature

  2. Make both the armature and the mesh child assets of the same object.

  3. 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.

    Weight paint view for one bone

    Weight paint view for another bone

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.

  1. 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.

    Shifted armature

  2. 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.

    Frames in animation

  3. 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.

How to handle multiple animations with Blender

To export a model with several embedded animations in Blender, you must create multiple actions from the Dope-Sheet.

Open 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).

Open action editor

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.

Open NLA editor

In the NLA Editor, select each action that you want to embed in the glTF model and click Stash.

Stash actions into glTF model

When adding the model to your Decentraland scene, you must activate animations by configuring the gltf-model entity. See Scene content guide for instructions.

Best practices for animations

  • Keep the armature simple, only create bones for the parts of the model that you intend to animate.
  • If the animation will be looped in your scene, make sure the final pose is identical to the starting pose to avoid jumps.
  • Sometimes in an animation you might want to only control the movements of parts of the armature, and leave other bones undefined. This can make it easier to combine animations together.
  • Animated characters in your scene shouldn’t ever stay completely still, even when they aren’t doing anything. It’s best to create an “idle” animation to use for when the character is still. The idle animation can include subtle movements like breathing and perhaps occasional glances.
  • Make sure your model only has one armature when you export it. Sometimes, when importing another animation to the program where you’re editing your model, it will bring in a copy of the armature. You want all animations of the model to be performed by the same base armature.
  • When exporting the glTF model, make sure you’re exporting all the objects and animations. Some exporters will only export the currently selected by default.