Entities

Entity instances are the actual data in a deployment. They follow a schema, and each instance has its own state.

Schema vs Instance

Entity Schema: "horse"
│
├── HORSE_1: { name: "Midnight Comet", speed: 0.85, wins: 3 }
├── HORSE_2: { name: "Thunder Bolt", speed: 0.78, wins: 1 }
└── HORSE_3: { name: "Golden Arrow", speed: 0.92, wins: 5 }

Schema: Defines structure (what fields exist, their types, defaults)
Instance: Holds actual values for a specific entity

Creating Instances

Request

POST /api/worlds/:worldAddress/deployments/:deploymentAddress/entity-instances

Request Body

{
  "entitySchema": "horse",
  "instanceId": "HORSE_1",
  "state": {
    "name": "Midnight Comet",
    "speed_rating": 0.85
  }
}

Instance IDs

The instanceId is a unique string identifier within the deployment:

Must be unique per deployment + schema combination
Used in state change references (e.g., "horse:HORSE_1")
Case-sensitive

Default Values

Attributes not provided in state use schema defaults:

Default Values Example

// Schema defaults: speed_rating=0.5, stamina=0.5, wins=0

// Create with partial state
{ "instanceId": "HORSE_1", "state": { "name": "Star" } }

// Result
{
  "instanceId": "HORSE_1",
  "state": {
    "name": "Star",
    "speed_rating": 0.5,
    "stamina": 0.5,
    "wins": 0
  }
}

Updating State

Via Event Execution

Events update state through AI-computed changes:

State Changes

// AI returns stateChanges
{
  "horse:HORSE_1": { "wins": 4, "lastRace": "2024-06-15" },
  "horse:HORSE_2": { "stamina": 0.65 }
}

The key format is "schemaName:instanceId".

State Change Modes

When events execute, the stateChangeSchema (event version field) determines how runtime stateChanges apply:

Mode	Behavior	Use Case
`partial`	Merge changes into existing state	Most updates
`full`	Replace entire state	Complete resets
`append`	Append to arrays, merge objects	Logs, history

Partial Example

// Existing: { name: "Star", speed: 0.8, wins: 3 }
// Change: { wins: 4 }
// Result: { name: "Star", speed: 0.8, wins: 4 }

Full Example

// Existing: { name: "Star", speed: 0.8, wins: 3 }
// Change: { name: "Star", wins: 4 }
// Result: { name: "Star", wins: 4 }  // speed is gone

Append Example

// Existing: { name: "Star", raceLog: ["race1"] }
// Change: { raceLog: ["race2"] }
// Result: { name: "Star", raceLog: ["race1", "race2"] }

Querying Instances

List by Deployment

GET /api/worlds/:worldAddress/deployments/:deploymentAddress/entity-instances

List by Schema

GET /api/worlds/:worldAddress/deployments/:deploymentAddress/entity-instances?entitySchema="schemaName"

Constraints

Important Limitations

Cannot modify instances in locked deployments - Instance IDs must be unique within deployment + schema

Architecture - Schema vs Instance relationship
AI Engine - How events modify state