Actors

Actors are the nouns of a scene.

An actor defines:

• exactly one type block — its shape or primitive type
• identity { ... } — how it is uniquely identified

Actors describe structure only. They do not contain behavior.

Actor types

An actor must contain exactly one type block.

Supported top-level type blocks:

• shape { ... } — object actor
• primitive type (string, integer, boolean, etc.)
• primitive with constraints
• array { ... } (rare at actor level, but supported)

Block ordering is not significant. The compiler validates that exactly one type block is present.

Object actors (shape)

Most actors are objects and use shape.

actor Item {
  shape {
    id { integer }

    name {
      shape {
        singular { string }
        plural   { string }
      }
    }
  }

  identity { id }
}

Rules

Inside shape:

• Entries are fields or group blocks.
• Field names must be unique across the entire shape (including inside groups).
• shape contains structure only.

Primitive actors

An actor may be a primitive.

actor Score {
  integer
}

Primitive constraints are defined inside the primitive block:

actor Score {
  integer {
    min { 0 }
  }
}

Supported primitive types include:

• string
• integer
• boolean

Additional primitive types may be introduced in future versions.

Field definition

A field block must contain:

• exactly one type block
• zero or more field predicates

Example:

count {
  integer { min { 0 } }
  optional { }
}

Type vs field constraints

Type constraints live inside the type block:

integer { min { 0 } }
string  { of { 'red' 'green' 'blue' } }

Field predicates live alongside the type block:

optional { }

This separation keeps:

• type semantics inside the type
• field semantics at the field level

Arrays

Arrays are defined explicitly using the array block.

tools {
  array {
    of  { Tool }
    min { 1 }
    max { 2 }
  }
}

Rules:

• array must contain exactly one of { ... } block.
• of references a type or actor.
• min and max constrain the number of elements.

Grouping fields

Fields may be organized using group.

actor GroupedActor {
  shape {
    id { integer }

    group Demographics {
      firstName { string }
      lastName  { string }
    }

    group Contact {
      email { string }
      phone { string }
    }
  }

  identity { id }
}

Groups:

• are organizational only
• do not affect structure
• are flattened in the compiled manifest
• must not introduce duplicate field names

Identity

identity defines how instances of the actor are uniquely identified.

Identity must ultimately resolve to primitive values.

Examples:

identity { id }
identity { playerId skillId }

Identity enables:

• comparison
• uniqueness
• stable projection validation

Validation rules

The compiler enforces:

• An actor must contain exactly one type block.
• A field must contain exactly one type block.
• Primitive constraints must live inside primitive blocks.
• optional { } is a field predicate.
• Groups may only contain fields.
• Field names must be unique within a shape.

What comes next

Now that you know what actors look like, we can continue to explore more about locations.