Spatial Intelligence

PRO All spatial tools are PRO intelligence tools. Filesystem-only, 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.

---

godotiq_scene_map

Spatial understanding of a .tscn scene: positions, distances, directions, bounds. Call before placing or moving 3D objects.

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": "godotiq_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

---

godotiq_placement

Find safe placement positions for new objects. Checks Marker3D slots first, then grid-searches with wall/overlap validation. Up to 3 suggestions with confidence scores.

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": "godotiq_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, godotiq_placement falls back to grid search around the target area

---

godotiq_spatial_audit

Automated 3D scene linter: floating objects, scale mismatches, z-fighting, overlapping instances, extreme positions.

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": "godotiq_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 godotiq_screenshot to visually verify spatial placement, godotiq_run + godotiq_camera for runtime inspection
• Flow tracing: godotiq_trace_flow can follow navigation-related signals and scripts
• Guides: Workflows: Common spatial workflow patterns

Tools Overview See all 22 GodotIQ tools.