InstancedBoxMeshDesc

The InstancedBoxMeshDesc class is a mesh descriptor that renders multiple box instances using GPU instancing. All boxes share a single geometry and material, rendered in one draw call for high performance. It extends InstancedMeshDesc.

In addition to the properties below, all common properties from the base class (position, rotation, scale, matrix, matrixWorld, pickable, visible) are available. See MeshDesc for details.

Shared Material Properties

Shared material properties applied to all instances. These are specified in the boxes config object.

color

Type: Color

Description: Specifies the base color for all instances using a Color instance.

Default: new Color().setStyle("#ffffff")

Example:

import { Color } from "@navaramap/three";

{
  boxes: {
    color: new Color().setHex(0xff0000),
  }
}

emissiveColor

Type: Color

Description: Specifies the emissive (self-illuminating) color using a Color instance.

Default: new Color().setHex(0x000000)

Example:

import { Color } from "@navaramap/three";

{
  boxes: {
    emissiveColor: new Color().setHex(0x222222),
  }
}

emissiveIntensity

Type: number

Description: Specifies the emissive intensity.

Default: 0

Example:

{
  boxes: {
    emissiveIntensity: 0.5,
  }
}

opacity

Type: number

Description: Specifies the opacity. Ranges from 0.0 (fully transparent) to 1.0 (fully opaque).

Default: 1

Example:

{
  boxes: {
    opacity: 0.5,
  }
}

transparent

Type: boolean

Description: Specifies whether to enable transparency.

Default: false

Example:

{
  boxes: {
    transparent: true,
  }
}

castShadow

Type: boolean

Description: Specifies whether the instances cast shadows.

Default: false

Example:

{
  boxes: {
    castShadow: true,
  }
}

receiveShadow

Type: boolean

Description: Specifies whether the instances receive shadows.

Default: false

Example:

{
  boxes: {
    receiveShadow: true,
  }
}

Per-Instance Properties (BoxChildConfig)

Properties for each individual box instance, specified in the children array.

width

Type: number

Description: Specifies the width of the box (X-axis). Encoded as scale in the instance matrix. Multiplied with scale.x if both are specified.

Default: 1

Example:

{
  boxes: {
    children: [
      { width: 100 },
    ],
  }
}

height

Type: number

Description: Specifies the height of the box (Y-axis). Encoded as scale in the instance matrix. Multiplied with scale.y if both are specified.

Default: 1

Example:

{
  boxes: {
    children: [
      { height: 100 },
    ],
  }
}

depth

Type: number

Description: Specifies the depth of the box (Z-axis). Encoded as scale in the instance matrix. Multiplied with scale.z if both are specified.

Default: 1

Example:

{
  boxes: {
    children: [
      { depth: 100 },
    ],
  }
}

color

Type: Color | undefined

Description: Specifies the per-instance color using a Color instance. Overrides the shared material color for this specific instance.

Default: undefined (uses shared material color)

Example:

import { Color } from "@navaramap/three";

{
  boxes: {
    children: [
      { color: new Color().setHex(0xff0000) },
    ],
  }
}

position

Type: { x: number, y: number, z: number } | undefined

Description: Specifies the local position relative to the parent group.

Default: { x: 0, y: 0, z: 0 }

Example:

{
  boxes: {
    children: [
      { position: { x: 100, y: 0, z: 0 } },
    ],
  }
}

rotation

Type: { x: number, y: number, z: number } | undefined

Description: Specifies the local rotation (Euler angles in radians).

Default: undefined

Example:

{
  boxes: {
    children: [
      { rotation: { x: 0, y: Math.PI / 4, z: 0 } },
    ],
  }
}

scale

Type: { x: number, y: number, z: number } | undefined

Description: Specifies the local scale. Multiplied with width, height, and depth.

Default: { x: 1, y: 1, z: 1 }

Example:

{
  boxes: {
    children: [
      { scale: { x: 2, y: 2, z: 2 } },
    ],
  }
}

matrix

Type: Matrix4 | undefined

Description: Specifies a pre-computed transform matrix. When set, position, rotation, and scale are ignored.

Default: undefined

Example:

import { Matrix4 } from "three";

{
  boxes: {
    children: [
      { matrix: new Matrix4().makeTranslation(100, 0, 0) },
    ],
  }
}

Config

effectIds

Type: string[] (optional)

Description: Specifies an array of selective effect descriptor IDs to apply to this mesh.

Example:

{
  boxes: {
    effectIds: ["bloom-effect", "outline-effect"],
  }
}

Instance Management

Methods inherited from InstancedMeshDesc for dynamic instance management:

handle.ref.add(config)

Adds a new instance. Returns the index of the added instance.

const index = handle.ref.add({
  position: { x: 100, y: 0, z: 0 },
  width: 20,
  height: 20,
  depth: 20,
  color: new Color().setHex(0xffff00),
});

handle.ref.removeAt(index)

Removes an instance by index. Uses swap-with-last for O(1) removal. Instance order is not preserved.

handle.ref.removeAt(1);

handle.ref.updateAt(index, config)

Updates an instance at the given index with partial config.

handle.ref.updateAt(0, {
  color: new Color().setHex(0xff00ff),
  height: 50,
});

handle.ref.clear()

Removes all instances.

handle.ref.clear();

handle.ref.replaceAll(configs)

Batch replaces all instances. More efficient than clear() + multiple add() calls as it emits a single update notification.

handle.ref.replaceAll([
  { position: { x: 0, y: 0, z: 0 }, width: 10, height: 10, depth: 10 },
  { position: { x: 20, y: 0, z: 0 }, width: 10, height: 10, depth: 10 },
]);

handle.ref.count

Gets the number of active instances.

console.log("Instance count:", handle.ref.count);

Usage Examples

Basic Usage

import ThreeView, { Color } from "@navaramap/three";
import { InstancedBoxMeshDesc } from "@navaramap/three_default_descs";

const view = new ThreeView();
view.registerMesh("boxes", InstancedBoxMeshDesc);
await view.init();

const handle = view.addMesh<InstancedBoxMeshDesc>({
  boxes: {
    color: new Color().setHex(0xffffff),
    castShadow: true,
    children: [
      { position: { x: 0, y: 0, z: 0 }, width: 10, height: 20, depth: 10, color: new Color().setHex(0xff0000) },
      { position: { x: 30, y: 0, z: 0 }, width: 15, height: 10, depth: 15, color: new Color().setHex(0x00ff00) },
      { position: { x: 60, y: 0, z: 0 }, width: 5, height: 40, depth: 5, color: new Color().setHex(0x0000ff) },
    ],
  },
  position: { x: 0, y: 0, z: 6378137 },
});

Dynamic Instance Management

// Add a new instance
const index = handle.ref.add({
  position: { x: 90, y: 0, z: 0 },
  width: 20,
  height: 20,
  depth: 20,
  color: new Color().setHex(0xffff00),
});

// Update instance at index 0
handle.ref.updateAt(0, {
  color: new Color().setHex(0xff00ff),
  height: 50,
});

// Remove instance at index 1
handle.ref.removeAt(1);

// Replace all instances
handle.ref.replaceAll([
  { position: { x: 0, y: 0, z: 0 }, width: 10, height: 10, depth: 10 },
  { position: { x: 20, y: 0, z: 0 }, width: 10, height: 10, depth: 10 },
]);

Updating Shared Material

handle.update({
  boxes: {
    color: new Color().setHex(0x333333),
    emissiveColor: new Color().setHex(0xff0000),
    emissiveIntensity: 0.5,
    opacity: 0.8,
    transparent: true,
  },
});