Crescent Hawks Tools

Crescent Hawks Tools is a dependency-free .NET 10 command-line toolkit for inspecting, extracting, converting, and safely editing data from legally owned DOS installations of:

• BattleTech: The Crescent Hawk's Inception (1988);
• BattleTech: The Crescent Hawks' Revenge (1990).

The repository contains tools and format knowledge, not either game. You must supply your own original installation. Generated images, audio, reports, and edited saves stay local and should not be redistributed.

Inception map export	Revenge scenario-map export

Toolsets

Game	Documentation	Highlights
The Crescent Hawk's Inception	InceptionTools	CMP/ICN graphics, MTP maps, ANM animation, BLD scripts, SIF music, PC-speaker effects, saves, characters, BattleMechs, and weapons
The Crescent Hawks' Revenge	RevengeTools	CPS/CMP/ICN graphics, COL palettes, fonts, maps, SCENE scripts, units, weapons, digital/PC-speaker audio, and save analysis/editing

Both tools use bounded parsers and reject malformed or unsupported input rather than silently inventing data. JSON and deterministic batch exports are available where useful for preservation and research.

Preserved game source

This repository contains the asset tooling, not the reconstructed game source. For the preservation-oriented C17/SDL3 source ports, see:

• The Crescent Hawk's Inception SDL port
• The Crescent Hawks' Revenge SDL port

Those projects reconstruct the original DOS program logic while replacing the lowest-level platform interfaces required to run on modern systems. Original game assets are not included and must be supplied from a legally owned copy.

Quick start

Install the .NET 10 SDK, clone this repository, and build both tools:

dotnet build CrescentHawksTools.sln --configuration Release

Show the command lists:

dotnet run --project src/InceptionTools -- help
dotnet run --project src/RevengeTools -- help

Point a command at an original installation explicitly:

dotnet run --project src/InceptionTools -- inventory --game-dir "D:\Games\BTECH"
dotnet run --project src/RevengeTools -- inventory --game-dir "D:\Games\REVENGE"

Extract both installations into a human-browsable local directory:

.\Export-AllAssets.ps1 `
  -InceptionGameDirectory "D:\Games\BTECH" `
  -RevengeGameDirectory "D:\Games\REVENGE"

The default ExtractedAssets output contains separate Inception and Revenge trees. Each has exact source files under raw, directly viewable or human-readable conversions under decoded, and hashes and inventories under metadata. Use -Game Inception or -Game Revenge for one title, -OutputDirectory to choose another root, and -Force to overwrite generated files. ExtractedAssets/ is ignored because its contents derive from the user's copyrighted game installation.

You may instead set BTCHI_GAME_DIR for Inception or BTCHR_GAME_DIR for Revenge. Full command syntax and supported formats are documented in the two toolset guides above.

Run the asset-independent verification programs:

dotnet run --project tests/InceptionTools.Verification
dotnet run --project tests/RevengeTools.Verification

On Windows, Build.ps1 performs restore, Release build, and both verification passes in one command.

Repository layout

Path	Purpose
src/InceptionTools	Inception inspection and extraction CLI
src/InceptionTools.Core	Reusable Inception parsers, records, and exporters
src/RevengeTools	Revenge inspection and extraction CLI
src/CrescentHawksTools.Cli	Shared command-line contract
Export-AllAssets.ps1	Complete local extraction into browsable per-game trees
tests	Dependency-free verification executables
docs	Per-game command guides, format notes, and illustrative outputs
.github/workflows	Public CI build and verification

Build products (bin, obj), local game installations, generated extraction directories, edited saves, and private research captures are ignored.

See the format index, game-data reference, and local conformance guide for the preservation-facing contracts behind the commands.

Contributing

See CONTRIBUTING.md. Format claims should be supported by repeatable evidence, parsers must remain bounded, and uncertain semantics must be labelled rather than guessed.

Copyright and licensing

Project-authored source code and documentation are available under the MIT License, to the extent contributors hold the relevant rights. The games, BattleTech setting, names, artwork, audio, text, data, and the small illustrative exports in docs/images remain the property of their respective rights holders and are not covered by the MIT grant.

Read NOTICE.md and the licensing map before redistributing repository material. No license to either original game is granted. This is an independent preservation project and is not affiliated with or endorsed by the original developers, publishers, FASA, or current BattleTech rights holders.