# BallSimParams

## Overview

`BallSimParams` is a data type that contains the initial state and physics parameters required for ball simulation. It includes properties such as mass, initial posture (`CFrame`), initial velocity and rotation, number of simulation steps, delta time, and physics coefficients like gravity, damping, restitution, and friction. It also provides options and thresholds to control gravity reduction based on altitude, allowing for realistic projectile or Magnus effect simulations. This type is passed to simulators/components to calculate the ball's trajectory and interactions.

## Constructors

This type is generally used as a parameter object in the simulator API. You do not need to call the constructor directly in scripts, but rather set the property values according to the format required by the engine/service.

## Properties

### Mass

`number`

Mass of the ball (equivalent to kg). Affects collision response and acceleration calculations.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.Mass = 0.43 -- Approx. standard soccer ball mass (kg)
```

### InitialCFrame

`CFrame`

The ball's position and posture at the start of the simulation.

#### Code Samples

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

### InitialVelocity

`Vector3`

Linear velocity vector at the start moment (cm/s).

#### Code Samples

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

### InitialSpinAxis

`Vector3`

Unit vector of the rotation axis at the start moment. Determines the direction of the Magnus effect.

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialSpinAxis = Vector3.new(0, 1, 0) -- Upward axis
```

### InitialSpinSpeed

`number`

Magnitude of angular velocity at the start moment (rad/s).

#### Code Samples

```lua
local Params = BallSimParams.new()
Params.InitialSpinSpeed = 40 -- Example of a spin kick
```

### Simsteps

`number`

Number of internal integration steps for the simulation. Higher values are more precise but increase cost.

#### Code Samples

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

### DeltaTime

`number`

Time interval per step (seconds). Together with `Simsteps`, it determines the total simulation time and precision.

#### Code Samples

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

### Gravity

`Vector3`

Base gravity acceleration vector (cm/s^2). Typically `Vector3.new(0, -980, 0)`.

#### Code Samples

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

### DampingLinear

`number`

Linear damping coefficient. Gradually reduces velocity due to air resistance, etc.

#### Code Samples

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

### DampingAngular

`number`

Angular damping coefficient. Controls how much the rotation gradually decreases.

#### Code Samples

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

### Restitution

`number`

Restitution coefficient (0–1). Represents the degree of energy conservation upon bounce.

#### Code Samples

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

### Friction

`number`

Friction coefficient. Affects velocity damping/rotation upon surface contact.

#### Code Samples

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

### SpinMagnusWeight

`number`

Weight of the Magnus force due to spin. Larger values result in greater trajectory deviation due to spin.

#### Code Samples

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

### BaseGravity

`number`

Base gravity magnitude near the ground (cm/s^2). Used when gravity falloff based on altitude is disabled.

#### Code Samples

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

### EnableGravityFalloff

`boolean`

Whether to enable gravity reduction based on altitude.

#### Code Samples

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

### MinFalloffGravity

`number`

Minimum gravity to maintain in the reduced state (cm/s^2). Applied at very high altitudes.

#### Code Samples

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

### GravityFalloffStartHeight

`number`

Height threshold where gravity reduction begins (Unit: Y of the corresponding world coordinate system or per engine convention).

#### Code Samples

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

### GravityFalloffEndHeight

`number`

Height threshold where gravity reduction ends and reaches minimum gravity.

#### Code Samples

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

## Methods

There are currently no methods exposed externally.

## See also

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