Struct ReplayProcessor 

pub struct ReplayProcessor<'a> {

    pub replay: &'a Replay,
    pub actor_state: ActorStateModeler,
    pub object_id_to_name: HashMap<ObjectId, String>,
    pub name_to_object_id: HashMap<String, ObjectId>,
    pub ball_actor_id: Option<ActorId>,
    pub team_zero: Vec<PlayerId>,
    pub team_one: Vec<PlayerId>,
    pub player_to_actor_id: HashMap<PlayerId, ActorId>,
    pub player_to_car: HashMap<ActorId, ActorId>,
    pub player_to_team: HashMap<ActorId, ActorId>,
    pub car_to_player: HashMap<ActorId, ActorId>,
    pub car_to_boost: HashMap<ActorId, ActorId>,
    pub car_to_jump: HashMap<ActorId, ActorId>,
    pub car_to_double_jump: HashMap<ActorId, ActorId>,
    pub car_to_dodge: HashMap<ActorId, ActorId>,
    pub boost_pad_events: Vec<BoostPadEvent>,
    pub touch_events: Vec<TouchEvent>,
    pub dodge_refreshed_events: Vec<DodgeRefreshedEvent>,
    pub goal_events: Vec<GoalEvent>,
    pub player_stat_events: Vec<PlayerStatEvent>,
    pub demolishes: Vec<DemolishInfo>,
    /* private fields */
}

The ReplayProcessor struct is a pivotal component in subtr-actor’s replay parsing pipeline. It is designed to process and traverse an actor graph of a Rocket League replay, and expose methods for collectors to gather specific data points as it progresses through the replay.

The processor pushes frames from a replay through an ActorStateModeler, which models the state all actors in the replay at a given point in time. The ReplayProcessor also maintains various mappings to allow efficient lookup and traversal of the actor graph, thus assisting Collector instances in their data accumulation tasks.

The primary method of this struct is process, which takes a collector and processes the replay. As it traverses the replay, it calls the Collector::process_frame method of the passed collector, passing the current frame along with its contextual data. This allows the collector to extract specific data from each frame as needed.

The ReplayProcessor also provides a number of helper methods for navigating the actor graph and extracting information, such as get_ball_rigid_body, get_player_name, get_player_team_key, get_player_is_team_0, and get_player_rigid_body.

See Also

• ActorStateModeler: A struct used to model the states of multiple actors at a given point in time.
• Collector: A trait implemented by objects that wish to collect data as the ReplayProcessor processes a replay.

Fields

replay: &'a Replay

The replay currently being traversed.

actor_state: ActorStateModeler

Modeled actor state for the current replay frame.

object_id_to_name: HashMap<ObjectId, String>

Mapping from object ids to their replay object names.

name_to_object_id: HashMap<String, ObjectId>

Reverse lookup from replay object names to object ids.

ball_actor_id: Option<ActorId>

Cached actor id for the replay ball when known.

team_zero: Vec<PlayerId>

Stable ordering of team 0 players.

team_one: Vec<PlayerId>

Stable ordering of team 1 players.

player_to_actor_id: HashMap<PlayerId, ActorId>

Mapping from player ids to their player-controller actor ids.

player_to_car: HashMap<ActorId, ActorId>

Mapping from player-controller actors to car actors.

player_to_team: HashMap<ActorId, ActorId>

Mapping from player-controller actors to team actors.

car_to_player: HashMap<ActorId, ActorId>

Reverse mapping from car actors to player-controller actors.

car_to_boost: HashMap<ActorId, ActorId>

Mapping from car actors to boost component actors.

car_to_jump: HashMap<ActorId, ActorId>

Mapping from car actors to jump component actors.

car_to_double_jump: HashMap<ActorId, ActorId>

Mapping from car actors to double-jump component actors.

car_to_dodge: HashMap<ActorId, ActorId>

Mapping from car actors to dodge component actors.

boost_pad_events: Vec<BoostPadEvent>

All boost-pad events observed so far in the replay.

