Name

Human-readable name for an entity. Shown in the editor hierarchy panel and preserved across save/reload.

Editor inspector

Properties

Property	Type	Description
value	string	Display name for the entity. Shown in the editor hierarchy.

API reference

• Class: Name
• Source: core/components/Name.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 name = this.getComponent(Name);

// Component on another entity, found by its scene name
const other = this.world.getEntityByName("Player");
if (other) {
  const name = this.world.getComponent(other.entityId, Name);
}

Drive the display name from the inspector

Rename the entity at runtime from an inspector string field. Useful for dynamic labels or debug output.

import { Behaviour, Name } from "@relu-interactives/spatial-ecs";
import type { StringInput } from "@relu-interactives/spatial-ecs";

export default class EntityRenamer extends Behaviour {
  data = {
    displayName: "My Entity" as StringInput,
  };

  protected onUpdate() {
    const name = this.getComponent(Name);
    if (name && name.value !== this.data.displayName) {
      name.value = this.data.displayName;
    }
  }
}

Find another entity by name

Query all Name components to locate a sibling entity and read its position.

import { Behaviour, Name, TransformComponent } from "@relu-interactives/spatial-ecs";
import type { StringInput } from "@relu-interactives/spatial-ecs";

export default class LookAtTarget extends Behaviour {
  data = {
    targetName: "Target" as StringInput,
  };

  protected onUpdate() {
    let targetTransform: TransformComponent | null = null;

    for (const [id, nameComp] of this.world.query([Name])) {
      if (nameComp.value === this.data.targetName) {
        targetTransform = this.world.getComponent(id, TransformComponent);
        break;
      }
    }

    if (!targetTransform) return;

    // Rotate to face the target on the Y axis
    const dx = targetTransform.position.x - this.transform.position.x;
    const dz = targetTransform.position.z - this.transform.position.z;
    this.transform.rotation.y = Math.atan2(dx, dz);
  }
}

Via EntityInput in the inspector

Alternatively, pick an entity from the inspector using an EntityInput field and then read the component off that entity via world.getComponent:

import {
  Behaviour,
  Name,
  type EntityInput,
  type WorldEntityView,
} from "@relu-interactives/spatial-ecs";

export default class Example extends Behaviour {
  data = {
    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
  };

  protected onUpdate() {
    const entity = this.data.targetEntity.value as WorldEntityView | null;
    if (!entity) return;

    const nameComp = this.world.getComponent(
      entity.entityId,
      Name,
    ) as Name | null;
    if (!nameComp) return;
    // Use the component on the picked entity.
  }
}