Godot Custom Resource Generator - R&D Framework Implementation

Instructions for GDScriptEngineer Agent

This skill implements the Reduce & Delegate (R&D) philosophy for Custom Resource generation:

Reduce: Move "How" to Deterministic Code

• Complex JSON schema analysis is implemented in lib/json_schema_analyzer.py
• GDScript code generation logic is handled by lib/gdscript_generator.py
• Resource validation is performed by lib/resource_validator.py
• Eliminates thousands of tokens of prompt instructions for resource generation

Delegate: Move "Work" to Isolated Components

• Schema analysis delegated to json_schema_analyzer.py module
• Code generation delegated to gdscript_generator.py module
• Validation delegated to resource_validator.py module
• Structured JSON communication between components

When to Use

Use this skill whenever you need to convert structured data from legacy parse-tbl output into Godot Custom Resource scripts. This is an Implement phase skill that creates the data foundation for the resource pipeline.

This skill MUST be used after the parse-tbl skill has generated structured JSON schema data.

What This Skill Does

This skill transforms JSON schema data into complete, idiomatic Godot Custom Resource scripts:

Core Functionality (Type 2 Executable Skill)

• Schema Analysis: Analyzes JSON schemas from parse-tbl skill with intelligent pattern recognition
• Type Mapping: Converts JSON types to appropriate GDScript types with @export hints
• Property Generation: Creates @export var declarations with proper naming conventions
• Template Rendering: Supports Jinja2 templates for flexible code generation
• Validation: Generates validation methods for data integrity checking
• Helper Methods: Creates utility methods based on resource type and properties

Output Structure

The generated Custom Resource includes:

• File Header: Comprehensive metadata with generation information
• Class Declaration: Proper class_name and extends Resource
• Export Properties: All schema fields as typed @export properties with hints
• Resource-Specific Methods: Specialized methods based on resource type (ship, weapon, etc.)
• Utility Methods: Common methods like to_dict(), from_dict(), get_summary()
• Validation Methods: Optional validation for data integrity

Expected Input/Output

Input Requirements

• JSON Schema: Structured output from parse-tbl skill containing:
  • entries: Object with named entries and their properties
  • Property values for type inference and default value extraction
  • Consistent structure across entries for analysis
• Resource Type: Optional type hint for specialized templates and methods
• Output Path: Destination path for generated .gd file

Output Deliverables

• GDScript Resource File: Complete Custom Resource script ready for Godot
• Class Integration: Proper class_name for Godot editor integration
• Type Safety: All properties properly typed with appropriate defaults
• Documentation: Comprehensive comments and method documentation
• Validation Report: JSON result with generation statistics and validation status

Usage Instructions

Basic Usage

# Generate single resource from schema
python scripts/generate_resource.py --schema ships_schema.json --output ShipStats.gd

# Generate with specific resource type
python scripts/generate_resource.py --schema weapons.json --output WeaponData.gd --type weapon

Advanced Usage

# Generate with validation methods
python scripts/generate_resource.py --schema ships.json --output ShipStats.gd --include-validation

# Generate with custom template
python scripts/generate_resource.py --schema ships.json --output ShipStats.gd --template custom_template.gd

# Skip helper methods (minimal output)
python scripts/generate_resource.py --schema ships.json --output ShipStats.gd --no-helper-methods

# Batch process directory
python scripts/generate_resource.py --batch --input-dir schemas/ --output-dir resources/

# Verbose output with detailed progress
python scripts/generate_resource.py --schema ships.json --output ShipStats.gd --verbose

Batch Processing (Enhanced Workflow Automation)

# Process all JSON files in directory with enhanced batch processor
python scripts/batch_processor.py --input-dir schemas/ --output-dir resources/

# Process specific file patterns with validation
python scripts/batch_processor.py --input-dir schemas/ --output-dir resources/ --pattern "*_ship.json" --include-validation

# Process with custom error handling
python scripts/batch_processor.py --input-dir schemas/ --output-dir resources/ --max-concurrent 2 --no-continue-on-error --verbose

Resource Testing and Validation

# Test generated resource for quality and compliance
python scripts/test_resources.py --resource ShipStats.gd --schema ships_schema.json

# Test complete generation pipeline
python scripts/test_resources.py --test-generation --schema ships_schema.json --type ship --include-validation

# Batch test generated resources
python scripts/test_resources.py --resource resources/ShipStats.gd --verbose

Command Line Arguments

