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

# 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

```lua
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

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