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

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

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

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

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

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

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

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

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

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

DampingAngular

number

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

Code Samples

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

Restitution

number

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

Code Samples

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

Friction

number

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

Code Samples

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

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

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

EnableGravityFalloff

boolean

Whether to enable gravity reduction based on altitude.

Code Samples

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

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

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

GravityFalloffEndHeight

number

Height threshold where gravity reduction ends and reaches minimum gravity.

Code Samples

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

Methods

There are currently no methods exposed externally.