> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/development/api-reference/datatype/ballsnapshot.md).

# 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

## 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)
```

### 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)
```

### 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)
```

### 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)
```

### 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)
```

### 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

## Events

## See also

{% content-ref url="/pages/ZaoG57umzS7C4yIBXybF" %}
[SimulationBall](/development/api-reference/classes/simulationball.md)
{% endcontent-ref %}