touch_events: Vec<TouchEvent>

All touch events observed so far in the replay.

dodge_refreshed_events: Vec<DodgeRefreshedEvent>

All dodge-refresh events observed so far in the replay.

goal_events: Vec<GoalEvent>

All goal events observed so far in the replay.

player_stat_events: Vec<PlayerStatEvent>

All shot/save/assist-style stat events observed so far in the replay.

demolishes: Vec<DemolishInfo>

All demolishes observed so far in the replay.

Implementations

impl<'a> ReplayProcessor<'a>

pub fn process_long_enough_to_get_actor_ids(&mut self) -> SubtrActorResult<()>

Processes the replay until it has gathered enough information to map players to their actor IDs.

This function is designed to ensure that each player that participated in the game is associated with a corresponding actor ID. It runs the processing operation for approximately the first 10 seconds of the replay (10 * 30 frames), as this time span is generally sufficient to identify all players.

Note that this function is particularly necessary because the headers of replays sometimes omit some players.

Errors

If any error other than FinishProcessingEarly occurs during the processing operation, it is propagated up by this function.

pub fn check_player_id_set(&self) -> SubtrActorResult<()>

Verifies that the discovered in-replay players match the stored player ordering.

pub fn process_and_get_replay_meta(&mut self) -> SubtrActorResult<ReplayMeta>

Processes the replay enough to get the actor IDs and then retrieves the replay metadata.

This method is a convenience function that combines the functionalities of process_long_enough_to_get_actor_ids and get_replay_meta into a single operation. It’s meant to be used when you don’t necessarily want to process the whole replay and need only the replay’s metadata.

pub fn get_replay_meta(&self) -> SubtrActorResult<ReplayMeta>

Retrieves the replay metadata.

This function collects information about each player in the replay and groups them by team. For each player, it gets the player’s name and statistics. All this information is then wrapped into a ReplayMeta object along with the properties from the replay.

impl<'a> ReplayProcessor<'a>

pub fn map_attribute_keys( &self, hash_map: &HashMap<ObjectId, (Attribute, usize)>, ) -> HashMap<String, Attribute>

Rewrites an attribute map to use object-name keys instead of object ids.

pub fn all_mappings_string(&self) -> String

Returns a formatted dump of the processor’s main actor-link mappings.

pub fn actor_state_string(&self, actor_id: &ActorId) -> String

Returns a formatted dump of a single actor’s current attribute state.

pub fn print_actors_by_id<'b>( &self, actor_ids: impl Iterator<Item = &'b ActorId>, )

Prints the named actor states for the provided actor ids.

