replicar 2.0.4__tar.gz

replicar-2.0.4/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: replicar
+Version: 2.0.4
+Summary: Read replicar files: Rocket League replays reconstructed as RocketSim states
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=15
+Provides-Extra: convert
+Requires-Dist: replicar-native==2.0.4; extra == "convert"
+Provides-Extra: rocketsim
+Requires-Dist: rocketsim>=2.1.1; extra == "rocketsim"
+Provides-Extra: rlgym
+Requires-Dist: rlgym-rocket-league>=2.0.1; extra == "rlgym"
+Requires-Dist: rocketsim>=2.1.1; extra == "rlgym"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# replicar (Python reader)
+
+Reads replicar files: Rocket League replays reconstructed as RocketSim states, one Parquet file per replay. Reading
+needs only pyarrow and NumPy; the files are written by the `replicar` command (`crates/replicar-cli`).
+
+```python
+import replicar
+
+f = replicar.read("match.parquet")
+f.header["players"]          # name, team, hitbox of each player index
+a = f.arrays()               # a["car_position"]: (frames, players, 3) float32, NaN when unknown
+f.records("ball_contacts")   # one row per contact, with its frame
+```
+
+The words are defined in `docs/glossary.md`. Tests: `PYTHONPATH=src python -m pytest tests` (Python 3.12 or newer).

replicar-2.0.4/README.md

@@ -0,0 +1,15 @@
+# replicar (Python reader)
+
+Reads replicar files: Rocket League replays reconstructed as RocketSim states, one Parquet file per replay. Reading
+needs only pyarrow and NumPy; the files are written by the `replicar` command (`crates/replicar-cli`).
+
+```python
+import replicar
+
+f = replicar.read("match.parquet")
+f.header["players"]          # name, team, hitbox of each player index
+a = f.arrays()               # a["car_position"]: (frames, players, 3) float32, NaN when unknown
+f.records("ball_contacts")   # one row per contact, with its frame
+```
+
+The words are defined in `docs/glossary.md`. Tests: `PYTHONPATH=src python -m pytest tests` (Python 3.12 or newer).

replicar-2.0.4/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "replicar"
+version = "2.0.4"
+description = "Read replicar files: Rocket League replays reconstructed as RocketSim states"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = ["numpy>=1.26", "pyarrow>=15"]
+
+[project.optional-dependencies]
+convert = ["replicar-native==2.0.4"]
+rocketsim = ["rocketsim>=2.1.1"]
+rlgym = ["rlgym-rocket-league>=2.0.1", "rocketsim>=2.1.1"]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+replicar = ["py.typed"]

replicar-2.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

replicar-2.0.4/src/replicar/__init__.py

