SimulationBall

SimulationBall : PVInstance

Overview

Simulation Ball is a Ball object designed to solve the problem of inaccurate synchronization of the physics engine in games. Traditional physics-based balls had issues where each client rendered the ball at different positions due to server latency effects. However, SimulationBall allows all clients to share the same position, velocity, and rotation based on pre-simulated trajectory data.

By using this method, you can obtain the following advantages:

• Latency Compensation: Maintains the same ball movement regardless of server-client latency.

• High Performance: Improves performance by eliminating frame-by-frame physics calculations.

• Predictable Results: Easily query position, velocity, and rotation at a specific point in time based on simulated results.

• Complex Physics Implementation: Enables implementation of non-linear movements based on rotation, such as the Magnus effect.

Properties

BallCFrame

CFrame

A read-only CFrame representing the actual world position and rotation where the Simulation Ball's collision sphere is currently located. While the CFrame property is used as the launch position (input) for starting a new simulation, BallCFrame represents the actual position/rotation updated every tick during playback.

Note: This value cannot be set directly.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check the actual position of the collision sphere
print("Collision sphere position:", ball.BallCFrame.Position)

BallMeshCollisionProfile

string

Specifies the name of the collision profile applied to the Simulation Ball's mesh component. Setting this value determines how collisions/overlaps with other objects are handled.

Note: This property only affects the actual collision/overlap behavior of the mesh component and does not participate in the trajectory simulation performed by the Simulate call.

Code Samples

BallRadius

number

Specifies the radius of the ball. It determines the physical collision and rendering size used in the simulation, and is used to match the ball's size with collision detection in the actual game. Larger values can affect the calculation of the ball's mass and air resistance.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")
ball.BallRadius =50

BallState

Enum.BallState

Indicates the current state of the Simulation Ball. It can have the following state values:

• Playing (1): The simulation is currently playing.

• Stopped (2): The simulation is stopped.

• Paused (3): The simulation is paused.

This property is read-only, and the state changes via the Play(), Pause(), and Stop() methods.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

if ball.BallState == Enum.BallState.Playing then
    print("The ball is currently playing")
elseif ball.BallState == Enum.BallState.Paused then
    print("The ball is paused")
end

CFrame

CFrame

A CFrame representing the starting position and rotation of the Simulation Ball. It can be changed while the ball is not playing.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set the ball's position to (0, 10, 0)
ball.CFrame = CFrame.new(0, 10, 0)

-- Set the ball's position and rotation together
ball.CFrame = CFrame.new(0, 10, 0) * CFrame.Angles(0, math.rad(45), 0)

Color

Color3

Specifies the color of the ball. This property only controls the visual representation of the ball and does not affect physical movement.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set the ball to red
ball.Color = Color3.new(1, 0, 0)

-- Set the ball to blue
ball.Color = Color3.fromRGB(0, 100, 255)

EnablePathMarker

boolean

Controls the visibility of path markers that visually display the ball's movement trajectory. If set to true, the simulated path of the ball is visually displayed, which is useful for debugging or visualization.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Enable path markers
ball.EnablePathMarker = true

-- Disable path markers
ball.EnablePathMarker = false

Material

Enum.Material

Specifies the surface material of the ball. Visual representation and physical reactions (friction, restitution, etc.) may vary depending on the material.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set the ball to Plastic material
ball.Material = Enum.Material.Plastic

-- Set the ball to Rubber material
ball.Material = Enum.Material.Rubber

MaterialVariant

string

A string specifying a variant of the material. Some materials support multiple variants, and this property allows you to select a specific variant.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set material variant
ball.MaterialVariant = "Smooth"

PathMarkerScale

number

Specifies the size scale of the path markers. Larger values make the path markers appear larger. The default value is 0.2.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Display path markers larger
ball.PathMarkerScale = 0.5

PlaybackTime

number

A read-only property representing the current playback time of the simulation (in seconds). It is the same as the value returned by the GetPlaybackTime() method.

Note: This value is read-only and cannot be assigned directly. To change the playback time, use the SetPlaybackTime() method.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check current playback time
print("Current playback time:", ball.PlaybackTime)

Position

Vector3

Represents the current world position of the Simulation Ball. This value is the same as the current CFrame.Position.

Code Samples

SlomoFactor

