Physics
These puzzles are used to simulate physics behavior of the objects.
Contents
Physics Puzzles Reference
create physics world
Initializes the physics engine using the specified gravity and frames-per-second parameters. The default gravity value of 9.8 corresponds to Earth surface conditions. Zero value means no gravity as in space. The higher fps value the better simulation quality at the expense of performance.
The soft body checker activates the soft body simulation capability.
Under the hood, this puzzle also enables collision detection and automatic synchronization with graphics.
create rigid body
Creates a physics body from a specified object, of dynamic, kinematic, static or ghost type. Assigns the collision shape and sets the mass for the body (valid for dynamic bodies only). Also works for a list of objects, a group (or a list of groups) or with the all objects puzzle.
Physics body types:
- dynamic - moved by the physics engine, influenced by collisions and collide with other bodies.
- kinematic - moved by animation or user action. Dynamic objects will be pushed away but there is no influence from dynamics objects.
- static - cannot move but collide with other bodies.
- ghost - similar to kinematic but does not produce any collision response. Use it to detect collision between bodies (for example to implement proximity sensor).
Supported rigid body shapes:
- box - a box-shaped bounding.
- sphere - a sphere-shaped bounding.
- mesh - a mesh shape.
- capsule - a capsule shape stretched along up-down axis.
- cone - a cone shape stretched along up-down axis.
- cylinder - a cylinder shape stretched along up-down axis.
- empty - an empty shape. Usefull for creating constraint attachments and soft body anchor points.
For performance reasons, give priority to primitive physics shapes (boxes, spheres, capsules, cones and cylinders) over mesh shapes. Also, static meshes have much better performance than dynamic, kinematic and ghost.
create soft body
Creates a soft body from a specified object with a given total mass and optional pressure params. Also works for a list of objects, a group (or a list of groups) or with the all objects puzzle.
Supported soft body shapes:
- volume - a closed pressurized 3D-dimentional volume.
- rope - a line object which behaves like a rope.
- patch - a polygonal surface like cloth or textile patch.
Don't forget to activate soft body simulation on the physics world before creating soft bodies.
remove physics body
Removes physics from a specified object by destroying the physics body associated with it. Also works for a list of objects, a group (or a list of groups) or with the all objects puzzle.
apply body param
Sets parameters for the physics body associated with a specified object. Also works for a list of objects, a group (or a list of groups) or with the all objects puzzle.
Parameters:
- angular damping - coefficient of resistance that will slow down a rotating object: 0 - no damping, 1 - maximum damping. Input values are clamped to [0, 1] range.
- angular factor - set rotational degrees of freedom for the specified body. For example by setting Z component to zero you can disable whirling the body around up-down (Blender, Max) or front-back (Maya) axis.
- angular velocity - set rotation speed vector.
- ccd motion threshold - motion threshold used for simulating Continuous Collision Detection (CCD) physics. Specify low value, such as 0.001
- ccd swept sphere radius - radius of the swept spere used for simulating Continuous Collision Detection (CCD) physics. This value should correspond to the size of the colliding objects. For example, to simulate a small bullet of size 0.01 m this value could be safely set to 0.5.
- force - push a body in a specified direction.
- friction - coefficient of resistance of relative motion of solid bodies sliding against each other.
- gravity - assign gravity individually for a specified body.
- impulse - acts like Linear Velocity but also takes the body mass into account (heavier objects will acquire less speed).
- linear damping - coefficient of resistance that will slow down a moving object: 0 - no damping (e.g. free fall), 1 - maximum damping (e.g. object falls with no acceleration). Input values are clamped to [0, 1] range.
- linear factor - set positional degrees of freedom for the specified body. For example by setting Z component to zero you can disable up-down (Blender, Max) or front-back (Maya) movement of the body.
- linear velocity - set movement speed vector.
- position - set body position (works like the snap body puzzle).
- rotation - set body rotation (euler rotation in XYZ order, works like the snap body puzzle).
- restitution - coefficient of elasticity: 0 - body is not elastic like clay, 1 - body behaves like being made from rubber.
- stiffness - stiffness of soft bodies like volumes and ropes.
- torque - spin a body in a specified direction.
- torque impulse - acts like Angular Velocity but also takes the body mass into account (heavier objects will acquire less rotation speed).
When two bodies collide, friction and restitution parameters of both of them are taken into consideration.
get body param
Gets a parameter from the physics body associated with a specified object.
Parameters:
- angular damping - coefficient of resistance that will slow down a rotating object: 0 - no damping, 1 - maximum damping.
- angular factor - rotational degrees of freedom for the specified body (XYZ).
- angular velocity - rotation speed vector.
- ccd motion threshold - motion threshold used for simulating Continuous Collision Detection (CCD) physics.
- ccd swept sphere radius - radius of the swept spere used for simulating Continuous Collision Detection (CCD) physics.
- force - force vector applied to the body.
- friction - coefficient of resistance of relative motion of solid bodies sliding against each other.
- gravity - gravity vector applied to a body.
- linear damping - coefficient of resistance that will slow down a moving object: 0 - no damping (e.g. free fall), 1 - maximum damping (e.g. object falls with no acceleration).
- linear factor - positional degrees of freedom for the specified body (XYZ).
- linear velocity - movement speed vector.
- position - body XYZ position.
- rotation - body XYZ euler rotation.
- restitution - coefficient of elasticity: 0 - body is not elastic like clay, 1 - body behaves like being made from rubber.
- stiffness - stiffness of soft bodies like volumes and ropes.
- torque - torque vector applied to the body.
set body state
Change the state to the physics body associated with a specified object. Also works for a list of objects, a group (or a list of groups) or with the all objects puzzle.
Parameters:
- activate - activate sleeping physics body.
- sleep - force sleeping state for the body.
- enable simulation - enable body simulation (enabled by default).
- disable simulation - disable body simulation.
- reset - clear all forces and velocities applied to the physics body.
- enable contact response - allow body to collide with other bodies (enabled by default).
- disable contact response - disable body colliding.
- make dynamic - make body dynamic.
- make kinematic - make body kinematic.
- make static - make body static.
- enable deactivation - allow body to turn into sleeping state after a period of inactivity (enabled by default).
- disable deactivation - disable body sleeping.
on simulation tick
Trigger puzzles specified in the *do" slot just before or just after the physics simulation tick.
Physics simulation tick corresponds to the FPS value specified when creating physics world and does not coincide with rendering frame. As such, we recommend that you apply forces/velocities/impulses before simulation tick and detect collisions between your bodies after simulation tick. This way you can achieve more stable and realistic simulations.
snap body
Moves a physics body associated with a specified object, and the object itself, to the position of another object by copying its transform data. Also copies rotation. Does not work with lists, groups or the "all objects" puzzle.
Works similar to apply body param / position puzzle.
add constraint to
Connect two physics bodies by a constraint of the given type.
Constraint types:
- hinge - connect the bodies by the shared axis.
- ball - connect the bodies by the ball-shaped socket.
- slider - limit movement of the bodies by the direction along the X axis.
- spring - connect two bodies by the spring-like joint.
- fixed - connect two bodies tightly.
remove constraint from
Remove physics constraint.
anchor soft body
Anchor soft body to a given rigid body at the point in space represented by the given vector.
detect collisions and collision info
Detects if there is a collision at the moment of a specified body with another body (or any body from a list or a group). If there is a collision, the puzzles in the "if touching do" slot are triggered, otherwise - in the "if not touching do".
The "detect collisions" puzzle triggers either of its callback slots every rendering frame.
The collision info puzzle outputs a dictionary with the following fields:
- objectA - the name of the first colliding body.
- objectB - the name of the second colliding body.
- distance - distance between points of collisions.
- positionOnA - XYZ coordinates of the collision point on the first object.
- positionOnB - XYZ coordinates of the collision point on the second object.
- normalOnB - XYZ components of the normal vector at the collision point on the second object.
Extending with JavaScript
Before you start reading, please get familiar with the Using JavaScript section of this User Manual.
To build physics puzzles we use a JavaScript library called Ammo.js. This library is basically the popular Bullet physics engine compiled to be used in the browser.
To get familiar with Bullet, check out the Bullet Physics SDK Manual available on GitHub as well as official Bullet API Reference.
In Verge3D you can execute Bullet/Ammo.js APIs directly by using the Ammo namespace:
var myVector = new Ammo.btVector3(1.0, 0.0, 0.0);
console.log('My physics vector is:', myVector.x(), myVector.y(), myVector.z());
Also you can get access to the following data structures we use in Puzzles via the puzzles argument of the runCode() function of your_app_name.js module or the built-in puzzles variable inside the exec script puzzle:
World
Depending on the initialized physics world it can be an instance to btDiscreteDynamicsWorld or btSoftRigidDynamicsWorld class:
var gravity = puzzles.physics.world.getGravity();
console.log('World gravity:', gravity.y());
Physics Bodies
Physics bodies are stored as key-value data inside the puzzles.physics.bodies object:
var body = puzzles.physics.bodies['Whirligig'];
console.log('Body mass:', 1.0 / body.getInvMass());
Rigid bodies are instances of the btRigidBody class, while soft bodies are instances of the btSoftBody class.
Physics Constraints
Bullet/Ammo constraints are stored as key-value data inside the two-dimensional puzzles.physics.constraints object:
var hingeConstraint = puzzles.physics.constraints['Suzanne']['Axis'];
hingeConstraint.enableAngularMotor(true, 10, 10);
The names represent the constraint's first and second bodies respectively.
Physics Sync List
Verge3D puzzles use the so-called synchronization list to move objects represented by physics bodies in space. Sync list is not directly accessible, so you need to use the following API methods to add/remove your bodies to/from that list.
// add obj / body to the sync list
// the type can be 'DYNAMIC', 'KINEMATIC', 'STATIC', 'GHOST', or 'SOFT_BODY'
puzzles.physics.addToSyncList(obj, body, 'DYNAMIC');
// remove obj / body from the sync list
puzzles.physics.removeFromSyncList(obj, body);
Having Troubles with Puzzles?
Seek help on the forums!