Getting Started

Prerequisites

• Godot 4.6.1 (standard build, not .NET) — download
• Python 3.11+ with the star-freight package installed
• Windows 11 (primary development platform)

Installation

Clone the repository:

git clone https://github.com/mcp-tool-shop-org/star-freight-client.git

Install the Python engine (required for the engine bridge):

pip install -e /path/to/star-freight

Running

1. Open the project folder in Godot 4.6
2. Press F5 to run the main scene
3. The roster scene loads all available character packs automatically

Controls

Key	Action
A/D or arrows	Rotate selected character facing
Tab	Cycle through characters
Space	Rotate all characters at once
B	Connect to Python engine bridge
Esc	Quit

First Run (Visual Only)

On first launch, the client works in visual-only mode — it loads sprite packs and displays characters without the engine. This proves the pack loader and character rendering pipeline.

Press B to attempt an engine bridge connection. If starfreight is installed and a save file exists, the title bar updates to show crew count from the engine.

Importing More Packs

The foundry has 20 character packs. To import all of them (defaults to F:/AI/star-freight-foundry/exports):

python scripts/import_packs.py

To import specific characters:

python scripts/import_packs.py --subjects sera_vale,drift_maw,scav_raider

To use a different foundry exports path:

python scripts/import_packs.py --source /path/to/foundry/exports

Packs are copied unchanged into assets/characters/ with their manifests intact. Only the latest run for each subject is imported.

Troubleshooting

“No characters loaded” on launch — The assets/characters/ directory is empty or has no valid packs. Run python scripts/import_packs.py to import packs from the foundry, then relaunch.

Engine bridge stays “offline” — Make sure the Python portlight package is installed (pip install -e /path/to/star-freight) and that python is on your PATH. The client invokes python -m portlight.app.cli rpc internally. You also need at least one save file for the bridge to return roster data.

Manifest validation errors — If verify.sh reports bad schema versions, the pack was generated by an incompatible foundry version. Re-export using the latest foundry and re-import.