openblack

openblack is an open source reimplementation of Black & White (2001) written in modern C++ and modern rendering engines (OpenGL, Vulkan).

You still need to have the original game assets in order to use this. See further below for an explanation on how to extract them.

Pre-built Binaries

For the latest build of openblack without having to build it yourself, we offer pre-built binaries from our test service.

Experimental

The following are qualified as exprimental. They have base minimum setup such as compilation and rendering system. Don't expect to be able to launch without some effort and your own patches.

Building

Clone the code using: git clone --recursive https://github.com/openblack/openblack.git

If you forgot to add --recursive, you will have to also run git submodule update --init from the openblack/ directory.

Configuration for using vcpkg (Recommended for new users)

The simplest way to obtain all the required dependencies is through vcpkg which is included with a manifest file.

The easiest way to get started on any platform is to allow CMake and vcpkg to handle all dependencies and configuration for you. To do so, you will be selecting the "ninja-multi-vcpkg" - Ninja Multi-Config (vcpkg) preset. Other presets are available for more advanced users.

Visual Studio Code

Install Visual Studio Code
Install the C++ Extension
- The extension might not be required on Linux
- Install a compiler depending on your platform
  - GNU or Clang compilers on Linux
  - Visual Studio's MSVC on Windows (See Visual Studio)
  - Clang compiler on Mac
Install the CMake Tools Extension
- Install CMake version 3.20+
You can simply open the openblack folder directly in Visual Studio Code and select a preset.

Visual Studio 2022

Install Visual Studio
- Select an appropriate MSVC C++ Component for your version
- Select an appropriate Windows SDK Component for your version
- Select the C++ CMake tools for Windows Component
You can simply open the openblack folder directly in Visual Studio and select a preset.

Clion

Install Clion
You can simply open the openblack folder directly in CLion and select a preset.

XCode

Install XCode
Install the homebrew depenedencies using homebrew: brew install cmake ninja pkg-config
Run sudo xcode-select --reset after installing cmake
You need to configure using the cmake preset xcode-vcpkg using cmake in either the GUI or using the command line argument --preset xcode-vcpkg

Android Studio

Install Android Studio
Install a recent SDK and an NDK of at least 23
Open openblack from the android directory
Set the SDK and NDK in the project settings
Do gradle configure which will run cmake configuration and compile the vcpkg dependencies
Build the project for either a virtual device or a connected device
Currently requires user to upload game assets to /data/local/tmp/bw and chmod -R a+wrx /data/local/tmp/bw with adb

Web Assembly

Get emsdk
Add the directory of emsdk as the EMSDK environment variable.
Run emsdk install latest
Run emsdk activate latest
Build the emscripten-vcpkg preset

Command Line

Your usual build tool-chain.
- Ubuntu / Debian: # apt install build-essential cmake ninja-build
- Arch Linux / Manjaro: # pacman -S base-devel cmake ninja
You can generate the cmake build preset using cmake --preset and you can list the presets using cmake --list-presets

Configuration for using System Dependencies (Recommended for packagers)

If you don't want to use vcpkg; CMake will use system libraries, or manually specified package directories.

CMake will find the required libraries as long as they provide a proper config file.

Arch Linux

Install openblack-git from the AUR which builds and installs directly for all Arch Linux derived distros such as Manjaro. This will require pacman to install all required dependencies.

The prefix to use is "linux-system-deps" - Linux (System Deps)

Contributing

Contributions are always welcome, whether it's modifying source code to add new features or bug fixes, documenting new file formats or simply editing some grammar.

You can also join the Discord for development discussion if you are unsure of anything.

Extracting asset files from original game

As mentioned before, the original game assets are required in order to run openblack. Since these data are copyrighted, we won't provide them, so please don't ask. Here is a guide for extracting them from the original game.

Prerequisites

You will need the following:

The original installer (usually on a CD)
Official patch 1.10
Official patch 1.2
Not needed (but will not compromise the extraction): Unofficial patch 1.42

Do not install 1.3, it is a patch to add P5 Power Glove support and is generally unstable

Installation

On Windows

Install the game from the installer, remember the installation directory (C:\\Program Files (x86)\\Lionhead Studios\\Black & White\\ is the default)
Install the official patch 1.10 (in the same directory)
Install the official patch 1.2 (in the same directory)

On Linux and macOS

If you run on Linux or macOS, you can install the game with Wine (App Page on WineHQ).

Install wine
Run wine Setup.exe from the directory containing the installer, don't change the install path
Run wine Black_White_Patch_v1.100.exe from the directory containing the first patch (adapt the command in case the filename isn't exactly that)
Run wine black_white_patch_v1_20.exe from the directory containing the second patch (adapt too)
In case you would like to install the unofficial patch, it requires .NET 2.0, that can be installed with winetricks dotnet20sp2 (you should install winetricks first)

All the files should be installed in the following directory: ~/.wine/drive_c/Program Files (x86)/Lionhead Studios Ltd/Black & White

Getting the assets

The folders you're interested in are the Audio, Data and Scripts folders in the installation directory. You can use them from there or make a copy to the location of your choice.

Using them in place

If you want to use them from there, remember the installation directory chosen in the installation step, unless you changed it, it should be either:

eitherC:\\Program Files (x86)\\Lionhead Studios\\Black & White\\
or ~/.wine/drive_c/Program Files (x86)/Lionhead Studios Ltd/Black & White

This is the path you will give to openblack (using the -g flag).

If you prefer to copy the data (e.g. if you want to uninstall the original game), just copy the Data and Scripts folders to the desired new location, and give the path to this location to openblack (using the -g flag).

License

openblack is released as open source software under the GPL v3 license, see the license file in the project root for the full license text.