subtr-actor-py 0.3.0

Python bindings for the Rocket League replay processing library subtr-actor.

subtr-actor-py

Python bindings for subtr-actor, a Rocket League replay processing library.

Installation

pip install subtr-actor-py

Usage

import subtr_actor

replay_path = "path/to/replay.replay"

# Parse raw replay bytes into the full replay structure.
with open(replay_path, "rb") as replay_file:
    replay = subtr_actor.parse_replay(replay_file.read())

# Build a numpy ndarray plus metadata.
meta, ndarray = subtr_actor.get_ndarray_with_info_from_replay_filepath(
    replay_path,
    global_feature_adders=["BallRigidBody", "SecondsRemaining"],
    player_feature_adders=["PlayerRigidBody", "PlayerBoost", "PlayerAnyJump"],
    fps=10.0,
    dtype="float32",
)

headers = subtr_actor.get_column_headers(
    global_feature_adders=["BallRigidBody", "SecondsRemaining"],
    player_feature_adders=["PlayerRigidBody", "PlayerBoost"],
)

replay_meta = subtr_actor.get_replay_meta(replay_path)
frames_data = subtr_actor.get_replay_frames_data(replay_path)

print(ndarray.shape)
print(headers["player_headers"][:5])
print(replay_meta["map_name"])

API Surface

parse_replay(data: bytes) -> dict

Parse raw replay bytes and return the full replay structure as Python data.

get_ndarray_with_info_from_replay_filepath(filepath, global_feature_adders=None, player_feature_adders=None, fps=None, dtype=None) -> tuple[dict, numpy.ndarray]

Process a replay file and return metadata plus a numpy.ndarray.

Parameters:

• filepath: path to the replay file
• global_feature_adders: list of global feature names, default ["BallRigidBody"]
• player_feature_adders: list of player feature names, default ["PlayerRigidBody", "PlayerBoost", "PlayerAnyJump"]
• fps: target FPS for resampling, default 10.0
• dtype: output dtype string. Supported values are float16/f16/half, float32/f32, and float64/f64/double

get_replay_meta(filepath, global_feature_adders=None, player_feature_adders=None) -> dict

Get replay metadata and ndarray headers without materializing the full ndarray.

get_column_headers(global_feature_adders=None, player_feature_adders=None) -> dict

Get header information for the configured ndarray layout.

get_replay_frames_data(filepath) -> dict

Get structured frame-by-frame game state data with no FPS resampling.

Feature Adders

See the subtr-actor ndarray docs for the full list of feature-adder names.

Common global features:

• BallRigidBody
• CurrentTime
• SecondsRemaining

Common player features:

• PlayerRigidBody
• PlayerBallDistance
• PlayerBoost
• PlayerAnyJump
• PlayerJump
• PlayerDodgeRefreshed

PlayerBoost is exposed in raw replay units (0-255), not 0-100 percent.

Development

Repository-level compile check:

just build-python

For an importable local Python environment, use maturin develop from the python/ directory:

cd python
uv sync --group dev
uv run maturin develop
uv run pytest

If you are using the repo flake, nix develop now provides the pinned CPython 3.11 toolchain and Python dev dependencies via uv2nix. Create a writable virtual environment from that interpreter, then install the local extension into it:

nix develop
uv venv /tmp/subtr-actor-venv
source /tmp/subtr-actor-venv/bin/activate
cd python
maturin develop
pytest

If you are not using uv or Nix, install maturin, pytest, and numpy in a virtual environment and run maturin develop directly.

Publishing Notes

This binding depends on the workspace crate via:

[dependencies.subtr-actor]
path = ".."
version = "0.2.3"

That keeps local development wired to the workspace crate while still pinning the published dependency version. Use just bump <version> to update the workspace and binding versions together.

License

MIT