# BallSnapshot

## Overview

`BallSnapshot`는 특정 시뮬레이션 시점의 공 상태를 캡처한 데이터 타입입니다. 자세(`CFrame`), 진행 방향(`Vector3`), 속도(`number`)와 함께, 충돌 이력 인덱스 및 스핀(축/속도) 정보를 포함합니다. 궤적 재구성, 디버깅, 하이라이트 생성, 리플레이 등에서 한 프레임의 공 상태를 조회할 때 사용됩니다.

## Constructors

스크립트에서 직접 생성하지 않습니다. 일반적으로 시뮬레이터/엔진 API가 스냅샷을 반환합니다(예: 내부 시뮬레이션 컴포넌트에서 시점별 `BallSnapshot` 제공).

## Properties

### CFrame

`CFrame`

스냅샷 시점의 공 위치와 자세(회전)입니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("CFrame:", Snapshot.CFrame)
```

### Direction

`Vector3`

스냅샷 시점의 진행 방향 단위 벡터입니다. 속도 크기와 곱해 선속도를 유도할 수 있습니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Direction:", Snapshot.Direction)
```

### Speed

`number`

스냅샷 시점의 속도 크기입니다. 단위는 cm/s 입니다. (100 cm/s = 3.6 km/h)

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Speed (cm/s):", Snapshot.Speed)
```

### hitCount

`number`

현재까지 발생한 충돌 횟수입니다. 필드명은 소문자 시작(`hitCount`)을 그대로 사용합니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Hit count:", Snapshot.hitCount)
```

### HitStartIndex

`number`

충돌 이력에서 현재 구간의 시작 인덱스입니다. 리플레이/이벤트 구간 분할에 사용할 수 있습니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Hit start index:", Snapshot.HitStartIndex)
```

### HitLastIndex

`number`

충돌 이력에서 현재까지의 마지막 인덱스입니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Hit last index:", Snapshot.HitLastIndex)
```

### SpinAxis

`Vector3`

스냅샷 시점의 회전 축(단위 벡터)입니다. 마그누스 효과 방향과 회전 상태 분석에 활용됩니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Spin axis:", Snapshot.SpinAxis)
```

### SpinSpeed

`number`

스냅샷 시점의 각속도 크기(rad/s)입니다.

#### Code Samples

```lua
local Snapshot = Snapshot -- 시뮬레이터에서 얻은 BallSnapshot
print("Spin speed (rad/s):", Snapshot.SpinSpeed)
```

## Methods

현재 외부에 노출되는 메서드는 없습니다.

## See also

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