Astrolabe

Astrolabe is a toolkit for extracting and converting data from Hype: The Time Quest (1999) into formats that are useful for inspection, reverse engineering, and Godot-based projects.

The game uses Ubisoft's OpenSpace Montreal engine, also used by titles such as Rayman 2 and Tonic Trouble. Astrolabe focuses on the Hype data pipeline:

• Read files from a mounted disc directory or already extracted game directory.
• Convert texture containers to PNG and audio files to WAV.
• Unpack OpenSpace level files into their embedded binary objects, scene graphs, meshes, materials, families, and scripts.
• Convert levels and assets into Godot projects, scenes, meshes, textures, and scripts.

Legal Notice

Astrolabe expects a legally obtained copy of Hype: The Time Quest as a mounted disc directory or extracted files.

Requirements

• .NET 10 SDK/runtime
• Git submodules initialized
• A mounted or extracted Hype disc directory
• Optional: Godot 4 for opening generated projects

Setup

Clone with submodules, or initialize them after cloning:

git submodule update --init --recursive
dotnet build

Run the CLI through the project:

dotnet run --project src/Astrolabe.Cli -- <command> [args]

For shorter examples below, astrolabe means the same command prefix.

Workflow

Start from a mounted disc directory or a directory that already contains the game files.

Copy raw files into a local working directory if needed:

astrolabe extract /mnt/hype ./disc --raw

Convert supported loose assets for inspection:

astrolabe extract ./disc ./output

Inspect the OpenSpace scene graph:

astrolabe tree ./disc/Gamedata/World/Levels/castle_village --stats --depth 3

Inspect mesh candidates before export:

astrolabe meshes ./disc/Gamedata/World/Levels/castle_village

Import an OpenSpace level into a Rete package:

astrolabe import-openspace ./disc/Gamedata/World/Levels/castle_village ./output/castle_village

Export back to OpenSpace level files:

astrolabe export-openspace ./output/castle_village ./output/castle_village.rebuilt

Level and Fix are the in-memory hubs; Rete is the on-disk encoding (separate level and fix packages), named for the rete plate on a historical astrolabe. OpenSpace level directories and Godot projects are export targets. The acceptance test for OpenSpace export is byte-identical cmp against the source on unedited packages. See docs/rete-format.md and plan.md.

Generate a Godot project with native scene and mesh resources:

astrolabe export-godot ./disc/Gamedata/World/Levels/castle_village ./output/castle_village
# or from a Rete package:
astrolabe export-godot ./output/castle_village ./output/castle_village-godot
godot --editor --path ./output/castle_village

The Godot export writes:

• project.godot
• <level>.tscn
• meshes/*.tres as ArrayMesh resources
• textures/* copied from resolved texture references when available

Commands

Command	Purpose
list <source>	List files in a mounted or extracted directory.
extract <source> [output]	Convert supported assets to PNG/WAV.
extract <source> [output] --raw	Copy raw files from one directory source to another.
import-openspace <level-dir> [rete-dir]	Import OpenSpace level → Rete package.
export-openspace <rete-dir> [level-dir]	Export Rete package → OpenSpace level.
textures <cnt-path> [output-dir]	Extract textures from a CNT container.
cnt <cnt-path>	Print CNT container metadata and sample entries.
audio <apm-path|bnm-path|directory> [output]	Convert APM files or extract BNM sound banks to WAV.
tree <path> [options]	Display scene graph roots from a level or game directory.
byte-tree <level-dir> [options]	Display scene graph with byte coverage analysis.
scene <level-dir> [level-name]	Print GPT and scene graph diagnostics.
meshes <level-dir> [level-name]	Scan a level for mesh candidates and print statistics.
export-godot <openspace-dir | rete-dir> [godot-dir]	Export a Godot project with scene and ArrayMesh resources.
scripts <level-dir> [--limit N] [--raw] [-o output-dir]	Inspect or save AI scripts from Perso data.
analyze <level-dir> [level-name]	Print low-level SNA, RTB, and geometry diagnostics.

Additional development commands include textures-sna, debug-gf, debug-sna, and debug-names.

Level Layout

Most level commands expect a directory whose name matches its level files:

disc/Gamedata/World/Levels/castle_village/
  castle_village.sna
  castle_village.gpt
  castle_village.rtb
  castle_village.ptx

Level loading can also use shared Fix.sna, Fix.rtb, Fix.ptx, and fixlvl.rtb files when they are present in the raw disc copy.

Project Structure

astrolabe/
├── src/
│   ├── Astrolabe.Cli/           # Command-line interface
│   └── Astrolabe.Core/          # OpenSpace readers, Rete codecs, exporters
├── docs/                        # OpenSpace, Hype, and Astrolabe file format documentation
├── notes/                       # Development notes and implementation checklists
├── lib/                         # Build-time dependency submodules
├── reference/                   # Development-only reverse-engineering references
├── disc/                        # Local raw game data (gitignored)
└── output/                      # Converted/exported assets (gitignored)

Core Components

• Extraction/ handles directory-backed game sources.
• FileFormats/ contains SNA, GPT, PTX, RTB, CNT, GF, scene graph, relocation, and memory readers.
• FileFormats/Geometry/ scans OpenSpace geometry.
• FileFormats/Animation/ reads family, object list, and animation structures.
• FileFormats/Audio/ converts APM and BNM audio to WAV.
• FileFormats/AI/ parses AI scripts and converts them to S-expressions.
• FileFormats/Godot/ writes Godot project, scene, and ArrayMesh resource files.

File Formats

Extension	Description
.sna	Compressed level and fix data blocks.
.gpt	Global pointer table and scene graph roots.
.ptx	Texture pointer table.
.rtb	Relocation table for OpenSpace pointer fixups.
.cnt	Texture archive container.
.gf	Individual RLE-encoded texture inside CNT archives.
.apm	Streaming audio.
.bnm	Sound bank containing audio entries.
.sda	Sound data.

See docs/ for documentation on CNT, GF, SNA, geometry, relocation tables, lighting, Perso meshes/animation, AI scripts, the Rete format, and the broader file catalogue.

The Rete format is specified in docs/rete-format.md. Architecture and implementation phases are in plan.md. Type promotion progress is tracked in notes/intermediate-type-checklist.md.

References

Astrolabe keeps several community reverse-engineering projects in reference/ as development-only material for comparing format notes and implementation details while working on readers and exporters.

The most important references are:

• Raymap
• BinarySerializer.OpenSpace
• OpenSpaceToolbox

Astrolabe itself keeps the core library independent of Unity and the reference projects.

License

CC0 License. See LICENSE for details.