The physics world.

This contains all the data-structures necessary for creating and simulating bodies with contacts, joints, and external forces.

Hierarchy

  • World

Constructors

  • Parameters

    • gravity: Vector
    • Optional rawIntegrationParameters: RawIntegrationParameters
    • Optional rawIslands: RawIslandManager
    • Optional rawBroadPhase: RawBroadPhase
    • Optional rawNarrowPhase: RawNarrowPhase
    • Optional rawBodies: RawRigidBodySet
    • Optional rawColliders: RawColliderSet
    • Optional rawImpulseJoints: RawImpulseJointSet
    • Optional rawMultibodyJoints: RawMultibodyJointSet
    • Optional rawCCDSolver: RawCCDSolver
    • Optional rawQueryPipeline: RawQueryPipeline
    • Optional rawPhysicsPipeline: RawPhysicsPipeline
    • Optional rawSerializationPipeline: RawSerializationPipeline
    • Optional rawDebugRenderPipeline: RawDebugRenderPipeline

    Returns World

Properties

bodies: RigidBodySet
broadPhase: BroadPhase
ccdSolver: CCDSolver
characterControllers: Set<KinematicCharacterController>
colliders: ColliderSet
debugRenderPipeline: DebugRenderPipeline
gravity: Vector
impulseJoints: ImpulseJointSet
integrationParameters: IntegrationParameters
islands: IslandManager
multibodyJoints: MultibodyJointSet
narrowPhase: NarrowPhase
physicsPipeline: PhysicsPipeline
queryPipeline: QueryPipeline
serializationPipeline: SerializationPipeline
vehicleControllers: Set<DynamicRayCastVehicleController>

Accessors

  • get lengthUnit(): number
  • The approximate size of most dynamic objects in the scene.

    See the documentation of the World.lengthUnit setter for further details.

    Returns number

  • set lengthUnit(unitsPerMeter: number): void
  • The approximate size of most dynamic objects in the scene.

    This value is used internally to estimate some length-based tolerance. In particular, the values IntegrationParameters.allowedLinearError, IntegrationParameters.maxPenetrationCorrection, IntegrationParameters.predictionDistance, RigidBodyActivation.linearThreshold are scaled by this value implicitly.

    This value can be understood as the number of units-per-meter in your physical world compared to a human-sized world in meter. For example, in a 2d game, if your typical object size is 100 pixels, set the [Self::length_unit] parameter to 100.0. The physics engine will interpret it as if 100 pixels is equivalent to 1 meter in its various internal threshold. (default 1.0).

    Parameters

    • unitsPerMeter: number

    Returns void

  • get numAdditionalFrictionIterations(): number
  • Number of addition friction resolution iteration run during the last solver sub-step (default: 4).

    Returns number

  • set numAdditionalFrictionIterations(niter: number): void
  • Sets the number of addition friction resolution iteration run during the last solver sub-step (default: 4).

    The greater this value is, the most realistic friction will be. However a greater number of iterations is more computationally intensive.

    Parameters

    • niter: number

      The new number of additional friction iterations.

    Returns void

  • get numInternalPgsIterations(): number
  • Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: 1).

    Returns number

  • set numInternalPgsIterations(niter: number): void
  • Sets the Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: 1).

    Increasing this parameter will improve stability of the simulation. It will have a lesser effect than increasing numSolverIterations but is also less computationally expensive.

    Parameters

    • niter: number

      The new number of internal PGS iterations.

    Returns void

  • get numSolverIterations(): number
  • The number of solver iterations run by the constraints solver for calculating forces (default: 4).

    Returns number

  • set numSolverIterations(niter: number): void
  • Sets the number of solver iterations run by the constraints solver for calculating forces (default: 4).

    The greater this value is, the most rigid and realistic the physics simulation will be. However a greater number of iterations is more computationally intensive.

    Parameters

    • niter: number

      The new number of solver iterations.

    Returns void

  • get timestep(): number
  • The current simulation timestep.

    Returns number

  • set timestep(dt: number): void
  • Sets the new simulation timestep.

    The simulation timestep governs by how much the physics state of the world will be integrated. A simulation timestep should:

    • be as small as possible. Typical values evolve around 0.016 (assuming the chosen unit is milliseconds, corresponds to the time between two frames of a game running at 60FPS).
    • not vary too much during the course of the simulation. A timestep with large variations may cause instabilities in the simulation.

    Parameters

    • dt: number

      The timestep length, in seconds.

    Returns void