• --schema (required): Path to JSON schema file from parse-tbl skill
• --output (required): Output path for generated GDScript file
• --type (optional): Resource type (ship, weapon, species, etc.)
• --template (optional): Path to custom Jinja2 template file
• --include-validation (optional): Generate validation methods
• --no-helper-methods (optional): Skip helper method generation
• --batch (optional): Enable batch processing mode
• --input-dir (optional): Input directory for batch processing
• --output-dir (optional): Output directory for batch processing
• --verbose (optional): Enable detailed output and progress reporting

R&D Architecture Implementation

Component Delegation

lib/json_schema_analyzer.py - Schema Analysis Component

• Analyzes JSON schemas from parse-tbl output for resource patterns
• Recognizes data types and structures for proper GDScript mapping
• Extracts property definitions with validation rules and export hints
• Determines resource type and appropriate class naming conventions

lib/gdscript_generator.py - Code Generation Component

• Generates properly formatted GDScript Custom Resource code
• Supports Jinja2 templates for flexible code generation
• Creates resource-specific helper methods based on property analysis
• Formats default values and export hints according to Godot standards

lib/resource_validator.py - Validation Component

• Validates generated GDScript code for syntax and structure compliance
• Checks Godot style guide compliance and naming conventions
• Validates against original schema for property completeness
• Generates detailed validation reports with warnings and errors

Data Flow Architecture

1. Input Processing: Validate and load JSON schema from parse-tbl skill
2. Schema Analysis: Use json_schema_analyzer to extract resource patterns
3. Code Generation: Use gdscript_generator to create GDScript content
4. Validation: Use resource_validator to verify output quality
5. Statistics: Generate comprehensive analysis and execution report

JSON to GDScript Mapping

The skill follows comprehensive type mapping from config/type_mappings.json:

Type Conversion Table

JSON Type	GDScript Type	Export Hint	Default Value	Example
string	String	None	""	@export var name: String = ""
integer	int	@export_range	0	@export var count: int = 0
float	float	@export_range	0.0	@export var speed: float = 0.0
boolean	bool	None	false	@export var enabled: bool = false
array[string]	Array[String]	None	[]	@export var items: Array[String] = []
array[number]	Array[float]	None	[]	@export var values: Array[float] = []
object	Dictionary	None	{}	@export var data: Dictionary = {}

Special Pattern Recognition

• Vector3: Detects comma-separated numeric values (e.g., "1.0, 2.0, 3.0")
• Color: Detects hex colors (#FF0000) and RGB tuples (255, 0, 0)
• Property Validation: Automatically generates validation rules for common patterns

Naming Convention Conversion

• $Mass → mass (removes $ prefix, snake_case)
• $Max Velocity → max_velocity (spaces to underscores, lowercase)
• Primary Banks → primary_banks (CamelCase to snake_case)
• Engine Glow → engine_glow (consistent formatting)

Resource Type Specialization

The skill automatically detects resource types and applies specialized templates:

Ship Resources

• Detection: Keywords like "ship", "fighter", "bomber", "corvette"
• Properties: mass, max_velocity, shields, hull, weapons
• Helper Methods: get_total_defense(), get_momentum(), get_weapon_capacity()
• Template: templates/ship_resource_template.gd

Weapon Resources

• Detection: Keywords like "weapon", "laser", "missile", "torpedo"
• Properties: damage, fire_rate, range, energy_cost
• Helper Methods: get_damage_per_second(), is_in_range()
• Template: templates/weapon_resource_template.gd

Armor Resources

• Detection: Keywords like "armor", "shield", "protection"
• Properties: hitpoints, damage_reduction, armor_type
• Helper Methods: get_effective_hitpoints()
• Template: templates/armor_resource_template.gd

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-resource",
  "version": "2.0.0",
  "execution_time_ms": 234,
  "result": {
    "class_name": "ShipStats",
    "resource_type": "ship",
    "output_file": "ShipStats.gd",
    "schema_file": "ships_schema.json",
    "properties_count": 12,
    "template_used": "default",
    "validation_passed": true,
    "validation_warnings": [],
    "statistics": {
      "export_properties": 12,
      "helper_methods": true,
      "validation_methods": false,
      "source_entries": 3
    }
  }
}

Error Response

