Spatial Intelligence

Free All spatial tools work from the filesystem — no addon required.

What is Spatial Intelligence?

Most AI tools can read and write code. GodotIQ goes further: it understands 3D space. Spatial intelligence means knowing where walls, floors, and objects are; understanding navmesh connectivity; detecting collision relationships; and reasoning about placement, visibility, and scale.

This matters because game development is inherently spatial. When you ask “place a torch on the wall near the door,” the AI needs to know where the wall is, where the door is, what’s already there, and whether the placement would clip through geometry. GodotIQ’s spatial tools provide that understanding.

---

scene_map

Analyzes the 3D spatial layout of a scene, reporting positions, bounds, and spatial relationships of all nodes.

When to Use It

• Understanding the layout of an unfamiliar scene
• Finding all objects within a region (e.g., “what’s near the player spawn?”)
• Getting node positions and bounding boxes for spatial reasoning

Parameters

Parameter	Type	Default	Description
scene_path	string	required	Path to the .tscn file to analyze
detail	string	"normal"	Output verbosity: brief (~80% fewer tokens), normal, or full
filter_type	string	null	Filter to specific node types (e.g., "MeshInstance3D", "Area3D")
region	object	null	Limit analysis to a bounding box {min: [x,y,z], max: [x,y,z]}

Example

Prompt: “What’s the layout of my main level?”

Tool call

{
  "tool": "scene_map",
  "args": {
    "scene_path": "res://scenes/levels/main.tscn",
    "detail": "normal"
  }
}

Output

{
  "scene": "res://scenes/levels/main.tscn",
  "root": "Main",
  "node_count": 47,
  "bounds": { "min": [-20, 0, -20], "max": [20, 8, 20] },
  "spatial_nodes": [
    {
      "name": "Player",
      "type": "CharacterBody3D",
      "position": [0, 1, 0],
      "bounds": { "min": [-0.3, 0, -0.3], "max": [0.3, 1.8, 0.3] }
    },
    {
      "name": "Door_01",
      "type": "AnimatableBody3D",
      "position": [5, 0, 3],
      "bounds": { "min": [4.5, 0, 2.9], "max": [5.5, 2.5, 3.1] }
    },
    {
      "name": "TorchWall_01",
      "type": "MeshInstance3D",
      "position": [4.8, 2, 3],
      "parent": "WallSegment_03"
    }
  ],
  "relationships": [
    { "type": "near", "a": "Player", "b": "Door_01", "distance": 5.38 },
    { "type": "attached", "a": "TorchWall_01", "b": "WallSegment_03" }
  ]
}

Tips

• Use detail: "brief" when you just need positions — it returns ~80% fewer tokens
• Combine with filter_type to focus on specific node types (e.g., only lights, only collision shapes)
• For large scenes with 100+ nodes, use region to limit the spatial area analyzed

---

placement

Smart object placement using spatial awareness, navmesh data, and collision avoidance. Calculates valid positions based on surface geometry, existing objects, and navigation constraints.

When to Use It

• Placing objects in a scene with spatial awareness (“put a crate near the door”)
• Finding valid spawn points that don’t overlap existing geometry
• Marker-aware placement using named Position3D markers in the scene

Parameters

Parameter	Type	Default	Description
scene_path	string	required	Scene to place objects in
object_scene	string	required	Scene to instantiate (e.g., "res://objects/crate.tscn")
near	string	null	Place near this node name or path
on_surface	string	null	Place on a specific surface (e.g., "floor", "wall", node name)
marker	string	null	Use a named Position3D marker for placement
min_distance	float	0.5	Minimum distance from other objects
use_navmesh	bool	true	Constrain placement to navigable areas
count	int	1	Number of placements to calculate

Example

Prompt: “Place 3 barrels near the tavern entrance, make sure they don’t block the path.”

Tool call

{
  "tool": "placement",
  "args": {
    "scene_path": "res://scenes/levels/town.tscn",
    "object_scene": "res://objects/barrel.tscn",
    "near": "TavernDoor",
    "use_navmesh": true,
    "min_distance": 1.0,
    "count": 3
  }
}

Output

{
  "placements": [
    { "position": [12.5, 0, 8.2], "valid": true, "surface": "floor", "navmesh": true },
    { "position": [13.1, 0, 7.8], "valid": true, "surface": "floor", "navmesh": true },
    { "position": [11.9, 0, 8.5], "valid": true, "surface": "floor", "navmesh": true }
  ],
  "rejected": [
    { "position": [12.8, 0, 8.0], "reason": "overlaps existing CollisionShape3D" }
  ],
  "reference_node": "TavernDoor",
  "reference_position": [12.0, 0, 8.0]
}

Tips

• use_navmesh: true ensures placed objects don’t block AI pathfinding
• Place named Position3D markers in your scene (e.g., SpawnPoint_01) and reference them with the marker parameter for precise control
• If no valid positions are found, placement falls back to grid search around the target area

---

spatial_audit

Audits a scene for common spatial issues: floating objects, geometry clipping, out-of-bounds nodes, navmesh gaps, and scale inconsistencies.

When to Use It

• Quality-checking a level before shipping
• Finding objects that accidentally got moved to wrong positions
• Detecting navmesh coverage gaps where players might get stuck

Parameters

Parameter	Type	Default	Description
scene_path	string	required	Scene to audit
checks	array	["all"]	Specific checks to run: "floating", "clipping", "oob", "navmesh", "scale"
bounds	object	auto	Custom level bounds {min: [x,y,z], max: [x,y,z]} (auto-detected if omitted)
detail	string	"normal"	Output verbosity: brief, normal, full

Example

Prompt: “Audit my dungeon level for spatial issues.”

Tool call

{
  "tool": "spatial_audit",
  "args": {
    "scene_path": "res://scenes/levels/dungeon.tscn",
    "detail": "normal"
  }
}

Output

{
  "scene": "res://scenes/levels/dungeon.tscn",
  "issues_found": 4,
  "issues": [
    {
      "type": "floating",
      "severity": "warning",
      "node": "Chest_03",
      "position": [8, 2.5, -3],
      "message": "Node is 2.5m above nearest surface"
    },
    {
      "type": "clipping",
      "severity": "warning",
      "nodes": ["Pillar_02", "WallSegment_07"],
      "overlap": 0.3,
      "message": "Meshes overlap by 0.3m"
    },
    {
      "type": "navmesh",
      "severity": "error",
      "message": "Gap in NavigationMesh near [4, 0, -6] — 2m gap between regions"
    },
    {
      "type": "scale",
      "severity": "info",
      "node": "Barrel_05",
      "scale": [2, 2, 2],
      "message": "Non-uniform or unusual scale (2x) compared to siblings"
    }
  ],
  "summary": {
    "errors": 1,
    "warnings": 2,
    "info": 1
  }
}

---

Related Tools

• Bridge tools — Use screenshot to visually verify spatial placement, run + camera for runtime inspection
• Flow tracing — trace_flow can follow navigation-related signals and scripts
• Guides: Workflows — Common spatial workflow patterns

Tools Overview See all 35 GodotIQ tools.