.. index:
    single: DynamicsWorld

.. highlight:: javascript

.. _dynamicsworld:

========================
The DynamicsWorld object
========================

Constructor
===========

A DynamicsWorld object can be constructed with :ref:`PhysicsDevice.createDynamicsWorld <physicsdevice_createdynamicsworld>`.


Methods
=======

.. index::
    pair: DynamicsWorld; update

`update`
--------

**Summary**

Updates the state of the physics simulation.
Only needs to be called once per frame.

**Syntax** ::

    dynamicsWorld.update();

.. _dynamicsworld_raytest:

.. index::
    pair: DynamicsWorld; rayTest

`rayTest`
---------

**Summary**

Performs a ray query against the physics world.

**Syntax** ::

    var rayHit = dynamicsWorld.rayTest({
            from: hitScanStart,
            to: hitScanEndPoint,
            group: physicsDevice.FILTER_PROJECTILE,
            exclude: ownerPhysicsObject
        });
    if (rayHit)
    {
    }

``group``
    A :ref:`filter value <physicsdevice_FILTER>`.

Returns a :ref:`RayHit <rayhit>` object if the test succeeded, null otherwise.

.. _dynamicsworld_convexsweeptest:

.. index::
    pair: DynamicsWorld; convexSweepTest

`convexSweepTest`
-----------------

**Summary**

Performs a convex sweep query against the physics world.

**Syntax** ::

    var hit = dynamicsWorld.convexSweepTest({
            shape: queryShape,
            from: transformStart,
            to: transformEnd,
            group: physicsDevice.FILTER_PROJECTILE,
            exclude: myRigidBody
        });

``shape``
    A :ref:`Shape <shape>` object.

``group``
    A :ref:`filter value <physicsdevice_FILTER>`.

Returns a :ref:`RayHit <rayhit>` object if the test succeeded, null otherwise.


.. index::
    pair: DynamicsWorld; addCollisionObject

`addCollisionObject`
--------------------

**Summary**

Adds a collision object to the simulation.

**Syntax** ::

    dynamicsWorld.addCollisionObject(collisionObject);

``collisionObject``
    A :ref:`CollisionObject <collisionobject>`.


.. index::
    pair: DynamicsWorld; removeCollisionObject

`removeCollisionObject`
-----------------------

**Summary**

Removes a collision object from the simulation.

**Syntax** ::

    dynamicsWorld.removeCollisionObject(collisionObject);

``collisionObject``
    A :ref:`CollisionObject <collisionobject>`.


.. index::
    pair: PhysicsDevice; addRigidBody

`addRigidBody`
--------------

**Summary**

Adds a rigid body to the simulation.

**Syntax** ::

    dynamicsWorld.addRigidBody(rigidBody);

``rigidBody``
    A :ref:`RigidBody <rigidbody>` object.


.. index::
    pair: DynamicsWorld; removeRigidBody

`removeRigidBody`
-----------------

**Summary**

Removes a rigid body from the simulation.

**Syntax** ::

    dynamicsWorld.removeRigidBody(rigidBody);

``rigidBody``
    A :ref:`RigidBody <rigidbody>` object.


.. index::
    pair: DynamicsWorld; addConstraint

`addConstraint`
---------------

**Summary**

Adds a constraint to the simulation.

**Syntax** ::

    dynamicsWorld.addConstraint(constraint);

``constraint``
    A :ref:`Constraint <constraint>` object.


.. index::
    pair: DynamicsWorld; removeConstraint

`removeConstraint`
------------------

**Summary**

Removes a constraint from the simulation.

**Syntax** ::

    dynamicsWorld.removeConstraint(constraint);

``constraint``
    A :ref:`Constraint <constraint>` object.


.. index::
    pair: DynamicsWorld; addCharacter

`addCharacter`
--------------

**Summary**

Adds a Character object to the simulation.

**Syntax** ::

    dynamicsWorld.addCharacter(character);

``character``
    A :ref:`Character <character>` object.


.. index::
    pair: DynamicsWorld; removeCharacter

`removeCharacter`
-----------------

**Summary**

Removes a Character object from the simulation.

**Syntax** ::

    dynamicsWorld.removeCharacter(character);

``character``
    A :ref:`Character <character>` object.


.. index::
    pair: DynamicsWorld; flush

`flush`
-------

**Summary**

Removes all objects from the DynamicsWorld.

**Syntax** ::

    dynamicsWorld.flush();


Properties
==========

.. index::
    pair: DynamicsWorld; maxSubSteps

`maxSubSteps`
-------------

**Summary**

The maximum number of substeps the simulation will perform per frame.

**Syntax** ::

    var maxSubSteps = dynamicsWorld.maxSubSteps;

.. note:: Read Only


.. index::
    pair: DynamicsWorld; fixedTimeStep

`fixedTimeStep`
---------------

**Summary**

Fixed simulation time in seconds per substep.

**Syntax** ::

    var fixedTimeStep = dynamicsWorld.fixedTimeStep;

.. note:: Read Only


.. index::
    pair: DynamicsWorld; gravity

`gravity`
---------

**Summary**

The direction and magnitude of a global `gravity` force applied to the
whole scene per frame.

**Syntax** ::

    var gravity = dynamicsWorld.gravity;

.. note:: Read Only