> 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/korean/development/api-reference/datatype/ballsimparams.md).

# BallSimParams

## Overview

BallSimParams는 SimulationBall의 초기 발사·물리 조건을 정의하는 데이터 타입입니다. 질량, 초기 속도·방향·스핀, 중력, 마찰·반발·마그누스 힘 등 시뮬레이션에 필요한 물리 파라미터를 담고 있으며, `SimulationBall:Simulate()`, `SimulationBall:SimulateToTarget()` 등 시뮬레이션을 실행하는 메서드에 인자로 전달됩니다.

## Constructors

### new

기본값으로 초기화된 새로운 BallSimParams 인스턴스를 생성하여 반환합니다.

#### Parameters

#### Return

| `BallSimParams` | 생성된 BallSimParams입니다. |
| --------------- | --------------------- |

#### Code Samples

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

## Properties

### BaseGravity

`number`

기준 중력 가속도(cm/s²)를 지정합니다. 지면 근처에서 항상 적용되는 기본 중력 값이며, 지구 표준 중력에 해당하는 기본값은 980입니다.

#### Code Samples

### DampingAngular

`number`

각속도(스핀)에 적용되는 감쇠 계수를 지정합니다. 초당 스핀이 감소하는 비율을 의미하며, 예를 들어 0.05이면 스핀이 초당 5%씩 감소합니다.

#### Code Samples

### DampingLinear

`number`

선속도에 적용되는 공기 저항 계수를 지정합니다. 초당 속도가 감소하는 비율을 의미하며, 예를 들어 0.012이면 속도가 초당 1.2%씩 감소합니다.

#### Code Samples

### EnableGravityFalloff

`boolean`

고도에 따라 중력이 감소하는 기능을 사용할지 여부를 지정합니다. true로 설정하면 MinFalloffGravity, GravityFalloffStartHeight, GravityFalloffEndHeight 값이 함께 적용되어 높이에 따라 중력이 점진적으로 감소합니다.

#### Code Samples

### ForwardSpaceSpinAxis

`boolean`

InitialSpinAxis를 해석하는 기준 좌표계를 지정합니다. true이면 InitialSpinAxis를 발사 방향(Forward) 기준의 로컬 공간으로 해석하여 발사 방향의 Yaw만큼 회전한 뒤 월드 공간으로 변환합니다. false이면 InitialSpinAxis가 이미 월드 공간 값임을 의미하며, 별도 변환 없이 그대로 사용됩니다.

#### Code Samples

### Friction

`number`

지면과의 마찰 계수를 지정합니다(0\~1). 값이 클수록 지면과 접촉했을 때 슬라이딩 속도가 더 빠르게 감소하며, 잔디 기준으로는 약 0.25가 사용됩니다.

#### Code Samples

### GravityFalloffEndHeight

`number`

중력이 MinFalloffGravity까지 감소를 완료하는 높이(cm)를 지정합니다. EnableGravityFalloff가 true일 때만 적용됩니다.

#### Code Samples

### GravityFalloffStartHeight

`number`

중력 감소가 시작되는 높이(cm)를 지정합니다. 이 높이 이하에서는 BaseGravity 값이 그대로 적용됩니다. EnableGravityFalloff가 true일 때만 적용됩니다.

#### Code Samples

### InertiaScale

`number`

구체의 회전 관성 배율을 지정합니다(0.01\~5.0). 관성은 `I = 0.4 × Mass × Radius² × InertiaScale` 공식으로 계산되며, 값이 작을수록 접촉 임펄스에 의해 스핀이 더 쉽게 변화합니다. 기본값 1.0은 균일한 구체의 표준 관성에 해당합니다.

#### Code Samples

### InitialCFrame

`CFrame`

시뮬레이션이 시작되는 CFrame을 지정합니다. 위치는 발사 시작 지점으로 사용되며, 회전은 볼의 초기 회전 상태로 사용됩니다.

#### Code Samples

### InitialDirection

`Vector3`

초기 발사 방향을 월드 공간 단위 벡터로 지정합니다. 값이 영벡터(0, 0, 0)이면 Simulate 호출 시 DirectionArrow의 WorldRotation이 대신 사용됩니다.

#### Code Samples

### InitialSpeed

`number`

초기 발사 속도를 km/h 단위로 지정합니다. BallSimulatorComponent 내부에서 cm/s로 변환되어 사용됩니다.

