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.

Get project context. Start with godotiq_project_summary so the AI understands your codebase.
Describe the symptom. Be specific: “The health bar doesn’t update when the player takes damage” is better than “combat is broken.”
Let the AI trace the flow. It will use godotiq_trace_flow to follow the data path from the damage source to the UI and godotiq_signal_map to check signal connections.
Review the findings. The AI will identify likely root causes with file paths and line numbers.
Apply the fix. The AI can make the code change and use godotiq_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: godotiq_project_summary → godotiq_trace_flow → godotiq_signal_map → godotiq_validate

Safe Refactoring

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

Check the blast radius. Use godotiq_impact_check to see everything that depends on what you’re changing.
Map signal connections. godotiq_signal_map reveals signal chains that might be affected by the rename or restructure.
Make the changes. The AI modifies all affected files based on the impact analysis.
Validate. Run godotiq_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: godotiq_impact_check → godotiq_signal_map → godotiq_dependency_graph → godotiq_validate

Level Review

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

Map the level. godotiq_scene_map gives the AI a complete understanding of the spatial layout.
Run a spatial audit. godotiq_spatial_audit checks for floating objects, clipping geometry, out-of-bounds nodes, and navmesh gaps.
Test navigation. godotiq_nav_query tests whether NPCs can reach key locations via the navigation mesh. (Requires addon; game must be running.)
Fix issues. Use godotiq_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: godotiq_scene_map → godotiq_spatial_audit → godotiq_nav_query → godotiq_placement

Understanding a New Codebase

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

Get the big picture. godotiq_project_summary with detail: "full" gives you architecture, file structure, autoloads, and conventions.
Explore a specific system. Use godotiq_file_context on key files (managers, autoloads) to understand their role and relationships.
Trace a feature. Pick a user-facing feature and use godotiq_trace_flow to follow it from UI to data layer.
Map dependencies. godotiq_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: godotiq_project_summary → godotiq_file_context → godotiq_trace_flow → godotiq_dependency_graph

Runtime Debugging

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

Start the game. godotiq_run launches from the editor.
Capture what you see. godotiq_screenshot takes a viewport capture for the AI to analyze visually.
Inspect the live tree. godotiq_scene_tree shows runtime-instantiated nodes that don’t exist in scene files.
Check UI state. godotiq_ui_map reveals what text labels show, which buttons are visible, and progress bar values.
Manipulate state. godotiq_node_ops lets you get/set properties and call methods on running nodes.
Test input. godotiq_input simulates player input: actions, keys, UI taps, and waits.
Stop and iterate. Stop the game with godotiq_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: godotiq_run → godotiq_screenshot → godotiq_ui_map → godotiq_state_inspect → godotiq_input

Asset Management

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

Inventory assets. godotiq_asset_registry finds unused assets, missing references, and provides a complete inventory by type.
Check scaling. godotiq_suggest_scale recommends scale and position for models based on similar assets in scenes.
Map dependencies. godotiq_dependency_graph shows which scripts and scenes reference each asset.
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: godotiq_asset_registry → godotiq_suggest_scale → godotiq_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.