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
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
Simulatecall.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Paused
Event called when the simulation is paused. This event occurs when the Pause() method is called.
Parameters
Code Samples
Played
Event called when the simulation starts playing. This event occurs when the Play() method is called.
Parameters
Code Samples
Stopped
Event called when the simulation is stopped. This event occurs when the Stop() method is called.
Parameters
Code Samples
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
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
See also
SimulationBallLast updated