Ballanced

Source-level reimplementation of the Ballance game runtime. Combines BallancePlayer with the NeMo2 Virtools engine in a Ballance-compatible directory layout.

Original game assets are not included - you need a copy of the original game to run it.

This document describes the cross-platform SDL3 runtime on the default sdl branch.

For players

Download the latest pre-built release:

https://github.com/doyaGu/Ballanced/releases

Installation

1. Get a legal copy of the original Ballance game.
2. Extract the release package into the game root, alongside the original asset directories. The archive already contains Bin/, RenderEngines/, Managers/, Plugins/, and BuildingBlocks/.
3. Run Bin\Player.exe on Windows or Bin/Player on Linux and macOS.

Windows does not require compatibility mode or registry edits.

For a macOS .dmg release, open the disk image and copy its contents into the game root before starting Bin/Player.

Flat layout (alternative)

Put Player (Player.exe on Windows), base.cmo, Database.tdb, the asset folders, and all runtime modules in the same directory. When base.cmo is next to the executable, the player treats that directory as its root.

For developers

Requirements

Platform	Toolchain	CMake
Windows (x86 / x64 / ARM64)	Visual Studio 2022 (MSVC)	3.25+
Linux (x64 / ARM64)	GCC or Clang + Ninja	3.25+
macOS (x64 / ARM64)	Apple Clang + Ninja	3.25+

SDL3 3.4.20 or newer must be on the CMake package path on all platforms. This includes the Metal fence completion and ownership fixes required by GPU uploads. The macOS stage layout supports SDL3 shared-library packages, including Homebrew. Staging rewrites the copied SDL3 library and its consumers to use @rpath and applies ad hoc signatures. SDL3 framework packages are not part of this layout. An optional manual CI workflow provides Developer ID signing and notarized disk images once signing credentials are configured. See macOS release signing.

Quick start (Windows x86)

The repository has nested Git submodules. Clone with --recurse-submodules; after pulling, run git submodule update --init --recursive. See BUILD.md for details.

git clone --recurse-submodules https://github.com/doyaGu/Ballanced.git
cd Ballanced
cmake --preset windows-x86-runtime
cmake --build --preset windows-x86-runtime-stage-release
ctest --preset windows-x86-runtime-stage-release

Output goes to:

build/windows-x86-runtime/stage/Bin/Player.exe

See BUILD.md for the full preset matrix, static builds, RenderEngine standalone builds, and troubleshooting.

Asset staging (optional)

Point CMake at an existing Ballance installation to copy assets into the stage:

cmake --preset windows-x86-runtime -DBALLANCE_ASSETS_ROOT=C:/path/to/your/Ballance
cmake --build --preset windows-x86-runtime-stage-release

For an explicit local-development shortcut, place the assets under assets/ and configure with -DBALLANCE_AUTO_DETECT_ASSETS=ON. Canonical presets do not read this ignored directory by default.

Source of truth and versioning

• CMakePresets.json defines the supported full-runtime platform, architecture, and linkage matrix.
• .github/workflows/build.yml builds and packages the platform/linkage matrix with tests disabled.
• .github/workflows/test.yml selects Player and assembly checks from source changes across the same matrix. NeMo2 owns the complete engine test suite and GPU diagnostic workflows.
• BUILD.md documents the supported superproject workflow. Component READMEs describe standalone workflows only.
• Ballanced and its Git submodules are independently versioned. The root project version identifies the assembled runtime; Player and the engine/module projects keep their own versions. A component version should not be inferred from the root version or release tag.

Repository structure

Ballanced manages two Git submodules:

Submodule	Repository	Description
Source/Player	BallancePlayer	Game player executable
Source/NeMo2	NeMo2	Virtools engine and its nested module repositories

NeMo2 owns VxMath, CK2, RenderEngine, Managers, Plugins, and BuildingBlocks under Source/NeMo2/Source/. Their independent repository histories and pinned versions are retained. See NeMo2's build guide for engine-only work. Ballance acceptance tools and the level route are under tests/player/.

Contributing

Open an issue or pull request. Decompilation, bug fixes, and compatibility work are all useful.

Acknowledgments

• The original Ballance developers for the game.
• The open-source projects this builds on.
• Everyone who has contributed code, tests, or bug reports.