Win MANA and LAND in Decentraland's Creator Contest! Sign up today
Hello! Please choose your
desired language:

Shape components

Three dimensional scenes in Decentraland are based on the Entity-Component model, where everything in a scene is an entity, and each entity can include components that shape its characteristics and functionality.

The rendered shape of an entity is determined by what component it uses. Each entity can have only one shape component assigned to it.

nested entities

Primitive shapes

Several basic shapes, often called primitives, can be added to an entity.

The following primitive shape components are available:

  • BoxShape
  • SphereShape
  • PlaneShape
  • CylinderShape
  • ConeShape

Each of these components has certain fields that are specific to that shape, for example the cylinder shape has arc, radiusTop, radiusBottom, etc.

See Component reference for more details on the fields available on each component.

To apply a component to an entity, you can instance a new component and assign it all in one operation:

myEntity.add(new SphereShape())

Or you can first create the component instance and then assign it to the entity.

let shpere = new SphereShape()

Primitive shapes don’t include materials. To give it a color or a texture, you must assign a material component to the same entity.

3D models

For more complex shapes, you can build a 3D model in an external tool like Blender and then import them in .glTF or .glb (binary .glTF). 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.

To add an external model into a scene, add a GLTFShape component to an entity and set its src to the path of the glTF file containing the model.

myEntity.add(new GLTFShape("models/House.gltf"))

Since the src field is required, you must give it a value when constructing the component.

In the example above, the model is located in a models folder at root level of the scene project folder.

Tip: We recommend keeping your models separate in a /models folder inside your scene.

glTF models can include their own embedded textures, materials, colliders and animations. See 3D models considerations for more information on this.

Keep in mind that all models, their shaders and their textures must be within the parameters of the scene limitations.

Note: 3D models in .obj format are also supported, but less encouraged. To add one, create an OBJShape component instead. Note that .obj models don’t support animations and other features.

Free libraries for 3D models

Instead of building your own 3d models, you can also download them from several free or paid libraries.

To get you started, below is a list of libraries that have free or relatively inexpensive content:

Note: Pay attention to the licence restrictions that the content you download has.

Note that in several of these sites, you can choose what format to download the model in. Always choose .glTF format if available. If not available, you must convert them to glTF before you can use them in a scene. For that, we recommend importing them into Blender and exporting them with one of the available glTF export add-ons.


Entities that have collisions enabled occupy space and block a user’s path, entities without collisions can be walked through by a user`s avatar.

Collision settings currently don’t affect how other entities interact with each other, entities can always overlap. Collision settings only affect how the entity interacts with the user’s avatar.

Decentraland currently doesn’t have a physics engine, so if you want entities to fall, crash or bounce, you must code this behavior into the scene.

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

Entities don’t use collisions by default. Depending on the type of the shape component it has, collisions are enabled as follows:

  • For primitive shapes (boxes, spheres, planes etc), you enable collisions by setting the withCollisions field of the shape component to true.

    This example defines a box entity that can’t be walked through.

    let box = new BoxShape()
    box.withCollisions = true

    Note: Planes only block movement in one direction.

  • To use collisions in a glTF shape, you can either:

    • Overlay an invisible entity with a primitive shape and the withCollisions field set to true.
    • Edit the model in an external tool like Blender to include a collider object. The collider must be named x_collider, where x is the name of the model. So for a model named house, the collider must be named house_collider.

A collider is a set of geometric shapes or planes that define which parts of the model are collided with. This allows for much greater control and is a lot less demanding on the system, as the collision object is usually a lot simpler (with less vertices) than the original model.

See 3D models considerations for more details on how to add colliders to a 3D model.

Make invisible

You can make an entity invisible by setting the visible field in its shape component. Doing this is especially useful when using the shape as a collider.

All components for primitive shape and 3D models are visible by default.

const myEntity = new Entity()
myEntity.add(new BoxShape())
myEntity.get(BoxShape).visible = false

Optimize 3D models

To ensure that 3D models in your scene load faster and take up less memory, follow these best practices:

  • Save your models in .glb format, which is a lighter version of .gltf.
  • If you have multiple models that share the same textures, export your models with textures in a separate file. That way multiple models can refer to a single texture file that only needs to be loaded once.
  • If you have multiple entities using the same 3D model and no animations, instance a single GLTFShape component and assign that same one to the entities that will use it.
  • If your scene has entities that appear and disappear, it might be a good idea to pool these entities and keep them already defined but removed from the engine until needed. This will help them appear faster, the trade-off is that they will occupy memory when not in use. See (/development-guide/entities-components/#pooling-entities-and-components)

Reuse shapes

If multiple entities in your scene use a same primitive or 3D model, there’s no need to create an instance of the shape component for each. All entities can share one same instance.

This keeps your scene lighter to load and prevents you from exceeding the maximum amount of bodies per scene.

Note: Reused shapes are added to the triangle count of the scene. So it is possible to exceed the triangle limit by reusing shapes.

// Create shape component
const house = new GLTFShape("models/House.gltf")

// Create entities
const myEntity = new Entity()
const mySecondEntity = new Entity()
const myThirdEntity = new Entity()

// Assign shape component to entities

Each entity that shares a shape can apply different scales, rotations or even materials (in the case of primitives) without affecting how the other entities are being rendered.

Reusing shape components is often advisable, except for 3D models that you plan to animate. If you animate a 3D model that’s shared amongst multiple entities, all the entities will move together. If you want to be able to animate entities individually, each will have to own a separate GLTFComponent to keep track of what part of the animation is currently being played.