Skip to content

World Model & Spatial System

Jump to bottom
Michael Voitovich edited this page Jun 16, 2026 · 30 revisions

Raw vs. Semantic Spatial Projection

In the Scanline Engine, spatial topology serves two different masters: the rendering geometry and the text parser. To handle this without compromising either, the engine maintains two distinct but related models: the Raw Spatial Hierarchy and the Semantic Spatial Projection . Understanding the difference between these two layers is critical for designing scenes, containers, and puzzles that respond naturally to player commands.

1. Raw Spatial Hierarchy (The Geometric Truth)

The Raw Spatial Hierarchy represents the strict physical structure and geometric placement of objects in the scene. Every scene object can have an optional spatial placement defined by two properties:

  • parentNodeId: Points to the parent object.
  • relation: Describes the spatial relationship to the parent.

The engine supports five raw spatial relations: 1. in (inside), 2. on (on top of), 3. under (beneath), 4. behind, and 5. near (proximity). This raw hierarchy is used by the Scene Editor for visual grouping, calculating relative coordinates, and managing point-and-click logic. However, the text parser does not use this raw tree directly. Relying purely on raw geometry would expose ugly implementation details to the player, forcing them to interact with invisible technical nodes like desk_surface or under-chair-slot.

2. Semantic Spatial Projection (The Text-Facing Model)

To provide a natural language experience, the engine dynamically calculates a Semantic Spatial Projection via a read-only system called the SceneTextLayer. This is the world model that the text parser, LLM Game Master, and player actually interact with. The projection works by filtering the raw hierarchy using Semantic Anchors:

  • Titled Objects: Any object with a Title text asset is considered semantically meaningful and becomes a Semantic Anchor.
  • Technical Nodes: Objects without a Title are considered technical or geometric nodes.
  • Collapsing: The SceneTextLayer collapses untitled technical nodes in the text model. If an untitled object has titled descendants, those descendants are projected upward and visually attached to the nearest titled ancestor.

Example: Imagine a desk (Titled: "Desk") containing a technical surface (Untitled), which in turn holds a key (Titled: "Key").

  • Raw Truth: Key is on -> Technical Surface is in -> Desk.
  • Semantic Projection: The parser ignores the technical surface. To the player, the Key is simply in the Desk.

If the technical surface contained a titled "Drawer", the Drawer would become a new Semantic Anchor, and the Key would be described relative to the Drawer instead of the Desk.

3. The Anchor-Relative Rule

Because technical nodes collapse, spatial queries (LOOK IN, TAKE FROM) evaluate spatial relations relative to the specific anchor being queried. This is known as the Anchor-Relative Rule. The rule dictates that the effective relation of an object is determined by the first semantic relation on the path from the queried anchor to the descendant. Internal relations between deeper nested objects are preserved but do not override their relationship to the outer anchor. The Classic Example: Assume a Cabinet (Titled) contains Book A (Titled) in it, and Book B (Titled) is placed on Book A.

  • Relative to the Cabinet: Both books are considered in the Cabinet, because the first relation from the Cabinet to the chain is in. Asking LOOK IN CABINET will successfully show both Book A and Book B.
  • Relative to Book A: Book B is considered on Book A, because the first relation from Book A to Book B is on. Asking LOOK ON BOOK A will show Book B.

This ensures that players can naturally say TAKE BOOK B FROM CABINET or TAKE BOOK B FROM BOOK A, and both commands will perfectly resolve the target without confusing the parser.

4. Visibility, Storage, and near

The semantic projection also strictly separates visual proximity from actionable storage:

  • Storage Requirements: A spatial relation of in or on does not automatically make an object an interactive container. Storage must be explicitly granted by attaching an Inventory or Surface component to the object.
  • The near Relation: The near relation is recognized by the parser for proximity and text grouping, but it is strictly forbidden to be used as a storage slot. The SceneSpatialValidator will reject near if it is configured inside an Inventory or Surface component, because an item cannot be "stored" in the abstract space "near" something.

Clone this wiki locally