Entity Naming Guide

Naming conventions for semantic IDs, positions, routes, and zones. Follow these patterns so that agents, choreographies, and bindings can reference scene elements consistently.

Semantic IDs (actor names)

The semanticId is how choreographies and agents target an entity. It's the entity's role, not its type.

Pattern: role-qualifier

Use kebab-case. The first segment is the role category, the second segment qualifies it.

Pattern	Example	When to use
role	agent	Single entity with that role in the scene
role-qualifier	agent-main	Multiple entities of the same role
role-location	door-kitchen	Entity defined by where it is
role-function	indicator-status	Entity defined by what it does
role-N	guard-1, guard-2	Numbered instances of the same role

Role categories

Common role prefixes and their intent:

Role prefix	Description	Examples
agent	AI agent representation	agent, agent-main, agent-research
worker	Task executor (NPC-like)	worker, worker-forge, worker-1
door	Openable passage	door-kitchen, door-main, door-vault
indicator	Status display	indicator-status, indicator-progress, indicator-error
machine	Process/tool	machine-forge, machine-press, machine-scanner
panel	Information display	panel-dashboard, panel-log, panel-chat
light	Light source entity	light-forge, light-entrance, light-alarm
npc	Non-player character	npc-merchant, npc-guard, npc-guide
fx	Visual effect	fx-spark, fx-smoke, fx-glow
prop	Interactive object	prop-lever, prop-chest, prop-switch

Rules

• kebab-case only — agent-main, not agentMain or Agent_Main
• Role first — the role is more important than the qualifier: door-kitchen not kitchen-door
• Unique per scene — each semanticId must be unique. Multiple entities can share the same semanticId for group targeting: a choreography step targeting a shared ID will animate all instances simultaneously.
• No entity type — use the role, not the sprite name: worker not peon, machine-forge not building-forge-sprite
• Short and scannable — 2 segments max. If you need 3, reconsider: agent-main-backup → backup-agent

Decoration (no semanticId)

Passive elements that don't participate in choreographies have no semanticId. They are placed for visual richness:

• Trees, grass, rocks, fences
• Background buildings
• Floor tiles, wall segments
• Ambient particles

Use list_entities(filter: 'decoration') to see them, list_entities(filter: 'actors') to skip them.

---

Positions (waypoints)

Positions are named locations on the scene that choreographies reference as movement targets.

Pattern: area-role or descriptive noun

Pattern	Example	When to use
noun	forge, entrance, exit	Unique landmark
area-function	kitchen-counter, lab-bench	Position within a zone
spawn-qualifier	spawn-agent, spawn-npc	Entry points
idle-qualifier	idle-agent, idle-worker	Default rest positions
queue-N	queue-1, queue-2	Ordered waiting spots

Type hints

Every position has a typeHint that signals its purpose:

typeHint	Naming convention	Examples
spawn	spawn-*	spawn-agent, spawn-worker, spawn-fx
destination	descriptive noun	forge, workstation, exit
waypoint	via-* or route context	via-corridor, via-bridge
generic	any	center, stage-left, balcony

---

Routes (paths)

Routes are named paths that entities follow during choreographed movement.

Pattern: from-to or descriptive-path

Pattern	Example	When to use
from-to	entrance-to-forge	Clear A→B route
descriptive	patrol-perimeter	Loop or abstract path
role-path	worker-commute	Path tied to a specific role

Rules

• Routes link to positions via fromPositionId and toPositionId when applicable
• Bidirectional routes (bidirectional: true) don't need from-to naming — use a descriptive name
• Use sharp corner style for indoor/structured paths, smooth for organic/outdoor paths

---

Zones (spatial regions)

Zone types define semantic regions of the scene.

Built-in zone types

Zone type	Description	Use
Command	Decision-making area	Agent headquarters, control rooms
Production	Work/processing area	Forges, workshops, labs
Perimeter	Boundary area	Walls, fences, patrol paths
Storage	Resource holding area	Warehouses, shelves, inventories
Transit	Movement corridor	Hallways, bridges, roads

Custom zone types

Follow the same pattern: capitalized singular noun with a short description.

---

Choreography naming

Choreographies don't have explicit names in the MCP tool (they get a UUID), but the on field (trigger signal type) and the when filter effectively name the behavior.

Pattern: signal type + filter = behavior identity

on: "tool_call"                          → general tool-call choreography
on: "tool_call", when: { toolName: "Read" } → specific Read-tool choreography
on: "agent_state_change"                 → agent state transitions
on: "task_dispatch"                      → new task arrival animation

When describing choreographies to other agents or in documentation, use the pattern: signal-type → entity-role → behavior

Example: "tool_call → agent → walk-to-workstation-and-flash"

---

Quick reference

Element	Convention	Example
semanticId	kebab-case, role-first	agent-main, door-kitchen
Position name	descriptive noun or area-function	forge, spawn-agent
Route name	from-to or descriptive	entrance-to-forge, patrol-loop
Zone type	Capitalized singular noun	Command, Production
Signal type	snake_case	tool_call, task_dispatch
Choreography action	camelCase	move, setAnimation, playSound
Entity type (entityId)	kebab-case	peon, building-townhall

---

Key files

• packages/mcp-server/src/tools/place-entity.ts — entity placement with semanticId
• packages/mcp-server/src/tools/list-entities.ts — entity roster (actors vs decoration)
• tools/scene-builder/src/types.ts — PlacedEntity, ScenePosition, SceneRoute types
• packages/mcp-server/src/tools/update-entity.ts — entity property updates
• packages/mcp-server/src/tools/set-entity-state.ts — animation state shortcut