Black & White

A work-in-progress decompilation of Lionhead Studios' Black & White (2001).

This repository does not contain any game assets or assembly. An existing copy of the game is required.

Scaffolded from encounter/dtk-template and adapted for PE/COFF (Windows) and PEF (Classic Mac OS) targets.

Supported versions:

• BW1W100 — Windows v1.00 (PE/COFF, MSVC 6.0 SP5 with /OPT:ICF)
• BW1W110 — Windows v1.10 (PE/COFF, MSVC 6.0 SP5)
• BW1W120 — Windows v1.20 (PE/COFF, MSVC 6.0 SP5)

Work in progress:

• BW1W130 — Windows v1.30 (PE/COFF, MSVC 6.0 SP5)
• BW1WCI — Windows Creature's Isle (PE/COFF, MSVC 6.0 SP5)
• BW1M100 — Classic Mac OS PowerPC v1.0.0 (PEF, CodeWarrior Mac)

Documentation

• Dependencies
• Getting Started
• symbols.txt
• splits.txt
• GitHub Actions

References

• openblack (Open-source engine reimplementation)
• encounter/dtk-template (Original GC/Wii project template this is based on)
• decomp-toolkit (Tooling — openblack fork)
• objdiff (Local diffing tool)
• decomp.me (Collaborate on matches)
• decomp.dev (Decompilation progress hub and API)

Features

• Few external dependencies: just python for the generator and ninja for the build system. See Dependencies.
• Simple configuration: everything lives in config.yml, symbols.txt, and splits.txt.
• Multi-version support: separate configurations for each game version, and a configure.py --version flag to switch between them.
• Feature-rich analyzer: many time-consuming tasks are automated, allowing you to focus on the decompilation itself.
• No manual assembly: decomp-toolkit handles splitting the original binary into relocatable objects based on the configuration. No game assets are committed to the repository.
• Progress calculation and integration with decomp.dev.
• Integration with objdiff for a diffing workflow.
• CI workflow for GitHub Actions.

Diffing

Once the initial build succeeds, an objdiff.json should exist in the project root.

Download the latest release from encounter/objdiff. Under project settings, set Project directory. The configuration should be loaded automatically.

Select an object from the left sidebar to begin diffing. Changes to the project will rebuild automatically: changes to source files, headers, configure.py, splits.txt or symbols.txt.

Project structure

• configure.py - Project configuration and generator script.
• config/[VERSION] - Configuration files for each game version (BW1W100, BW1W110, BW1W120, BW1M100).
• config/[VERSION]/build.sha1 - SHA-1 hashes for each built artifact, for final verification.
• build/ - Build artifacts generated by the build process. Ignored by .gitignore.
• orig/[VERSION] - Original game files. Ignored by .gitignore.
• src/ - C/C++ source files.
• include/ - C/C++ header files.
• tools/ - Scripts shared between projects.