# BallSimParams

## Overview

`BallSimParams`는 공 시뮬레이션에 필요한 초기 상태와 물리 파라미터를 담는 데이터 타입입니다. 질량, 초기 자세(`CFrame`), 초기 속도와 회전, 시뮬레이션 스텝 수와 델타 타임, 중력/감쇠/반발/마찰 등의 물리 계수를 포함합니다. 또한 고도에 따른 중력 감소를 제어하는 옵션과 임계값을 제공하여 현실적인 포물선/마그누스 효과 시뮬레이션을 구성할 수 있습니다. 이 타입은 시뮬레이터/컴포넌트에 전달되어 공의 궤적과 상호작용을 계산하는 데 사용됩니다.

## Constructors

이 타입은 일반적으로 시뮬레이터 API에서 파라미터 객체로 사용됩니다. 스크립트에서 직접 생성자를 호출하지 않아도 되며, 엔진/서비스가 요구하는 형태에 맞춰 속성 값을 설정해 사용합니다.

## Properties

### Mass

`number`

공의 질량(kg에 상응). 충돌 반응과 가속도 계산에 영향을 줍니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Mass = 0.43 -- 축구공 표준 질량(kg) 근사
```

### InitialCFrame

`CFrame`

시뮬레이션 시작 시 공의 위치와 자세입니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialCFrame = CFrame.new(Vector3.new(0, 100, 0))
```

### InitialVelocity

`Vector3`

시작 순간의 선속도 벡터(cm/s).

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialVelocity = Vector3.new(0, 800, -3000)
```

### InitialSpinAxis

`Vector3`

시작 순간의 회전 축 단위 벡터. 마그누스 효과 방향을 결정합니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialSpinAxis = Vector3.new(0, 1, 0) -- 위쪽 축
```

### InitialSpinSpeed

`number`

시작 순간의 각속도 크기(rad/s).

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialSpinSpeed = 40 -- 회전 킥 예시
```

### Simsteps

`number`

시뮬레이션 내적 적분 스텝 수. 값이 클수록 정밀하지만 비용이 증가합니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Simsteps = 120
```

### DeltaTime

`number`

스텝당 시간 간격(초). `Simsteps`와 함께 총 시뮬레이션 시간과 정밀도를 결정합니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.DeltaTime = 1.0 / 120.0
```

### Gravity

`Vector3`

기본 중력 가속도 벡터(cm/s^2). 일반적으로 `Vector3.new(0, -980, 0)`을 사용합니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Gravity = Vector3.new(0, -980, 0)
```

### DampingLinear

`number`

선형 감쇠 계수. 공기 저항 등으로 속도를 점진적으로 줄입니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.DampingLinear = 0.02
```

### DampingAngular

`number`

각속도 감쇠 계수. 회전이 점차 줄어드는 정도를 제어합니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.DampingAngular = 0.03
```

### Restitution

`number`

반발 계수(0–1). 바운스 시 에너지 보존 정도를 나타냅니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Restitution = 0.6
```

### Friction

`number`

마찰 계수. 표면과의 접촉 시 속도 감쇠/회전에 영향을 줍니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Friction = 0.4
```

### SpinMagnusWeight

`number`

스핀에 의한 마그누스 힘 가중치. 값이 클수록 스핀에 의한 궤적 편향이 커집니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.SpinMagnusWeight = 1.0
```

### BaseGravity

`number`

지면 근처에서의 기준 중력 크기(cm/s^2). 고도에 따른 중력 감소가 비활성화되었을 때 사용됩니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.BaseGravity = 980
```

### EnableGravityFalloff

`boolean`

고도에 따른 중력 감소 기능 활성화 여부.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.EnableGravityFalloff = true
```

### MinFalloffGravity

`number`

감소된 상태에서 유지할 최소 중력(cm/s^2). 매우 높은 고도에서 적용됩니다.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.MinFalloffGravity = 200
```

### GravityFalloffStartHeight

`number`

중력 감소가 시작되는 높이 기준(단위: 해당 월드 좌표계의 Y 또는 엔진 규약에 따름).

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.GravityFalloffStartHeight = 200
```

### GravityFalloffEndHeight

`number`

중력 감소가 끝나 최소 중력에 도달하는 높이 기준.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.GravityFalloffEndHeight = 1000
```

## Methods

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

## See also

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