Void Reckoning Engine

Void Reckoning Engine is an experimental, headless 4X campaign and combat simulation framework written primarily in Python, with optional Rust and GPU acceleration paths. It explores persistent factions, strategic AI, campaign economies, tactical combat, reporting, and simulation telemetry.

Important

This is an alpha research and game-development project, not a finished game or a production-ready engine. Several systems are prototypes, the complete test suite still contains legacy failures, and some optional integrations require additional local setup.

Project status

Area	Status	Notes
Headless campaign simulation	Experimental	The strongest and most actively exercised path
Void Reckoning universe pack	Included	Original factions, units, rules, and configuration
Tactical combat	Experimental	Python implementation with optional Rust acceleration
Reporting and terminal dashboard	Experimental	Useful for diagnostics; not a polished player interface
Web dashboard	Prototype	Incomplete and not recommended for public deployment
GPU acceleration	Optional	Falls back to CPU when CuPy/CUDA is unavailable
Player-facing game loop	Incomplete	Current public code is primarily simulation-oriented

The public baseline is version 0.1.0 alpha. The narrow CI workflow checks installation, both CLI entry paths, configuration tests, and a small public correctness contract. Passing that workflow does not mean every legacy system or test is complete.

Quick start

Python 3.10 or newer is required. Python 3.11 is the CI reference version.

git clone https://github.com/JaySpiffy/void-reckoning-engine.git
cd void-reckoning-engine
python -m venv .venv

Activate the environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS or Linux
source .venv/bin/activate

Install the project and inspect the available commands:

python -m pip install --upgrade pip
python -m pip install -e .
python run.py --help

The installed console command exposes the same command registry:

sim-engine --help

Validate the included universe data before attempting a simulation:

python run.py validate --universe void_reckoning

Useful commands

# Show all commands
python run.py --help

# Validate configuration and universe data
python run.py validate --universe void_reckoning

# Run a short campaign path
python run.py campaign --universe void_reckoning --quick

# Inspect tactical simulation options
python run.py simulate --help

# Inspect the terminal dashboard command
python run.py dashboard --help

Command availability does not imply that every combination of arguments, universe data, GPU backend, or dashboard mode has been fully verified.

Repository layout

src/                 Core simulation, combat, AI, CLI, and reporting code
universes/base/      Shared universe contracts and data structures
universes/void_reckoning/
                     Void Reckoning rules and content
native_pulse/        Optional Rust crates and Python bridge source
visualizer/          Experimental web visualizer
tests/               Unit, integration, and legacy regression tests
public_docs/         Maintained public technical notes

Generated Python builds, Rust target/ output, logs, local databases, reports, and compiled native binaries are intentionally excluded from version control.

Testing

Run the public smoke contract with:

python -m pytest -q tests/test_config.py tests/test_public_contract.py

The repository also contains a much larger historical test collection:

python -m pytest

That full command is useful for development triage, but it is not currently a green release gate. Some tests depend on legacy fixtures, unavailable universe packs, GPU hardware, local game installations, or systems that are being consolidated. New verified scopes should be added to CI incrementally rather than described as complete before they pass from a clean checkout.

See public testing notes and the project structure for additional context.

Optional Rust and GPU paths

Rust source lives under native_pulse/. Cargo build output and Python wheels are local artifacts and are not committed. The engine is intended to retain a Python/CPU fallback when native extensions or CUDA are unavailable.

These acceleration paths are experimental. Build and benchmark results from one machine should not be treated as portable performance guarantees.

Known limitations

• The project is not yet a cohesive, player-facing 4X game.
• The complete historical test suite is not green.
• Dashboard V2 is a prototype and has not received a production-readiness or internet-exposure review.
• Some older modules and tests reference retired universe packs or local game installations.
• Packaging is intended primarily for development installs from a checkout; publication to PyPI is not currently part of the release process.
• Balance, performance, and feature claims should be treated as experimental until backed by reproducible tests or benchmarks.

Development transparency

This is a personal, AI-assisted project. AI tools have contributed to parts of the implementation, documentation, debugging, and refactoring. Historical code has not all received the same level of manual review.

The standard for public claims in this repository is therefore deliberately simple: verified behavior should have a reproducible command or automated check; unfinished or unreviewed behavior should be labelled experimental.

Contributing

Small, evidence-backed changes are welcome. A useful contribution should:

1. Describe the narrow behavior being changed.
2. Include or update a focused test when practical.
3. Avoid committing generated artifacts or local machine output.
4. Avoid presenting experimental systems as production-ready.

Open an issue before attempting a large architectural rewrite so the intended simulation boundary can be discussed first.

License

Released under the MIT License.