subtr-actor-py 0.1.16

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

# Parse a replay file to get raw replay data
replay = subtr_actor.parse_replay(open("path/to/replay.replay", "rb").read())

# Get numerical data as numpy ndarray (useful for ML)
meta, ndarray = subtr_actor.get_ndarray_with_info_from_replay_filepath(
    "path/to/replay.replay",
    global_feature_adders=["BallRigidBody"],  # optional
    player_feature_adders=["PlayerRigidBody", "PlayerBoost", "PlayerAnyJump"],  # optional
    fps=10.0,  # optional, default is 10.0
    dtype="float16"  # optional: float16|float32|float64 (default float32)
)

# Get column headers to understand the ndarray structure
headers = subtr_actor.get_column_headers(
    global_feature_adders=["BallRigidBody"],
    player_feature_adders=["PlayerRigidBody", "PlayerBoost"]
)

# Get replay metadata without processing all frames (faster)
meta = subtr_actor.get_replay_meta("path/to/replay.replay")

# Get structured frame-by-frame data
frames_data = subtr_actor.get_replay_frames_data("path/to/replay.replay")

API Reference

parse_replay(data: bytes) -> dict

Parse raw replay bytes and return the complete replay structure.

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 of features.

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 - Frames per second for processing (default: 10.0)
• dtype - Output ndarray dtype string: float16/f16, float32/f32, float64/f64 (default: float32)

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

Get replay metadata without processing frame data (faster than full processing).

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

Get column header information for understanding ndarray structure.

get_replay_frames_data(filepath) -> dict

Get structured frame-by-frame game state data.

Feature Adders

See the subtr-actor documentation for available feature adder names.

Common global features: BallRigidBody, GameTime

Common player features: PlayerRigidBody, PlayerBoost, PlayerAnyJump, PlayerDoubleJump

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

Building from Source

Requirements:

• Rust toolchain
• maturin
• just (command runner)

# Clone the repository
git clone https://github.com/rlrml/subtr-actor.git
cd subtr-actor

# Build the Python package
just build-python

# Or for development (editable install)
cd python && maturin develop

Monorepo Dependency Management

This package is part of the subtr-actor monorepo. The Cargo.toml uses a dual dependency specification:

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

This allows:

• Local development: Cargo uses the path dependency, so changes to the main subtr-actor crate are immediately available for testing
• Publishing: crates.io/PyPI strips the path and uses the version, ensuring the published package depends on the published crate

Use just bump <version> to update all versions in sync (workspace version and dependency versions).

Publishing

To publish all packages in the correct order:

just publish-all  # Publishes: Rust crate -> Python bindings -> JS bindings

Or publish individually:

just publish-rust    # Publish main Rust crate first
just publish-python  # Then publish Python bindings

Important: The main subtr-actor Rust crate must be published to crates.io before publishing the bindings, as the published bindings depend on the published crate version.

License

MIT