#### Code Samples

### InitialSpinAxis

`Vector3`

초기 스핀 축을 Lua 좌표계 기준의 단위 벡터로 지정합니다. Lua는 왼손 좌표계를 사용하여 전방 = -Z, 위 = Y, 오른쪽 = X입니다. 예를 들어 백스핀을 표현하려면 (1, 0, 0)을 입력합니다.

#### Code Samples

### InitialSpinSpeed

`number`

초기 스핀 속도를 RPM(분당 회전수) 단위로 지정합니다(-12000~~12000). 절댓값이 클수록 마그누스 힘이 커지며, 부호는 스핀 축을 기준으로 회전 방향을 결정합니다. 예: MLB 포심 패스트볼 2200~~2600 RPM, 커브볼 2500~~3200 RPM, 너클볼 100 RPM 미만, 골프 웨지 8000~~12000 RPM.

#### Code Samples

### Mass

`number`

볼의 질량을 킬로그램(kg) 단위로 지정합니다. 충돌 임펄스 및 회전 관성 계산에 사용되며, 질량이 클수록 선속도와 각속도를 변화시키기 위해 더 큰 힘이 필요합니다. 예: 골프공 약 0.046kg.

#### Code Samples

### MaxSpeedForMagnus

`number`

마그누스 힘 계산에 기여하는 속도의 상한을 km/h 단위로 지정합니다. 실제 기여 속도는 MaxSpeedForMagnus에서 MinSpeedForMagnus를 뺀 범위로 제한되며, BallSimulatorComponent에 전달되기 전 cm/s로 변환됩니다.

#### Code Samples

### MinFalloffGravity

`number`

GravityFalloffEndHeight 이상의 높이에서 유지되는 최소 중력 가속도(cm/s²)를 지정합니다. EnableGravityFalloff가 true일 때만 적용됩니다.

#### Code Samples

### MinSpeedForMagnus

`number`

마그누스 힘 계산에서 기준값으로 차감되는 속도를 km/h 단위로 지정합니다. 이 값을 초과하는 속도 분량만 마그누스 힘에 기여하며, BallSimulatorComponent에 전달되기 전 cm/s로 변환됩니다.

#### Code Samples

### MinSpinForMagnus

`number`

마그누스 힘 계산에서 기준값으로 차감되는 스핀 속도를 rad/s 단위로 지정합니다. 이 값을 초과하는 스핀 분량만 마그누스 힘에 기여합니다.

#### Code Samples

### Restitution

`number`

충돌 시 반발 계수를 지정합니다(0\~1). 1에 가까울수록 완전 탄성 충돌에 가까워지며, 골프공 기준으로는 약 0.68이 사용됩니다.

#### Code Samples

### RollingFriction

`number`

구름 저항 계수(Rolling Resistance Coefficient, Crr)를 지정합니다(0\~1). 지면에 접촉해 구르는 동안 매 스텝마다 중력 가속도의 Crr배만큼 속도가 감소하며, 0이면 이 저항이 비활성화됩니다. 기본값 0.1은 잔디 표면 기준이며, 실내 바닥은 약 0.02가 사용됩니다.

#### Code Samples

### Simsteps

`number`

시뮬레이션이 진행되는 총 스텝 수를 지정합니다(1\~14400). 전체 시뮬레이션 시간은 `TotalTime = Simsteps / StepsPerSecond`로 계산됩니다.

#### Code Samples

### SpinMagnusWeight

`number`

마그누스 횡력의 스케일을 지정합니다(0.0~~0.1). 값이 0이면 마그누스 효과가 발생하지 않으며, 값이 커질수록 스핀에 의한 궤적의 휘어짐이 강해집니다. 축구공이나 골프공 수준의 자연스러운 효과는 대략 0.01~~0.015 부근이며, 0.1에 가까운 값은 매우 과장된 효과를 만듭니다.

#### Code Samples

### StepsPerSecond

`number`

시뮬레이션 주파수를 Hz 단위(초당 시뮬레이션 스텝 수)로 지정합니다(1\~480). 값이 높을수록 정밀해지지만 연산 비용이 증가하며, 시뮬레이션의 시간 간격은 `DeltaTime = 1 / StepsPerSecond`로 계산됩니다.

#### Code Samples

## Methods

## Events

## See also

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