number

Specifies the multiplier for the simulation playback speed. 1.0 is normal speed, 0.5 is half speed, and 2.0 is double speed. It can be used to implement slow-motion effects or time-lapses.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Play at half speed
ball.SlomoFactor = 0.5

-- Play at double speed
ball.SlomoFactor = 2.0

StaticObjectTypes

Array

An array of Enum.CollisionChannel values used for collision detection against static objects during the simulation. Collision targets are filtered by object type (ObjectType), and if the array is empty, only the WorldStatic channel is targeted by default.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Limit static object collisions to WorldStatic and WorldDynamic
ball.StaticObjectTypes = {Enum.CollisionChannel.WorldStatic, Enum.CollisionChannel.WorldDynamic}

TextureId

string

The Asset ID of the texture to apply to the ball's surface. This controls only the visual representation and does not affect physical movement. For example, you can express various styles such as soccer balls, basketballs, etc.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set texture
ball.TextureId = "ovdrassetid://123456789"

Transparency

number

Sets the transparency of the ball. 0 is fully opaque and 1 is fully transparent.

Code Samples

Methods

ClearPathMarkers

Removes all path markers generated to visualize the simulated trajectory. Useful for resetting existing markers before displaying a new path.

Parameters

Return

void

Code Samples

FindNextBallBounce

Returns information about the next bounce (collision) that will occur after the current playback time (PlaybackTime). If there is no bounce or if it is a sliding collision, an empty BallBounce object may be returned.

Parameters

Return

BallBounce	A BallBounce object containing information about the next bounce. If there is no bounce, an empty object is returned.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Get next bounce information
local nextBounce = ball:FindNextBallBounce()

if nextBounce.BouncedTime > 0 then
    print("Next bounce time:", nextBounce.BouncedTime)
    print("Bounce position:", nextBounce.BouncedPosition)
end

GetAngularVelocityAtTime

Returns the angular velocity (Vector3) of the ball when a specific time (Time) has elapsed since the simulation started. This value represents the rotation direction and speed of the ball, and can be used for the Magnus effect or rotation-based trajectory prediction.

Parameters

number Time	Time elapsed since the simulation started (in seconds). Queries the ball's angular velocity at the specified point.

Return

Vector3	The angular velocity of the ball at the specified point. Direction represents the axis of rotation, and magnitude represents the angular speed.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query angular velocity after 2 seconds
local angularVelocity = ball:GetAngularVelocityAtTime(2.0)
print("Angular velocity:", angularVelocity)
print("Rotation speed:", angularVelocity.Magnitude)

GetBallBounceByIndex

Returns bounce information corresponding to the specified index. The index represents the order of bounces that occurred during the simulation, starting from 0. If the index is invalid, an empty BallBounce object may be returned.

Parameters

number bounceIndex	The index of the bounce to query. Starts from 0 and represents the sequence of bounces that occurred during the simulation.

Return

BallBounce	A BallBounce object containing bounce information for the specified index.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Get first bounce information
local firstBounce = ball:GetBallBounceByIndex(0)

if firstBounce.BouncedTime > 0 then
    print("First bounce time:", firstBounce.BouncedTime)
    print("Bounce position:", firstBounce.BouncedPosition)
end

GetBestVelocityToTargetAtTime

Calculates the optimal velocity vector that can reach the target position when the ball is launched toward it at the specified playback time. The return value is a vector combining direction and speed (unit: km/h), and the search takes the Magnus effect caused by spin into account to find a combination that can land within the target radius (InTargetRadius). If UseDesiredPitchAngle is set to true, the search is fixed to the launch pitch angle specified in InDesiredPitchAngle; if false, the pitch angle is also searched freely.

Parameters

number InPlaybackTime	Simulation playback time. The launch trajectory is calculated based on the ball's position at this point.
Vector3 InTargetPosition	Target position.
number InDesiredSpeed_Kmh	Launch speed (in km/h).
Vector3 SpinAxis	Rotation axis vector.
number InSpinSpeed_RPM	Rotation speed (in RPM).
number InStepCount	Number of simulation steps used for the search.
number InTargetRadius	Target radius. It is considered a success if reached within this range.
number InMaxSampleCount	Maximum number of samples.
boolean UseDesiredPitchAngle	If true, the search is fixed to the launch pitch angle specified by InDesiredPitchAngle. If false, the pitch angle is also searched freely.
number InDesiredPitchAngle	The fixed launch pitch angle used when UseDesiredPitchAngle is true.

