engine.physics Functions
This set of functions controls the simulation of physics. For more information on principles and implementation of physics in real-time rendering, see the articles Execution Sequence, Physics and Simulation of Physics.
void engine.physics.addUpdateNode (Node node)
Adds the node which physical state should be updated. If a node is not added with this function, it won't be updated when out of physics simulation distance.Arguments
- Node node - Node to be updated.
void engine.physics.addUpdateNodes (int id)
Adds multiple nodes which physical state should be updated. If nodes are not added with this function, they won't be updated when out of physics simulation distance.Arguments
- int id - Nodes array ID.
float engine.physics.getAngularDamping ()
Returns the current angular damping value. The default is 0.01.Return value
Angular damping.Body engine.physics.getBody (int id)
Returns a body instance by its ID.Arguments
- int id - Body ID.
Return value
The body instance.float engine.physics.getBroadTime ()
Returns the duration of the broad phase, during which potentially colliding objects are found.Return value
The broad phase duration value, milliseconds.float engine.physics.getBudget ()
Returns the physic simulation budget.Return value
The budget value in milliseconds.float engine.physics.getDistance ()
Returns a distance after which the physics will not be simulated.Return value
Distance in units.int engine.physics.getFrame ()
Returns the current frame of physics update.Return value
Frame number.float engine.physics.getFrozenAngularVelocity ()
Returns the current angular velocity threshold for freezing object simulation. An object stops to be updated if its angular velocity remains lower than this threshold during the number of Frozen frames (together with linear one). The default is 0.01.Return value
"Freeze" angular velocity.float engine.physics.getFrozenLinearVelocity ()
Returns the current linear velocity threshold for freezing object simulation. An object stops to be updated if its linear velocity remains lower than this threshold during the number of Frozen frames (together with angular one). The default is 0.01.Return value
"Freeze" linear velocity.vec3 engine.physics.getGravity ()
Returns the current gravity value. The default is (0.0, 0.0, -9.8).Return value
Gravity.float engine.physics.getIFps ()
Returns a physics frame duration. The default is 1/60.Return value
Inverse frame duration (1 / FPS).float engine.physics.getIntegrateTime ()
Returns the duration of the integrate phase, in which physics simulation results are applied to bodies.Return value
An integrate phase duration value, milliseconds.Object engine.physics.getIntersection (vec3 p0, vec3 p1, int mask, int ret_id)
Performs tracing from the point p0 to the point p1 to find an Object located on that line. If an object is assigned a Body, intersection occurs with its Shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag. Intersection is found only for objects with a matching mask.World space coordinates are used for this function.
Arguments
- vec3 p0 - Source point.
- vec3 p1 - Destination point.
- int mask - Intersection mask.
- int ret_id - Return array, its components are:
- ret[0]: intersection point (vec3), in the world coordinates.
- ret[1]: normal of the intersection point (vec3).
- ret[2]: surface number.
- ret[3]: object shape.
Return value
Reference to the first crossed object or NULL (0), if no object is crossed.Joint engine.physics.getJoint (int num)
Returns a joint by its ID.Arguments
- int num - Joint ID.
Return value
The joint.float engine.physics.getLinearDamping ()
Returns the current linear damping value. The default is 0.01.Return value
Linear damping.float engine.physics.getMaxAngularVelocity ()
Returns the current maximum possible angular velocity. The default is infinity.Return value
Maximum possible angular velocity.float engine.physics.getMaxLinearVelocity ()
Returns the current maximum possible linear velocity. The default is infinity.Return value
Maximum possible linear velocity.float engine.physics.getNarrowTime ()
Returns the duration of the narrow phase, during which exact collision tests are performed.Return value
The narrow phase duration value, milliseconds.int engine.physics.getNumBodies ()
Returns the number of bodies present within the physics radius.Return value
The number of bodies.int engine.physics.getNumContacts ()
Returns the number of contacts within the physics radius; it includes contacts between the bodies (their shapes) and body-mesh contacts.Return value
The number of contacts.int engine.physics.getNumFrozenFrames ()
Returns the current number of frames, during which an object should keep certain angular and linear velocities to become frozen. The default is 4.Return value
Number of frames.int engine.physics.getNumIslands ()
Returns the number of physical islands within the physics radius that could be calculated separately. The lower this number, the less efficient multi-threading is, if enabled.Return value
The number of physical islands.int engine.physics.getNumIterations ()
Returns the current number of iterations used to solve contacts and constraints. The default is 4.Return value
Current number of iterations.int engine.physics.getNumJoints ()
Returns the number of joints within the physics radius.Return value
The number of joints.float engine.physics.getPenetrationFactor ()
Returns a penalty force factor. 0 means no penalty force in contacts. The maximum value is 1. The default is 0.1.Return value
Current penetration factor.float engine.physics.getPenetrationTolerance ()
Returns a value indicating how deeply one object can penetrate another. The default is 0.01.Return value
Current penetration tolerance.float engine.physics.getResponseTime ()
Returns the duration value of the response phase, in which collision response is calculated and joints are solved.Return value
A response phase duration value, milliseconds.float engine.physics.getScale ()
Returns a value used to scale a frame duration. The default is 1.Return value
Value to scale the frame duration.Shape engine.physics.getShape (int num)
Returns a shape by its ID.Arguments
- int num - Shape ID.
Return value
The shape.float engine.physics.getSimulationTime ()
Returns the duration of all of the simulation phases added together.Return value
A simulation phases duration value, milliseconds.float engine.physics.getTime ()
Returns the current time that can be used when shifting between physics update frames.Return value
Time in seconds.float engine.physics.getTotalTime ()
Returns the total time that both rendering and calculating of the frame took (the duration of the main loop in the application execution sequence).Return value
The total time value, milliseconds.float engine.physics.getUpdateTime ()
Returns the duration of the update phase, during which the objects are prepared for their collision response to be calculated.Return value
The update phase duration value, milliseconds.int engine.physics.isBody (variable v)
Checks a given body for validity. Either a body itself can be passed or the body ID.Arguments
- variable v - A body or its ID.
Return value
1 if the variable holds a valid Body instance; otherwise, 0.int engine.physics.isEnabled ()
Returns a value indicating if physics simulation is enabled. The default is 1.Return value
1 if physics is enabled; otherwise, 0.int engine.physics.isFixed ()
Returns a flag indicating if rendering FPS is synchronized to physics one. Such FPS limitation allows to calculate physics each rendered frame (rather then interpolate it when this flag is set to 0). In this mode, there are no twitching of physical objects if they have non-linear velocities. (If the rendering FPS is lower than the physics one, this flag has no effect.)Return value
1 to cap rendering FPS to physics one; 0 to interpolate physics if rendering FPS is higher.int engine.physics.isJoint (variable v)
Checks a given joint for validity. Either a joint itself can be passed or the joint ID.Arguments
- variable v - A joint or its ID.
Return value
1 if the variable holds a valid Joint instance; otherwise, 0.int engine.physics.isShape (variable v)
Checks a given shape for validity. Either a shape itself can be passed or the shape ID.Arguments
- variable v - A shape or its ID.
Return value
1 if the variable holds a valid Shape instance; otherwise, 0.int engine.physics.isStable ()
Returns a value that indicates if objects are updated in a definite order or not. The default is 0.Return value
1 if the objects are updated in a definite order; otherwise 0.int engine.physics.loadSettings (string file)
Loads physics settings from a given file.Arguments
- string file - Path to an XML file with desired settings.
Return value
1 if the settings are loaded successfully; otherwise, 0.int engine.physics.removeScene (int id)
Removes the previously saved scene.Arguments
- int id - ID number of the scene.
Return value
1 if the scene was removed successfully; otherwise, 0.int engine.physics.restoreScene (int id)
Restores the previously saved scene.Arguments
- int id - ID number of the scene.
Return value
1 if the scene was restored successfully; otherwise, 0.int engine.physics.saveScene ()
Saves the physical properties of all objects in the scene.Return value
ID number of the saved scene.int engine.physics.saveSettings (string file)
Saves current physics settings to a given file.Arguments
- string file - Path to a target file.
Return value
1 if the settings are saved successfully; otherwise, 0.void engine.physics.setAngularDamping (float damping)
Updates the current angular damping value.Arguments
- float damping - New angular damping. If a negative value is provided, 0 will be used instead.
void engine.physics.setBudget (float budget)
Sets the physic simulation budget in milliseconds.Arguments
- float budget - The budget value.
void engine.physics.setDistance (float distance)
Updates a distance after which the physics will not be simulated.Arguments
- float distance - Distance in units.
void engine.physics.setEnabled (int mode)
Enables or disables physics simulation.Arguments
- int mode - Positive number to enable physics, 0 to disable it.
void engine.physics.setFixed (int fixed)
Sets a flag to synchronize rendering FPS to physics one. Such FPS limitation allows to calculate physics each rendered frame (rather then interpolate it when this flag is set to 0). In this mode, there are no twitching of physical objects if they have non-linear velocities. (If the rendering FPS is lower than the physics one, this flag has no effect.)Arguments
- int fixed - 1 to cap rendering FPS to physics one; 0 to interpolate physics if rendering FPS is higher.
void engine.physics.setFrozenAngularVelocity (float velocity)
Updates the angular velocity threshold for freezing object simulation. If the object angular velocity remains lower than this threshold during the number of Frozen frames (together with linear one), it stops to be updated.Arguments
- float velocity - New "freeze" angular velocity. If a negative value is provided, 0 will be used instead.
void engine.physics.setFrozenLinearVelocity (float velocity)
Updates the linear velocity threshold for freezing object simulation. If the object linear velocity remains lower than this threshold during the number of Frozen frames (together with angular one), it stops to be updated.Arguments
- float velocity - New "freeze" linear velocity. If a negative value is provided, 0 will be used instead.
void engine.physics.setGravity (vec3 gravity)
Updates the current gravity value.Arguments
- vec3 gravity - New gravity.
void engine.physics.setIFps (float time)
Updates a frame duration. In fact, this function updates the FPS count used to calculate physics.Arguments
- float time - Frame duration. The value should be reciprocal, that is (1.0f / frame_duration).
void engine.physics.setLinearDamping (float damping)
Updates the current linear damping value.Arguments
- float damping - New linear damping. If a negative value is provided, 0 will be used instead.
void engine.physics.setMaxAngularVelocity (float velocity)
Updates the maximum possible angular velocity.Arguments
- float velocity - New maximum velocity value. If a negative value is provided, 0 will be used instead.
void engine.physics.setMaxLinearVelocity (float velocity)
Updates the maximum possible linear velocity.Arguments
- float velocity - New maximum velocity value. If a negative value is provided, 0 will be used instead.
void engine.physics.setNumFrozenFrames (int count)
Updates the number of frames, during which an object should keep certain angular and linear velocities to become frozen.Arguments
- int count - Number of frames. If a non-positive value is provided, 1 will be used instead.
void engine.physics.setNumIterations (int iterations)
Updates the number of iterations used to solve contacts and constraints. Note that if this value is too low, the precision of calculations will suffer.Arguments
- int iterations - New number of iterations. If a non-positive value is provided, 1 will be used instead.
void engine.physics.setPenetrationFactor (float factor)
Updates the current penalty force factor.Arguments
- float factor - New penetration factor. 0 means no penalty force in contacts. The provided value is saturated in the range [0; 1].
void engine.physics.setPenetrationTolerance (float tolerance)
Updates the current penetration tolerance.Arguments
- float tolerance - New penetration tolerance. If a negative value is provided, 0 will be used instead, however, this value should be greater than 0 for stable simulation.
void engine.physics.setScale (float factor)
Updates a value that is used to scale a frame duration. The provided value is saturated in the range [0;16].Arguments
- float factor - Scaling factor.
void engine.physics.setStable (int stable)
Sets a value that indicates if objects are updated in a definite order or not.Arguments
- int stable - 1 to indicate that the objects are updated in a definite order; 0 to indicate that an objects update order may change.
void engine.physics.setTime (float time)
Forces simulation of physics for a given time. It means, until the set time elapses, physics will be calculated each physics tick (frame) that occurs depending on physics framerate. It allows to control the starting point for physics simulation.Example code:
Source code
(UnigineScript)
In the example, ifps is the time between frames of the renderer.
int init() {
//to prevent physics from being automatically calculated with each update, set one of the following:
engine.physics.setEnabled(0)
//or
engine.physics.setScale(0)
}
int update() {
//add the time elapsed from the last physics update to the next time count cycle:
engine.physics.setTime(engine.physics.getTime()+ifps));
}
Arguments
- float time - Time to continue updating physics in seconds.
Last update: 2017-07-03
Help improve this article
Was this article helpful?
(or select a word/phrase and press Ctrl+Enter)