POF to GLB Converter - 3D Geometry Migration

Instructions for AssetPipelineEngineer Agent

When a task requires converting a .pof model's 3D geometry, you MUST use the scripts/convert_pof_to_glb.py skill.

Provide the path to the input .pof file, the output .glb path, and the directory containing the model's textures.

This skill will parse the .pof, reconstruct the geometry from the complex bsp_data (BSP Tree), convert textures to PBR, and build a complete .glb file.

When to Use

Use this skill whenever you need to convert 3D geometry from WCS proprietary format to Godot-compatible format. This is an Implement phase skill that handles the heavy lifting of 3D model conversion.

Usage Instructions

Basic Usage

python scripts/convert_pof_to_glb.py input.pof output.glb --textures-dir textures/

Command Line Interface

python scripts/convert_pof_to_glb.py [OPTIONS] INPUT_POF OUTPUT_GLB

Options:
  --textures-dir PATH     Directory containing model textures [required]
  --lod-levels INT        Number of LOD levels to generate [default: 3]
  --optimize-mesh         Enable mesh optimization [default: True]
  --convert-materials     Convert materials to PBR [default: True]
  --verbose, -v           Enable verbose logging
  --help                  Show help message

Input Requirements

• POF File: Binary 3D model file with geometry and material references
• Texture Directory: Folder containing legacy texture files (.pcx, .dds, .ani)
• Conversion Config: Optional JSON file for material mapping overrides

Output Deliverables

• GLB File: Complete 3D model with embedded geometry and materials
• Conversion Report: JSON with statistics and any warnings
• LOD Files: Optional lower-detail versions for performance

What This Skill Does

This is the "heavy-lifter" skill of the asset pipeline, responsible for the full 3D geometry conversion. Its complexity warrants a detailed technical blueprint.

Geometry Processing

• Full POF Parsing: Parses all chunks (PSPO, HDR2, TXTR, OBJ2, etc.) into Python dataclasses
• BSP Tree Traversal: Recursively traverses bsp_data inside OBJ2 chunks to aggregate polygon fragments
• Mesh Reconstruction: Combines BSP fragments into coherent, indexed meshes with vertices, normals, and UVs
• Large Array Handling: Uses numpy for efficient processing of large vertex data arrays

Material Conversion

• Legacy Texture Loading: Uses FreeImagePy to load legacy textures (.pcx, .dds) from TXTR chunk
• PBR Material Mapping: Converts legacy texture maps to glTF PBR material slots:
  • diffuse → baseColorTexture
  • glow → emissiveTexture
  • shine → metallicRoughnessTexture
  • bump → normalTexture
• Texture Format Conversion: Converts legacy formats to PNG/JPEG for glTF compatibility

Scene Assembly

• glTF Scene Construction: Uses pygltflib to build complete glTF scenes
• Single Binary Buffer: Creates optimized binary buffer for all geometry data
• Node Hierarchy: Reconstructs model's node hierarchy based on submodel_parent data
• Material Assignment: Applies converted materials to appropriate mesh primitives

Expected Output Format

The skill returns a completion status and saves the .glb file:

{
  "conversion_stats": {
    "input_file": "scimitar.pof",
    "output_file": "scimitar.glb",
    "vertices": 8452,
    "triangles": 4226,
    "materials": 3,
    "textures_converted": 5,
    "processing_time": 2.34
  },
  "lod_info": {
    "levels_generated": 3,
    "lod0_triangles": 4226,
    "lod1_triangles": 2113,
    "lod2_triangles": 1056
  }
}

Usage Instructions

Basic Usage

python scripts/convert_pof_to_glb.py input/scimitar.pof output/scimitar.glb --textures-dir textures/

The skill handles:

1. Parsing: Implements the full POF parser to read all chunks into Python dataclasses
2. Geometry Reconstruction: For each OBJ2 subobject, reads bsp_data blob and recursively traverses BSP Tree using SORTNORM (interior) and POLYLIST (leaf) nodes to aggregate polygon fragments
3. Texture Conversion: Uses FreeImagePy to load legacy textures and convert to modern formats
4. Material Translation: Maps legacy material properties to glTF PBR slots
5. glTF Assembly: Uses pygltflib to create BufferView, Accessor, Mesh, and Material objects
6. Serialization: Calls gltf.save() to serialize the final binary blob

Dependencies

• Python Libraries: pygltflib, FreeImagePy, numpy
• Input: .pof file + texture directory
• Output: Single .glb file with embedded materials and textures

Hybrid Strategy Note

The BSP parser implementation is a "non-trivial computer science problem". A v1.0 of this skill may adopt a hybrid strategy:

1. Use existing tools: Call "Pof Tools" via subprocess to convert POF → DAE (Collada)
2. Bridge conversion: Use pycollada to convert DAE → glTF
3. Fallback: Implement full BSP parser for production reliability

This de-risks the initial implementation while providing a path to full independence.

Material Mapping

Legacy to PBR Conversion

# POF texture types to glTF material slots
texture_mappings = {
    "diffuse": "baseColorTexture",      # Main albedo
    "glow": "emissiveTexture",         # Engine glows, lights
    "shine": "metallicRoughnessTexture", # Specular/roughness
    "bump": "normalTexture",           # Surface detail
    "ambient": "occlusionTexture"      # Ambient occlusion
}

PBR Material Properties

• Base Color: Direct mapping from diffuse textures
• Metallic: Calculated from shine/specular values
• Roughness: Inverse of specular sharpness
• Emission: Glow textures with intensity multiplier
• Normal: Converted from bump maps if available

Integration with Pipeline

Input Requirements

• POF File: Binary 3D model file with geometry and material references
• Texture Directory: Folder containing legacy texture files (.pcx, .dds)
• Conversion Config: Optional JSON file for material mapping overrides

Output Deliverables

• GLB File: Complete 3D model with embedded geometry and materials
• Conversion Report: JSON with statistics and any warnings
• LOD Files: Optional lower-detail versions for performance

Next Steps

After conversion:

1. The generated .glb file becomes the geometry part of the Composite Asset
2. parse-pof skill provides the metadata part
3. generate-importer skill creates the EditorImportPlugin to reunite them at import time

Critical Requirements

• Complete Geometry: Must extract all mesh data from BSP trees
• Material Accuracy: Preserve visual appearance through PBR conversion
• UV Preservation: Maintain original texture coordinates exactly
• Hierarchy Integrity: Preserve subobject relationships for metadata attachment
• Performance: Handle large models efficiently with numpy arrays

Error Handling

The skill provides detailed error reporting for troubleshooting:

{
  "conversion_error": {
    "type": "bsp_parsing_error",
    "chunk_id": "OBJ2",
    "subobject": "hull",
    "message": "Invalid BSP node in geometry data",
    "suggestion": "POF file may be corrupted, try hybrid conversion mode",
    "recovery": "fallback_to_dae_conversion"
  }
}

This skill transforms the complex proprietary 3D format into modern glTF while preserving all visual fidelity needed for the Composite Asset system.