LimboAI Tree Generator - R&D Framework Implementation

Instructions for MigrationArchitect or GDScriptEngineer Agent

This skill implements the Reduce & Delegate (R&D) philosophy for AI migration:

Reduce: Move "How" to Deterministic Code

• Complex tree generation logic is implemented in deterministic Python modules
• C++ AST pattern recognition is handled by specialized analyzer
• .tres file formatting follows strict validation rules
• Eliminates 10,000+ tokens of prompt instructions for tree generation

Delegate: Move "Work" to Isolated Components

• C++ AST analysis delegated to cpp_ast_analyzer.py module
• .tres generation delegated to tres_generator.py module
• Configuration mapping handled by config/cpp_to_limboai_mapping.json
• Structured JSON communication between components

When to Use

Use this skill whenever you need to:

• Convert C++ AI logic from aigoals.cpp, aiturret.cpp to LimboAI Behavior Trees
• Generate hierarchical AI decision trees for ship and turret behaviors
• Create .tres files that define complete AI behavior structure
• Bridge deterministic C++ AI logic to Godot's visual AI system

This skill MUST be used after the cpp-code-analyst skill has generated structured C++ AST analysis.

What This Skill Does

This skill transforms structural C++ AI analysis into complete LimboAI Behavior Tree resources:

Core Functionality (Type 2 Executable Skill)

• AST Analysis Processing: Analyzes structured C++ AST data for AI patterns
• Tree Structure Generation: Creates hierarchical Behavior Tree from C++ logic
• Node Type Mapping: Maps C++ patterns to LimboAI node types using configuration
• Resource File Creation: Generates valid .tres files with proper LimboAI formatting
• Validation: Ensures generated trees are syntactically correct and complete

Output Structure

The generated Behavior Tree includes:

• Composite Nodes: Selectors, Sequences, Parallel nodes from C++ control flow
• Decorator Nodes: Inverters, Repeaters from C++ loops and conditions
• Action Node References: Calls to custom GDScript BTAction classes
• Blackboard Integration: State variables from C++ member variables
• Metadata: Complete mapping information and statistics

Expected Input/Output

Input Requirements

• C++ AST Analysis: JSON file from cpp-code-analyst skill with:
  • ai_analysis: High-level AI information and behavior types
  • decision_patterns: Control flow structures and logic patterns
  • state_variables: Variables to be mapped to blackboard
  • task_mappings: C++ function to GDScript class mappings
  • behavior_complexity: Complexity assessment of the AI logic

Output Deliverables

• BehaviorTree Resource: Complete .tres file ready for LimboAI plugin
• Action Node Requirements: List of required GDScript BTAction classes
• Blackboard Schema: Variables and their type definitions
• Generation Statistics: Tree complexity and node count information

Usage Instructions

Basic Usage

# Generate behavior tree from C++ analysis
python scripts/generate_limboai_tree.py --input ai_analysis.json --output fighter_behavior.tres

Advanced Usage

# Generate with specific behavior type
python scripts/generate_limboai_tree.py --input turret_analysis.json --type combat --output turret_defense.tres

# Generate with custom configuration
python scripts/generate_limboai_tree.py --input ai_analysis.json --config custom_mapping.json --output advanced_ai.tres

# Generate with verbose output
python scripts/generate_limboai_tree.py --input ai_analysis.json --output behavior.tres --verbose

Command Line Arguments

• --input (required): Path to C++ AST analysis JSON file
• --output (required): Output path for generated .tres file
• --type (optional): Behavior type (combat, navigation, formation, general)
• --config (optional): Path to custom configuration file
• --template (optional): Path to custom template file
• --verbose (optional): Enable detailed output and statistics

R&D Architecture Implementation

Component Delegation

lib/cpp_ast_analyzer.py - AST Analysis Component

• Analyzes structured C++ AST data for AI behavior patterns
• Recognizes control flow structures (if-else, loops, switches)
• Extracts state variables and function mappings
• Assesses behavior complexity and nesting depth

lib/tres_generator.py - .tres File Generation Component

• Generates properly formatted Godot .tres resource files
• Validates tree structure for LimboAI compatibility
• Creates subresource definitions for all tree nodes
• Formats blackboard variable configurations

config/cpp_to_limboai_mapping.json - Configuration Component

• Maps C++ constructs to LimboAI node types
• Defines behavior pattern keywords and structures
• Specifies blackboard variable types and defaults
• Provides task mappings for C++ functions

Data Flow Architecture

1. Input Processing: Validate and load C++ AST analysis JSON
2. Pattern Recognition: Use cpp_ast_analyzer to extract AI patterns
3. Tree Construction: Build hierarchical tree structure based on patterns
4. Resource Generation: Use tres_generator to create .tres file
5. Validation: Verify output compatibility with LimboAI plugin
6. Statistics: Generate comprehensive analysis report

C++ to LimboAI Mapping

The skill follows comprehensive mapping from config/cpp_to_limboai_mapping.json:

File-Level Mapping

C++ File	Purpose	LimboAI Target	Implementation
aigoals.cpp	High-level strategic objectives	High-Level Branches	Selector/Sequence nodes for strategic decisions
aiturret.cpp	Low-level weapon/turret behaviors	BT Action Nodes	Custom GDScript BTAction classes
ai_profiles.cpp	AI personality and parameters	Blackboard Variables	Resource loaded to Blackboard at runtime