Return

Vector3	The optimal velocity vector to reach the target position. It contains both direction and speed (in km/h).

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")
local targetPosition = Vector3.new(100, 0, 50)

-- Calculate the optimal velocity toward the target at the current playback time
local bestVelocity = ball:GetBestVelocityToTargetAtTime(
    ball.PlaybackTime,
    targetPosition,
    2000,  -- speed (km/h)
    Vector3.new(0, 1, 0),  -- spin axis
    50,  -- spin speed (RPM)
    100,  -- step count
    5,  -- target radius
    100,  -- max sample count
    false,  -- search pitch angle freely
    0  -- unused since UseDesiredPitchAngle is false
)

print("Optimal launch velocity:", bestVelocity)

GetCFrameAtTime

Returns the ball's position and rotation (CFrame) at a specified time (Time) after the simulation starts. This method is useful for obtaining the exact position of the ball at a future or past point in time, and is often used by NPCs or AI to predict the ball's landing spot.

Parameters

number Time	Time elapsed since the simulation started (in seconds). Queries the ball's CFrame at the specified point.

Return

CFrame	The CFrame of the ball at the specified point. You can know the position and rotation values.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query ball position and rotation after 3 seconds
local futureCFrame = ball:GetCFrameAtTime(3.0)
print("Position after 3 seconds:", futureCFrame.Position)

-- AI predicts the ball's landing spot
local landingTime = 5.0
local landingCFrame = ball:GetCFrameAtTime(landingTime)
print("Expected landing spot:", landingCFrame.Position)

GetCurrentPlaybackPosition

Returns the ball's position at the current playback time (PlaybackTime). This method returns the same result as GetCFrameAtTime(ball.PlaybackTime).Position.

Parameters

Return

Vector3	The ball's position at the current playback time.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check current ball position
local currentPosition = ball:GetCurrentPlaybackPosition()
print("Current ball position:", currentPosition)

GetCurrentSnapshotIndex

Returns the index of the snapshot corresponding to the current playback time (PlaybackTime). The snapshot index indicates the position in the snapshot array generated during the simulation.

Parameters

Return

Value	The index of the snapshot corresponding to the current playback time.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check current snapshot index
local snapshotIndex = ball:GetCurrentSnapshotIndex()
print("Current snapshot index:", snapshotIndex)

GetLinearVelocityAtTime

Returns the linear velocity (Vector3) at a specified time (Time) after the simulation starts. It is used when calculating the ball's movement direction and speed, and is utilized for calculating reflection angles upon collision or visualizing the ball's trajectory.

Parameters

number Time	Time elapsed since the simulation started (in seconds). Queries the ball's velocity at the specified point.

Return

Vector3	The ball's velocity at the specified point. Direction represents the movement direction, and magnitude represents the speed.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query velocity after 2 seconds
local velocity = ball:GetLinearVelocityAtTime(2.0)
print("Velocity:", velocity)
print("Speed:", velocity.Magnitude)

GetNextSnapshot

Returns the next BallSnapshot in the cached simulation snapshot array based on the current playback time (PlaybackTime). It does not take a separate time argument and always operates based on the ball's current playback time. If there is no valid next snapshot, an empty BallSnapshot is returned.

Parameters

Return

BallSnapshot	The snapshot following the current playback time. If there is no valid snapshot, an empty object is returned.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query the next snapshot
local nextSnapshot = ball:GetNextSnapshot()
print("Next snapshot position:", nextSnapshot.CFrame.Position)

GetPlaybackTime

Returns the current playback time of the simulation. This value indicates how far the simulation has progressed along the trajectory timeline.

Parameters

Return

number	The current playback time of the simulation (in seconds).

Code Samples

GetPrevSnapshot

Returns the previous BallSnapshot in the cached simulation snapshot array based on the current playback time (PlaybackTime). It does not take a separate time argument and always operates based on the ball's current playback time. If there is no valid previous snapshot, an empty BallSnapshot is returned.

Parameters

Return

