Crate subtr_actor

Expand description

subtr-actor turns raw boxcars replay data into higher-level game state, derived replay events, structured frame payloads, and dense numeric features for analytics and ML workflows.

Higher-level game state modeled from the raw actor graph
Frame-by-frame structured data ready for JSON export and playback UIs
Dense numeric feature matrices for ML, built from a string-addressable feature registry
Derived events and cumulative stats — touches, boost pickups, dodge refreshes, goals, demolishes, and more
One pipeline, three languages — the same Rust core drives the Python and JavaScript/WASM bindings

§Processing model

ReplayProcessor walks the replay’s network frames, models actor state, and tracks derived replay events such as touches, boost pad pickups, dodge refreshes, goals, player stat events, and demolishes.
Collector is the core extension point. Collectors observe the replay frame by frame and can either process every frame or control sampling via TimeAdvance.
ReplayProcessor::process_all lets multiple collectors share a single replay pass when you want to build several outputs at once.
FrameRateDecorator and CallbackCollector provide lightweight utilities for downsampling a collector or attaching side-effectful hooks such as progress reporting and debugging.

§Primary output layers

ReplayDataCollector builds a serde-friendly replay payload with frame data, replay metadata, and derived event streams suitable for JSON export and playback UIs.
NDArrayCollector emits a dense ndarray::Array2 with replay metadata and headers. It supports both explicit feature adders and the string-based registry exposed through NDArrayCollector::from_strings and NDArrayCollector::from_strings_typed.
StatsCollector accumulates graph-backed replay statistics as a module-keyed dynamic payload suitable for builtin module selection and JSON export.
StatsTimelineEventCollector accumulates graph-backed replay statistics as event streams plus lightweight frame scaffolding. This is the preferred timeline export when callers do not need to serialize full per-frame partial sums.
StatsTimelineCollector preserves the legacy full snapshot timeline form (ReplayStatsTimeline) for parity checks and compatibility.

§Stats and exports

The stats module houses analysis calculators, graph nodes, stat event calculators, and the labeled stat-aggregation types (LabeledCounts, LabeledFloatSums) consumed by the stats collectors.

§Architecture / module map

Read top-down — each module’s own documentation expands on the summary here and links to the collections of implementations it contains.

processor — the replay-walking core. ReplayProcessor models actor state from boxcars network frames and tracks derived events, applying a sequence of per-frame state updaters.
collector — the output layer. The Collector trait is the extension point; built-in collectors are ReplayDataCollector (structured frames), NDArrayCollector (numeric features), and the stats-timeline collectors (collector::stats).
stats — the analysis layer. A dependency graph of analysis nodes wraps [gameplay-event calculators][StatsEvent] that detect mechanics; results land in accumulators and the [exported stat-field model][stats::export].
replay_model / replay_meta — the serde-friendly higher-level game state and replay metadata produced for export and playback UIs.
interop — bindings-facing helpers shared by the Python and JavaScript/WASM wrappers (e.g. the replay-player manifest).
util — geometry, search, and small data-structure helpers used throughout the crate.

§Where to find collections of implementations

Several parts of the crate are large families of similar types. Each has a catalog in its module documentation, and the shared trait’s Implementors list is a second way to browse them:

Collection	Module	Shared trait / registry
Gameplay-event calculators	`stats::analysis_graph`	[`StatsEvent`]
Analysis-graph nodes	`stats::analysis_graph`	`AnalysisNode`
Stat accumulators	`stats::accumulators`	(plain accumulation structs)
Exported stat fields	[`stats::export`]	[`StatFieldProvider`]
NDArray feature adders	`collector::ndarray`	`FeatureAdder` family + string registry
Processor state updaters	`processor`	(`impl ReplayProcessor` methods)

§In-depth guides

Longer prose guides are rendered into the API docs under guides:

guides::calculators_and_analysis_nodes — the stats runtime DAG layout.
guides::stat_confidence — how to read exported-stat confidence levels.
guides::replay_format_evolution — replay-format changes that matter to parsing.

§Examples

§Collect structured replay data

use boxcars::ParserBuilder;
use subtr_actor::ReplayDataCollector;

let bytes = std::fs::read("replay.replay").unwrap();
let replay = ParserBuilder::new(&bytes)
    .must_parse_network_data()
    .on_error_check_crc()
    .parse()
    .unwrap();

let replay_data = ReplayDataCollector::new().get_replay_data(&replay).unwrap();
println!("frames: {}", replay_data.frame_data.frame_count());
println!("touches: {}", replay_data.touch_events.len());

§Build a sampled feature matrix

