Scene Management

Methods for adding, removing, updating, and disposing objects in the Threebox scene

add

Adds an object to the Threebox scene.

tb.add(obj, layerId, sourceId)

Parameters

obj · Object3D · required

The 3D object to add to the scene

layerId · string

Optional layer ID to associate with this object

sourceId · string

Optional source ID to associate with this object

Example

tb.loadObj(options, function (model) {
  soldier = model.setCoords(origin);
  tb.add(soldier, 'custom_layer');
});

---

remove

Removes an object from the Threebox scene.

tb.remove(obj)

Parameters

obj · Object3D · required

The 3D object to remove from the scene. If the object has a dispose method, it will be called automatically

Example

tb.remove(soldier);

---

removeByName

Removes an object from the Threebox scene by name.

tb.removeByName(name)

Parameters

name · string · required

The name of the object to remove. Searches through the scene and its children, starting with the object itself, and removes the first with a matching name

Example

tb.removeByName('my-soldier');

---

update

Updates the Threebox scene and renders it. This is the most important method in Threebox as it’s responsible for invoking the THREE.WebGLRenderer.render(scene, camera) method.

tb.update()

This method should be called from the render function of your custom layer:

Example

map.addLayer({
  id: 'custom_layer',
  type: 'custom',
  renderingMode: '3d',
  onAdd: function (map, gl) {
    window.tb = new Threebox(map, gl, { defaultLights: true });
  },
  render: function (gl, matrix) {
    tb.update(); // Call this to render the scene
  }
});

---

clear

Removes all children from the Threebox scene.

await tb.clear(layerId, dispose)

Parameters

layerId · string

Optional layer ID. If provided, only objects in that layer will be removed. If omitted, all objects are removed

dispose · boolean · default: "false"

If true, will also call obj.dispose() on each object to dispose all resources

Returns

Promise · Promise<string>

Returns a Promise that resolves with “clear” when complete

Example

// Clear all objects and dispose resources
await tb.clear(null, true);

// Clear only objects in a specific layer
await tb.clear('custom_layer');

---

dispose

Fully disposes the Threebox instance and all associated resources from Three.js and Mapbox GL.

await tb.dispose()

This method should be called before navigating to another page to prevent memory leaks. It will:

• Dispose every object, geometry, material and texture in Three.js
• Dispose all resources from Mapbox GL
• Dispose the WebGLRenderingContext
• Remove the map instance

Returns

Promise · Promise

Returns a Promise that resolves when disposal is complete

Example

// Before navigating away or cleaning up
await tb.dispose();

After calling dispose(), the Threebox and Mapbox GL map instances will be fully disposed and cannot be used. Only call this method when you’re done with the map entirely.

---

removeLayer

Removes a layer from Mapbox, including all 3D objects from the Threebox scene.

tb.removeLayer(layerId)

Parameters

layerId · string · required

The ID of the layer to remove

Example

tb.removeLayer('custom_layer');