Methods

  • Find the closest intersection between a ray and the physics world.

    Parameters

    • ray: Ray

      The ray to cast.

    • maxToi: number

      The maximum time-of-impact that can be reported by this cast. This effectively limits the length of the ray to ray.dir.norm() * maxToi.

    • solid: boolean

      If false then the ray will attempt to hit the boundary of a shape, even if its origin already lies inside of a shape. In other terms, true implies that all shapes are plain, whereas false implies that all shapes are hollow for this ray-cast.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns RayColliderHit

  • Find the closest intersection between a ray and the physics world.

    This also computes the normal at the hit point.

    Parameters

    • ray: Ray

      The ray to cast.

    • maxToi: number

      The maximum time-of-impact that can be reported by this cast. This effectively limits the length of the ray to ray.dir.norm() * maxToi.

    • solid: boolean

      If false then the ray will attempt to hit the boundary of a shape, even if its origin already lies inside of a shape. In other terms, true implies that all shapes are plain, whereas false implies that all shapes are hollow for this ray-cast.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns RayColliderIntersection

  • Casts a shape at a constant linear velocity and retrieve the first collider it hits. This is similar to ray-casting except that we are casting a whole shape instead of just a point (the ray origin).

    Parameters

    • shapePos: Vector

      The initial position of the shape to cast.

    • shapeRot: Rotation

      The initial rotation of the shape to cast.

    • shapeVel: Vector

      The constant velocity of the shape to cast (i.e. the cast direction).

    • shape: Shape

      The shape to cast.

    • targetDistance: number

      − If the shape moves closer to this distance from a collider, a hit will be returned.

    • maxToi: number

      The maximum time-of-impact that can be reported by this cast. This effectively limits the distance traveled by the shape to shapeVel.norm() * maxToi.

    • stopAtPenetration: boolean

      If set to false, the linear shape-cast won’t immediately stop if the shape is penetrating another shape at its starting point and its trajectory is such that it’s on a path to exist that penetration state.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns ColliderShapeCastHit

  • Finds the handles of all the colliders with an AABB intersecting the given AABB.

    Parameters

    • aabbCenter: Vector

      The center of the AABB to test.

    • aabbHalfExtents: Vector

      The half-extents of the AABB to test.

    • callback: ((handle: Collider) => boolean)

      The callback that will be called with the handles of all the colliders currently intersecting the given AABB.

    Returns void

  • Iterates through all the contact manifolds between the given pair of colliders.

    Parameters

    • collider1: Collider

      The first collider involved in the contact.

    • collider2: Collider

      The second collider involved in the contact.

    • f: ((manifold: TempContactManifold, flipped: boolean) => void)

      Closure that will be called on each contact manifold between the two colliders. If the second argument passed to this closure is true, then the contact manifold data is flipped, i.e., methods like localNormal1 actually apply to the collider2 and fields like localNormal2 apply to the collider1.

    Returns void

  • Enumerates all the colliders potentially in contact with the given collider.

    Parameters

    • collider1: Collider

      The second collider involved in the contact.

    • f: ((collider2: Collider) => void)

      Closure that will be called on each collider that is in contact with collider1.

    Returns void

  • Creates a new character controller.

    Parameters

    • offset: number

      The artificial gap added between the character’s chape and its environment.

    Returns KinematicCharacterController

  • Creates a new impulse joint from the given joint descriptor.

    Parameters

    • params: JointData

      The description of the joint to create.

    • parent1: RigidBody

      The first rigid-body attached to this joint.

    • parent2: RigidBody

      The second rigid-body attached to this joint.

    • wakeUp: boolean

      Should the attached rigid-bodies be awakened?

    Returns ImpulseJoint

  • Creates a new multibody joint from the given joint descriptor.

    Parameters

    • params: JointData

      The description of the joint to create.

    • parent1: RigidBody

      The first rigid-body attached to this joint.

    • parent2: RigidBody

      The second rigid-body attached to this joint.

    • wakeUp: boolean

      Should the attached rigid-bodies be awakened?

    Returns MultibodyJoint

  • Creates a new rigid-body from the given rigid-body descriptor.

    Parameters

    • body: RigidBodyDesc

      The description of the rigid-body to create.

    Returns RigidBody

  • Creates a new vehicle controller.

    Parameters

    • chassis: RigidBody

      The rigid-body used as the chassis of the vehicle controller. When the vehicle controller is updated, it will change directly the rigid-body’s velocity. This rigid-body must be a dynamic or kinematic-velocity-based rigid-body.

    Returns DynamicRayCastVehicleController

  • Applies the given closure to each active rigid-body managed by this physics world.

    After a short time of inactivity, a rigid-body is automatically deactivated ("asleep") by the physics engine in order to save computational power. A sleeping rigid-body never moves unless it is moved manually by the user.

    Parameters

    • f: ((body: RigidBody) => void)

      The function to apply to each active rigid-body managed by this physics world. Called as f(collider).

    Returns void

  • Applies the given closure to each collider managed by this physics world.

    Parameters

    Returns void

  • Applies the given closure to each rigid-body managed by this physics world.

    Parameters

    Returns void

  • Release the WASM memory occupied by this physics world.

    All the fields of this physics world will be freed as well, so there is no need to call their .free() methods individually.

    Returns void

  • Retrieves a collider from its handle.

    Parameters

    • handle: number

      The integer handle of the collider to retrieve.

    Returns Collider

  • Retrieves an impulse joint from its handle.

    Parameters

    • handle: number

      The integer handle of the impulse joint to retrieve.

    Returns ImpulseJoint

  • Retrieves an multibody joint from its handle.

    Parameters

    • handle: number

      The integer handle of the multibody joint to retrieve.

    Returns MultibodyJoint

  • Retrieves a rigid-body from its handle.

    Parameters

    • handle: number

      The integer handle of the rigid-body to retrieve.

    Returns RigidBody

  • Returns true if collider1 and collider2 intersect and at least one of them is a sensor.

    Parameters

    • collider1: Collider

      − The first collider involved in the intersection.

    • collider2: Collider

      − The second collider involved in the intersection.

    Returns boolean

  • Enumerates all the colliders intersecting the given colliders, assuming one of them is a sensor.

    Parameters

    Returns void

  • Gets the handle of up to one collider intersecting the given shape.

    Parameters

    • shapePos: Vector

      The position of the shape used for the intersection test.

    • shapeRot: Rotation

      The orientation of the shape used for the intersection test.

    • shape: Shape

      The shape used for the intersection test.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns Collider

  • Find all the colliders containing the given point.

    Parameters

    • point: Vector

      The point used for the containment test.

    • callback: ((handle: Collider) => boolean)

      A function called with the handles of each collider with a shape containing the point.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns void

  • Cast a ray and collects all the intersections between a ray and the scene.

    Parameters

    • ray: Ray

      The ray to cast.

    • maxToi: number

      The maximum time-of-impact that can be reported by this cast. This effectively limits the length of the ray to ray.dir.norm() * maxToi.

    • solid: boolean

      If false then the ray will attempt to hit the boundary of a shape, even if its origin already lies inside of a shape. In other terms, true implies that all shapes are plain, whereas false implies that all shapes are hollow for this ray-cast.

    • callback: ((intersect: RayColliderIntersection) => boolean)

      The callback called once per hit (in no particular order) between a ray and a collider. If this callback returns false, then the cast will stop and no further hits will be detected/reported.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns void

  • Retrieve all the colliders intersecting the given shape.

    Parameters

    • shapePos: Vector

      The position of the shape to test.

    • shapeRot: Rotation

      The orientation of the shape to test.

    • shape: Shape

      The shape to test.

    • callback: ((collider: Collider) => boolean)

      A function called with the handles of each collider intersecting the shape.

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns void

  • Find the projection of a point on the closest collider.

    Parameters

    • point: Vector

      The point to project.

    • solid: boolean

      If this is set to true then the collider shapes are considered to be plain (if the point is located inside of a plain shape, its projection is the point itself). If it is set to false the collider shapes are considered to be hollow (if the point is located inside of an hollow shape, it is projected on the shape's boundary).

    • Optional filterFlags: QueryFilterFlags
    • Optional filterGroups: number
    • Optional filterExcludeCollider: Collider
    • Optional filterExcludeRigidBody: RigidBody
    • Optional filterPredicate: ((collider: Collider) => boolean)

    Returns PointColliderProjection

  • Update colliders positions after rigid-bodies moved.

    When a rigid-body moves, the positions of the colliders attached to it need to be updated. This update is generally automatically done at the beginning and the end of each simulation step with World.step. If the positions need to be updated without running a simulation step this method can be called manually.

    Returns void

  • Removes the given collider from this physics world.

    Parameters

    • collider: Collider

      The collider to remove.

    • wakeUp: boolean

      If set to true, the rigid-body this collider is attached to will be awaken.

    Returns void

  • Removes the given impulse joint from this physics world.

    Parameters

    • joint: ImpulseJoint

      The impulse joint to remove.

    • wakeUp: boolean

      If set to true, the rigid-bodies attached by this joint will be awaken.

    Returns void

  • Removes the given multibody joint from this physics world.

    Parameters

    • joint: MultibodyJoint

      The multibody joint to remove.

    • wakeUp: boolean

      If set to true, the rigid-bodies attached by this joint will be awaken.

    Returns void

  • Removes the given rigid-body from this physics world.

    This will remove this rigid-body as well as all its attached colliders and joints. Every other bodies touching or attached by joints to this rigid-body will be woken-up.

    Parameters

    Returns void

  • Advance the simulation by one time step.

    All events generated by the physics engine are ignored.

    Parameters

    Returns void

  • Returns void

  • Returns void

  • Returns void

  • Takes a snapshot of this world.

    Use World.restoreSnapshot to create a new physics world with a state identical to the state when .takeSnapshot() is called.

    Returns Uint8Array

  • Ensure subsequent scene queries take into account the collider positions set before this method is called.

    This does not step the physics simulation forward.

    Returns void

  • Parameters

    • raw: RawDeserializedWorld

    Returns World

  • Creates a new physics world from a snapshot.

    This new physics world will be an identical copy of the snapshoted physics world.

    Parameters

    • data: Uint8Array

    Returns World

Generated using TypeDoc