Instance Slot

Marks an entity as a single instance within an InstancedMeshComponent group. Instance slot entities are lightweight data containers — they carry a TransformComponent (the per-instance local transform) and this component, but do not have an Object3DRef. InstancedMeshSystem reads every slot's TransformComponent each frame to compose the instance matrix for that slot's index.

Slot entities appear in the hierarchy as children of their owning instancedMesh group entity. Removing a slot entity from the world (or removing its ID from InstancedMeshComponent.instanceEntityIds) retires that instance.

Used by: InstancedMeshSystem, InstancedMeshComponent

Properties

Property	Type	Description
groupEntityId	number	Entity ID of the owning InstancedMeshComponent group entity.
slotIndex	number	Zero-based index of this slot within the group's instanceEntityIds array. Used by InstancedMeshSystem to write the correct column of the instance-matrix buffer.

API reference

• Class: InstanceSlotComponent
• Source: core/components/InstanceSlotComponent.ts

Scripting examples

Component access patterns

Use this.getComponent(X) to access a component on the entity this script is attached to. Use this.world.getEntityByName to find another entity by name, then this.world.getComponent to read its component:

// Component on the entity this script is on
const slot = this.getComponent(InstanceSlotComponent);

// Component on another entity
const other = this.world.getEntityByName("Instance 3");
if (other) {
  const slot = this.world.getComponent(other.entityId, InstanceSlotComponent);
}

Find the group from a slot

import {
  Behaviour,
  InstanceSlotComponent,
  InstancedMeshComponent,
} from "@relu-interactives/spatial-ecs";

export default class SlotInfo extends Behaviour {
  protected init() {
    const slot = this.getComponent(InstanceSlotComponent);
    if (!slot) return;

    const groupEntity = this.world.getEntityById(slot.groupEntityId);
    if (!groupEntity) return;

    const group = this.world.getComponent(slot.groupEntityId, InstancedMeshComponent);
    console.log(
      `This is slot #${slot.slotIndex} of a group with ${group?.instanceEntityIds.length} instances`,
    );
  }
}

Accept a slot reference via ComponentInput

Use a ComponentInput field so the inspector can wire any instance slot entity to this script.

import {
  Behaviour,
  InstanceSlotComponent,
  TransformComponent,
} from "@relu-interactives/spatial-ecs";
import type { ComponentInput, FloatInput } from "@relu-interactives/spatial-ecs";

export default class MoveSlot extends Behaviour {
  data = {
    targetSlot: {
      type: "component",
      componentKind: "InstanceSlot",
      value: null,
    } as unknown as ComponentInput<InstanceSlotComponent>,
    offsetX: 1 as FloatInput,
  };

  protected init() {
    const slot = this.data.targetSlot.value as InstanceSlotComponent | null;
    if (!slot) return;

    const transform = this.world.getComponentById(slot.groupEntityId, TransformComponent);
    // Operate on the slot entity's own transform instead:
    const slotEntity = this.world.getEntityById(
      // find the slot entity ID from the group
      (this.world.getComponent(slot.groupEntityId, { prototype: {} } as never) as never) ?? -1,
    );
    // Simpler: if this script is on the slot entity itself:
    const ownTransform = this.getComponent(TransformComponent);
    if (ownTransform) {
      ownTransform.position.x += this.data.offsetX;
    }
  }
}