Black & White

<img src="https://decomp.dev/openblack/bw1-decomp.svg?w=512&h=256" width="1024" height="512">

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:

• — Windows v1.00 (PE/COFF, MSVC 6.0 SP4 with /OPT:ICF)
• — Windows v1.10 (PE/COFF, MSVC 6.0 SP4)
• — Windows v1.20 (PE/COFF, MSVC 6.0 SP5)
• — Windows v1.30 (PE/COFF, MSVC 6.0 SP5)
• — Windows Creature Isle (PE/COFF, MSVC 6.0 SP5)

Documentation

• Dependencies
• Getting Started
• symbols.txt
• splits.txt
• GitHub Actions
• Porting a version's config

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, 1.2 and 1.3 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
• build/BW1W130/runblack-linked.exe
• build/BW1W130/runblack-linked.pdb

Use runblack-linked.exe and the pdb sitting next to it. Loading it into Ghidra or IDA gives function names across the whole image, plus the class layouts of every translation unit already matched and linked from source, so the types fill in as the decomp progresses. The exe is very close to the original: the differences are minor and do not have any offset differences.

They should be good enough to use as a reference.

Ghidra

In ghidra, pdb loading needs an experimental feature to be on. This option is only available in Auto Analyze Options under PDB Universal if you uncomment VMARGS=-Dghidra.pdb.developerMode=true in Ghidra's launch.properties file:

• Windows: <ghidra install>\support\launch.properties
• Linux and macOS: <ghidra install>/support/launch.properties

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, BW1W130, BW1WCI, BW1M119).
• 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 static CRT libs in orig/libs/msvc6.<sp>/ (SP5, SP4 and RTM copies, depending on the version and the library), Visual Studio .NET 2002's libcmt.lib in orig/libs/msvc7.0/ (1.20/1.30's LHLogR.dll), the Intel libraries in orig/libs/amaths-2.0/ and orig/libs/icc-5.0.115/, QSound's QMixer 5.00 SDK header in orig/libs/qmixer-5.00/, 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.