@@ -0,0 +1,283 @@
+"""Read replicar files: Rocket League replays reconstructed as RocketSim states, one Parquet file per replay.
+
+A replicar file is an ordinary Parquet file; this package only adds conveniences (docs/glossary.md):
+
+>>> import replicar
+>>> f = replicar.read("match.parquet")
+>>> f.header["players"]                   # who is at each player index
+>>> a = f.arrays()                        # NumPy: a["car_position"] has shape (rows, players, 3)
+>>> f.records("events")                   # a pyarrow table with one row per event and its frame
+
+Floats are float32 with NaN for unknown values; integers use -1 for unknown; quantized columns are decoded with
+their scale. Reading needs only pyarrow and NumPy.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.compute as pc
+import pyarrow.parquet as pq
+
+__all__ = ["FORMAT_VERSION", "ReplicarFile", "convert", "convert_many", "iter_frames", "read", "resimulate"]
+
+#: The newest file format this reader reads.
+FORMAT_VERSION = 1
+
+_PLAYER = re.compile(r"^(car|player|network_car|network_player)_(\d+)_(.+)$")
+_PAD = re.compile(r"^pad_(\d+)_(.+)$")
+_COMPONENTS = ("x", "y", "z", "w")
+
+
+def _values(column: pa.ChunkedArray, field: pa.Field) -> np.ndarray:
+    """A column as NumPy: float32 with NaN, integers with -1, booleans (int8 with -1 when any is null),
+    names as strings ('' for null); integers with a `scale` decoded to float32."""
+    array = column.combine_chunks()
+    metadata = field.metadata or {}
+    kind = field.type
+    if b"scale" in metadata:
+        scale = float(metadata[b"scale"])
+        values = array.to_numpy(zero_copy_only=False).astype(np.float64)
+        if array.null_count:
+            values[np.asarray(array.is_null())] = np.nan
+        return (values * scale).astype(np.float32)
+    if pa.types.is_dictionary(kind):
+        array = array.cast(pa.string())
+        kind = pa.string()
+    if pa.types.is_floating(kind):
+        return array.to_numpy(zero_copy_only=False).astype(np.float32)
+    if pa.types.is_integer(kind):
+        return pc.fill_null(array.cast(pa.int64()), -1).to_numpy(zero_copy_only=False)
+    if pa.types.is_boolean(kind):
+        if array.null_count:
+            return pc.fill_null(array.cast(pa.int8()), -1).to_numpy(zero_copy_only=False)
+        return array.to_numpy(zero_copy_only=False)
+    if pa.types.is_string(kind):
+        return np.array(pc.fill_null(array, "").to_pylist(), dtype=object)
+    raise TypeError(f"{field.name}: {kind} is not a plain column; use records()")
+
+
+@dataclass
+class ReplicarFile:
+    """An opened replicar file: its header and its columns."""
+
+    path: Path
+    header: dict[str, Any]
+    table: pa.Table
+    _arrays: dict[str, np.ndarray] | None = field(default=None, repr=False)
+
+    @property
+    def players(self) -> list[dict[str, Any]]:
+        return self.header["players"]
+
+    @property
+    def groups(self) -> list[str]:
+        return self.header["groups"]
+
+    def arrays(self) -> dict[str, np.ndarray]:
+        """Every plain column as a NumPy array, with the components of a vector stacked last (`ball_position`:
+        (rows, 3)), per-player columns stacked by player index (`car_position`: (rows, players, 3)) and
+        per-pad columns by pad index (`pad_cooldown`: (rows, pads)). Record lists are left to `records`."""
+        if self._arrays is not None:
+            return self._arrays
+        columns: dict[str, np.ndarray] = {}
+        for name, column in zip(self.table.column_names, self.table.columns):
+            field = self.table.schema.field(name)
+            if pa.types.is_list(field.type) or pa.types.is_struct(field.type):
+                continue
+            columns[name] = _values(column, field)
+        # Per player or pad: car_0_position_x -> car_position_x at index 0.
+        indexed: dict[str, dict[int, np.ndarray]] = {}
+        plain: dict[str, np.ndarray] = {}
+        for name, values in columns.items():
+            match = _PLAYER.match(name)
+            if match:
+                indexed.setdefault(f"{match[1]}_{match[3]}", {})[int(match[2])] = values
+                continue
+            match = _PAD.match(name)
+            if match:
+                indexed.setdefault(f"pad_{match[2]}", {})[int(match[1])] = values
+                continue
+            plain[name] = values
+        rows = self.table.num_rows
+        for name, by_index in indexed.items():
+            count = max(by_index) + 1
+            first = next(iter(by_index.values()))
+            stacked = np.full((rows, count), np.nan if first.dtype.kind == "f" else -1, dtype=first.dtype)
+            for index, values in by_index.items():
+                stacked[:, index] = values
+            plain[name] = stacked
+        self._arrays = _stack_components(plain)
+        return self._arrays
+
+    def players_table(self) -> pa.Table:
+        """The header's players as a table: index, name, team (0 blue, 1 orange), hitbox, body, key, and one
+        column per final statistic (null for a statistic the header's `counted_stats` does not list: unknown)."""
+        players = self.header["players"]
+        stats = sorted({k for p in players for k in p.get("final_stats", {})})
+        columns = {
+            "player": pa.array([p["index"] for p in players], pa.uint8()),
+            "name": pa.array([p.get("name") for p in players], pa.string()),
+            "team": pa.array([p["team"] for p in players], pa.uint8()),
+            "hitbox": pa.array([p["hitbox"] for p in players], pa.string()),
+            "body_product_id": pa.array([p.get("body_product_id") for p in players], pa.uint32()),
+            "key": pa.array([p["key"] for p in players], pa.string()),
+        }
+        for stat in stats:
+            columns[f"final_{stat}"] = pa.array([p.get("final_stats", {}).get(stat) for p in players], pa.int32())
+        return pa.table(columns)
+
+    def long(self, prefix: str = "car") -> pa.Table:
+        """The per-player columns of `prefix` (`car`, `player`, `network_car`, `network_player`) in long form: one
+        row per file row and player, with the row's `frame` (and `sim_tick` and `frame_row` when the file has them),
+        `player` and the columns without their index (`car_0_boost` -> `car_boost`), for pandas and SQL. Players
+        absent from a row have null values there."""
+        by_name: dict[str, dict[int, str]] = {}
+        for name in self.table.column_names:
+            match = _PLAYER.match(name)
+            if match and match[1] == prefix:
+                by_name.setdefault(f"{prefix}_{match[3]}", {})[int(match[2])] = name
+        players = sorted({i for indexed in by_name.values() for i in indexed})
+        rows = self.table.num_rows
+        keys = {k: self.table.column(k).combine_chunks() for k in ("frame", "sim_tick", "frame_row")
+                if k in self.table.column_names}
+        order = pa.array(np.arange(rows, dtype=np.int64))
+        pieces = []
+        for player in players:
+            columns = {**keys, "player": pa.array(np.full(rows, player, np.uint8)), "_row": order}
+            for base, indexed in by_name.items():
+                if player in indexed:
+                    columns[base] = self.table.column(indexed[player]).combine_chunks()
+                else:
+                    first = self.table.column(next(iter(indexed.values()))).type
+                    columns[base] = pa.nulls(rows, first)
+            pieces.append(pa.table(columns))
+        if not pieces:
+            return pa.table({"frame": pa.array([], pa.uint32()), "player": pa.array([], pa.uint8())})
+        return pa.concat_tables(pieces).sort_by([("_row", "ascending"), ("player", "ascending")]).drop_columns("_row")
+
+    def records(self, name: str) -> pa.Table:
+        """A record-list column (`events`, `ball_contacts`, `boost_pickups`, `prediction_errors`, ...) as one row
+        per record, with the `frame` (and `sim_tick`) of its row."""
+        column = self.table.column(name).combine_chunks()
+        lengths = pc.list_value_length(column).fill_null(0).to_numpy(zero_copy_only=False)
+        frames = np.repeat(self.table.column("frame").to_numpy(), lengths)
+        flat = pc.list_flatten(column)
+        fields = {"frame": pa.array(frames, pa.uint32())}
+        if "sim_tick" in self.table.column_names:
+            fields["sim_tick"] = pa.array(np.repeat(self.table.column("sim_tick").to_numpy(), lengths), pa.uint64())
+        for i, child in enumerate(flat.type):
+            fields[child.name] = flat.field(i)
+        return pa.table(fields)
+
+
+def _stack_components(columns: dict[str, np.ndarray]) -> dict[str, np.ndarray]:
+    """`<name>_x`, `_y`, `_z` (and `_w`) of the same shape and type become one array `<name>` with the
+    components last; a lone `_x` stays as it is."""
+    out: dict[str, np.ndarray] = {}
+    used: set[str] = set()
+    for name in columns:
+        if name in used or not name.endswith("_x"):
+            continue
+        base = name[:-2]
+        parts = []
+        for component in _COMPONENTS:
+            part = columns.get(f"{base}_{component}")
+            if part is None or part.shape != columns[name].shape or part.dtype != columns[name].dtype:
+                break
+            parts.append(f"{base}_{component}")
+        if len(parts) >= 3 and base not in columns:
+            out[base] = np.stack([columns[p] for p in parts], axis=-1)
+            used.update(parts)
+    for name, values in columns.items():
+        if name not in used:
+            out[name] = values
+    return out
+
+
+def read(path: str | Path, columns: list[str] | None = None, replay: str | Path | None = None) -> ReplicarFile:
+    """Open a replicar file (all columns, or the named ones). `replay` is for a file without the `state` group,
+    which must be resimulated: that needs the native extra (`pip install replicar[convert]`)."""
+    path = Path(path)
+    metadata = pq.read_metadata(path).metadata or {}
+    if b"replicar" not in metadata:
+        raise ValueError(f"{path} has no replicar header: not a replicar file")
+    header = json.loads(metadata[b"replicar"])
+    if header.get("format_version", 0) > FORMAT_VERSION:
+        raise ValueError(
+            f"{path} is format version {header['format_version']}; this reader reads {FORMAT_VERSION} and earlier"
+        )
+    if replay is not None and "state" not in header.get("groups", []):
+        # Resimulate the states and read them with the file's own groups.
+        native = _native("reading a file without the state group")
+        with tempfile.TemporaryDirectory() as directory:
+            full = Path(directory) / "full.parquet"
+            groups = [g for g in header.get("groups", []) if g != "resimulation"] + ["state"]
+            native.resimulate(str(path), str(replay), str(full), precision=header.get("precision", "float32"),
+                              groups=groups, all_frames=header.get("all_frames", False),
+                              rows=header.get("rows", "frames"), tick_step=header.get("tick_step", 1))
+            opened = read(full, columns)
+            opened.table = opened.table.combine_chunks()
+            return ReplicarFile(path=path, header={**opened.header, "groups": header.get("groups", [])},
+                                table=opened.table)
+    if columns is not None and "frame" not in columns:
+        columns = ["frame", *columns]
+    table = pq.read_table(path, columns=columns)
+    return ReplicarFile(path=path, header=header, table=table)
+
+
+def _native(purpose: str):
+    try:
+        import replicar_native
+    except ImportError as error:
+        raise ImportError(f"{purpose} needs the native extra: pip install replicar[convert]") from error
+    return replicar_native
+
+
+def iter_frames(path: str | Path, replay: str | Path | None = None, batch_frames: int = 4096):
+    """The file's rows in pyarrow record batches of `batch_frames` (resimulating a file without states when
+    `replay` is given)."""
+    if replay is not None:
+        opened = read(path, replay=replay)
+        yield from opened.table.to_batches(max_chunksize=batch_frames)
+        return
+    yield from pq.ParquetFile(path).iter_batches(batch_size=batch_frames)
+
+
+def convert(replay: str | Path, output: str | Path, *, precision: str = "float32", groups: list[str] | None = None,
+            with_groups: list[str] | None = None, all_frames: bool = False, rows: str = "ticks", tick_step: int = 1,
+            meshes: str | Path | None = None) -> None:
+    """Convert a replay to a replicar file (needs the native extra): a row per simulated tick in play (`rows="ticks"`,
+    every `tick_step`-th) or per replay frame (`rows="frames"`). `meshes`: RocketSim's collision meshes, else
+    $REPLICAR_MESHES, else ./collision_meshes."""
+    _native("converting").convert(str(replay), str(output), precision=precision, groups=groups,
+                                  with_groups=with_groups, all_frames=all_frames, rows=rows, tick_step=tick_step,
+                                  meshes_dir=None if meshes is None else str(meshes))
+
+
+def convert_many(replays: list[str | Path], output_dir: str | Path, *, jobs: int | None = None,
+                 skip_existing: bool = False, precision: str = "float32", groups: list[str] | None = None,
+                 with_groups: list[str] | None = None, all_frames: bool = False, rows: str = "ticks",
+                 tick_step: int = 1, meshes: str | Path | None = None) -> list[dict[str, Any]]:
+    """Convert replays to `output_dir/<name>.parquet`, `jobs` at a time, and write `output_dir/index.parquet`.
+    Returns one dict per replay; a failed one has its `error`."""
+    return _native("converting").convert_many(
+        [str(r) for r in replays], str(output_dir), jobs=jobs, skip_existing=skip_existing, precision=precision,
+        groups=groups, with_groups=with_groups, all_frames=all_frames, rows=rows, tick_step=tick_step,
+        meshes_dir=None if meshes is None else str(meshes))
+
+
+def resimulate(file: str | Path, replay: str | Path, output: str | Path, *, precision: str = "float32",
+               groups: list[str] | None = None, with_groups: list[str] | None = None, all_frames: bool = False,
+               rows: str = "ticks", tick_step: int = 1, meshes: str | Path | None = None) -> None:
+    """Rebuild a file from its replay and its `resimulation` group, without fitting (needs the native extra)."""
+    _native("resimulating").resimulate(str(file), str(replay), str(output), precision=precision, groups=groups,
+                                       with_groups=with_groups, all_frames=all_frames, rows=rows, tick_step=tick_step,
+                                       meshes_dir=None if meshes is None else str(meshes))

replicar-2.0.4/src/replicar/rlgym.py

@@ -0,0 +1,136 @@
+"""A replicar row as an RLGym `GameState` (rlgym 2, `rlgym.rocket_league`), for `RocketSimEngine.set_state` or a
+state mutator: an RLGym environment that starts from any replay frame.
+
+    import replicar, replicar.rlgym
+    f = replicar.read("match.parquet")
+    state = replicar.rlgym.game_state(f, row=1200)        # cars keyed by player index
+    engine.set_state(state, {})
+
+A `GameState` has less than a RocketSim state: no controls (an environment's actions supply them), of the previous
+controls only the jump (`is_holding_jump`), and no air time, world contact or bump cooldown. `RocketSimEngine.set_state`
+fills a RocketSim arena from it; for everything a row has, use `replicar.rocketsim` instead. The derived values follow
+RLGym's definitions: `is_demoed` is a positive `demo_respawn_timer`, `on_ground` three wheels in contact, and
+`is_supersonic` a positive `supersonic_time`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Hashable
+
+import numpy as np
+
+from .rocketsim import PAD_TOLERANCE, has_car, rotation_matrix
+
+#: replicar's hitbox names and RLGym's hitbox constants (`rlgym.rocket_league.common_values`; it has no `psyclops`).
+HITBOXES = {"octane": 0, "dominus": 1, "plank": 2, "breakout": 3, "hybrid": 4, "merc": 5}
+
+#: Seconds of one tick: a supersonic car gets at least this much `supersonic_time`, else RLGym counts it as not
+#: supersonic.
+_TICK = 1.0 / 120.0
+
+
+def _modules():
+    try:
+        from rlgym.rocket_league import common_values
+        from rlgym.rocket_league.api import Car, GameConfig, GameState, PhysicsObject
+    except ImportError as error:
+        raise ImportError("replicar.rlgym needs RLGym 2: pip install replicar[rlgym]") from error
+    return common_values, Car, GameConfig, GameState, PhysicsObject
+
+
+def _physics(PhysicsObject, position, velocity, angular_velocity, rotation):
+    physics = PhysicsObject()
+    physics.position = np.asarray(position, dtype=np.float32)
+    physics.linear_velocity = np.asarray(velocity, dtype=np.float32)
+    physics.angular_velocity = np.asarray(angular_velocity, dtype=np.float32)
+    physics.rotation_mtx = rotation_matrix(rotation).astype(np.float32)
+    return physics
+
+
+def game_state(
+    file,
+    row: int,
+    *,
+    agent_ids: dict[int, Hashable] | None = None,
+    hitboxes: dict[str, int] | None = None,
+) -> Any:
+    """The row as a `GameState`: the ball, a `Car` per player with a car in the row (keyed by `agent_ids[player]`,
+    else the player index), the pad timers in RLGym's pad order (`BOOST_LOCATIONS`), the row's sim tick as
+    `tick_count`, and RLGym's default `GameConfig` (standard gravity, boost consumption and dodge deadzone).
+    `hitboxes` adds or replaces entries of `HITBOXES`."""
+    common_values, Car, GameConfig, GameState, PhysicsObject = _modules()
+    a = file.arrays()
+    if "car_position" not in a or "ball_position" not in a:
+        raise ValueError(f"{file.path}: no state group (read the file with replay=... to rebuild it)")
+    presets = {**HITBOXES, **(hitboxes or {})}
+
+    state = GameState()
+    state.tick_count = int(a["sim_tick"][row])
+    state.config = GameConfig()
+    state.config.gravity = 1.0
+    state.config.boost_consumption = 1.0
+    state.config.dodge_deadzone = 0.5
+    state.ball = _physics(
+        PhysicsObject,
+        a["ball_position"][row],
+        a["ball_velocity"][row],
+        a["ball_angular_velocity"][row],
+        a["ball_rotation"][row],
+    )
+    state.goal_scored = bool(abs(a["ball_position"][row][1]) > common_values.GOAL_THRESHOLD)
+
+    state.cars = {}
+    for info in file.players:
+        p = info["index"]
+        if not has_car(file, row, p):
+            continue
+        if info["hitbox"] not in presets:
+            raise ValueError(f"RLGym has no {info['hitbox']} hitbox (player {p}); pass hitboxes=")
+        flag = lambda name: bool(a[f"car_{name}"][row, p] == 1)  # noqa: E731
+        number = lambda name: float(a[f"car_{name}"][row, p])  # noqa: E731
+        car = Car()
+        car.team_num = int(info["team"])
+        car.hitbox_type = presets[info["hitbox"]]
+        car.ball_touches = 0
+        car.bump_victim_id = None
+        car.physics = _physics(
+            PhysicsObject,
+            a["car_position"][row, p],
+            a["car_velocity"][row, p],
+            a["car_angular_velocity"][row, p],
+            a["car_rotation"][row, p],
+        )
+        car.demo_respawn_timer = number("demo_respawn_timer") if flag("is_demoed") else 0.0
+        car.wheels_with_contact = tuple(bool(a[f"car_wheel_{k}_contact"][row, p] == 1) for k in range(4))
+        # As in replicar.rocketsim: the time left in the grace below start speed, and at least a tick while supersonic.
+        car.supersonic_time = max(number("supersonic_grace_timer"), _TICK) if flag("is_supersonic") else 0.0
+        car.boost_amount = number("boost")
+        car.boost_active_time = number("boosting_time")
+        car.handbrake = number("handbrake_value")
+        car.is_jumping = flag("is_jumping")
+        car.has_jumped = flag("has_jumped")
+        car.is_holding_jump = flag("previous_controls_jump")
+        car.jump_time = float(a["car_jump_ticks"][row, p]) / 120.0
+        car.has_flipped = flag("has_flipped")
+        car.has_double_jumped = flag("has_double_jumped")
+        car.air_time_since_jump = number("air_time_since_jump")
+        car.flip_time = number("flip_time")
+        car.flip_torque = np.asarray(a["car_flip_relative_torque"][row, p], dtype=np.float32)
+        car.is_autoflipping = flag("is_auto_flipping")
+        car.autoflip_timer = number("auto_flip_timer")
+        car.autoflip_direction = number("auto_flip_torque_scale")
+        state.cars[agent_ids[p] if agent_ids else p] = car
+
+    # RLGym indexes the pad timers in its BOOST_LOCATIONS order: match the header's pads by position.
+    header = np.array([pad["position"][:2] for pad in file.header["pads"]], dtype=np.float64)
+    locations = np.array(common_values.BOOST_LOCATIONS, dtype=np.float64)[:, :2]
+    timers = np.zeros(len(locations), dtype=np.float32)
+    cooldowns = a.get("pad_cooldown")
+    for i, (x, y) in enumerate(locations):
+        distance = np.hypot(header[:, 0] - x, header[:, 1] - y)
+        k = int(np.argmin(distance))
+        if distance[k] > PAD_TOLERANCE:
+            raise ValueError(f"no pad of the file at RLGym's pad {i} ({x}, {y})")
+        timers[i] = 0.0 if cooldowns is None else max(float(cooldowns[row, k]), 0.0)
+    state.boost_pad_timers = timers
+    return state

replicar-2.0.4/src/replicar/rocketsim.py

@@ -0,0 +1,209 @@
+"""A replicar row as a state of mtheall's RocketSim bindings (the `rocketsim` package, module `RocketSim`, as RLGym
+uses it), to continue a match from any frame or to start an RLGym environment there.
+
+    import RocketSim, replicar, replicar.rocketsim
+    RocketSim.init("collision_meshes")
+    f = replicar.read("match.parquet")
+    arena, cars = replicar.rocketsim.arena(f, row=1200)   # cars: {player index: RocketSim.Car}
+    arena.step(8)
+
+replicar simulates with the Rust port of RocketSim (the `rocketsim` crate); the bindings are the C++ RocketSim. They
+model the same game, but a state stepped in the bindings is not replicar's: one frame ahead, a car is about 0.2 UU
+apart at the median (docs/v2-guide.md, "Continuing in RocketSim"), and the difference grows with time. What the bindings' state has and a replicar row does not is left at its
+default: the ball's heatseeker state, a car's flip-reset flags, the car a bump cooldown is for, and the tick of a car's
+last extra ball-hit impulse.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+#: How far (UU) a pad may be from the file's to be the same pad (RLGym's table has one 2 UU off; pads are hundreds
+#: of UU apart).
+PAD_TOLERANCE = 10.0
+
+#: replicar's hitbox names and the bindings' `CarConfig` presets (the bindings have no `psyclops`).
+HITBOXES = {
+    "octane": "OCTANE",
+    "dominus": "DOMINUS",
+    "plank": "PLANK",
+    "breakout": "BREAKOUT",
+    "hybrid": "HYBRID",
+    "merc": "MERC",
+}
+
+
+def _module():
+    try:
+        import RocketSim
+    except ImportError as error:
+        raise ImportError(
+            "replicar.rocketsim needs mtheall's RocketSim bindings: pip install rocketsim"
+        ) from error
+    return RocketSim
+
+
+def rotation_matrix(rotation: np.ndarray) -> np.ndarray:
+    """A unit quaternion (x, y, z, w) as the rotation matrix whose columns are the forward, right and up axes."""
+    x, y, z, w = (float(v) for v in rotation)
+    return np.array(
+        [
+            [1 - 2 * (y * y + z * z), 2 * (x * y - w * z), 2 * (x * z + w * y)],
+            [2 * (x * y + w * z), 1 - 2 * (x * x + z * z), 2 * (y * z - w * x)],
+            [2 * (x * z - w * y), 2 * (y * z + w * x), 1 - 2 * (x * x + y * y)],
+        ]
+    )
+
+
+def _rot_mat(rs, rotation: np.ndarray):
+    """The bindings' rotation matrix, given by its forward, right and up axes."""
+    return rs.RotMat(*rotation_matrix(rotation).T.flatten())
+
+
+def _vec(rs, values: np.ndarray):
+    return rs.Vec(*(float(v) for v in values))
+
+
+def _controls(rs, a: dict[str, np.ndarray], prefix: str, row: int, p: int):
+    controls = rs.CarControls()
+    for name in ("throttle", "steer", "pitch", "yaw", "roll"):
+        controls.__setattr__(name, float(a[f"car_{prefix}_{name}"][row, p]))
+    for name in ("jump", "boost", "handbrake"):
+        controls.__setattr__(name, bool(a[f"car_{prefix}_{name}"][row, p] == 1))
+    return controls
+
+
+def _arrays(file) -> dict[str, np.ndarray]:
+    a = file.arrays()
+    if "car_position" not in a or "ball_position" not in a:
+        raise ValueError(f"{file.path}: no state group (read the file with replay=... to rebuild it)")
+    return a
+
+
+def has_car(file, row: int, player: int) -> bool:
+    """The player has a car in the row."""
+    a = _arrays(file)
+    return a["car_status"][row, player] not in ("", "absent") and not np.isnan(a["car_position"][row, player, 0])
+
+
+def ball_state(file, row: int):
+    """The row's ball as a `RocketSim.BallState`."""
+    rs = _module()
+    a = _arrays(file)
+    state = rs.BallState()
+    state.pos = _vec(rs, a["ball_position"][row])
+    state.vel = _vec(rs, a["ball_velocity"][row])
+    state.ang_vel = _vec(rs, a["ball_angular_velocity"][row])
+    state.rot_mat = _rot_mat(rs, a["ball_rotation"][row])
+    return state
+
+
+def car_state(file, row: int, player: int):
+    """The row's car of `player` as a `RocketSim.CarState`, with its previous controls as `last_controls`."""
+    rs = _module()
+    a = _arrays(file)
+    if not has_car(file, row, player):
+        raise ValueError(f"player {player} has no car in row {row}")
+    p = player
+    flag = lambda name: bool(a[f"car_{name}"][row, p] == 1)  # noqa: E731
+    number = lambda name: float(a[f"car_{name}"][row, p])  # noqa: E731
+    state = rs.CarState()
+    state.pos = _vec(rs, a["car_position"][row, p])
+    state.vel = _vec(rs, a["car_velocity"][row, p])
+    state.ang_vel = _vec(rs, a["car_angular_velocity"][row, p])
+    state.rot_mat = _rot_mat(rs, a["car_rotation"][row, p])
+    state.boost = number("boost")
+    state.is_on_ground = flag("is_on_ground")
+    state.wheels_with_contact = tuple(bool(a[f"car_wheel_{k}_contact"][row, p] == 1) for k in range(4))
+    state.has_jumped = flag("has_jumped")
+    state.has_double_jumped = flag("has_double_jumped")
+    state.has_flipped = flag("has_flipped")
+    state.flip_rel_torque = _vec(rs, a["car_flip_relative_torque"][row, p])
+    # The port counts `jump_ticks` on every tick, on the ground too, and restarts it when a jump ends; the bindings'
+    # `jump_time` is 0 until the car jumps and then counts from the jump's start (measured, 2026-10-08). The same
+    # while the jump lasts; 0 before any jump; after the jump the port's count is the time since it ended.
+    state.jump_time = float(a["car_jump_ticks"][row, p]) / 120.0 if flag("has_jumped") else 0.0
+    state.flip_time = number("flip_time")
+    state.is_flipping = flag("is_flipping")
+    state.is_jumping = flag("is_jumping")
+    state.air_time = number("air_time")
+    state.air_time_since_jump = number("air_time_since_jump")
+    state.time_spent_boosting = number("boosting_time")
+    state.is_supersonic = flag("is_supersonic")
+    # Not the same quantity: the bindings' `supersonic_time` counts from when the car became supersonic, the port's
+    # grace timer the time spent below the start speed (measured, 2026-10-08); which matches the game is open.
+    state.supersonic_time = number("supersonic_grace_timer")
+    state.handbrake_val = number("handbrake_value")
+    state.is_auto_flipping = flag("is_auto_flipping")
+    state.auto_flip_timer = number("auto_flip_timer")
+    state.auto_flip_torque_scale = number("auto_flip_torque_scale")
+    state.car_contact_cooldown_timer = number("bump_cooldown_timer")
+    normal = a["car_world_contact_normal"][row, p]
+    state.has_world_contact = not np.isnan(normal[0])
+    if state.has_world_contact:
+        state.world_contact_normal = _vec(rs, normal)
+    state.is_demoed = flag("is_demoed")
+    state.demo_respawn_timer = number("demo_respawn_timer")
+    state.last_controls = _controls(rs, a, "previous_controls", row, p)
+    return state
+
+
+def car_controls(file, row: int, player: int):
+    """The controls the row's car of `player` drives on with from this row, as `RocketSim.CarControls`."""
+    return _controls(_module(), _arrays(file), "controls", row, player)
+
+
+def _pad_order(file, arena) -> list[int]:
+    """For each of the arena's pads, the header's pad at the same place."""
+    header = np.array([pad["position"][:2] for pad in file.header["pads"]], dtype=np.float64)
+    order = []
+    for pad in arena.get_boost_pads():
+        position = pad.get_pos()
+        distance = np.hypot(header[:, 0] - position.x, header[:, 1] - position.y)
+        nearest = int(np.argmin(distance))
+        if distance[nearest] > PAD_TOLERANCE:
+            raise ValueError(f"no pad of the file at the arena's pad ({position.x}, {position.y})")
+        order.append(nearest)
+    return order
+
+
+def set_state(arena, cars: dict[int, Any], file, row: int) -> None:
+    """Writes the row into `arena`: the ball, each car of `cars` (player index: `RocketSim.Car`; its state and
+    controls) and the pads' cooldowns."""
+    rs = _module()
+    a = _arrays(file)
+    arena.ball.set_state(ball_state(file, row))
+    for player, car in cars.items():
+        car.set_state(car_state(file, row, player))
+        car.set_controls(car_controls(file, row, player))
+    cooldowns = a.get("pad_cooldown")
+    if cooldowns is not None:
+        for pad, k in zip(arena.get_boost_pads(), _pad_order(file, arena)):
+            state = rs.BoostPadState()
+            cooldown = float(cooldowns[row, k])
+            state.cooldown = cooldown
+            state.is_active = cooldown <= 0.0
+            pad.set_state(state)
+
+
+def arena(file, row: int, *, game_mode=None, hitboxes: dict[str, str] | None = None) -> tuple[Any, dict[int, Any]]:
+    """A new `RocketSim.Arena` (soccar unless `game_mode`) in the row's state, with a car for every player who has
+    one in the row (their hitbox and team), and those cars by player index. `hitboxes` adds or replaces entries of
+    `HITBOXES` (`{"psyclops": "OCTANE"}` to accept a stand-in). `RocketSim.init` must have been called."""
+    rs = _module()
+    presets = {**HITBOXES, **(hitboxes or {})}
+    new = rs.Arena(rs.GameMode.SOCCAR if game_mode is None else game_mode)
+    cars = {}
+    for info in file.players:
+        player = info["index"]
+        if not has_car(file, row, player):
+            continue
+        if info["hitbox"] not in presets:
+            raise ValueError(f"the bindings have no {info['hitbox']} hitbox (player {player}); pass hitboxes=")
+        preset = getattr(rs.CarConfig, presets[info["hitbox"]])
+        team = rs.Team.BLUE if info["team"] == 0 else rs.Team.ORANGE
+        cars[player] = new.add_car(team, rs.CarConfig(preset))
+    set_state(new, cars, file, row)
+    return new, cars

