Ballanced

Source-level reimplementation of the Ballance game runtime. Rebuilds the player, engine libraries, building blocks, and plugins from source into 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.

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.

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 defines the configurations continuously built by CI.
• CI runs the complete component test preset on Linux x64 in addition to the platform/linkage build matrix.
• 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

Components under Source/ are Git submodules:

Submodule	Repository	Description
Source/Player	BallancePlayer	Game player executable
Source/CK2	CK2	Virtools behavioral engine
Source/VxMath	VxMath	Math and platform utilities
Source/RenderEngine	CKRenderEngine	Render engine (SDL GPU)
Source/BuildingBlocks	CKBuildingBlocks	Virtools building block modules
Source/Plugins	CKPlugins	File format plugins (image, audio, CMO)
Source/Managers/ParameterOperations	CKParameterOperations	Parameter operations manager
Source/Managers/SdlInputManager	SdlInputManager	SDL3 input manager
Source/Managers/SdlSoundManager	SdlSoundManager	SDL3 sound manager

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.