subtr-actor-py
Python bindings for subtr-actor, a Rocket League replay processing library.
Installation
pip install subtr-actor-py
# or, with uv:
uv add subtr-actor-py
# or, with Poetry:
poetry add 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)
stats_events = subtr_actor.get_stats_events(replay_path)
summed_stats = subtr_actor.get_summed_stats(
replay_path,
module_names=["core", "boost", "movement"],
)
stats_module_names = subtr_actor.get_stats_module_names()
stats_snapshot_data = subtr_actor.get_stats_snapshot_data(
replay_path,
module_names=["core", "boost"],
frame_step_seconds=1.0,
)
stats_timeline = subtr_actor.get_stats_timeline(
replay_path,
frame_step_seconds=1.0,
)
legacy_stats_timeline = subtr_actor.get_legacy_stats_timeline(
replay_path,
module_names=["core", "boost", "movement"],
frame_step_seconds=1.0,
)
print(ndarray.shape)
print(headers["player_headers"][:5])
print([player["name"] for player in replay_meta["replay_meta"]["team_zero"]])
print(stats_events["events"][-1])
print(summed_stats["modules"]["boost"]["team_zero"]["amount_collected"])
print(stats_module_names)
print(stats_snapshot_data["frames"][-1]["modules"]["boost"]["team_zero"]["amount_collected"])
print(stats_timeline["events"]["events"][-1])
print(legacy_stats_timeline["frames"][-1]["team_zero"]["boost"]["amount_collected"])
get_stats_timeline is the compact event-backed timeline. Its frames contain
timing, gameplay state, and player identity scaffolding only; stat deltas live
under events. Use get_legacy_stats_timeline only for compatibility code that
still needs serialized per-frame team/player snapshots.
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 fileglobal_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, default10.0dtype: output dtype string. Supported values arefloat16/f16/half,float32/f32, andfloat64/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.
get_stats_events(filepath, frame_step_seconds=None, include_expected_goals=False) -> dict
Get the compact modern stats event streams for a replay.
Parameters:
filepath: path to the replay fileframe_step_seconds: optional positive sampling interval in seconds for the accompanying timeline collector. Events are still emitted as compact stat change streams.include_expected_goals: opt in to the model-backed expected-goals event streams. It is disabled by default.
get_summed_stats(filepath, module_names=None) -> dict
Get aggregate summed stats for the selected builtin modules.
Parameters:
filepath: path to the replay filemodule_names: optional list of builtin stats module names. By default the non-model-backed modules are included; selectexpected_goalsexplicitly to enable it.
get_stats_module_names() -> list[str]
List the builtin stats modules that can be selected in get_summed_stats,
get_stats_snapshot_data, and get_legacy_stats_timeline.
get_stats_snapshot_data(filepath, module_names=None, frame_step_seconds=None) -> dict
Get the raw stats snapshot payload produced by StatsCollector, including:
config: module configuration emitted by the selected stats modulesmodules: aggregate module outputsframes: per-sample module snapshots keyed by module name
Parameters:
filepath: path to the replay filemodule_names: optional list of builtin stats module names. By default the non-model-backed modules are included; selectexpected_goalsexplicitly to enable it.frame_step_seconds: optional positive sampling interval in seconds. By default every replay frame is captured.
get_stats_timeline(filepath, frame_step_seconds=None, include_expected_goals=False) -> dict
Get the compact event-backed stats timeline for each replay sample.
Frames contain timing, gameplay state, and player identity scaffolding only;
stat state changes are transferred through events, and full team/player
snapshots can be derived by clients that need them.
Parameters:
filepath: path to the replay fileframe_step_seconds: optional positive sampling interval in seconds. By default every replay frame is captured.include_expected_goals: opt in to the model-backed expected-goals tracks. It is disabled by default.
module_names filtering is not supported for compact event timelines. Passing
it raises ValueError; use get_legacy_stats_timeline if filtered full
snapshot timelines are needed.
get_legacy_stats_timeline(filepath, module_names=None, frame_step_seconds=None) -> dict
Get cumulative typed stats snapshots for each replay sample.
This preserves the pre-compact timeline behavior for compatibility and for explicit parity checks, but it serializes the full team/player partial sums.
Parameters:
filepath: path to the replay filemodule_names: optional list of builtin stats module names. By default all builtin modules are included.frame_step_seconds: optional positive sampling interval in seconds. By default every replay frame is captured.
Feature Adders
See the subtr-actor ndarray docs for the full list of feature-adder names.
Common global features:
BallRigidBodyCurrentTimeSecondsRemaining
Common player features:
PlayerRigidBodyPlayerBallDistancePlayerBoostPlayerAnyJumpPlayerJumpPlayerDodgeRefreshedPlayerEvent:touch
PlayerBoost is exposed in raw replay units (0-255), not 0-100 percent.
Analysis-backed player event indicators use PlayerEvent:<event_name> and emit
1 for a sampled frame when that player has a new event, otherwise 0.
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 = "1.5.0"
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
1 maintainer
Metadata
1 maintainer
Release files for subtr-actor-py 1.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| subtr_actor_py-1.5.0.tar.gz | 2.3 MB | Without provenance | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| subtr_actor_py-1.5.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details |
| subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| subtr_actor_py-1.5.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64, macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64) | Details |
Total release size: 14.6 MB
Release files / subtr_actor_py-1.5.0.tar.gz
| Download URL | subtr_actor_py-1.5.0.tar.gz |
|---|---|
| Size | 2.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
77b4b23666f01f6d93be071e01c9d3e1fef1ed5bf04ac7fa7036ca0ca07ee769
|
|
BLAKE2b-256 checksum How to use checksums |
2d82da000e36d926e2e3033449dc5abd6a17cb23c40b04447139cc7a4c502de7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / subtr_actor_py-1.5.0-cp39-abi3-win_amd64.whl
| Download URL | subtr_actor_py-1.5.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
177ee6d2f6bc28d08920816bed61c6df480697ebf8473253fb03207e371cbf32
|
|
BLAKE2b-256 checksum How to use checksums |
bd5d1a08dbcf5236f11d2500c7b7827676285bce70f432aba7db081b2c526aa6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.5 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
cc78be9501d8f0f6fa3e079307ced108090c5677999bf0dce0cc0f3256bd666f
|
|
BLAKE2b-256 checksum How to use checksums |
46545daa9d8e11032fcfb432119d92a9c58e38ef973f2d9f8c0b435e83aedd76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | subtr_actor_py-1.5.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e94a96c8f6de5d1ee0789af22cdac8a1afc8218027783d11558abf1b6955454c
|
|
BLAKE2b-256 checksum How to use checksums |
50d1802f9fb7eeb3d08c2825550b4daa4b2e7c67dbc173dde024bc99f96fa930
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / subtr_actor_py-1.5.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | subtr_actor_py-1.5.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b61fd8d0d554cae83fbd9295a89f1bf46994bacc7cff25a9222968cebdce1441
|
|
BLAKE2b-256 checksum How to use checksums |
1a04106691a6057861e16b5204b665efc9aa3102d634947ea121aa17251eb0ca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for subtr-actor-py 1.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
