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 SP4 with /OPT:ICF)
• BW1W110 — Windows v1.10 (PE/COFF, MSVC 6.0 SP4)
• 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.

Debug Symbols

Black & White 1.1 and 1.2 releases were built with debug symbols in a now-missing .pdb file that wasn't leaked.

The compilation with .pdb left traces in the released artifact and the default target here will produce a working executable with pdb as an intermediate step before changes are applied to make it byte-match:

• build/BW1W110/runblack-linked.exe
• build/BW1W110/runblack-linked.pdb
• build/BW1W120/runblack-linked.exe
• build/BW1W120/runblack-linked.pdb

Loading the exe for 1.1 and 1.2 into Ghidra or IDA will give the tool access to type, function name and line number information while having an exe that is very close to the original. The differences with the original are minor and do not have any offset differences.

They should be good enough to use as a reference.

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/ - User-supplied original files, none committed (ignored by .gitignore). Holds each version's game binary in orig/[VERSION]/, the MSVC 6.0 SP5 static CRT libs in orig/libs/msvc6.5/, and the DirectX 7.0 DDK in orig/directx7.0/ (include/ and lib/). See Getting Started.
• src/ - C/C++ source files.
• include/ - C/C++ header files.
• tools/ - Scripts shared between projects.