World

---

A world is a container that manages all physics elements of your application. It contains all PhysicObject as well as RigidConstraint and SoftConstraint etc...

The world also allows you to tweak parameters and settings that will have a direct impact on the physics simulation such as gravity, wind, air, water and more.

Other options are available to either increase or decrease the precision of the simulation, speeding it up or slowing it down based on the requirements of your application.

In addition, it also provides debugging functionalities that allows you to visualize a different aspect of the physics simulation such as bounds, constraints, contact points etc...

See Also

PhysicObject, RigidConstraint, SoftBody, RigidBody, SoftConstraint, PhysicMaterial, Collider

Static Variables

---

Name	Description
collisionlayer_count	Total amount of CollisionLayer.
Declaration unsigned char collisionlayer_count

Variables

---

Name	Description
sub_steps	The maximum amount of sub steps per physics pass.
Declaration unsigned char sub_steps Range 0 to 16 Remarks A value of 0 will force the physic engine to run as many passes in order to stay in sync.
fps	Regulate the amount of physics frames per seconds.
Declaration unsigned char fps Range 0 to 120 Note A value of 0 will use the current realtime framerate.
traversal_mode	The type of traversal algorithm used by the physics bounding volume hierarchies (BVH).
Declaration TraversalMode traversal_mode
deactivation_time	The generic deactivation time to use for soft, rigid and dynamic physics expressed in seconds (1.0 = 1sec.).
Declaration float deactivation_time Range 0.0 to 10.0
traversal_mode	The type of traversal algorithm used by the physics bounding volume hierarchies (BVH).
Declaration TraversalMode traversal_mode
contact_breaking_threshold	Minimum threshold used to invalidate a contact point when using relative breaking threshold.
Declaration float contact_breaking_threshold Range 0.0 to 1.0
relative_contact_breaking_threshold	Enable or disable relative contact breaking threshold.
Declaration bool relative_contact_breaking_threshold
tau	Constant spring force to apply on constraints.
Declaration float tau Range 0.0 to 1.0
damping	Default amount of damping applied on constraints.
Declaration float damping Range 0.0 to 1.0
friction	Default amount of friction to use on constraints.
Declaration float friction Range 0.0 to 1.0
restitution	Bounciness factor to apply on constraints.
Declaration float restitution Range 0.0 to 1.0
iterations	Base amounts of iterations to apply on RigidConstraint.
Declaration unsigned char iterations Range 0 to 16
position_iterations	Used by SoftConstraint to smoothly interpolate the positions between nodes.
Declaration unsigned char position_iterations Range 0 to 16
velocity_iterations	Numbers of velocity iterations used by SoftBody aeros.
Declaration unsigned char velocity_iterations Range 0 to 16
erp	Control the ERP used for constraints solving; increase this value to avoid jittering.
Declaration float erp Range 0.0 to 1.0
cfm	Common constant force mixing factor to use for constraints solving.
Declaration float cfm Range 0.0 to 1.0
linear_slop	Additive distance factor used to calculate penetration.
Declaration float linear_slop Range 0.0 to 1.0
warmstart_factor	Value to use in order to warm start constraints solving.
Declaration float warmstart_factor Range 0.0 to 1.0
resting_contact_restitution_frames	Numbers of frames to evaluate to determine if a constraint is resting.
Declaration unsigned char resting_contact_restitution_frames Range 0 to 10
min_batch_size	How many constraints should be solved per batch.
Declaration unsigned short min_batch_size Range 8 to 1024
split_impulse	Enable or disable impulse slplit.
Declaration bool split_impulse Remarks If enabled the impulse will be divided into two linear components, therefore, increasing the fidelity of the resolved data at the cost of a slight CPU overhead.
split_impulse_penetration_threshold	If impulse split is enabled this value controls the penetration threshold value.
Declaration float split_impulse_penetration_threshold Range -2.0 to 2.0
split_impulse_erp	The error reduction parameter used as Baumgarte factor.
Declaration float split_impulse_erp Range 0.0 to 1.0 Note A value of 0.0 represents no correcting force is applied and the bodies will eventually drift apart as the simulation proceeds. A value of 1.0 attempt to fix all joint error during the next time step (not recommended as joint error will never be completely fixed due to approximation. Recommended values are in the range of 0.1 and 0.8.
gravity	Controls the gravity direction vector that will be applied to all PhysicObject, RigidConstraint, SoftConstraint as well as SoftBody contained in the physics World.
Declaration vec3 gravity
air_density	Controls the air density; primarily used by/and to influence lightweight SoftBody and especially aeros.
Declaration float air_density Remarks This value is represented as Kg per m3.
wind_velocity	Wind velocity vector; that affect lightweight SoftBody.
Declaration vec3 wind_velocity
water_density	Represents the density of the water in terms of kilograms per meters cube.
Declaration float water_density
water_normal	A normalized vector that controls the water level direction.
Declaration vec3 water_normal Range -1.0 to 1.0
water_offset	Water level position aligned to the water_normal.
Declaration float water_offset
continuous	Enable or disable continuous collision detection.
Declaration bool continuous
solver_mode	Bit mask of SolverMode flags that controls the behaviors of the constraint solver.
Declaration SolverMode solver_mode
debug_draw	Bit mask of DebugDraw flags that controls physics visual debugging.
Declaration DebugDraw debug_draw

Functions

---

Name	Description
Optimize	Optimize the active World.
Declaration void Optimize( void ) Note This function worth being called when all physics elements are in place; there's no need to call this function every time a resource is added or removed. In addition, take note that the performance gain is substantial.
AddPhysicObject	Add an existing PhysicObject to the current physics World.
Declaration bool AddPhysicObject( PhysicObject *physicobject ) Parameters physicobject: Reference to the PhysicObject to add. Return Value true if the PhysicObject have been integrated successfully; false if the reference is invalid.
RemovePhysicObject	Remove a PhysicObject refrence from the active World.
Declaration bool RemovePhysicObject( PhysicObject *physicobject ) Parameters physicobject: Reference of the PhysicObject to remove. Return Value true if the reference is removed succesfully; else return false if the reference is invalid.
AddCollisionLayer	Function that retrieve the internal index of an existing Sector.
Declaration CollisionLayer *AddCollisionLayer( const char *name, int cap ) Parameters name: Name to identify the CollisionLayer within the active World. cap: Unique cap value to represent the new CollisionLayer using a bit mask; use -1 to let the system assign a unique cap (recommended). Return Value Reference to the newly created CollisionLayer.
GetCollisionLayer	Retrieve an existing CollisionLayer by name.
Declaration CollisionLayer *GetCollisionLayer( const char *name ) Parameters name: Name of the CollisionLayer to retrieve. Return Value nil if no CollisionLayer match the name provided in parameter; else reference to the CollisionLayer that matches the name pass down to the function.
GetCollisionLayerIndex	Return the index of a CollisionLayer reference.
Declaration int GetCollisionLayerIndex( const CollisionLayer *collisionlayer ) Parameters collisionlayer: Reference to the CollisionLayer to retrieve the index. Return Value -1 if the reference is invalid else return the index of the CollisionLayer reference.
SetCollisionLayerIndex	Move a CollisionLayer to a new index.
Declaration bool SetCollisionLayerIndex( CollisionLayer *collisionlayer, unsigned char index ) Parameters collisionlayer: Reference to the CollisionLayer to move. index: Index where to place the reference to. Return Value true if the operation is successfull; false if the index provided does not exists.
RemoveCollisionLayer	Remove a CollisionLayer from the active World.
Declaration bool RemoveCollisionLayer( CollisionLayer *collisionLayer ) Parameters collisionLayer: Reference of the CollisionLayer to remove. Return Value true if the reference have been removed successfully; false if the CollisionLayer reference is invalid.
RemoveCollisionLayerAt	Remove a CollisionLayer using its index as key.
Declaration bool RemoveCollisionLayerAt( int index ) Parameters index: Index of the CollisionLayer to remove. Return Value true if the CollisionLayer have been removed; else return false if the layer index does not exists.
AddRigidConstraint	Add a RigidConstraint to the active physics World.
Declaration bool AddRigidConstraint( RigidConstraint *rigidconstraint ) Parameters rigidconstraint: Reference of the RigidConstraint to append to the current World. Return Value true the RigidConstraint have been added successfully; false if the reference is invalid.
RemoveRigidConstraint	Remove an existing RigidConstraint from the World.
Declaration bool RemoveRigidConstraint( RigidConstraint *rigidconstraint ) Parameters rigidconstraint: Reference of the RigidConstraint to remove. Return Value true if removed; false if the reference is invalid.
AddRigidConstraint	Add a RigidConstraint to the active physics World.
Declaration int GenerateConstraintsFromContacts( const Object *object0, const Object *object1, bool fixed_constraint, float breaking_threshold, float influence, bool static_kinematic ) Parameters object0: Reference to the first Object. object1: Reference to the second Object. fixed_constraint: Generate fixed constraints or generic constraints. breaking_threshold: Amount of impulse that can be applied based on ratio vs the object mass before the constraint breaks. influence: Specify the impulse ratio (vs the Object mass) the constraint(s) will generate. A value of > 1.0 will force the constraint to act as a static anchor that cannot breaks. static_kinematic: Determine wether or not constraints should be generate if one of the object is static or kinematic. Return Value The amount of constraint generated.
PerformDiscreteCollisionDetection	Manually perform a collision detection step.
Declaration void PerformDiscreteCollisionDetection( void ) Warning This function will block the physics thread until the operation is done.
Raycast	Perform a multi-hit raycast operation against all the PhysicObject currently available in the World.
Declaration WorldRay Raycast( const vec3 ray_from, const vec3 ray_to, int collisionlayer_mask, int collisionlayer_filter, bool cull_face ) Parameters ray_from: Starting point of the ray. ray_to: Ending point of the ray. collisionlayer_mask: Bit mask of CollisionLayer caps that represent which layer(s) to include. collisionlayer_filter: Bit mask of CollisionLayer caps specifying which layer(s) can collide. cull_face: Enable back face culling. Return Value The result of the raycast operation store in a WorldRay structure. To ensure that the raycast was successful verify the hit_count property; if the value is set to 0 no-hit occurs. Warning This function will block the physics thread until the operation is done.
SingleRaycast	Perform a single-hit raycast operation (faster) against all the PhysicObject currently available in the World.
Declaration WorldRay SingleRaycast( const vec3 ray_from, const vec3 ray_to, int collisionlayer_mask, int collisionlayer_filter, bool cull_face ) Parameters ray_from: Starting point of the ray. ray_to: Ending point of the ray. collisionlayer_mask: Bit mask of CollisionLayer caps that represent which layer(s) to include. collisionlayer_filter: Bit mask of CollisionLayer caps specifying which layer(s) can collide. cull_face: Enable back face culling. Return Value The result of the raycast operation store in a WorldRay structure. To ensure that the raycast was successful verify the hit_count property; if the value is set to 0 no-hit occurs. Note The main difference between single and multi-hit raycast is that single will return the closest hit while multi will return all hits. Warning This function will block the physics thread until the operation is done.
AddRaycast	Add a new raycast action to the physics pipeline.
Declaration WorldRay *AddRaycast( void ) Return Value Reference to a WorldRay structure that will allow you to control and process raycast queries. Remarks By default raycast queries handles multiple hits; for the closests single hit see AddSingleRaycast.
AddSingleRaycast	Add a new single raycast query to the physics pipeline.
Declaration WorldRay *AddSingleRaycast( void ) Return Value Reference to a WorldRay structure that will allow you to control and process single hit raycast queries.
RemoveRaycast	Remove an existing raycast operation from the physics pipeline.
Declaration WorldRay *RemoveRaycast( WorldRay *worldray ) Return Value Upon success return nil else return back the original worldray reference.
Sync	Resynchronize the physics thread time with the one of the main thread.
Declaration void Sync( void )

WorldRay

---

A structure used to store the result of a World raycast operation.

Static Variables

---

Name	Description
hit_count	Total amount of hits.
Declaration unsigned char hit_count

Variables

---

Name	Description
ray_from	Start position of the ray.
Declaration vec3 ray_from
ray_to	End position of the ray.
Declaration vec3 ray_to
collisionlayer_mask	The Specify on which collision layer(s) the ray is placed.
Declaration int collisionlayer_mask
collisionlayer_filter	Specify with which collision layer(s) objects the ray should intersect with.
Declaration int collisionlayer_filter
cull_face	Enable or disable backface culling.
Declaration bool cull_face
enabled	Enable or disable continuous raycast.
Declaration bool enabled
query_available	Determine if the raycast query is ready or not.
Declaration bool cull_face Remarks To relaunch another ray you have to set it to false to indicate that the result have been processed by your script or plugin.

Functions

---

Name	Description
GetHitPoint	Retrieve the position of a specific hit.
Declaration vec3 GetHitPoint( unsigned char hit_index ) Parameters hit_index: The index of the hit to retrieve the position for. Return Value On success return the hit position; if the hit index is invalid return a zeroed vector.
GetHitNormal	Retrieve the normal at a specific hit position.
Declaration vec3 GetHitNormal( unsigned char hit_index ) Parameters hit_index: The index of the hit to retrieve the normal for. Return Value On success return the normal; if the hit index is invalid return a zeroed vector.
GetHitFraction	Retrieve the fraction for a specific hit.
Declaration vec3 GetHitFraction( unsigned char hit_index ) Parameters hit_index: The index of the hit to retrieve the fraction for. Return Value 0.0 if the hit index provided is invalid; else return the hit fraction for the hit specified by the index.
GetPhysicObject	Return the PhysicObject for a specific hit.
Declaration PhysicObject *GetPhysicObject( unsigned char hit_index ) Parameters hit_index: The index of the hit to retrieve the PhysicObject for. Return Value nil if the hit index in invalid; else return reference of the PhysicObject hit by the ray.

WorldContact

---

A structure that contains all the information available for a contact point between two PhysicObject.

Static Variables

---

Name	Description
physicobject0	Reference of the first PhysicObject involved in the collision.
Declaration PhysicObject *physicobject0
physicobject1	Reference to the second PhysicObject involved.
Declaration PhysicObject *physicobject1
physicmaterial0	Reference of the PhysicMaterial used by the first PhysicObject.
Declaration PhysicMaterial *physicmaterial0
physicmaterial1	Reference of the PhysicMaterial used by the second PhysicObject.
Declaration PhysicMaterial *physicmaterial1
collider0	Reference to the first Collider involved in the contact.
Declaration Collider *collider0
collider1	Reference to the second Collider involved in the contact.
Declaration Collider *collider1
point	Location of the contact in world space.
Declaration vec3 point
normal	Normal vector of the contact point.
Declaration vec3 normal
local0	Position of the contact in local space relative to the first PhysicObject pivot.
Declaration vec3 local0
local1	Position of the contact in local space relative to the second PhysicObject pivot.
Declaration vec3 local1
distance	Distance of the contact between the two physic bodies.
Declaration float distance
lifetime	Life time of the active contact point.
Declaration int lifetime
applied_impulse	The amount of impulse applied on the contact.
Declaration float applied_impulse

SolverMode

---

Find below the list of all available flags that can be used to tweak the behaviors of the constraint solver.

• fRandomizeOrder: Use a non-sequential pattern to progressively solve constraints.
• fFrictionSeparate: Improve the performance of constraints solving by ignoring velocity dependent friction calculation.
• fUseWarmStarting: Warmstart all constraints using the default warm start value set in the constraint Solver section to give a head start to all constraints solving at start time.
• fFrictionWarmStarting: Warmstart the friction parameter of all constraints.
• fUseTwoFrictionDirection: Improve the constraint's friction calculations quality by splitting the incoming and released friction value.
• fEnableFrictionDirectionCaching: Improve the speed of the friction calculations at the cost of more memory.
• fDisableVelocityDependenFrictionDirection: Improve the performance of constraints solving by ignoring velocity dependent friction calculation.
• fUse3PointsArea: Approximate the convex hull area of contact using 3 points instead of 4 (the default value), it is less accurate but faster to calculate and maintain.
• fUseSIMD: Use SIMD instructions (when available on the platform) for solving constraints.

TraversalMode

---

List of all available BVH traversal mode.

• kStackless: Stackless traversal.
• kCacheFriendly: Stackless and cache friendly.
• kRecursive: Recursively traverse the BVH tree.

DebugDraw

---

Available flags for physics debugging and visualization.

• fNoDeactivation: Disable deactivation.
• fDrawPhysicBounds: Enable physics bounds debugging.
• fDrawColliders: Draw physics colliders.
• fDrawContactPoints: Draw contact points and their associated normal (runtime only).
• fDrawNormals: Enable faces normal debugging; especially useful when using mesh types to ensure that all normals are actually pointing the right way.
• fDrawCollisionBounds: Draw a rough representation of the internal bounds used by the physics engine to calculate collision.
• fDrawCCD: Draw the swept sphere of each object that will be used for continuous collision detection.
• fSelectedPhysicObjects: Only debug draw selected PhysicObject.
• fDrawPhysicConstraints: Enable physic constraints debugging.
• fDrawConstraint: Provides visual shape feedback to constraints.
• fDrawConstraintLimits: Draw the constraint limits.
• fDrawConstraintRelation: Draw a dashed line between constraints that are related.
• fSelectedConstraints: Only debug draw constraints that are connected to selected PhysicObject.
• fDrawSoftBody: Enable SoftBody debugging.
• fDrawSoftNormals: Draw the soft body face normals.
• fDrawSoftContactPoints: Only available at runtime; this option allows you to visually represent the contact point(s) of each node with the surface they collide with.
• fDrawSoftLinks: Visually represent how the mesh faces are linked.
• fDrawSoftNodeTree: Draw the soft body node tree.
• fDrawSoftClusters: Only available when the SoftBody is using clusters; this option allows you to draw the clusters used internally by the engine.
• fSelectedSoftBodies: Only debug draw the selected SoftBody.