# 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 ### new Creates a new BallSimParams instance. #### Parameters #### Return | `BallSimParams` | The created BallSimParams. | | --------------- | -------------------------- | #### Code Samples ## Properties ### 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 ``` ### DampingAngular `number` Angular damping coefficient. Controls how much the rotation gradually decreases. #### Code Samples ```lua local Params = BallSimParams.new() Params.DampingAngular = 0.03 ``` ### DampingLinear `number` Linear damping coefficient. Gradually reduces velocity due to air resistance, etc. #### Code Samples ```lua local Params = BallSimParams.new() Params.DampingLinear = 0.02 ``` ### 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 ``` ### EnableGravityFalloff `boolean` Whether to enable gravity reduction based on altitude. #### Code Samples ```lua local Params = BallSimParams.new() Params.EnableGravityFalloff = true ``` ### Friction `number` Friction coefficient. Affects velocity damping/rotation upon surface contact. #### Code Samples ```lua local Params = BallSimParams.new() Params.Friction = 0.4 ``` ### 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) ``` ### GravityFalloffEndHeight `number` Height threshold where gravity reduction ends and reaches minimum gravity. #### Code Samples ```lua local Params = BallSimParams.new() Params.GravityFalloffEndHeight = 1000 ``` ### 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 ``` ### 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)) ``` ### 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 ``` ### 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) ``` ### 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) ``` ### 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 ``` ### 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 ``` ### 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 ``` ### 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 ``` ## Methods ## Events ## See also {% content-ref url="/pages/ZaoG57umzS7C4yIBXybF" %} [SimulationBall](/development/api-reference/classes/simulationball.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.overdare.com/development/api-reference/datatype/ballsimparams.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.