replicar-2.0.4/src/replicar.egg-info/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: replicar
+Version: 2.0.4
+Summary: Read replicar files: Rocket League replays reconstructed as RocketSim states
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=15
+Provides-Extra: convert
+Requires-Dist: replicar-native==2.0.4; extra == "convert"
+Provides-Extra: rocketsim
+Requires-Dist: rocketsim>=2.1.1; extra == "rocketsim"
+Provides-Extra: rlgym
+Requires-Dist: rlgym-rocket-league>=2.0.1; extra == "rlgym"
+Requires-Dist: rocketsim>=2.1.1; extra == "rlgym"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# replicar (Python reader)
+
+Reads replicar files: Rocket League replays reconstructed as RocketSim states, one Parquet file per replay. Reading
+needs only pyarrow and NumPy; the files are written by the `replicar` command (`crates/replicar-cli`).
+
+```python
+import replicar
+
+f = replicar.read("match.parquet")
+f.header["players"]          # name, team, hitbox of each player index
+a = f.arrays()               # a["car_position"]: (frames, players, 3) float32, NaN when unknown
+f.records("ball_contacts")   # one row per contact, with its frame
+```
+
+The words are defined in `docs/glossary.md`. Tests: `PYTHONPATH=src python -m pytest tests` (Python 3.12 or newer).

