# 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 `BallSnapshot`s).

## Properties

### CFrame

`CFrame`

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

#### Code Samples

```lua
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

```lua
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

```lua
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

```lua
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

```lua
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

```lua
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

```lua
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

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

## Methods

There are currently no methods exposed externally.

## See also

{% content-ref url="../classes/simulationball" %}
[simulationball](https://docs.overdare.com/development/api-reference/classes/simulationball)
{% endcontent-ref %}