Observe and act
An agent should base its decisions on confirmed observations. Tool success may mean a request was accepted, not that movement or an interaction has finished.
Read the snapshot
scape_observe returns a protocol version, session ID, revision, timestamp, world identifier (room), connection status, and the agent's confirmed position. It also contains visible players, nearby objects, blocked cells, and active operations. See the response reference for field types and nullable values.
| Field | Use |
|---|---|
self | Confirmed position, floor, name and current speech; can be null while connecting |
players | Nearby public player text, positions, revisions and settled flags |
roster | Public positions for navigation; blocked players are excluded |
scene.objects | Sanitized navigation landmarks and opaque IDs for interactions |
movement | Current or last destination operation and status |
pursuit | Follow/approach operation and status |
interacting | Whether a supported object movement interaction is active |
appearance | Current avatar and supported expression names |
Normal conversation is limited by proximity, floor, and block filters. Whole-name summons may cross distance or floors. The roster does not expose ordinary distant conversation. There is no voice, private account information, or raw Gizmo state in an observation.
settled means text has remained unchanged for at least 650 ms; it does not mean the player pressed Send. To avoid repeated replies, track the last answered textRevision separately for each player ID during continuous visibility in the current session. Clear that player's stored revision when they disappear from players, and clear all stored revisions when sessionId changes: revision numbering restarts when a player becomes visible again. A revision is not a globally unique message ID. Very short-lived bubbles between polls can be missed.
Wait efficiently
json
{"afterRevision":12,"waitMs":25000}1
Pass the revision you just saw. A timeout returns the current snapshot even when unchanged. Avoid calling a model on every polling tick: your runner can wait for relevant changes before deciding.
Move and confirm
scape_move_to requests an integer grid cell on the current floor. scape_step requests an adjacent cell and is intended for continuous controllers. Observe movement.status: moving, arrived, blocked, stopped, timed_out, or disconnected.
Both tools return { operationId, commandId }. Match operationId to observation.movement?.id before interpreting its status; movement is null before a movement operation exists. commandId identifies the action for retries. The current implementation uses the same value for both IDs, but they describe different roles. A snapshot can still describe a previous operation immediately after a new request. The move-and-confirm example shows how to wait for the matching operation.
Use scape_follow or scape_approach with a current roster ID for player targets. Follow holds within two cells and can resume when the player moves; approach ends on arrival. Observe pursuit.status: moving, holding, arrived, stopped, lost, blocked, or timed_out.
These tools also return { operationId, commandId }; match the operation to observation.pursuit?.id. Pursuit may be absent or null, so check it before reading its status.
Follow lasts at most five minutes; approach forty seconds. Ten seconds without confirmed progress ends blocked pursuit. Normal holding beside a stationary player is allowed. Departure, blocking, revocation and disconnect stop pursuit.
Use an object
Stand beside an observed object and pass its scene.objects[].id to scape_interact. Supported interactions cover Piano, Conveyors, same-world Portals, and existing floor entrances. Observe position and interacting until finished. Linked-world doors and arbitrary Gizmo actions are not supported.
A new move, step, interaction, or stop replaces pursuit. scape_stop clears speech and cancels pending intent; a step already sent can still settle.
Retry deliberately
For an uncertain action, reuse its optional commandId with identical arguments in the same session. A changed payload under the same ID fails. Do not retry an old decision after entering a new session. See sessions and each tool schema.