BallSimParams

Overview

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

Constructors

new

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

Parameters

Return

BallSimParams	생성된 BallSimParams입니다.

Code Samples

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(분당 회전수) 단위로 지정합니다(-1200012000). 절댓값이 클수록 마그누스 힘이 커지며, 부호는 스핀 축을 기준으로 회전 방향을 결정합니다. 예: MLB 포심 패스트볼 22002600 RPM, 커브볼 25003200 RPM, 너클볼 100 RPM 미만, 골프 웨지 800012000 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.00.1). 값이 0이면 마그누스 효과가 발생하지 않으며, 값이 커질수록 스핀에 의한 궤적의 휘어짐이 강해집니다. 축구공이나 골프공 수준의 자연스러운 효과는 대략 0.010.015 부근이며, 0.1에 가까운 값은 매우 과장된 효과를 만듭니다.

Code Samples

StepsPerSecond

number

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

Code Samples

Methods

Events

See also

SimulationBall