Godot Project Parser - Offline Structural Analysis

Instructions for Agent Use

When you need to read, analyze, or modify a .tscn or .tres file, you MUST NOT use regular expressions. You MUST use the GodotProject.get_scene() or GodotProject.get_resource() methods, which are wrappers for the godot-parser library.

These methods provide a robust API (e.g., scene.use_tree()) for offline modification and correctly handle the five sections: [gd_scene], [ext_resource], [sub_resource], [node], and [connection].

To find broken signal connections, use the GodotProject.find_broken_signals() method. This synthesis skill parses both the .tscn file for the connection and the attached .gd script (using gdtoolkit.parser) to verify the target function exists.

When to Use

Use this skill during the Validate phase or whenever you need to:

• Analyze scene structure without running Godot
• Find broken node references or signal connections
• Modify scene files programmatically
• Validate resource dependencies
• Detect structural issues before runtime

What This Skill Does

This skill is not a loose script but a core capability of the GodotProject class. It provides the "eyes" for the agents to understand the current state of the Godot project's assets, enabling robust analysis and modification.

Core Capabilities

• Scene Parsing: .tscn files into structured AST objects
• Resource Parsing: .tres files with full type information
• Signal Analysis: Cross-referencing .tscn connections with .gd script methods
• Dependency Mapping: Tracing resource references across the project
• Offline Modification: Programmatic changes to scenes and resources

Correctly Handles These Sections

• [gd_scene]: Scene metadata and format version
• [ext_resource]: External resource references (scripts, textures, etc.)
• [sub_resource]: Internal resource definitions (materials, shapes, etc.)
• [node]: Scene hierarchy with all node properties
• [connection]: Signal connections between nodes

Expected Output Format

The skill returns structured data objects that can be programmatically manipulated:

Scene Analysis Output

# Example: scene = godot_project.get_scene("res://scenes/ship.tscn")
scene = {
    "header": {
        "format_type": "gd_scene",
        "format_version": "3",
        "uid": "uid://bqxvxrxnch1qp"
    },
    "external_resources": [
        {
            "type": "Script",
            "path": "res://scripts/ship_controller.gd",
            "id": "1_0xxxx"
        }
    ],
    "nodes": {
        "Ship": {
            "type": "Node3D",
            "properties": {
                "transform": "Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"
            },
            "children": {
                "MeshInstance3D": {
                    "type": "MeshInstance3D",
                    "properties": {
                        "mesh": "SubResource(2)"
                    }
                }
            }
        }
    },
    "connections": [
        {
            "signal": "health_changed",
            "from": "Ship",
            "to": "Ship",
            "method": "_on_health_changed"
        }
    ]
}

Broken Signal Analysis Output

{
    "broken_signals": [
        {
            "type": "method_not_found",
            "signal": "pressed",
            "emitter_node": "StartButton",
            "target_node": "MainMenu",
            "target_method": "_on_start_clicked",
            "source_file": "res://scenes/main_menu.tscn",
            "script_file": "res://scripts/main_menu.gd",
            "line_number": 15,
            "available_methods": ["_on_start_pressed", "_on_options_pressed"],
            "suggestion": "Change connection method to '_on_start_pressed'"
        }
    ]
}

Usage Instructions

Basic Scene Parsing

# Parse a scene file
scene = godot_project.get_scene("res://scenes/player_ship.tscn")

# Navigate the node tree
root_node = scene.get_root_node()
mesh_node = scene.get_node("MeshInstance3D")

# Check node properties
transform = scene.get_node_property("MeshInstance3D", "transform")

Resource Analysis

# Parse a resource file
resource = godot_project.get_resource("res://resources/ship_stats.tres")

# Get resource properties
mass = resource.get_property("mass")
max_velocity = resource.get_property("max_velocity")

Broken Signal Detection

# Find all broken signals in the project
broken_signals = godot_project.find_broken_signals()

for signal_issue in broken_signals:
    print(f"Broken signal: {signal_issue['signal']}")
    print(f"In file: {signal_issue['source_file']}")
    print(f"Suggestion: {signal_issue['suggestion']}")

Integration with Workflow

For QAEngineer Agent

• Use find_broken_signals() to validate signal connections
• Use get_scene() to verify scene structure
• Use get_resource() to validate resource references

For AssetPipelineEngineer Agent

• Use get_scene() to analyze generated scene structure
• Use scene modification APIs to programmatically fix issues
• Verify generated EditorImportPlugin output

For GDScriptEngineer Agent

• Use parser to verify generated script attachments
• Validate scene-script compatibility
• Check for missing @export properties in resources

Critical Requirements

• NO REGEX: Never use regular expressions for parsing .tscn/.tres files
• ALWAYS use API: Use GodotProject methods, not direct file manipulation
• Structural validation: Ensure all five sections are properly parsed
• Type safety: Maintain Godot's type system in parsed objects
• Cross-referencing: Signal analysis must check both .tscn and .gd files

Error Handling Patterns

The skill provides detailed error information for debugging:

{
    "parse_error": {
        "file": "res://scenes/corrupted.tscn",
        "line": 45,
        "section": "node",
        "issue": "malformed_node_definition",
        "message": "Invalid node property format",
        "suggestion": "Check for missing quotes or commas",
        "recovery": "skipping_to_next_section"
    }
}

This skill is the foundation for reliable offline analysis and modification of Godot project assets, enabling the automated remediation loop to work with structured, validated data rather than raw text manipulation.