use boxcars::ParserBuilder;
use subtr_actor::{Collector, FrameRateDecorator, NDArrayCollector};

let bytes = std::fs::read("replay.replay").unwrap();
let replay = ParserBuilder::new(&bytes)
    .must_parse_network_data()
    .on_error_check_crc()
    .parse()
    .unwrap();

let mut collector = NDArrayCollector::<f32>::from_strings(
    &["BallRigidBody", "CurrentTime"],
    &["PlayerRigidBody", "PlayerBoost", "PlayerAnyJump"],
)
.unwrap();

FrameRateDecorator::new_from_fps(30.0, &mut collector)
    .process_replay(&replay)
    .unwrap();

let (meta, features) = collector.get_meta_and_ndarray().unwrap();
println!("players: {}", meta.replay_meta.player_count());
println!("shape: {:?}", features.raw_dim());

§Export compact event-backed stats timeline

use boxcars::ParserBuilder;
use subtr_actor::StatsTimelineEventCollector;

let bytes = std::fs::read("replay.replay").unwrap();
let replay = ParserBuilder::new(&bytes)
    .must_parse_network_data()
    .on_error_check_crc()
    .parse()
    .unwrap();

let timeline = StatsTimelineEventCollector::new()
    .get_replay_stats_timeline_scaffold(&replay)
    .unwrap();

println!("timeline frames: {}", timeline.frames.len());
let rush_events = timeline
    .events
    .events
    .iter()
    .filter(|event| event.meta.stream == "rush")
    .count();
println!("rush events: {rush_events}");

Re-exports§

pub use crate::actor_state::*;
pub use crate::ballistics::*;
pub use crate::boost_pad_locations::*;
pub use crate::boost_units::*;
pub use crate::clip::*;
pub use crate::collector::*;
pub use crate::error::*;
pub use crate::geometry::*;
pub use crate::processor::*;
pub use crate::replay_meta::*;
pub use crate::replay_model::*;
pub use crate::search::*;
pub use crate::stats::*;

Modules§

actor_state: Compatibility re-export for processor actor-state types.
ballistics: Free-flight Rocket League ball prediction helpers.
boost_pad_locations
boost_units
clip: Replay clipping: trim a boxcars::Replay down to a small, self-contained window of frames that still processes through the full ReplayProcessor pipeline unchanged.
collector: The output layer: turn a processed replay into structured data, numeric features, or stat timelines.
error: Crate-wide error type and result alias.
geometry: Compatibility re-export for geometry helpers.
guides: In-depth prose guides, rendered from the repository’s docs/ directory.
interop: Support code for external language and client-facing contracts.
processor: The replay-walking core: model actor state from raw boxcars frames and track derived gameplay events.
replay_meta: Replay-level metadata: teams, players, and per-player identity/header information extracted from a parsed replay.
replay_model: Higher-level, serde-friendly game-state model derived from the raw replay.
search: Compatibility re-export for search helpers.
stats: Replay analysis: detect gameplay mechanics, accumulate stats, and export them.
util: Small shared helpers used throughout the crate.

Macros§

analysis_global_feature_adder: Implements the ndarray traits for an existing analysis-backed global feature type.
analysis_player_feature_adder: Implements the ndarray traits for an existing analysis-backed per-player feature type.
attribute_match: Attempts to match an attribute value with the given type.
build_analysis_global_feature_adder: Declares a new analysis-backed global feature-adder type.
build_analysis_player_feature_adder: Declares a new analysis-backed per-player feature-adder type.
build_global_feature_adder: Declares a new global feature-adder type and wires it into the ndarray traits.
build_player_feature_adder: Declares a new per-player feature-adder type and wires it into the ndarray traits.
convert_all: Converts a fixed list of values with a caller-supplied error mapper.
convert_all_floats: Converts a fixed list of float-like values using convert_float_conversion_error.
get_attribute_errors_expected: Obtains an attribute from a map and ensures it matches the expected type.
global_feature_adder: Implements the ndarray feature-adder traits for an existing global feature type.
impl_analysis_feature_adder: Implements AnalysisFeatureAdder for a fixed-width analysis-backed type.
impl_analysis_player_feature_adder: Implements AnalysisPlayerFeatureAdder for a fixed-width analysis-backed type.
impl_feature_adder: Implements FeatureAdder for a type that already satisfies LengthCheckedFeatureAdder.
impl_player_feature_adder: Implements PlayerFeatureAdder for a type that satisfies LengthCheckedPlayerFeatureAdder.
player_feature_adder: Implements the ndarray feature-adder traits for an existing per-player feature type.