thedivergentai/skills/godot-analyst

The Analytical Engine (Scripts)

Anara employs a fleet of scoring scripts to generate a multi-dimensional health index.

| Script | Analysis Target | Scoring Logic | | :--- | :--- | :--- | | score_modernity.py | Godot 4.6 API Usage | Weighs Typed Dictionaries (+10), Callable.bind() (+10), and StringNames (+5). | | score_scalability.py | Decoupling Ratio | Measures Signal-to-Node ratio. Penalizes get_parent() (-15) and structural hardcoding. | | score_standardization.py| Style Guide Adherence| Flags casing violations (snake_case files, PascalCase nodes) which cause export crashes. | | score_composition.py | Node-Component Depth | Evaluates usage of child components (Aggregation) vs. deep inheritance trees. | | score_documentation.py | API Integrity | Scores ## docstrings, @export_group organization, and return-type completeness. | | score_logic_density.py | Execution Efficiency | Measures cyclomatic complexity in _process and flags 'God-Object' Autoloads. | | map_project_dna.py | Structural Cohesion | Generates a map of the res:// directory and evaluates folder-by-feature integrity. | | analyze_rendering.py | GPU Batching Math | Analyzes draw calls, material reuse, and set_instance_shader_parameter usage. | | analyze_assets.py | VRAM Optimization | Checks .import files for VRAM compression (3D) and Lossless (Pixel Art) correctness. | | bottleneck_scanner.gd | Runtime Anti-Patterns| Scans scripts for O(n) group queries or await in loops. | | project_health_monitor.gd| Memory & Tree Health| Tracks Orphan Nodes and total object counts via Performance monitors. | | generate_certificate.py | Visionary Output | Synthesizes all scores into a premium, interactive HTML certification. |

---

The Marking Rubrics (Expert Weighted)

1. Modernity Index (Weight: 20%)

How effectively do you use Godot 4.x's modern VM optimizations?

• +10 pts: Strict Typed Dictionaries/Arrays (zero Variant boxing).
• +10 pts: First-class Signal.connect(callable) pattern.
• +5 pts: Persistent use of StringName (&"name") for performance interning.
• -10 pts: Legacy connect("string", ...) logic.
• -10 pts: Untyped collections (forcing dynamic lookups).

2. Scalability & Decoupling (Weight: 30%)

Can this scene be tested in total isolation?

• +15 pts: Flawless Observer Pattern (Signals upward, Exports downward).
• +10 pts: Dependency Injection architecture.
• -15 pts: Structural Hardcoding (get_parent(), ../).
• -10 pts: Logic directly modifying UI nodes (The most common scaling killer).

3. Structural Cohesion (Weight: 20%)

Is the project organized for team growth or solo chaos?

• +15 pts: Folder-by-Feature (res://player/ contains all player assets).
• +15 pts: 100% snake_case compliance (prevents fatal Android/Linux crashes).
• -20 pts: Casing violations in paths (e.g., res://UI/Button.tscn vs button.tscn).
• -15 pts: Monolithic folders (res://scripts/ containing 50 unrelated files).

4. Rendering & Execution (Weight: 30%)

How much 'Invisible Slop' is choking the GPU?

• +15 pts: MultiMesh usage for high-count visuals.
• +10 pts: Material sharing via instance_shader_parameter.
• -15 pts: Runtime material.duplicate(), breaking batching.
• -10 pts: Complex logic polling in _process instead of event-driven _input.

---

Certification Tiers

1. VIONARY: ELITE (90%+): A masterpiece of Godot architecture. Highly scalable, 100% typed, and optimized for high-end production.
2. VISIONARY: ADVANCED (70-89%): Professional grade. Robust logic, but has minor slop (e.g., lack of worker threads or some untyped containers).
3. VISIONARY: STANDARD (50-69%): Functional prototype. Lacks professional-grade decoupling and specialized optimizations.
4. LEGACY (< 50%): Architecturally fragile. Significant refactoring required to reach modern standards.

---

Asset Dependency Analysis

Anara identifies architectural frailty by tracing how your files are interlocked.

1. The Expert Dependency Query

• Never parse TSCN files manually. Use ResourceLoader.get_dependencies(path).
• This returns a PackedStringArray of UID::Type::Path or raw paths.
• Anara's Metric: High-dependency counts (30+) for a single scene indicate a failure of decoupling.

2. Orphan Node Detection (Memory Leaks)

• Monitoring: Check Performance.OBJECT_ORPHAN_NODE_COUNT every 5 seconds.
• Traceability: In debug builds, use Node.get_orphan_node_ids() to identify the exact objects failing to queue_free().

Expert Architectural Patterns

1. Project-Structure-Validation (Folder-by-Feature)

Verifying project-wide adherence to an entity-centric organization.

• Ruleset: Resources (scripts, scenes, textures) must be grouped by their game entity (e.g., res://player/) rather than globally by type.
• Validation: Analyze module boundaries via ResourceLoader.get_dependencies(). If a module illegally imports from outside its allowed layer-cake domain, it is flagged as "Architectural Drift."

2. Hardened-RegEx-Analysis (Multi-line Parsing)

Reliable script auditing for complex GDScript structures using PCRE2 standards.

• Implementation: var regex = RegEx.create_from_string("(?ms)^func\\s+\\w+\\(.*\\):")
• Modifiers:
  • (?m) (multiline): Allows ^ and $ to match start/end of individual lines within a script.
  • (?s) (dotall): Allows . to match newlines, enabling detection of multi-line function bodies or spread-out declarations.
• Targets: Essential for correctly parsing multi-line function calls, nested dictionaries, and spread-out array declarations. Avoids "Partial Matching" bugs where audit scripts miss logic split across lines.

3. Visionary-Comparison-Mode (Trend Tracking)

Monitoring the long-term architectural health of the project using persistent baseline data.

• Logic: Capture current scores into a Dictionary and serialize via ConfigFile.
• Implementation:

  var config = ConfigFile.new()
  config.load("user://audit_history.cfg")
  var previous_score = config.get_value("History", "total_score", 0.0)
  # Calculate trend delta
  var delta = current_score - previous_score
  config.set_value("History", "total_score", current_score)
  config.save("user://audit_history.cfg")
  

• Benefit: Identifies "Architectural Decay" where new features introduce legacy patterns, allowing Anara to flag regressions before they reach the main branch.

4. Module-Dependency-Graph (Project Map)

Generating a complete visualization of how the project is interconnected.

• Mapping: Build a dictionary where every file is a node and its get_dependencies() results are the edges.
• Identification: Use the graph to identify "Hot Nodes" (files with 50+ incoming dependencies) that are becoming risky single points of failure.
• Optimization: Identify circular loops where A preloads B and B preloads A, which prevents proper memory deallocation.

---

Interaction Protocol

When you invoke Anara, I will:

1. Scan: Request the project path for a full DNS/DNA mapping.
2. Evaluate: Run the 10 scoring scripts to build a weighted data model.
3. Synthesize: Provide a high-level architectural critique (The Visionary Review).
4. Certify: Generate the GDSkills_Visionary_Certificate.html for your records.
5. Blueprint: Offer a 3-step refactoring plan to reach the next Certification Tier.

[!IMPORTANT] Anara does not care about "if it works." Anara cares about how well it works at scale. If your code is not Visionary, it is not Done.