POF to TSCN Converter - Complete Pipeline Integration

Instructions for AssetPipelineEngineer Agent

When a task requires converting a POF file directly to a ready-to-use Godot TSCN scene, you MUST use the scripts/create_pof_tscn.py skill.

This skill implements the complete conversion pipeline:

1. Geometry Extraction: Converts POF 3D geometry to GLB format
2. Metadata Parsing: Uses parse-pof skill output for game logic data
3. Scene Composition: Merges GLB geometry with POF metadata into complete TSCN files

This skill solves the "Composite Asset" problem by handling the entire workflow from source POF to final Godot scene.

When to Use

Use this skill whenever you need to:

• Convert POF files directly to Godot TSCN scenes
• Create complete, game-ready assets from WCS source files
• Automate the full pipeline from POF to functional Godot objects
• Produce scenes that combine 3D geometry with complete game logic

What This Skill Does

Complete Pipeline Implementation

• POF Geometry Processing: Extracts and converts 3D geometry to GLB format
• Metadata Integration: Consumes parse-pof skill JSON output
• Scene Generation: Creates complete .tscn files with merged geometry and metadata
• Node Reconstruction: Adds all game logic nodes (hardpoints, subsystems, thrusters, etc.)

Workflow Integration

The skill orchestrates these steps automatically:

1. Calls parse-pof skill to extract metadata from POF file
2. Processes POF geometry and exports as GLB
3. Combines GLB geometry with metadata in Godot scene
4. Generates final .tscn file ready for game use

Expected Input/Output

Input Requirements

• POF File: Source Wing Commander Saga POF model file
• Output Path: Destination path for the generated .tscn file

Output Deliverables

• GLB File: 3D geometry extracted from POF (intermediate output)
• TSCN File: Complete Godot scene with geometry and metadata
• Metadata JSON: Parsed game logic metadata (intermediate output)
• Conversion Report: Statistics and validation results

Usage Instructions

Basic Usage

python scripts/create_pof_tscn.py --pof scimitar.pof --output scenes/scimitar.tscn

Advanced Usage

# Convert with custom scale and temporary directory
python scripts/create_pof_tscn.py --pof fighter.pof --output scenes/fighter.tscn --scale 0.01 --temp-dir temp/

# Batch process multiple POF files
python scripts/create_pof_tscn.py --input-dir assets/pof/ --output-dir scenes/ --batch

# Convert with verbose output and custom configuration
python scripts/create_pof_tscn.py --pof capital.pof --output scenes/capital.tscn --config capital_config.json --verbose

Command Line Options

• --pof: Input POF file path
• --output: Output TSCN file path
• --input-dir: Input directory for batch processing
• --output-dir: Output directory for batch processing
• --scale: Scale factor for POF to Godot conversion (default: 0.01)
• --temp-dir: Temporary directory for intermediate files
• --config: Configuration file path
• --batch: Enable batch processing mode
• --verbose: Enable detailed output
• --keep-temp: Keep intermediate files (GLB, JSON)

POF Metadata to Godot Node Mapping

The skill reconstructs these game logic elements from parse-pof output:

Technical Implementation

Geometry Processing

• Uses POF binary format parsing to extract vertex data
• Converts BSP geometry to mesh data compatible with GLB format
• Applies coordinate system transformation for Godot compatibility
• Generates materials and textures from POF data

Metadata Integration

• Calls parse-pof skill to extract game logic metadata
• Maps POF chunk data to appropriate Godot node types
• Applies spatial transformations and positioning data
• Stores original POF data in node metadata for runtime access

Scene Generation

• Creates Godot scene hierarchy with proper node organization
• Places POF metadata nodes in organized structure under POF_Metadata root
• Applies collision layers and masks for game logic functionality
• Sets up node properties for runtime accessibility

Error Handling

The skill provides structured JSON error reporting:

{
  "conversion_error": {
    "type": "pof_parsing_error",
    "file": "scimitar.pof",
    "message": "Failed to parse POF geometry data",
    "suggestion": "Verify POF file is valid and not corrupted",
    "recovery": "Check POF file source and try again"
  }
}

Exit Codes

• 0: Success - TSCN scene created successfully
• 1: Validation Error - Invalid input files or parameters
• 2: Processing Error - POF parsing or GLB conversion failed
• 3: Scene Generation Error - TSCN creation failed
• 4: System Error - File I/O or Godot engine issues

Integration Benefits

Streamlined Workflow

• Single Command: Converts POF directly to TSCN without intermediate steps
• Automatic Cleanup: Manages temporary files and intermediate outputs
• Error Recovery: Provides detailed error messages and recovery suggestions
• Batch Processing: Handles multiple files efficiently

Complete Asset Generation

• Game Ready: Output TSCN files are immediately usable in Godot
• Metadata Access: All POF game logic data available at runtime
• Collision Setup: Proper collision layers and shapes configured
• Performance Optimized: Efficient scene structure for game use

Runtime Usage

After conversion, access POF metadata in GDScript:

# Load the generated scene
var ship_scene = preload("res://scenes/scimitar.tscn")
var ship_instance = ship_scene.instantiate()

# Find all weapon hardpoints
var gun_points = []
for child in ship_instance.get_node("POF_Metadata").get_children():
    if child.get_meta("pof_type") == "GPNT":
        gun_points.append(child)

# Access specific subsystem
var engines = ship_instance.get_node("POF_Metadata/SUBS_Engines")
var engine_hp = engines.get_meta("hitpoints")

# Use docking points for gameplay
var dock_ports = []
for child in ship_instance.get_node("POF_Metadata").get_children():
    if child.get_meta("pof_type") == "DOCK":
        dock_ports.append(child)

This skill provides the most direct path from WCS source assets to functional Godot game objects, handling the complete conversion pipeline automatically while maintaining full game logic functionality.