Entities and components

A scene is a set of entities. Each entity has a name, an optional parent, and any number of components: plain data such as a Transform, a Light or a RigidBody. Behaviour comes from systems and C# scripts that read and write those components; see the Scripting overview.

#An entity record

In a scene file, each entity is one record keyed by its ID:

"e_4chy": {
  "name": "CrateLight",
  "parent": "e_8d41",
  "order": "a0",
  "Light": {
    "intensity": 400
  },
  "Transform": {
    "position": [0, 2, 0]
  }
}

The full record type is Entity.

#Components

Components are plain data with typed, documented fields. Each field has a default and, where it applies, a unit. To see a component's fields:

ara schema Light

| Field | Type | Default | Unit | Description |
|---|---|---|---|---|
| `kind` | `LightKind` | `"point"` |  | Point, spot or directional. |
| `color` | `color` | `[1,1,1,1]` |  | Linear RGB tint (alpha is ignored). |
| `intensity` | `f32` | `800` |  | Luminous flux in lumens (point/spot) or illuminance in lux (directional). |
| `range` | `f32` | `10` | m | Influence radius of point and spot lights. |
| `innerAngle` | `f32` | `20` | deg | Spot inner cone half-angle. |
| `outerAngle` | `f32` | `30` | deg | Spot outer cone half-angle. |

ara schema with no arguments lists every component in your engine version. In 0.0.2-alpha.3 they include:

The type reference documents all of them.

#Hierarchy

An entity's Transform is relative to its parent: position in meters, rotation as XYZ Euler angles in degrees, and scale. Moving a parent moves its children.

#Editing entities

Use commands to create, change and delete entities. Each one is a transaction you can undo.

property.set takes a field path: name, a component field such as Light.intensity, or a part of one, such as Transform.position.y:

ara do property.set -p entity=name:CrateLight -p path=Light.intensity -p value=500 --why "Dimmer crate light"
ara do component.add --args '{entity: "name:Crate", component: RigidBody}' --why "Let the crate fall"
ara do entity.reparent --args '{entity: "name:CrateLight", parent: "name:Camera"}' --why "Carry the light with the camera"

Values use the field's schema type and unit. A wrong type fails before anything is applied:

error[ARA1102]: expected a number (`f32`), got a string
  --> call #0 · Light.intensity

#Naming entities in commands

Wherever a command takes an entity, you can give:

• an ID: e_8d41;
• an address inside a prefab instance: e_4f9a/e_m4tz;
• a batch symbol minted earlier in the same batch: $crate (see Commands and transactions);
• a name: name:Crate, or name:Floor/Crate to pick the Crate under Floor.

If a name matches several entities, the command fails and offers one fix per match:

error[ARA1609]: `name:Crate` matches 2 entities; use one of their IDs, or name a parent too (`name:Parent/Child`)
  --> call #0 · commands[0].args.target
  = fix: Use `e_qg8h` (Crate)
  = fix: Use `e_tfc6` (Crate)

If the entities you name exist in more than one document, pass --doc to choose (ARA1814). --doc accepts a path, an ID or just a unique file name such as main.

#Prefabs

A prefab is a reusable entity subtree with exactly one root, saved as its own .prefab document. Placing it in a scene creates an instance: a record that links to the prefab and stores only what differs.

ara do prefab.instantiate --args '{prefab: "prefabs/crate.prefab", position: [0, 0, 4]}' --why "Place a crate"

"e_p66p": {
  "order": "a2",
  "prefab": "@prefabs/crate.prefab#pf_crate001",
  "overrides": {
    "Transform.position": [0, 0, 4]
  }
}

An instance never stores components inline. It carries:

• prefab: the reference to the prefab;
• overrides: changed values, keyed by [<id path>/]<field path>. Only names and components can be overridden;
• removed: prefab entities or components this instance drops.

You don't write overrides yourself. Edit the instance, or an entity inside it, with the normal commands, and the engine records the change as an override:

ara do property.set -p entity=e_p66p -p path=MeshRenderer.color -p value=[0.8,0.2,0.2,1] --why "Paint this crate red"

"overrides": {
  "MeshRenderer.color": [0.8, 0.2, 0.2, 1],
  "Transform.position": [0, 0, 4]
}

Deleting an entity inside an instance adds it to removed, and component.remove on a prefab entity removes the component from this instance only. To undo overrides, use prefab.override.revert, which reverts one path or everything on the entity. prefab.override.set sets an override explicitly.

Changes you make to the prefab document itself reach every instance, except where an instance overrides that value.

#Seeing effective values

ara inspect shows an entity with prefab overrides applied and defaults filled in:

ara inspect e_p66p

e_p66p Crate prefab:crate [MeshRenderer] pos(0,0,4) · defined in pf_crate001#e_g1tm
  MeshRenderer: shape=box size=(1,1,1)m model=null node=null primitive=null materialOverrides=() color=(0.8,0.2,0.2,1) roughness=0.6 metallic=0 emissive=(0,0,0) emissiveEnabled=true emissiveStrength=1 emissiveFactor=null emissiveMaterials=()
  Transform: position=(0,0,4)m rotation=(0,0,0)deg scale=(1,1,1)

Agents get the same view from the ara_inspect MCP tool.