dm2-tools (Python bindings)

Pythonic bindings for the Dungeon Master II: The Legend of Skullkeep asset parsers, layered over the dm2-ffi C ABI via ctypes. Every function takes bytes in and returns bytes / dict / str / bool out; failures raise dm2_tools.Dm2Error.

Install

pip install ./bindings/python

This runs a hatchling build hook that invokes cargo build -p dm2-ffi --release against the workspace and bundles the resulting cdylib (libdm2_ffi.dylib / libdm2_ffi.so / dm2_ffi.dll) into the wheel under dm2_tools/_lib/. A Rust toolchain must be installed and on PATH to install this way. Python 3.11 or newer is required.

Tagged releases attach prebuilt wheels for x86-64 Linux (manylinux) and x86-64 Windows, which need no Rust toolchain — one wheel per platform covers every supported Python, since the library is loaded through ctypes rather than linked against a specific interpreter. macOS and other architectures build from a checkout as above.

Development / override

For local iteration without reinstalling, the module also looks for the native library at:

1. dm2_tools/_lib/<lib> (bundled, present after a real install)
2. the path in the DM2_FFI_LIB environment variable, if set
3. <repo-root>/target/release/<lib> (the plain cargo build output — used automatically when running the package straight out of a checkout)

Set DM2_FFI_LIB=/path/to/libdm2_ffi.so (or .dylib / .dll) to point at a specific build.

Usage

import dm2_tools

dump = dm2_tools.save_to_json(save_bytes)   # -> dict
dump["gameplay"]["champions"][0]["cur_hp"] = 999
edited = dm2_tools.save_from_json(dump)      # -> bytes

JSON-returning functions parse the C ABI's UTF-8 JSON payload with json.loads and return a plain dict; JSON-consuming functions accept a plain dict and serialize it with json.dumps before calling in.

API

All exceptions raised by the above are dm2_tools.Dm2Error.

Testing

python -m pytest -q

Tests that need workspace fixtures look for them at <repo-root>/fixtures/ (override with DM2_FIXTURES_DIR); anything whose fixture isn't present skips cleanly rather than failing.

Scope

Out of scope for this package, intentionally deferred:

• Publishing to PyPI.
• Prebuilt / multi-platform wheels (CI-built manylinux, macOS universal2, Windows, …). Installing always compiles the cdylib locally via Cargo.