BallSnapshot

Overview

BallSnapshot is a data type that captures the state of the ball at a specific point in the simulation. It includes posture (CFrame), movement direction (Vector3), speed (number), as well as collision history index and spin (axis/speed) information. It is used to query the state of the ball for a single frame in trajectory reconstruction, debugging, highlight creation, and replays.

Constructors

It is not created directly in scripts. Typically, the simulator/engine API returns a snapshot (e.g., internal simulation components provide time-specific BallSnapshots).

Properties

CFrame

CFrame

The position and posture (rotation) of the ball at the time of the snapshot.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("CFrame:", Snapshot.CFrame)

Direction

Vector3

The unit vector of the movement direction at the time of the snapshot. Can be multiplied by speed magnitude to derive linear velocity.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Direction:", Snapshot.Direction)

Speed

number

The magnitude of the speed at the time of the snapshot. Unit is cm/s. (100 cm/s = 3.6 km/h)

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Speed (cm/s):", Snapshot.Speed)

hitCount

number

The number of collisions that have occurred so far. The field name uses a lowercase start (hitCount).

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Hit count:", Snapshot.hitCount)

HitStartIndex

number

The start index of the current segment in the collision history. Can be used for replay/event segment division.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Hit start index:", Snapshot.HitStartIndex)

HitLastIndex

number

The last index so far in the collision history.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Hit last index:", Snapshot.HitLastIndex)

SpinAxis

Vector3

The rotation axis (unit vector) at the time of the snapshot. Used for analyzing Magnus effect direction and rotation state.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Spin axis:", Snapshot.SpinAxis)

SpinSpeed

number

The magnitude of the angular speed (rad/s) at the time of the snapshot.

Code Samples

local Snapshot = Snapshot -- BallSnapshot obtained from the simulator
print("Spin speed (rad/s):", Snapshot.SpinSpeed)

Methods

There are currently no methods exposed externally.