Workflows

These workflow patterns show how to combine GodotIQ tools for common game development tasks. Each workflow is client-agnostic — it works with Claude Code, Cursor, Windsurf, or VS Code.

Debugging a Bug

When something isn’t working and you don’t know why.

1. Get project context — Start with project_summary so the AI understands your codebase.

2. Describe the symptom — Be specific: “The health bar doesn’t update when the player takes damage” is better than “combat is broken.”

3. Let the AI trace the flow — It will use trace_flow to follow the data path from the damage source to the UI and signal_map to check signal connections.

4. Review the findings — The AI will identify likely root causes with file paths and line numbers.

5. Apply the fix — The AI can make the code change and use validate to confirm the fix doesn’t break conventions.

Example prompt:

“The enemy attacks play their animation but the player health bar doesn’t decrease. Trace the flow to find why.”

Tools used: project_summary → trace_flow → signal_map → validate

---

Safe Refactoring

When you need to rename, move, or restructure code without breaking things.

1. Check the blast radius — Use impact_check to see everything that depends on what you’re changing.

2. Map signal connections — signal_map reveals signal chains that might be affected by the rename or restructure.

3. Make the changes — The AI modifies all affected files based on the impact analysis.

4. Validate — Run validate to check that the refactored code follows project conventions.

Example prompt:

“I want to rename PlayerManager to CharacterController. What would break, and can you do the rename safely?”

Tools used: impact_check → signal_map → dependency_graph → validate

---

Level Review

When you want an AI review of a level’s spatial quality before shipping.

1. Map the level — scene_map gives the AI a complete understanding of the spatial layout.

2. Run a spatial audit — spatial_audit checks for floating objects, clipping geometry, out-of-bounds nodes, and navmesh gaps.

3. Test navigation — nav_query tests whether NPCs can reach key locations via the navigation mesh. (Requires Pro addon.)

4. Fix issues — Use placement to reposition problem objects with collision avoidance.

Example prompt:

“Audit my dungeon level for spatial issues and test that NPCs can navigate from the entrance to the boss room.”

Tools used: scene_map → spatial_audit → nav_query → placement

---

Understanding a New Codebase

When you’re joining a project or picking up code you haven’t touched in a while.

1. Get the big picture — project_summary with detail: "full" gives you architecture, file structure, autoloads, and conventions.

2. Explore a specific system — Use file_context on key files (managers, autoloads) to understand their role and relationships.

3. Trace a feature — Pick a user-facing feature and use trace_flow to follow it from UI to data layer.

4. Map dependencies — dependency_graph shows how modules connect and where the coupling is tight.

Example prompt:

“I’m new to this project. Give me a full project overview, then walk me through how the order system works from the UI button press to the kitchen queue.”

Tools used: project_summary → file_context → trace_flow → dependency_graph

---

Runtime Debugging (Pro)

When you need to see and interact with the running game.

Note

This workflow requires the Pro addon. See the Addon Reference for setup.

1. Start the game — run launches from the editor.

2. Capture what you see — screenshot takes a viewport capture for the AI to analyze visually.

3. Inspect the live tree — scene_tree shows runtime-instantiated nodes that don’t exist in scene files.

4. Check UI state — ui_map reveals what text labels show, which buttons are visible, and progress bar values.

5. Manipulate state — node_ops lets you get/set properties and call methods on running nodes.

6. Test input — input simulates player input: actions, keys, UI taps, and waits.

7. Stop and iterate — Stop the game with run, make changes, repeat.

Example prompt:

“Run the game, take a screenshot, then check what the HUD is displaying. The score label might be wrong.”

Tools used: run → screenshot → ui_map → state_inspect → input

---

Asset Management

When you need to find unused assets or check asset scaling.

1. Inventory assets — asset_registry finds unused assets, missing references, and provides a complete inventory by type.

2. Check scaling — suggest_scale recommends scale and position for models based on similar assets in scenes.

3. Map dependencies — dependency_graph shows which scripts and scenes reference each asset.

4. Clean up — Based on the inventory, remove unused assets or fix broken references.

Example prompt:

“Find all unused assets in this project and check if any models have unusual scale relative to similar assets.”

Tools used: asset_registry → suggest_scale → dependency_graph

---

Building Good Prompts

Be Specific About the Problem

Instead of…	Try…
”My game is broken"	"The player clips through walls on the second floor"
"Fix the UI"	"The health bar doesn’t update when taking damage"
"Make the level better"	"Audit the dungeon for floating objects and navmesh gaps”

Provide Context

Include relevant details:

• Scene names and file paths when you know them
• Steps to reproduce for bugs
• What you’ve already tried

Chain Tools with Natural Language

You don’t need to know tool names. Describe what you want in stages:

“First understand the project structure, then trace how damage flows from enemy attack to player health bar, and fix whatever’s broken.”

The AI will select and chain the right tools automatically.

Tools Overview See all available tools and what they do.

Getting Started Try your first five GodotIQ prompts.