{
  "status": "error",
  "timestamp": "2025-01-15T10:30:00Z",
  "skill_name": "generate-resource",
  "version": "2.0.0",
  "error": {
    "type": "invalid_json",
    "message": "Invalid JSON format in schema file",
    "details": {
      "file": "ships_schema.json",
      "line": 15,
      "column": 8
    },
    "suggestion": "Validate JSON syntax using a JSON validator",
    "recovery": {
      "automated_fix_possible": false,
      "manual_steps": [
        "Use a JSON validator to check syntax",
        "Check line 15 and column 8",
        "Ensure proper JSON formatting (commas, brackets, quotes)"
      ]
    }
  },
  "exit_code": 2
}

Exit Codes

• 0: Success - Resource generated and validated
• 1: Validation Error - Invalid input parameters or file paths
• 2: Processing Error - Schema parsing or code generation failed
• 3: System Error - Import errors or resource access issues

Integration with Agentic Pipeline

Prerequisites (Required)

1. parse-tbl skill: Must have processed .tbl files into JSON schema format
2. godot-style-guide skill: For ensuring code quality compliance

Generated Resources

1. GDScript Custom Resource: Complete resource script ready for Godot
2. Class Integration: Proper class_name for editor integration
3. Validation Methods: Optional data integrity checking
4. Generation Report: Statistics and validation results

Implementation Workflow

1. MigrationArchitect runs parse-tbl skill on legacy table files
2. GDScriptEngineer invokes this skill with schema output
3. Skill generates complete Custom Resource script with validation
4. QA Engineer validates integration using run-gdlint skill
5. GDScriptEngineer enhances generated script if needed

File Placement Guidelines

• Custom Resources: res://resources/{resource_type}/{ClassName}.gd
• Generated Files: Place in appropriate resource directories
• Templates: Use templates/ directory for custom templates

Template System

Supported Template Engines

• Jinja2: Primary template engine with full feature support
• Fallback: Built-in template generation if Jinja2 unavailable

Template Variables

Templates receive this context:

• schema: Complete ResourceSchema object with all properties
• class_name: Generated class name (e.g., "ShipStats")
• resource_type: Detected resource type (e.g., "ship")
• properties: Array of PropertyDefinition objects
• include_validation: Boolean flag for validation method generation
• timestamp: Generation timestamp in ISO format

Default Templates

• base_resource_template.gd: Generic resource template
• ship_resource_template.gd: Ship-specific with combat methods
• weapon_resource_template.gd: Weapon-specific with damage calculations
• armor_resource_template.gd: Armor-specific with protection and resistance calculations

Specialized Template Features

Weapon Resource Template (weapon_resource_template.gd)

• Damage Calculations: get_damage_per_second(), get_effective_damage()
• Range and Targeting: is_in_range(), can_fire(), tracking capabilities
• Classification: Automatic weapon class detection (light/medium/heavy fighter, capital)
• Ammo and Energy: Resource management with capacity and consumption tracking
• Damage Types: Energy, kinetic, explosive resistance calculations

Armor Resource Template (armor_resource_template.gd)

• Protection Calculations: get_effective_hitpoints(), damage reduction formulas
• Resistance System: Energy, kinetic, explosive resistance with damage type handling
• Repair and Regeneration: repair(), regenerate(), status tracking
• Damage Assessment: calculate_damage(), get_armor_status() with descriptive levels
• Classification: Protection level detection (Light/Medium/Heavy/Capital)
• Quality Assurance: Validation for logical consistency and faction-appropriate configurations

Quality Assurance & Validation

Automatic Validation

Generated resources undergo comprehensive validation:

• Syntax Validation: Proper GDScript syntax and structure
• Type Validation: Correct GDScript types and export hints
• Naming Validation: Compliance with snake_case/PascalCase conventions
• Schema Compliance: All schema properties included in output

Quality Metrics

Each generated resource includes quality assessment:

• Property Count: Number of exported properties generated
• Method Generation: Status of helper and validation methods
• Template Usage: Which template was used for generation
• Validation Status: Pass/fail results from automated validation

Style Guide Compliance

Generated code follows Godot style guidelines:

• snake_case for variables and functions
• PascalCase for class names
• Static typing required for all properties
• Documentation comments for all public methods

Performance Considerations

Optimization Features

• Modular Architecture: Separate components for specific tasks
• Template Caching: Reuse parsed templates for multiple generations
• Batch Processing: Efficient handling of multiple schema files
• Memory Efficient: Streaming processing for large schemas

Scalability

• Large Schemas: Handles schemas with thousands of entries
• Batch Generation: Processes multiple files in single operation
• Configuration: Adaptable to different schema formats and patterns

This skill exemplifies the R&D framework by converting complex, context-intensive resource generation into deterministic, reliable automation while maintaining the flexibility to handle diverse schema patterns and resource types.