.. _physicsdevice: .. highlight:: javascript .. index:: single: PhysicsDevice ------------------------ The PhysicsDevice Object ------------------------ Provides rigid body physics using the Bullet Physics Library. The PhysicsDevice object can be used to create the following objects: * Rigid bodies: dynamic or kinematic. * Collision objects: static or kinematic. * Shapes: plane, box, sphere, capsule, cylinder, cone, triangle mesh and convex hull. * Constraints: point to point, hinge, cone twist, 6DOF and slider. * Character * DynamicsWorld Shapes can be shared between multiple rigid bodies or collision objects. Methods ======= .. _physicsdevice_createdynamicsworld: .. index:: pair: PhysicsDevice; createDynamicsWorld `createDynamicsWorld` --------------------- **Summary** Create a simulation world to which collision objects, rigid bodies and constraints can be added. Physics objects and constraints can only be added to a single DynamicsWorld at any given time, although a constraints can span rigid bodies in two different worlds. **Syntax** :: var dynamicsWorldParameters = { maxSubSteps: 10, fixedTimeStep: (1.0 / 60.0), gravity: [0, -10, 0] }; var dyncamicsWorld = physicsDevice.createDynamicsWorld(dynamicsWorldParameters); ``maxSubSteps`` Limits the maximum number of substeps the simulation will perform per frame. Defaults to 10. ``fixedTimeStep`` Sets a fixed simulation time in seconds per substep. Defaults to 1.0 / 60.0. ``gravity`` The direction and magnitude of a global `gravity` force applied to the whole scene per frame. Defaults to [0, -10, 0]. .. index:: pair: PhysicsDevice; createPlaneShape `createPlaneShape` ------------------ **Summary** Creates a plane shape. **Syntax** :: physicsDevice.createPlaneShape({ normal : [0, 1, 0], distance : 0, margin : 0.001 }); Returns a plane :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createBoxShape `createBoxShape` ---------------- **Summary** Creates a box shape. **Syntax** :: physicsDevice.createBoxShape({ halfExtents : [0.5, 0.5, 0.5], margin : 0.001 }); Returns a box :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createSphereShape `createSphereShape` ------------------- **Summary** Creates a sphere shape. **Syntax** :: physicsDevice.createSphereShape({ radius : 1.0, margin : 0.001 }); Returns a sphere :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createCapsuleShape `createCapsuleShape` -------------------- **Summary** Creates a capsule shape. **Syntax** :: physicsDevice.createCapsuleShape({ radius : 0.25, height : 1.0, margin : 0.001 }); Returns a capsule :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createCylinderShape `createCylinderShape` --------------------- **Summary** Creates a cylinder shape. **Syntax** :: physicsDevice.createCylinderShape({ halfExtents : [0.25, 1.0, 0.25], margin : 0.001 }); Returns a cylinder :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createConeShape `createConeShape` ----------------- **Summary** Creates a cone shape. **Syntax** :: physicsDevice.createConeShape({ radius : 0.25, height : 1.0, margin : 0.001 }); Returns a cone :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createCollisionObject .. _physicsdevice_createcollisionobject: `createCollisionObject` ----------------------- **Summary** Creates a collision object. **Syntax** :: var boxObject = physicsDevice.createCollisionObject({ shape : boxShape, transform : [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 100.0, 10.0, 0.0], friction : 0.5, restitution : 0.3, kinematic : false }); ``shape`` A :ref:`Shape ` object. Returns a :ref:`CollisionObject ` object. .. index:: pair: PhysicsDevice; createRigidBody .. _physicsdevice_createrigidbody: `createRigidBody` ----------------- **Summary** Creates a rigid body. **Syntax** :: var shapeInertia = boxShape.inertia; var mass = 10.0; var boxBody = physicsDevice.createRigidBody({ shape : boxShape, mass : mass, inertia : [mass * shapeInertia[0], mass * shapeInertia[1], mass * shapeInertia[2]], transform : [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 100.0, 1.0, 0.0], friction : 0.5, restitution : 0.3, frozen : false }); ``shape`` A :ref:`Shape ` object. Returns a :ref:`RigidBody ` object. .. index:: pair: PhysicsDevice; createPoint2PointConstraint `createPoint2PointConstraint` ----------------------------- **Summary** Creates a point to point constraint. Point to point constraint limits the translation so that the local pivot points of 2 rigidbodies match in worldspace. A chain of rigidbodies can be connected using this constraint. If only one body is specified then the body's centre of mass is used as the other pivot. **Syntax** :: var constraint = physicsDevice.createPoint2PointConstraint({ bodyA : boxBodyA, bodyB : boxBodyB, pivotA : [0, -1.0, 0], pivotB : [0, 1.0, 0], force : 0.3, damping : 1.0, impulseClamp : 0.0 }); var constraint = physicsDevice.createPoint2PointConstraint({ bodyA : boxBodyA, pivotA : [0, -1.0, 0], force : 0.3, damping : 1.0, impulseClamp : 2.0 }); Returns a :ref:`Constraint ` object. **Parameters** ``bodyA`` One of the rigid bodies to be constrained. ``bodyB`` The other rigid body to be constrained. ``pivotA`` The :ref:`Vector3 ` representing the local point on bodyA. ``pivotB`` The :ref:`Vector3 ` representing the local point on bodyB. ``force (Optional)`` Represents tau in the bullet documentation. The scalar value representing the maximum force for the constraint. ``damping (Optional)`` The scalar value representing the damping of the constraint. ``impulseClamp (Optional)`` The scalar value representing the maximum impulse the constraint can apply. A value of 0.0 means unconstrained. .. index:: pair: PhysicsDevice; createHingeConstraint `createHingeConstraint` ----------------------- **Summary** Creates a hinge constraint. Hinge constraint, or revolute joint restricts two additional angular degrees of freedom, so the body can only rotate around one axis, the hinge axis. This can be useful to represent doors or wheels rotating around one axis. The user can specify limits to the rotation. If only one body is specified then world space is used for the other transform. **Syntax** :: var constraint = physicsDevice.createHingeConstraint({ bodyA : boxBodyA, bodyB : boxBodyB, transformA : matrixA, transformB : matrixB, low : 0.0, high : Math.PI / 2 }); var constraint = physicsDevice.createHingeConstraint({ bodyA : hingeDoorBody, transformA : frameInA, low : 0.0, high : Math.PI / 2 }); Returns a :ref:`Constraint ` object. **Parameters** ``bodyA`` One of the rigid bodies to be constrained. ``bodyB`` The other rigid body to be constrained. ``transformA`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyA. ``transformB`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyB. ``low (Optional)`` The scalar representing the lower limit of the constraint's rotation (in radians). ``high (Optional)`` The scalar representing the upper limit of the constraint's rotation (in radians). .. index:: pair: PhysicsDevice; createConeTwistConstraint `createConeTwistConstraint` --------------------------- **Summary** Creates a cone twist constraint. To create ragdolls, the cone twist constraint is very useful for limbs like the upper arm. It is a special point to point constraint that adds cone and twist axis limits. The x-axis serves as the twist axis. If only one body is specified then world space is used for the other transform. **Syntax** :: var constraint = physicsDevice.createConeTwistConstraint({ bodyA : boxBodyA, bodyB : boxBodyB, transformA : matrixA, transformB : matrixB, swingSpan1 : Math.PI / 4, swingSpan2 : Math.PI / 4, twistSpan : Math.PI * 0.7, damping : 0.4 }); var constraint = physicsDevice.createConeTwistConstraint({ bodyA : boxBodyA, transformA : matrixA, swingSpan1 : Math.PI / 4, swingSpan2 : Math.PI / 4, twistSpan : Math.PI * 0.7, damping : 0.4 }); Returns a :ref:`Constraint ` object. **Parameters** ``bodyA`` One of the rigid bodies to be constrained. ``bodyB`` The other rigid body to be constrained. ``transformA`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyA. ``transformB`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyB. ``swingSpan1 (Optional)`` The scalar representing the angle used to form the ellipsis in one axis (in radians). ``swingSpan2 (Optional)`` The scalar representing the angle used to form the ellipsis in one axis (in radians). ``twistSpan (Optional)`` The scalar representing the limit of the rotation around the x-axis (in radians). ``damping (Optional)`` The scalar representing the damping of the constraint. .. index:: pair: PhysicsDevice; create6DOFConstraint `create6DOFConstraint` ---------------------- **Summary** Creates a 6 degrees of freedom constraint. This generic constraint can emulate a variety of standard constraints, by configuring each of the 6 degrees of freedom (dof). The first 3 dof axis are linear axis, which represent translations of rigid bodies. The latter 3 dof axis represent the angular motion. Each axis can be either locked, free or limited. On construction of a new 6DOFConstraint, all axis are locked. Afterwards the axis can be reconfigured. Note that several combinations that include free and/or limited angular degrees of freedom are undefined. :: For each axis: Lowerlimit == Upperlimit -> axis is locked. Lowerlimit > Upperlimit -> axis is free Lowerlimit < Upperlimit -> axis is limited in that range **Syntax** :: var constraint = physicsDevice.create6DOFConstraint({ bodyA : boxBodyA, bodyB : boxBodyB, transformA : matrixA, transformB : matrixB, linearLowerLimit : mathDevice.v3Build(-4.0, -2.0, -2.0), linearUpperLimit : mathDevice.v3Build(4.0, 2.0, 2.0), angularLowerLimit : mathDevice.v3Build(-Math.PI / 2, -0.75, -Math.PI / 2), angularUpperLimit : mathDevice.v3Build(Math.PI / 2, 0.75, Math.PI / 2) }); Returns a :ref:`Constraint ` object. **Parameters** ``bodyA`` One of the rigid bodies to be constrained. ``bodyB`` The other rigid body to be constrained. ``transformA`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyA. ``transformB`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyB. ``linearLowerLimit (Optional)`` The :ref:`Vector3 ` representing the translational lower limit for each axis. ``linearUpperLimit (Optional)`` The :ref:`Vector3 ` representing the translational upper limit for each axis. ``angularLowerLimit (Optional)`` The :ref:`Vector3 ` representing the angular lower limit for each axis. ``angularUpperLimit (Optional)`` The :ref:`Vector3 ` representing the angular upper limit for each axis. .. index:: pair: PhysicsDevice; createSliderConstraint `createSliderConstraint` ------------------------ **Summary** Creates a slider constraint. The slider constraint allows the body to rotate around the x-axis and translate along this axis. **Syntax** :: var constraint = physicsDevice.createSliderConstraint({ bodyA : boxBodyA, bodyB : boxBodyB, transformA : matrixA, transformB : matrixB, linearLowerLimit : 1.2, linearUpperLimit : 8, angularLowerLimit : 0, angularUpperLimit : Math.PI / 2 }); Returns a :ref:`Constraint ` object. **Parameters** ``bodyA`` One of the rigid bodies to be constrained. ``bodyB`` The other rigid body to be constrained. ``transformA`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyA. ``transformB`` The :ref:`Matrix43 ` representing the constraint's transform local to bodyB. ``linearLowerLimit (Optional)`` The scalar representing the translational lower limit along the x-axis. ``linearUpperLimit (Optional)`` The scalar representing the translational upper limit along the x-axis. ``angularLowerLimit (Optional)`` The scalar representing the angular lower limit around the x-axis. ``angularUpperLimit (Optional)`` The scalar representing the angular upper limit around the x-axis. .. index:: pair: PhysicsDevice; createTriangleArray .. _physicsdevice_createtrianglearray: `createTriangleArray` --------------------- **Summary** Creates a triangle array object, required for triangle mesh shapes. **Syntax** :: var triangleArray = physicsDevice.createTriangleArray({ vertices: positionsData, indices: indices, minExtent: positionsMin, maxExtent: positionsMax }); Returns a :ref:`TriangleArray ` object. .. index:: pair: PhysicsDevice; createTriangleMeshShape `createTriangleMeshShape` ------------------------- **Summary** Creates a triangle mesh shape. **Syntax** :: var triangleMeshShape = physicsDevice.createTriangleMeshShape({ triangleArray: triangleArray, margin: 0.001 }); Returns a triangle mesh :ref:`Shape ` object. .. index:: pair: PhysicsDevice; createConvexHullShape `createConvexHullShape` ----------------------- **Summary** Creates a convex hull shape. **Syntax** :: var convexHullShape = physicsDevice.createConvexHullShape({ points: positionsData, margin: 0.001 }); Returns a convex hull :ref:`Shape ` object. .. _physicsdevice_createcharacter: .. index:: pair: PhysicsDevice; createCharacter `createCharacter` ----------------- **Summary** Creates a Character object. **Syntax** :: var character = physicsDevice.createCharacter({ transform : characterMatrix, mass: 100.0, radius : characterRadius, height : characterHeight, crouchHeight: (characterHeight * 0.5)), stepHeight : (characterHeight * 0.1), maxJumpHeight : (characterHeight * 0.4), restitution: 0.1, friction: 0.7 }); Returns a :ref:`Character ` object. Properties ========== .. index:: pair: PhysicsDevice; vendor `vendor` -------- **Summary** The name of the company responsible for the physics library used by the physics device. **Syntax** :: var vendorString = physicsDevice.vendor; .. note:: Read Only .. index:: pair: PhysicsDevice; version `version` --------- **Summary** The version string of the physics library used by the physics device. **Syntax** :: var versionString = physicsDevice.version; if ('2.75' >= versionString) { useFeaturesFrom275(); } .. note:: Read Only .. index:: pair: PhysicsDevice; FILTER_ .. _physicsdevice_FILTER: `FILTER_` --------- **Summary** Valid filter values, required for queries and when creating rigid bodies or collision objects. .. hlist:: :columns: 3 - FILTER_DYNAMIC - FILTER_STATIC - FILTER_KINEMATIC - FILTER_DEBRIS - FILTER_TRIGGER - FILTER_CHARACTER - FILTER_PROJECTILE - FILTER_USER_MIN - FILTER_USER_MAX - FILTER_ALL **Syntax** :: var queryFilterMask = (physicsDevice.FILTER_CHARACTER + physicsDevice.FILTER_PROJECTILE); .. note:: Read Only