replicar-2.0.4/src/replicar.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/replicar/__init__.py
+src/replicar/py.typed
+src/replicar/rlgym.py
+src/replicar/rocketsim.py
+src/replicar.egg-info/PKG-INFO
+src/replicar.egg-info/SOURCES.txt
+src/replicar.egg-info/dependency_links.txt
+src/replicar.egg-info/requires.txt
+src/replicar.egg-info/top_level.txt
+tests/test_read.py
+tests/test_rocketsim.py

replicar-2.0.4/src/replicar.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

replicar-2.0.4/src/replicar.egg-info/requires.txt

@@ -0,0 +1,15 @@
+numpy>=1.26
+pyarrow>=15
+
+[convert]
+replicar-native==2.0.4
+
+[rlgym]
+rlgym-rocket-league>=2.0.1
+rocketsim>=2.1.1
+
+[rocketsim]
+rocketsim>=2.1.1
+
+[test]
+pytest>=8

replicar-2.0.4/src/replicar.egg-info/top_level.txt

@@ -0,0 +1 @@
+replicar

replicar-2.0.4/tests/test_read.py

@@ -0,0 +1,129 @@
+"""Unit tests of the reader on small files written with pyarrow in the replicar layout."""
+
+import json
+
+import numpy as np
+import pyarrow as pa
+import pyarrow.parquet as pq
+import pytest
+
+import replicar
+
+
+def write(path, columns, header=None, metadata=None):
+    fields = []
+    arrays = []
+    for name, (array, field_metadata) in columns.items():
+        fields.append(pa.field(name, array.type, metadata=field_metadata))
+        arrays.append(array)
+    table = pa.Table.from_arrays(arrays, schema=pa.schema(fields))
+    header = {"format_version": 1, "groups": ["state", "game"], "precision": "float32",
+              "players": [{"index": 0}, {"index": 1}], **(header or {})}
+    table = table.replace_schema_metadata({"replicar": json.dumps(header)})
+    pq.write_table(table, path)
+
+
+def plain(values, kind):
+    return pa.array(values, kind), None
+
+
+def test_vectors_and_players_are_stacked_and_unknowns_are_nan_or_minus_one(tmp_path):
+    path = tmp_path / "x.parquet"
+    columns = {"frame": plain([3, 4], pa.uint32())}
+    for p, offset in [(0, 0.0), (1, 10.0)]:
+        for k, axis in enumerate("xyz"):
+            values = [offset + k, None] if p == 1 else [offset + k, offset + k + 1]
+            columns[f"car_{p}_position_{axis}"] = plain(values, pa.float32())
+        columns[f"car_{p}_update_tick"] = plain([7, None], pa.uint32())
+    columns["pad_0_cooldown"] = plain([0.0, 4.0], pa.float32())
+    columns["pad_1_cooldown"] = plain([1.0, 0.0], pa.float32())
+    write(path, columns)
+    a = replicar.read(path).arrays()
+    assert a["car_position"].shape == (2, 2, 3)
+    assert a["car_position"].dtype == np.float32
+    np.testing.assert_array_equal(a["car_position"][0, 1], [10, 11, 12])
+    assert np.isnan(a["car_position"][1, 1]).all()
+    np.testing.assert_array_equal(a["car_update_tick"], [[7, 7], [-1, -1]])
+    np.testing.assert_array_equal(a["pad_cooldown"], [[0, 1], [4, 0]])
+
+
+def test_quantized_columns_are_decoded_with_their_scale(tmp_path):
+    path = tmp_path / "q.parquet"
+    scale = {b"scale": b"1e-2", b"group": b"state"}
+    write(path, {
+        "frame": plain([0, 1], pa.uint32()),
+        "ball_position_x": (pa.array([123, -5], pa.int32()), scale),
+        "ball_position_y": (pa.array([0, None], pa.int32()), scale),
+        "ball_position_z": (pa.array([9275, 9275], pa.int32()), scale),
+    }, header={"precision": "quantized"})
+    a = replicar.read(path).arrays()
+    np.testing.assert_allclose(a["ball_position"][0], [1.23, 0.0, 92.75], rtol=1e-6)
+    assert np.isnan(a["ball_position"][1, 1])
+
+
+def test_names_and_flags(tmp_path):
+    path = tmp_path / "n.parquet"
+    names = pa.array(["running", None, "kickoff"]).dictionary_encode()
+    write(path, {
+        "frame": plain([0, 1, 2], pa.uint32()),
+        "clock_phase": (names, None),
+        "ball_updated": plain([True, False, True], pa.bool_()),
+        "car_0_updated": plain([True, None, False], pa.bool_()),
+    })
+    a = replicar.read(path).arrays()
+    assert list(a["clock_phase"]) == ["running", "", "kickoff"]
+    assert a["ball_updated"].dtype == bool
+    np.testing.assert_array_equal(a["car_updated"][:, 0], [1, -1, 0])
+
+
+def test_records_are_one_row_per_record_with_their_frame(tmp_path):
+    path = tmp_path / "r.parquet"
+    event = pa.struct([("kind", pa.string()), ("scoring_team", pa.uint8())])
+    events = pa.array([[], [{"kind": "goal", "scoring_team": 1}, {"kind": "goal", "scoring_team": 0}], []],
+                      pa.list_(event))
+    write(path, {"frame": plain([5, 6, 7], pa.uint32()), "events": (events, None)})
+    f = replicar.read(path)
+    assert "events" not in f.arrays()
+    records = f.records("events").to_pylist()
+    assert records == [{"frame": 6, "kind": "goal", "scoring_team": 1},
+                       {"frame": 6, "kind": "goal", "scoring_team": 0}]
+
+
+def test_other_files_are_refused(tmp_path):
+    path = tmp_path / "plain.parquet"
+    pq.write_table(pa.table({"a": [1]}), path)
+    with pytest.raises(ValueError, match="not a replicar file"):
+        replicar.read(path)
+    later = tmp_path / "later.parquet"
+    write(later, {"frame": plain([0], pa.uint32())}, header={"format_version": 99})
+    with pytest.raises(ValueError, match="format version 99"):
+        replicar.read(later)
+
+
+def test_a_file_without_states_needs_the_native_extra(tmp_path, monkeypatch):
+    import sys
+    monkeypatch.setitem(sys.modules, "replicar_native", None)
+    path = tmp_path / "s.parquet"
+    write(path, {"frame": plain([0], pa.uint32())}, header={"groups": ["game", "resimulation"]})
+    with pytest.raises(ImportError, match="native extra"):
+        replicar.read(path, replay="x.replay")
+
+
+def test_players_table_and_long_views(tmp_path):
+    path = tmp_path / "p.parquet"
+    write(path, {
+        "frame": plain([3, 4], pa.uint32()),
+        "car_0_boost": plain([10.0, 20.0], pa.float32()),
+        "car_1_boost": plain([30.0, None], pa.float32()),
+        "pad_0_cooldown": plain([0.0, 1.0], pa.float32()),
+    }, header={"players": [
+        {"index": 0, "name": "a", "team": 0, "hitbox": "octane", "key": "k0", "final_stats": {"goal": 2}},
+        {"index": 1, "name": "b", "team": 1, "hitbox": "dominus", "key": "k1", "final_stats": {"save": 1}},
+    ]})
+    f = replicar.read(path)
+    players = f.players_table().to_pylist()
+    assert players[0]["name"] == "a" and players[0]["final_goal"] == 2 and players[0]["final_save"] is None
+    assert players[1]["final_save"] == 1
+    long = f.long("car").to_pylist()
+    assert [(r["frame"], r["player"], r["car_boost"]) for r in long] == [(3, 0, 10.0), (3, 1, 30.0), (4, 0, 20.0),
+                                                                         (4, 1, None)]