BallSnapshot	The snapshot preceding the current playback time. If there is no valid snapshot, an empty object is returned.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query the previous snapshot
local prevSnapshot = ball:GetPrevSnapshot()
print("Previous snapshot position:", prevSnapshot.CFrame.Position)

GetRemainedTimeForNextBounce

Returns the time remaining from the current playback time until the next bounce. If there is no bounce or it is a sliding collision, a very large value (FLT_MAX) is returned.

Parameters

Return

number	Time remaining until the next bounce (in seconds). If there is no bounce, a very large value is returned.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check time remaining until next bounce
local remainingTime = ball:GetRemainedTimeForNextBounce()

if remainingTime < math.huge then
    print("Time remaining until next bounce:", remainingTime, "seconds")
else
    print("No next bounce")
end

GetServerWorldTime

Returns the server's current world time in seconds. If a valid game state (GameState) exists, it returns the world time synchronized with the server; otherwise, it falls back to the local world time. Used in networked environments where time must be synchronized across multiple clients.

Parameters

Return

number	The server's current world time (in seconds).

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check server world time
print("Server world time:", ball:GetServerWorldTime())

GetSpeedAtTime

Returns the scalar speed at a specified time (Time) after the simulation starts. Unlike GetLinearVelocityAtTime, it does not have direction information and simply provides the magnitude of the velocity.

Parameters

number Time	Time elapsed since the simulation started (in seconds). Queries the ball's speed at the specified point.

Return

number	The ball's speed at the specified point.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Query speed after 2 seconds
local speed = ball:GetSpeedAtTime(2.0)
print("Speed after 2 seconds:", speed)

GetStartTime

Returns the time at which the current playback started. This value is recorded based on the server world time when Play() is called, and 0 is returned if playback has not started yet.

Parameters

Return

number	The time at which playback started (server world time, in seconds). Returns 0 if playback has not started yet.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball:Play()

-- Check the server time when playback started
print("Playback start time:", ball:GetStartTime())

IsValidBounceIndex

Checks if the specified index is a valid bounce index. Verifies that the index is within the range of bounces that occurred during the simulation.

Parameters

number bounceIndex	The bounce index to check.

Return

boolean	Returns true if the index is valid, false otherwise.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Check bounce index validity
if ball:IsValidBounceIndex(0) then
    local bounce = ball:GetBallBounceByIndex(0)
    print("First bounce time:", bounce.BouncedTime)
else
    print("Invalid bounce index")
end

Pause

Pauses the currently running simulation. This method can be resumed with Play(), and the time paused is not reflected in the simulation. Used when implementing game pauses or slow-motion effects.

Parameters

Return

void	No return value.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Play simulation
ball:Play()

-- Pause after 2 seconds
wait(2)
ball:Pause()

-- Resume
wait(1)
ball:Play()

Play

Plays simulation data to actually execute the ball's movement. It is played with the same timing and results on all clients, and it is also possible to resume playback after Pause().

Parameters

boolean bReset	Whether to reset the PlaybackTime when playback starts. If omitted, the default value is false.

Return

void	No return value.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Set simulation parameters
local params = BallSimParams.new()
params.InitialCFrame = CFrame.new(0, 10, 0)
params.InitialVelocity = Vector3.new(100, 500, 0)
params.Mass = 0.5

-- Run simulation
ball:Simulate(params)

-- Start playback
ball:Play()

ReSimulateSpinToTargetWithDelay

Performs a resimulation so that the ball heads toward the target position after the specified delay time from the current playback time, using the specified spin axis and spin speed. If UseDesiredSpeed is true, the speed specified in InDesiredSpeed is used as-is and only the direction is calculated; if false, both the speed and direction that can reach the target are searched.

Parameters

number InDelayTime	Delay time from the current playback time (in seconds).
Vector3 InTargetPosition	Target position.
number InDesiredSpeed	Launch speed.
Vector3 InSpinAxis	Rotation axis vector.
number InSpinSpeed	Rotation speed.
number InStepCount	Number of simulation steps.
boolean UseDesiredSpeed	If true, the speed specified by InDesiredSpeed is used as-is. If false, the speed that can reach the target is also searched.

Return

BallSimTargetResult	The resimulation result. Includes whether a trajectory reaching the target was found (bHit), the actual speed (ActualSpeed) and direction (Direction) used, and the time the target is reached (HitTime).

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")
local targetPosition = Vector3.new(100, 0, 50)

