Star Freight Client Handbook

The Star Freight Client is a Godot 4.6 rendering surface for the Star Freight space merchant RPG. It displays crew, creatures, and hostiles using pixel sprite packs generated by the Sprite Foundry pipeline.

The Python engine (portlight) is always the source of truth. This client never computes game logic — it renders what the engine tells it via JSON-RPC over stdio.

Key Concepts

• Sprite packs: 8-direction pixel art with albedo, normal, and depth maps
• Engine bridge: JSON-RPC 2.0 subprocess communication
• Pack loader: Manifest-driven texture loading with CanvasTexture
• Character node: Sprite2D wrapper with direction switching

Project Structure

star-freight-client/
├── project.godot           # Godot 4.6 project (960×640, nearest-neighbor)
├── assets/characters/      # Vendored sprite packs
├── scripts/
│   ├── pack_loader.gd      # Manifest → CanvasTexture pipeline
│   ├── engine_bridge.gd    # JSON-RPC client (spawns Python subprocess)
│   ├── character_node.gd   # Sprite2D with 8 directions
│   ├── roster_scene.gd     # Crew display scene + input handling
│   └── import_packs.py     # Python utility — imports packs from foundry
├── scenes/
│   ├── main.tscn           # Entry point (loads roster)
│   └── roster.tscn         # Crew roster scene
└── verify.sh               # Structure + manifest validation

Related Repos

Repo	Role
star-freight	Python engine — game logic, RPC server
star-freight-foundry	Sprite generation pipeline — ComfyUI + Godot finish

Quick Verification

bash verify.sh

Checks project structure, asset manifest validity, GDScript file integrity, and scene references. Run it after importing packs or editing scripts.