replicar-2.0.4/tests/test_rocketsim.py

@@ -0,0 +1,77 @@
+"""Tests of `replicar.rocketsim`: the rotation without the bindings, and a real file with them (skipped without the
+`rocketsim` package, `collision_meshes/` or `target/sample/match-default.parquet` at the repository root)."""
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+import replicar
+import replicar.rocketsim as bridge
+
+ROOT = Path(__file__).resolve().parents[3]
+SAMPLE = ROOT / "target" / "sample" / "match-default.parquet"
+MESHES = ROOT / "collision_meshes"
+
+
+def test_a_quaternion_becomes_rows_forward_right_up():
+    fake = SimpleNamespace(RotMat=lambda *values: np.array(values).reshape(3, 3))
+    # A quarter turn left about z: forward is +y, right is -x, up stays +z.
+    s = np.sqrt(0.5)
+    rows = bridge._rot_mat(fake, np.array([0.0, 0.0, s, s]))
+    np.testing.assert_allclose(rows, [[0, 1, 0], [-1, 0, 0], [0, 0, 1]], atol=1e-6)
+    np.testing.assert_allclose(bridge._rot_mat(fake, np.array([0.0, 0.0, 0.0, 1.0])), np.eye(3))
+
+
+@pytest.fixture(scope="module")
+def sample():
+    rs = pytest.importorskip("RocketSim")
+    if not SAMPLE.exists() or not MESHES.exists():
+        pytest.skip("no sample file or collision meshes")
+    rs.init(str(MESHES))
+    return rs, replicar.read(SAMPLE)
+
+
+def test_a_row_restores_into_an_arena_and_steps_like_the_file(sample):
+    rs, f = sample
+    a = f.arrays()
+    row = int(np.flatnonzero((a["segment"][:-1] >= 0) & (a["segment"][:-1] == a["segment"][1:]))[200])
+    arena, cars = bridge.arena(f, row)
+    assert sorted(cars) == [p["index"] for p in f.players if bridge.has_car(f, row, p["index"])]
+    ball = arena.ball.get_state()
+    np.testing.assert_allclose([ball.pos.x, ball.pos.y, ball.pos.z], a["ball_position"][row], atol=1e-3)
+    for p, car in cars.items():
+        s = car.get_state()
+        np.testing.assert_allclose([s.pos.x, s.pos.y, s.pos.z], a["car_position"][row, p], atol=1e-3)
+        assert car.team == (rs.Team.BLUE if f.players[p]["team"] == 0 else rs.Team.ORANGE)
+    cooldowns = sorted(pad.get_state().cooldown for pad in arena.get_boost_pads())
+    np.testing.assert_allclose(cooldowns, sorted(a["pad_cooldown"][row]), atol=1e-4)
+    # One frame ahead the ball is where the file has it, unless the next row updated it.
+    arena.step(int(a["sim_tick"][row + 1] - a["sim_tick"][row]))
+    if a["ball_updated"][row + 1] != 1:
+        ball = arena.ball.get_state()
+        np.testing.assert_allclose([ball.pos.x, ball.pos.y, ball.pos.z], a["ball_position"][row + 1], atol=0.5)
+
+
+def test_a_row_as_an_rlgym_game_state_restores_through_the_engine(sample):
+    pytest.importorskip("rlgym.rocket_league")
+    from rlgym.rocket_league.sim import RocketSimEngine
+
+    import replicar.rlgym
+
+    _, f = sample
+    a = f.arrays()
+    row = int(np.flatnonzero(a["segment"] >= 0)[300])
+    state = replicar.rlgym.game_state(f, row, agent_ids={p["index"]: p["name"] for p in f.players})
+    assert set(state.cars) == {p["name"] for p in f.players if bridge.has_car(f, row, p["index"])}
+    out = RocketSimEngine(rlbot_delay=False).set_state(state, {})
+    np.testing.assert_allclose(out.ball.position, a["ball_position"][row], atol=1e-3)
+    for p in f.players:
+        if p["name"] in out.cars:
+            car = out.cars[p["name"]]
+            np.testing.assert_allclose(car.physics.position, a["car_position"][row, p["index"]], atol=1e-3)
+            np.testing.assert_allclose(car.physics.rotation_mtx, state.cars[p["name"]].physics.rotation_mtx, atol=1e-5)
+    # The engine indexes pads in its arena's order; the timers come back where they were put.
+    np.testing.assert_allclose(out.boost_pad_timers, state.boost_pad_timers, atol=1e-5)
+    assert sorted(state.boost_pad_timers) == pytest.approx(sorted(np.maximum(a["pad_cooldown"][row], 0)), abs=1e-5)