BallSimParams

Overview

BallSimParams is a data type that defines the initial launch and physics conditions of a SimulationBall. It contains the physics parameters required for the simulation, such as mass, initial speed/direction/spin, gravity, friction, restitution, and Magnus force, and is passed as an argument to simulation-executing methods such as SimulationBall:Simulate() and SimulationBall:SimulateToTarget().

Constructors

new

Creates and returns a new BallSimParams instance initialized with default values.

Parameters

Return

BallSimParams	The created BallSimParams.

Code Samples

local Params = BallSimParams.new()

Properties

BaseGravity

number

Specifies the base gravitational acceleration (cm/s²). This is the default gravity value always applied near the ground; the default value of 980 corresponds to standard Earth gravity.

Code Samples

DampingAngular

number

Specifies the damping coefficient applied to angular velocity (spin). It represents the rate at which the spin decreases per second; for example, a value of 0.05 means the spin decreases by 5% per second.

Code Samples

DampingLinear

number

Specifies the air resistance coefficient applied to linear velocity. It represents the rate at which the speed decreases per second; for example, a value of 0.012 means the speed decreases by 1.2% per second.

Code Samples

EnableGravityFalloff

boolean

Specifies whether to enable gravity reduction based on altitude. When set to true, the MinFalloffGravity, GravityFalloffStartHeight, and GravityFalloffEndHeight values are applied together, causing gravity to gradually decrease with height.

Code Samples

ForwardSpaceSpinAxis

boolean

Specifies the reference coordinate space used to interpret InitialSpinAxis. If true, InitialSpinAxis is interpreted in local space relative to the launch direction (Forward): it is rotated by the yaw of the launch direction and then converted to world space. If false, InitialSpinAxis is treated as an already world-space value and is used as-is without any conversion.

Code Samples

Friction

number

Specifies the friction coefficient against the ground (0–1). Higher values cause the sliding speed to decrease more quickly on ground contact; approximately 0.25 is used for grass.

Code Samples

GravityFalloffEndHeight

number

Specifies the height (cm) at which gravity finishes decreasing down to MinFalloffGravity. Applied only when EnableGravityFalloff is true.

Code Samples

GravityFalloffStartHeight

number

Specifies the height (cm) at which gravity reduction begins. Below this height, the BaseGravity value is applied as-is. Applied only when EnableGravityFalloff is true.

Code Samples

InertiaScale

number

Specifies the rotational inertia scale of the sphere (0.01–5.0). Inertia is calculated using the formula I = 0.4 × Mass × Radius² × InertiaScale; smaller values allow the spin to change more easily from contact impulses. The default value of 1.0 corresponds to the standard inertia of a uniform sphere.

Code Samples

InitialCFrame

CFrame

Specifies the CFrame at which the simulation starts. The position is used as the launch starting point, and the rotation is used as the ball's initial rotation state.

Code Samples

InitialDirection

Vector3

Specifies the initial launch direction as a world-space unit vector. If the value is the zero vector (0, 0, 0), the WorldRotation of the DirectionArrow is used instead when Simulate is called.

Code Samples

InitialSpeed

number

Specifies the initial launch speed in km/h. It is converted to cm/s internally by the BallSimulatorComponent.

Code Samples

InitialSpinAxis

Vector3

Specifies the initial spin axis as a unit vector in the Lua coordinate system. Lua uses a left-handed coordinate system where forward = -Z, up = Y, and right = X. For example, enter (1, 0, 0) to express backspin.

Code Samples

InitialSpinSpeed

number

Specifies the initial spin speed in RPM (revolutions per minute) (-12000–12000). A larger absolute value produces a stronger Magnus force, and the sign determines the rotation direction relative to the spin axis. Examples: MLB four-seam fastball 2200–2600 RPM, curveball 2500–3200 RPM, knuckleball under 100 RPM, golf wedge 8000–12000 RPM.

Code Samples

Mass

number

Specifies the mass of the ball in kilograms (kg). It is used in collision impulse and rotational inertia calculations; the greater the mass, the more force is required to change the linear and angular velocity. Example: a golf ball is approximately 0.046 kg.

Code Samples

MaxSpeedForMagnus

number

Specifies the upper limit, in km/h, of the speed that contributes to the Magnus force calculation. The actual contributing speed is clamped to the range of MaxSpeedForMagnus minus MinSpeedForMagnus, and the value is converted to cm/s before being passed to the BallSimulatorComponent.

Code Samples

MinFalloffGravity

number

Specifies the minimum gravitational acceleration (cm/s²) maintained at heights above GravityFalloffEndHeight. Applied only when EnableGravityFalloff is true.

Code Samples

MinSpeedForMagnus

number

Specifies the speed, in km/h, that is subtracted as a baseline in the Magnus force calculation. Only the portion of speed exceeding this value contributes to the Magnus force, and the value is converted to cm/s before being passed to the BallSimulatorComponent.

Code Samples

MinSpinForMagnus

number

Specifies the spin speed, in rad/s, that is subtracted as a baseline in the Magnus force calculation. Only the portion of spin exceeding this value contributes to the Magnus force.

Code Samples

Restitution

number

Specifies the coefficient of restitution on collision (0–1). The closer the value is to 1, the closer the collision is to perfectly elastic; approximately 0.68 is used for a golf ball.

Code Samples

RollingFriction

number

Specifies the rolling resistance coefficient (Crr) (0–1). While the ball rolls in contact with the ground, its speed decreases by Crr times the gravitational acceleration every step; a value of 0 disables this resistance. The default value of 0.1 is based on a grass surface, and approximately 0.02 is used for indoor floors.

Code Samples

Simsteps

number

Specifies the total number of steps the simulation runs (1–14400). The total simulation time is calculated as TotalTime = Simsteps / StepsPerSecond.

Code Samples

SpinMagnusWeight

number

Specifies the scale of the Magnus lateral force (0.0–0.1). A value of 0 produces no Magnus effect, and larger values result in stronger spin-induced curving of the trajectory. A natural effect at the level of a soccer ball or golf ball is roughly around 0.01–0.015, while values close to 0.1 produce a highly exaggerated effect.

Code Samples

StepsPerSecond

number

Specifies the simulation frequency in Hz (simulation steps per second) (1–480). Higher values increase precision but also computation cost; the simulation time interval is calculated as DeltaTime = 1 / StepsPerSecond.

Code Samples

Methods

Events

See also

SimulationBall