Spatial World Model (world-model-mcp)

This skill provides step-by-step guidance and operational patterns for interacting with @putervision/world-model-mcp.

---

1. Role in the PuterVision Triad

• Perception Layer (vision-memory-mcp): Ingests images, detects bounding boxes, extracts OCR.
• World Model Layer (world-model-mcp): Maintains persistent 3D/2D coordinates, bounding volumes, topological relations, and object permanence.
• Action/State Layer (state-memory-mcp): Manages task execution DAGs, decisions, blockers, and milestones.

---

2. Core Operational Sequence

1. Inspect World: Call get_spatial_map with format: 'summary' to check total entities and spatial bounding box.
2. Proximity Lookup: Call query_entities with near_position and max_distance, or entity_id for direct lookup.
3. Ingest Perception: When new visual elements are detected, call ingest_observation.
4. Collision Pre-Check: Call simulate_movement before issuing action commands.
5. Update State: Call record_outcome after actions complete.

---

3. Tool Reference (15 Tools)

Tool Name	Key Inputs	Description
update_entity	name, type, position, bounding_box, properties	Upsert entity into spatial memory
query_entities	query, type, near_position, entity_id, include_history	Find entities by text search, proximity, or entity ID
set_relation	source_id, relation, target_id, offset	Record spatial relationship (on, inside, near, etc.)
get_spatial_map	region_id, format (json, gltf, obj, summary)	Export structured spatial layout or summary
simulate_movement	entity_id, delta_position, mode, check_collisions	Predict movement path or compute navigation waypoints
ingest_observation	observer_pose, detections, visual_state_id, reconcile	Ingest perception detections and reconcile frustum view
get_expected_view	observer_position, observer_orientation, fov	Calculate visible entities from observer pose
link_to_goal	task_id, entity_id, relationship, action	Associate entity with task or extract spatial slice
record_outcome	action_name, success, resulting_position	Update world state after action completion
manage_spatial_spec	action, name, bounds, constraints	Spatial SDD contract registration and verification
create_evidence_pack	task_id, entity_ids, snapshot_ids	Immutable cryptographic evidence package
use_spatial_blackboard	action, topic, sender, payload	Multi-agent coordination and mutex locks
manage_snapshot	action, name, snapshot_a, snapshot_b, entity_id	Snapshots, diffs, undo mutations, and time-travel
generate_game_inputs	entity_id, target_position, control_profile, action	Playwright game inputs and screen coordinate projection
wait_for_spatial_state	entity_id, condition, threshold, timeout_ms	Polling and waiting for spatial state condition