-- Resimulate with spin toward the target after 1 second
local result = ball:ReSimulateSpinToTargetWithDelay(
    1.0,  -- after 1 second
    targetPosition,
    2000,  -- speed
    Vector3.new(0, 1, 0),  -- spin axis
    50,  -- spin speed (RPM)
    100,  -- step count
    true  -- use the specified speed as-is
)

if result.bHit then
    print("Hit time:", result.HitTime)
end

ReSimulateToTargetWithDelay

Performs a resimulation so that the ball heads toward the target position after the specified delay time from the current playback time. This method recalculates the trajectory so that the ball heads to the target point at a specific time, and the spin is automatically calculated based on the current angular velocity (if the angular velocity is nearly zero, a minimal spin around an arbitrary axis is applied instead). If UseDesiredSpeed is true, the speed specified in InDesiredSpeed is used as-is and only the direction is calculated; if false, both the speed and direction that can reach the target are searched.

Parameters

number InDelayTime	Delay time from the current playback time (in seconds).
Vector3 InTargetPosition	Target position.
number InDesiredSpeed	Launch speed.
number InStepCount	Number of simulation steps.
boolean UseDesiredSpeed	If true, the speed specified by InDesiredSpeed is used as-is. If false, the speed that can reach the target is also searched.

Return

BallSimTargetResult	The resimulation result. Includes whether a trajectory reaching the target was found (bHit), the actual speed (ActualSpeed) and direction (Direction) used, and the time the target is reached (HitTime).

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")
local targetPosition = Vector3.new(100, 0, 50)

-- Resimulate toward the target after 1 second
local result = ball:ReSimulateToTargetWithDelay(
    1.0,  -- after 1 second
    targetPosition,
    2000,  -- speed
    100,  -- step count
    true  -- use the specified speed as-is
)

if result.bHit then
    print("Hit time:", result.HitTime)
end

ReSimulateWithDelay

Resimulates with the specified direction and velocity after a specified delay time from the current playback time. This method recalculates the ball's trajectory with a new direction and velocity at a specific point in time.

Parameters

number InDelayTime	Delay time from the current playback time (in seconds).
Vector3 InDirection	Launch direction vector.
number InSpeed	Launch speed.
Vector3 InSpinAxis	Rotation axis vector.
number InSpinSpeed	Rotation speed.
number InStepCount	Number of simulation steps.

Return

void

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Resimulate with a new direction after 1 second
ball:ReSimulateWithDelay(
    1.0,  -- after 1 second
    Vector3.new(1, 0, 0),  -- direction
    2000,  -- speed
    Vector3.new(0, 1, 0),  -- spin axis
    50,  -- spin speed
    100  -- step count
)

SetPlaybackTime

Changes the simulation's progress time to an arbitrary point. This allows you to rewind to a specific moment or immediately check the state at a future point. For example, calling SetPlaybackTime(2.5) sets the simulation to a state where 2.5 seconds have progressed. It can also be changed during Play.

Parameters

number InPlaybackTime	Target point in time to move to within the simulation (in seconds). Specify a real number value of 0 or greater, where 0 means the simulation start point.

Return

void

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Run the simulation
ball:Simulate(params)
ball:Play()

-- Move to the 2.5 second mark
ball:SetPlaybackTime(2.5)

-- Check the ball position at that point
local position = ball:GetCurrentPlaybackPosition()
print("Position at 2.5 seconds:", position)

Simulate

Performs the physics simulation of the Simulation Ball and pre-calculates the ball's movement trajectory based on the specified parameters (BallSimParams). If AutoPlay is true, playback starts immediately after the simulation finishes; if false, you must call Play() separately to start playback.

Parameters

BallSimParams InBallSimParams	A physics parameter structure used for the simulation. Contains physical properties such as mass, gravity, initial velocity, spin, damping, and collision characteristics, and the trajectory result varies depending on these values.
boolean AutoPlay	If true, playback starts immediately after the simulation completes. If false, playback starts only when Play() is called.

Return

void

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Create simulation parameters
local params = BallSimParams.new()
params.InitialCFrame = CFrame.new(0, 10, 0)
params.InitialSpeed = 2000
params.InitialDirection = Vector3.new(0, 1, 0)
params.Mass = 0.5
params.InitialSpinAxis = Vector3.new(0, 1, 0)
params.InitialSpinSpeed = 50