pub fn print_actors_of_type(&self, actor_type: &'static str)

Logs all actors of a specific object type with their mapped attributes.

pub fn print_actor_types(&self)

Logs the set of actor object types currently present in the state model.

pub fn print_all_actors(&self)

Logs every currently known actor with its mapped state.

impl<'a> ReplayProcessor<'a>

pub fn find_update_in_direction( &self, current_index: usize, actor_id: &ActorId, object_id: &ObjectId, direction: SearchDirection, ) -> SubtrActorResult<(Attribute, usize)>

Searches forward or backward for the next update of a specific actor property.

pub fn get_player_id_from_car_id( &self, actor_id: &ActorId, ) -> SubtrActorResult<PlayerId>

Resolves a car actor id back to the owning player id.

pub fn get_demolish_format(&self) -> Option<DemolishFormat>

Returns the demolish attribute encoding currently used by the replay, if known.

pub fn current_frame_boost_pad_events(&self) -> &[BoostPadEvent]

Returns the boost-pad events detected while processing the current frame.

pub fn current_frame_touch_events(&self) -> &[TouchEvent]

Returns the touch events detected while processing the current frame.

pub fn current_frame_dodge_refreshed_events(&self) -> &[DodgeRefreshedEvent]

Returns the dodge-refresh events detected while processing the current frame.

pub fn current_frame_goal_events(&self) -> &[GoalEvent]

Returns the goal events detected while processing the current frame.

pub fn current_frame_player_stat_events(&self) -> &[PlayerStatEvent]

Returns the player stat events detected while processing the current frame.

pub fn detect_demolish_format(&self) -> Option<DemolishFormat>

Inspects current actor state to infer which demolish attribute format is present.

pub fn get_active_demos( &self, ) -> SubtrActorResult<impl Iterator<Item = DemolishAttribute> + '_>

Returns an iterator over currently active demolish attributes in actor state.

pub fn get_interpolated_actor_rigid_body( &self, actor_id: &ActorId, time: f32, close_enough: f32, ) -> SubtrActorResult<RigidBody>

Interpolates an arbitrary actor rigid body to the requested replay time.

pub fn get_object_id_for_key( &self, name: &'static str, ) -> SubtrActorResult<&ObjectId>

Looks up the object id associated with a replay property name.

pub fn get_actor_ids_by_type( &self, name: &'static str, ) -> SubtrActorResult<&[ActorId]>

Returns the actor ids currently associated with a named object type.

pub fn get_attribute<'b>( &'b self, map: &'b HashMap<ObjectId, (Attribute, usize)>, property: &'static str, ) -> SubtrActorResult<&'b Attribute>

Reads a property from an actor or derived-attribute map by property name.

pub fn get_attribute_and_updated<'b>( &'b self, map: &'b HashMap<ObjectId, (Attribute, usize)>, property: &'static str, ) -> SubtrActorResult<&'b (Attribute, usize)>

Reads a property and the frame index when it was last updated.

pub fn get_ball_actor_id(&self) -> SubtrActorResult<ActorId>

Returns the tracked actor id for the replay ball.

pub fn get_metadata_actor_id(&self) -> SubtrActorResult<&ActorId>

Returns the main game metadata actor id.

pub fn get_player_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the actor id associated with a player id.

pub fn get_car_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the car actor id currently associated with a player.

pub fn get_car_connected_actor_id( &self, player_id: &PlayerId, map: &HashMap<ActorId, ActorId>, name: &'static str, ) -> SubtrActorResult<ActorId>

Resolves a player to a connected component actor through the supplied mapping.

pub fn get_boost_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the player’s boost component actor id.

pub fn get_jump_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the player’s jump component actor id.

pub fn get_double_jump_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the player’s double-jump component actor id.

pub fn get_dodge_actor_id( &self, player_id: &PlayerId, ) -> SubtrActorResult<ActorId>

Returns the player’s dodge component actor id.

pub fn get_actor_rigid_body( &self, actor_id: &ActorId, ) -> SubtrActorResult<(&RigidBody, &usize)>

Returns an actor’s rigid body together with the frame index of its last update.

pub fn get_actor_rigid_body_or_recently_deleted( &self, actor_id: &ActorId, ) -> SubtrActorResult<(&RigidBody, &usize)>

Like Self::get_actor_rigid_body, but falls back to recently deleted actor state.

pub fn iter_player_ids_in_order(&self) -> impl Iterator<Item = &PlayerId>

Iterates over players in the stable team-zero, then team-one ordering.

pub fn current_in_game_team_player_counts(&self) -> [usize; 2]

Counts currently in-game players per team from live actor state.

pub fn player_count(&self) -> usize

Returns the number of players in the stored replay ordering.

pub fn get_player_names(&self) -> HashMap<PlayerId, String>

Returns a map from player ids to their resolved display names.

pub fn iter_actors_by_type( &self, name: &'static str, ) -> Option<impl Iterator<Item = (&ActorId, &ActorState)>>

Iterates over actors of a named object type, if that type exists in the replay.

pub fn iter_actors_by_object_id<'b>( &'b self, object_id: &'b ObjectId, ) -> impl Iterator<Item = (&'b ActorId, &'b ActorState)> + 'b

Iterates over actors for a concrete object id.

pub fn get_seconds_remaining(&self) -> SubtrActorResult<i32>

Returns the replicated match clock in whole seconds.

pub fn get_replicated_state_name(&self) -> SubtrActorResult<i32>

Returns the replicated game-state enum value from the metadata actor.

pub fn get_replicated_game_state_time_remaining(&self) -> SubtrActorResult<i32>

Returns the replicated kickoff countdown / time-remaining field.

pub fn get_ball_has_been_hit(&self) -> SubtrActorResult<bool>

Returns whether the replay currently reports that the ball has been hit.

pub fn get_ignore_ball_syncing(&self) -> SubtrActorResult<bool>

Returns the ball actor’s ignore-syncing flag.

pub fn get_ball_rigid_body(&self) -> SubtrActorResult<&RigidBody>

Returns the current ball rigid body from live actor state.

pub fn get_normalized_ball_rigid_body(&self) -> SubtrActorResult<RigidBody>

Returns the current ball rigid body after spatial normalization.

pub fn ball_rigid_body_exists(&self) -> SubtrActorResult<bool>

Returns whether a non-sleeping ball rigid body is currently available.

pub fn get_ball_rigid_body_and_updated( &self, ) -> SubtrActorResult<(&RigidBody, &usize)>

Returns the current ball rigid body and the frame where it was last updated.

pub fn get_velocity_applied_ball_rigid_body( &self, target_time: f32, ) -> SubtrActorResult<RigidBody>

Applies stored ball velocity forward to the requested time.

pub fn get_interpolated_ball_rigid_body( &self, time: f32, close_enough: f32, ) -> SubtrActorResult<RigidBody>

Interpolates the ball rigid body to the requested time.

pub fn get_player_name(&self, player_id: &PlayerId) -> SubtrActorResult<String>

Returns the player’s replicated display name.

pub fn get_player_team_key( &self, player_id: &PlayerId, ) -> SubtrActorResult<String>

Returns the replay object-name key for the player’s team actor.

pub fn get_player_is_team_0( &self, player_id: &PlayerId, ) -> SubtrActorResult<bool>

Returns whether the player belongs to team 0.

pub fn get_team_score(&self, is_team_0: bool) -> SubtrActorResult<i32>

Returns the score for the requested team side.

pub fn get_team_scores(&self) -> SubtrActorResult<(i32, i32)>

Returns (team_zero_score, team_one_score).

pub fn get_player_rigid_body( &self, player_id: &PlayerId, ) -> SubtrActorResult<&RigidBody>

Returns the player’s current car rigid body.

pub fn get_normalized_player_rigid_body( &self, player_id: &PlayerId, ) -> SubtrActorResult<RigidBody>

Returns the player’s current car rigid body after spatial normalization.

pub fn get_player_rigid_body_and_updated( &self, player_id: &PlayerId, ) -> SubtrActorResult<(&RigidBody, &usize)>

Returns the player’s rigid body and the frame where it was last updated.

pub fn get_player_rigid_body_and_updated_or_recently_deleted( &self, player_id: &PlayerId, ) -> SubtrActorResult<(&RigidBody, &usize)>

Like Self::get_player_rigid_body_and_updated, but can use recently deleted state.

pub fn get_velocity_applied_player_rigid_body( &self, player_id: &PlayerId, target_time: f32, ) -> SubtrActorResult<RigidBody>

Applies stored player velocity forward to the requested time.

pub fn get_interpolated_player_rigid_body( &self, player_id: &PlayerId, time: f32, close_enough: f32, ) -> SubtrActorResult<RigidBody>

Interpolates the player’s car rigid body to the requested time.

pub fn get_player_boost_level( &self, player_id: &PlayerId, ) -> SubtrActorResult<f32>

Returns the player’s current boost amount in raw replay units.

pub fn get_player_last_boost_level( &self, player_id: &PlayerId, ) -> SubtrActorResult<f32>

Returns the previous boost amount recorded for the player in raw replay units.

pub fn get_player_boost_percentage( &self, player_id: &PlayerId, ) -> SubtrActorResult<f32>

Returns the player’s boost level scaled to the conventional 0.0-100.0 range.

pub fn get_player_match_assists( &self, player_id: &PlayerId, ) -> SubtrActorResult<i32>

Returns the player’s match assists counter.

pub fn get_player_match_goals( &self, player_id: &PlayerId, ) -> SubtrActorResult<i32>

Returns the player’s match goals counter.

pub fn get_player_match_saves( &self, player_id: &PlayerId, ) -> SubtrActorResult<i32>

Returns the player’s match saves counter.

pub fn get_player_match_score( &self, player_id: &PlayerId, ) -> SubtrActorResult<i32>

Returns the player’s match score counter.

pub fn get_player_match_shots( &self, player_id: &PlayerId, ) -> SubtrActorResult<i32>

Returns the player’s match shots counter.

pub fn get_ball_hit_team_num(&self) -> SubtrActorResult<u8>

Returns the team number recorded as the last ball-touching side.

pub fn get_scored_on_team_num(&self) -> SubtrActorResult<u8>

Returns the team number currently marked as having been scored on.

pub fn get_component_active(&self, actor_id: &ActorId) -> SubtrActorResult<u8>

Returns a component actor’s active byte.

pub fn get_boost_active(&self, player_id: &PlayerId) -> SubtrActorResult<u8>

Returns the active byte for the player’s boost component.

pub fn get_jump_active(&self, player_id: &PlayerId) -> SubtrActorResult<u8>

Returns the active byte for the player’s jump component.

pub fn get_double_jump_active( &self, player_id: &PlayerId, ) -> SubtrActorResult<u8>

Returns the active byte for the player’s double-jump component.

pub fn get_dodge_active(&self, player_id: &PlayerId) -> SubtrActorResult<u8>

Returns the active byte for the player’s dodge component.

pub fn get_powerslide_active( &self, player_id: &PlayerId, ) -> SubtrActorResult<bool>

Returns whether the player’s handbrake / powerslide flag is active.

impl<'a> ReplayProcessor<'a>

pub fn new(replay: &'a Replay) -> SubtrActorResult<Self>

Constructs a new ReplayProcessor instance with the provided replay.

Arguments

• replay - A reference to the boxcars::Replay to be processed.

Returns

Returns a SubtrActorResult of ReplayProcessor. In the process of initialization, the ReplayProcessor: - Maps each object id in the replay to its corresponding name. - Initializes empty state and attribute maps. - Sets the player order from either replay headers or frames, if available.

pub fn spatial_normalization_factor(&self) -> f32

Returns the scale factor applied when normalizing replay spatial values.

pub fn process<H: Collector>(&mut self, handler: &mut H) -> SubtrActorResult<()>

Self::process takes a Collector as an argument and iterates over each frame in the replay, updating the internal state of the processor and other relevant mappings based on the current frame.

After each a frame is processed, Collector::process_frame of the collector is called. The TimeAdvance return value of this call into Collector::process_frame is used to determine what happens next: in the case of TimeAdvance::Time, the notion of current time is advanced by the provided amount, and only the timestamp of the frame is exceeded, do we process the next frame. This mechanism allows fine grained control of frame processing, and the frequency of invocations of the Collector. If time is advanced by less than the delay between frames, the collector will be called more than once per frame, and can use functions like Self::get_interpolated_player_rigid_body to get values that are interpolated between frames. Its also possible to skip over frames by providing time advance values that are sufficiently large.

At the end of processing, it checks to make sure that no unknown players were encountered during the replay. If any unknown players are found, an error is returned.

pub fn process_all( &mut self, collectors: &mut [&mut dyn Collector], ) -> SubtrActorResult<()>

Process multiple collectors simultaneously over the same replay frames.

All collectors receive the same frame data for each frame. This is useful when you have multiple independent collectors that each gather different aspects of replay data.

Note: This method always advances frame-by-frame. If collectors return TimeAdvance::Time values, those are ignored.

pub fn reset(&mut self)

Reset the state of the ReplayProcessor.