Construct-Level Mapping

C++ Construct	LimboAI Node	Implementation Notes
Sequential logic (if-else chains)	Sequence	Execute children in order until failure
Conditional logic (switch/case)	Selector	Execute children until success
Loop logic (while/for)	Repeater	Repeat child N times or indefinitely
Function negation	Inverter	Invert result of child node
Boolean conditions	Condition	Evaluate against blackboard variables
Method calls	BTAction	Reference custom GDScript classes

Variable Mapping

C++ Variable Type	Blackboard Type	Example
bool	TYPE_BOOL	is_combat_ready, target_locked
float/int	TYPE_FLOAT/TYPE_INT	health_percentage, ammo_count
Object*	TYPE_OBJECT	current_target, selected_weapon
Vector3	TYPE_VECTOR3	formation_position, destination

Error Handling (Strong Signal Protocol)

The skill provides structured JSON error reporting following the R&D framework:

Success Response

{
  "status": "success",
  "timestamp": "2025-01-15T10:30:00Z",
  "skill_name": "generate-limboai-tree",
  "version": "2.0.0",
  "execution_time_ms": 456,
  "result": {
    "behavior_type": "combat",
    "output_file": "fighter_behavior.tres",
    "analysis_file": "ai_analysis.json",
    "tree_structure": {
      "total_nodes": 15,
      "max_depth": 4,
      "action_nodes": 6,
      "condition_nodes": 4
    },
    "required_tasks": ["BTAimAtTarget", "BTFireWeapons", "BTEvasiveManeuvers"]
  },
  "statistics": {
    "validation_passed": true,
    "blackboard_variables": 8,
    "complexity_score": 7.5
  }
}

Error Response

{
  "status": "error",
  "timestamp": "2025-01-15T10:30:00Z",
  "skill_name": "generate-limboai-tree",
  "version": "2.0.0",
  "error": {
    "type": "validation_error",
    "code": "INVALID_AST_STRUCTURE",
    "message": "C++ AST analysis missing required fields",
    "details": {
      "missing_fields": ["decision_patterns", "ai_analysis"],
      "provided_fields": ["functions", "variables"]
    },
    "suggestion": "Re-run cpp-code-analyst skill with complete analysis",
    "recovery": {
      "automated_fix_possible": false,
      "manual_steps": [
        "Verify cpp-code-analyst completed successfully",
        "Check AST analysis JSON contains all required fields",
        "Ensure decision_patterns array is not empty"
      ]
    }
  },
  "exit_code": 1
}

Exit Codes

• 0: Success - Behavior Tree generated and validated
• 1: Validation Error - Invalid input analysis structure
• 2: Processing Error - Tree generation or .tres creation failed
• 3: System Error - File I/O, permission, or resource issues

Integration with Agentic Pipeline

Prerequisites (Required)

1. cpp-code-analyst skill: Must have analyzed C++ AI code and generated AST JSON
2. ai-migration-patterns skill: For architectural guidance and R&D principles

Generated Resources

1. .tres Behavior Tree: Complete resource file for LimboAI plugin
2. Action Node Requirements: List of GDScript classes requiring implementation
3. Blackboard Schema: Variable definitions for AI state management
4. Generation Report: Statistics and validation results

Implementation Workflow

1. MigrationArchitect runs cpp-code-analyst skill on C++ AI code
2. MigrationArchitect invokes this skill with analysis output
3. Skill generates complete Behavior Tree .tres resource
4. GDScriptEngineer implements required custom BTAction classes
5. QA Engineer validates integration with LimboAI plugin

File Placement Guidelines

• Behavior Trees: res://ai/behaviors/[behavior_name].tres
• Action Scripts: res://scripts/ai/actions/[ActionName].gd
• Blackboard Resources: res://ai/variables/[behavior_name]_blackboard.tres

Quality Assurance & Validation

Automatic Validation

Generated trees undergo comprehensive validation:

• Structure Validation: Proper parent-child relationships and node hierarchy
• Type Validation: Correct LimboAI node types and property assignments
• Reference Validation: Valid file paths and GDScript class references
• Blackboard Validation: Proper variable type definitions and usage

Quality Metrics

Each generated tree includes quality assessment:

• Complexity Score: Overall behavior complexity (0-10 scale)
• Node Distribution: Breakdown of composite, action, and condition nodes
• Depth Analysis: Maximum nesting depth and average depth
• Completeness: Percentage of required elements implemented

Debugging Support

• Verbose Mode: Detailed step-by-step generation process
• Statistics Output: Comprehensive tree analysis and metrics
• Error Context: Detailed error messages with recovery suggestions
• Template Examples: Sample inputs and expected outputs in templates/

Performance Considerations

Optimization Features

• Modular Architecture: Separate components for specific tasks
• Configuration-Driven: Customizable mappings without code changes
• Validation Caching: Reuse validation results where possible
• Memory Efficient: Streaming processing for large AST analyses

Scalability

• Large Trees: Handles complex AI behaviors with 100+ nodes
• Batch Processing: Can process multiple analyses in sequence
• Configuration: Adaptable to different C++ codebases and patterns

This skill exemplifies the R&D framework by converting complex, context-intensive AI behavior generation into deterministic, reliable automation while maintaining the flexibility to handle diverse C++ AI patterns and structures.