-- Run the simulation (start playback separately)
ball:Simulate(params, false)

-- Start playback
ball:Play()

SimulateToTarget

Based on the specified physics parameters (BallSimParams), automatically calculates the optimal launch speed and direction that can reach the target position (InTargetPosition) and runs the simulation. Unlike Simulate(), instead of specifying the initial speed and direction directly, it solves the trajectory backward so that it heads toward the target point. If UseDesiredSpeed is true, the speed specified in InBallSimParams is used as-is and only the direction is calculated; if false, both the speed and direction that can reach the target are searched. If AutoPlay is true, playback starts immediately after the simulation completes; if false, playback starts only when Play() is called separately.

Parameters

BallSimParams InBallSimParams	A physics parameter structure used for the simulation. When UseDesiredSpeed is true, its InitialSpeed value is used as-is as the launch speed.
Vector3 InTargetPosition	Target position.
boolean UseDesiredSpeed	If true, the speed specified in InBallSimParams is used as-is. If false, the speed that can reach the target is also searched.
boolean AutoPlay	If true, playback starts immediately after the simulation completes. If false, playback starts only when Play() is called.

Return

BallSimTargetResult	The simulation result. Includes whether a trajectory reaching the target was found (bHit), the actual speed (ActualSpeed) and direction (Direction) used, and the time the target is reached (HitTime).

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

local params = BallSimParams.new()
params.InitialCFrame = CFrame.new(0, 10, 0)
params.InitialSpeed = 2000
params.Mass = 0.5

local targetPosition = Vector3.new(100, 0, 50)

-- Calculate the velocity toward the target, simulate, and play immediately
local result = ball:SimulateToTarget(params, targetPosition, false, true)

if result.bHit then
    print("Hit time:", result.HitTime)
    print("Actual launch speed:", result.ActualSpeed)
end

Stop

Stops the currently running simulation. Unlike Pause(), it aborts playback, and calling Play() again will replay from the beginning of the simulation.

Parameters

Return

void

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

-- Play the simulation
ball:Play()

-- Stop after 3 seconds
wait(3)
ball:Stop()

-- Replay (from the beginning)
ball:Play()

Events

Bounded

Event called when the Simulation Ball bounces (collision reflection) off another part. Unlike the Touched event, it is called only when a bounce occurs, and sliding collisions are not included.

Parameters

| BasePart otherPart | The part that collided with the ball. |

BallBounce bounce	Information at the moment the ball bounces.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.Bounded:Connect(function(otherPart)
    print("Ball bounced with", otherPart.Name)

    -- Get bounce information
    local bounce = ball:FindNextBallBounce()
    print("Bounce position:", bounce.BouncedPosition)
    print("Velocity after bounce:", bounce.BouncedSpeed)
end)

Paused

Event called when the simulation is paused. This event occurs when the Pause() method is called.

Parameters

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.Paused:Connect(function()
    print("Simulation paused")
end)

ball:Pause()

Played

Event called when the simulation starts playing. This event occurs when the Play() method is called.

Parameters

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.Played:Connect(function()
    print("Simulation started playing")
end)

ball:Play()

Stopped

Event called when the simulation is stopped. This event occurs when the Stop() method is called.

Parameters

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.Stopped:Connect(function()
    print("Simulation stopped")
end)

ball:Stop()

Touched

Event called when the Simulation Ball collides with another part. You can use this event to implement collision-based logic such as goal detection, reflection handling, sound playback, etc.

Parameters

BasePart otherPart	The part that collided with the ball.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.Touched:Connect(function(otherPart)
    print("Ball collided with", otherPart.Name)

    -- Goal detection example
    if otherPart.Name == "Goal" then
        print("Goal!")
    end
end)

TouchEnded

Event called when the Simulation Ball ends contact with another part. Occurs when the ball moves away after colliding with a part.

Parameters

BasePart otherPart	The part that the ball had collided with.

Code Samples

local ball = workspace:FindFirstChild("SimulationBall")

ball.TouchEnded:Connect(function(otherPart)
    print("Ball ended contact with", otherPart.Name)
end)

See also

SimulationBall