This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

engine.physics 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.

Physics Class

Members


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.

float engine.physics.getAngularDamping()

Returns the current angular damping value.

Return value

Angular damping.

Body engine.physics.getBody(int id)

Returns a body with a given ID.

Arguments

  • int id - Body ID.

Return value

Body with a given ID or NULL (0), if there is no body with a given ID.

int engine.physics.isBody(int id)

Checks if a body with a given ID exists.

Arguments

  • int id - Body ID.

Return value

1 if a body with a given ID exists; otherwise, 0.

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.

void engine.physics.setBudget(float budget)

Sets the physics simulation budget in seconds. Physics isn't simulated when time is out of the budget.

Arguments

  • float budget - The budget value in seconds. The default value is 1/20.

float engine.physics.getBudget()

Returns the physics simulation budget. Physics isn't simulated when time is out of the budget.

Return value

The budget value in seconds.

void engine.physics.setData(string data)

Updates user data associated with the physics. This string is written directly into a *.world file. Namely, into the data child tag of the physics tag, for example:
Source code (XML)
<world version="1.21">
	<physics>
		<data>User data</data>
	</physics>
</world>

Arguments

  • string data - User data. Data can contain an XML formatted string.

string engine.physics.getData()

Returns user data associated with the physics. This string is written directly into a *.world file. Namely, into the data child tag of the physics tag, for example:
Source code (XML)
<world version="1.21">
	<physics>
		<data>User data</data>
	</physics>
</world>

Return value

User data. Data can contain an XML formatted string.

void engine.physics.setDistance(float distance)

Updates a distance after which the physics will not be simulated.

Arguments

  • float distance - Distance in units.

float engine.physics.getDistance()

Returns a distance after which the physics will not be simulated.

Return value

Distance in units.

void engine.physics.setEnabled(int enable)

Enables or disables physics simulation.

Arguments

  • int enable - Positive number to enable physics, 0 to disable it.

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.

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.

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.getFrame()

Returns the current frame of physics update.

Return value

Frame number.

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.

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).

Return value

"Freeze" angular velocity.

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.

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).

Return value

"Freeze" linear velocity.

void engine.physics.setGravity(vec3 gravity)

Updates the current gravity value.

Arguments

  • vec3 gravity - New gravity.

vec3 engine.physics.getGravity()

Returns the current gravity value.

Return value

Gravity.

void engine.physics.setIFps(float ifps)

Updates a frame duration. In fact, this function updates the FPS count used to calculate physics.

Arguments

  • float ifps - Frame duration (1/FPS).

float engine.physics.getIFps()

Returns a physics frame duration.

Return value

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.

Joint engine.physics.getJoint(int id)

Returns a joint with a given ID.

Arguments

  • int id - Joint ID.

Return value

Joint with a given ID or NULL (0), if there is no joint with a given ID.

int engine.physics.isJoint(int id)

Checks if a joint with a given ID exists.

Arguments

  • int id - Joint ID.

Return value

1 if a joint with a given ID exists; otherwise, 0.

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.

float engine.physics.getLinearDamping()

Returns the current linear damping value.

Return value

Linear damping.

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.

float engine.physics.getMaxAngularVelocity()

Returns the current maximum possible angular velocity.

Return value

Maximum possible angular velocity.

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.

float engine.physics.getMaxLinearVelocity()

Returns the current maximum possible linear velocity.

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.

void engine.physics.setNumFrozenFrames(int frames)

Updates the number of frames, during which an object should keep certain angular and linear velocities to become frozen.

Arguments

  • int frames - Number of frames. If a non-positive value is provided, 1 will be used instead.

int engine.physics.getNumFrozenFrames()

Returns the current number of frames, during which an object should keep certain angular and linear velocities to become frozen.

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.

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.

int engine.physics.getNumIterations()

Returns the current number of iterations used to solve contacts and constraints.

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.

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].

float engine.physics.getPenetrationFactor()

Returns a penalty force factor. 0 means no penalty force in contacts. The maximum value is 1.

Return value

Current penetration factor.

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.

float engine.physics.getPenetrationTolerance()

Returns a value indicating how deeply one object can penetrate another.

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.

void engine.physics.setScale(float scale)

Updates a value that is used to scale a frame duration. The provided value is saturated in the range [0;16].

Arguments

  • float scale - Scaling factor.

float engine.physics.getScale()

Returns a value used to scale a frame duration.

Return value

Value to scale the frame duration.

Shape engine.physics.getShape(int id)

Returns a shape with a given ID.

Arguments

  • int id - Shape ID.

Return value

Shape with a given ID or NULL (0), if there is no shape with a given ID.

int engine.physics.isShape(int id)

Checks if a shape with a given ID exists

Arguments

  • int id - Shape ID.

Return value

1 if a shape with a given ID exists; otherwise, 0.

float engine.physics.getSimulationTime()

Returns the duration of all of the simulation phases added together.

Return value

A simulation phases duration value, milliseconds.

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.

int engine.physics.isStable()

Returns a value that indicates if objects are updated in a definite order or not.

Return value

1 if the objects are updated in a definite order; otherwise 0.

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 frame rate. It allows to control the starting point for physics simulation.

Example code:

Source code (UnigineScript)
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));
}
In the example, ifps is the time between frames of the renderer.

Arguments

  • float time - Time to continue updating physics in seconds.

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.

void engine.physics.addUpdateNode(Node node)

Adds the node for 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.

int engine.physics.loadSettings(string name)

Loads physics settings from a given file.

Arguments

  • string name - Path to an XML file with desired settings.

Return value

1 if the settings are loaded successfully; otherwise, 0.

int engine.physics.loadWorld(Xml xml)

Loads physics settings from the given Xml node.

Arguments

  • Xml xml - Xml node.

Return value

1 if 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.restoreState(Stream stream)

Restores physics settings from the stream.
Warning
This function is deprecated and will be removed in the next release.

Arguments

  • Stream stream - Stream to restore settings from.

Return value

1 if settings are 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 name, int force = 0)

Saves the current physics settings to a given file.

Arguments

  • string name - Path to a target file.
  • int force - Forced saving of physics settings.

Return value

1 if the settings are saved successfully; otherwise, 0.

int engine.physics.saveState(Stream stream)

Saves physics settings into the stream.
Warning
This function is deprecated and will be removed in the next release.

Arguments

  • Stream stream - Stream to save settings into.

Return value

1 if settings are saved successfully; otherwise, 0.

int engine.physics.saveWorld(Xml xml, int force = 0)

Saves the current physics settings into the given Xml node.

Arguments

  • Xml xml - Xml node.
  • int force - Forced saving of physics settings.

Return value

1 if settings are saved successfully; otherwise, 0.
Last update: 2017-07-03
Build: ()