pySAGE

A collection of Python tools for reading, editing, linting and visualising the data formats of the SAGE engine - the engine behind Command & Conquer: Generals and The Battle for Middle-earth. It grew out of an ini parser and now spans ini game data, binary maps, replays, and UI, with a domain overlay for the Edain mod.

Everything installs as one package with optional extras (see Install). Each subproject has its own README with the details; this page is the map.

Can be downloaded pre-packaged from here: https://www.moddb.com/games/battle-for-middle-earth-ii/downloads/pysage-tools

Projects

Ini game data

Binary formats

Domain overlays & apps

Shared

Install

Requires Python ≥ 3.12. The project is pySAGE; on PyPI it is published as pysage-tools.

Note: the bare pysage name on PyPI is an unrelated, abandoned messaging library last released in 2011, and py-sage is likewise taken by another project. pip install pysage will not get you this project - install pysage-tools.

pip install pysage-tools             # core library + linter
pip install "pysage-tools[ui]"       # + the PyQt6 desktop apps (sage-ui)
pip install "pysage-tools[wiki]"     # + the wiki updater
pip install "pysage-tools[apt]"      # + reading .const/.apt out of .big archives
pip install "pysage-tools[asset-ui]" # + the SAGE Asset desktop app (build/combine asset.dat)
pip install "pysage-tools[w3d-view]" # + the OpenGL model viewer (sage-w3d view)
pip install "pysage-tools[patch]"    # + the game.dat disassembly/RE tools
pip install "pysage-tools[all]"      # + everything above at once

From a clone, for development, swap the name for an editable install of the checkout:

pip install -e ".[ui]"

The extras (ui, lint-ui, wiki, apt, asset-ui, cah-ui, w3d-view, patch, and all for the lot) pull in the optional dependencies each peripheral tool needs. The ini, map, replay, asset, w3d, cah and patch layers are stdlib-only and always ship, so no extra is needed to parse, lint or diff a map, to build and combine an asset.dat from the command line, or to apply and verify a game.dat patch. The one non-optional dependency is reversebox on Windows, the native RefPack compressor that makes saving large maps fast (its DLL is Windows-only, so other platforms use the byte-identical pure-Python compressor).

Console scripts are installed for the CLI tools: sage-ini, sage-lint, sage-live, sage-replay, sage-apt, sage-map, sage-save, sage-asset, sage-w3d, sage-cah, sage-patch, sage-verify (and the GUI scripts sage-ui, sage-wiki, sage-lint-ui, sage-asset-ui, the SAGE Asset builder/combiner window, and sage-cah-ui, the SAGE Custom Hero editor).

Mod overlays

pySAGE stays engine-generic. Knowledge of one mod's data - which faction owns which structure, which powers field permanent units, which map conventions a mod expects - lives in its own overlay package, wired in through the hooks this repo exposes (sage_utils.factiongraph, sage_replay's aggregate hooks, sage_map.checks, sage_lint's rule interface). The Edain overlay is pySAGE-edain (sage_edain): faction graphs, map checks, patch notes, horde formations, a Worldbuilder launcher and a skirmish bot.

Tests

pytest            # fast, data-free core suite
pytest --full     # + corpus acceptance gates and peripheral-package suites

Contributing

Contributions are welcome - bug reports, fixes, new checks and rules, format coverage, and documentation all help. See CONTRIBUTING.md to get set up and CONVENTIONS.md for the coding rules. AI-assisted contributions are welcome too, with one expectation: you have read, understood, and can stand behind every line you submit.