Physics Components
    Preparing search index...

    Class JoltManager

    Jolt Manager is responsible to handle the Jolt Physics backend.

    Hierarchy

    • PhysicsManager
      • JoltManager
    Index

    Accessors

    backend fixedStep gravity paused steps updateEvent

    Methods

    addIdleCallback castRay castShape collidePoint collideShape createCollisionGroups createShape destroyShape interpolate removeIdleCallback reset step toggleGroupPair

    Accessors

    • get backend(): any

      Gets the Jolt Backend instance. This is useful, when components are not sufficient and you wish to access Jolt's API directly.

      Note, this will be null, if the backend runs in a web worker. In this case you don't have access to the instance.

      Returns any

      const backend = app.physics.backend;
      const Jolt = backend.Jolt;
      const joltVec = new Jolt.Vec3(0, 0, 0);

      // common Jolt interfaces you might want, which the backend has already instantiated
      backend.physicsSystem;
      backend.bodyInterface;
      backend.joltInterface;
    • get paused(): boolean

      Gets the current state of the physics world. Whether it is paused or not.

      Returns boolean

      false
    • set paused(bool: boolean): void

      Allows to pause/unpause physics update. Useful, when you have some UI popup and want to freeze the game world, but still be able to interact with the application.

      Parameters

      • bool: boolean

        If true, will pause the physics world update.

      Returns void

    • get steps(): number

      Gets the number of times the physics world has been updated (steps count).

      Returns number

      0
    • get updateEvent(): null | EventHandle

      Gets the update event used to step physics.

      Returns null | EventHandle

    • set updateEvent(eventHandle: null | EventHandle): void

      Sets the update event to step physics.

      Parameters

      • eventHandle: null | EventHandle

      Returns void

    Methods

    • A callback function to call when all rigid and soft bodies fall asleep. It will be called every frame, while the bodies are not active.

      Note, that if a kinematic body has an BodyComponent.isometryUpdate set to ISOMETRY_DEFAULT or ISOMETRY_FRONT_TO_BACK, then the body will have its transforms get auto-updated in physics world every frame, preventing it from falling asleep. If you need this callback while using a kinematic body, then set its isometry update to ISOMETRY_BACK_TO_FRONT and control its transforms via component's move methods, e.g. BodyComponent.teleport, BodyComponent.linearVelocity etc. That will stop the frontend from sending isometry updates every frame and will rely on you setting its transforms when needed.

      Feature is disabled when web worker is used.

      Parameters

      • func: Function

        Callback function to execute.

      Returns void

    • Creates a raycast query to the physics world.

      Note, that a callback function is optional when running physics on main thread. When using a web worker, the method will not return any results directly, but will send them to your callback function instead once the frontend gets the worker's response. It also means that when using a web worker a callback function is no longer optional and is required.

      Parameters

      • origin: Vec3

        World point where the ray originates from.

      • dir: Vec3

        Non-normalized ray direction. The magnitude is ray's distance.

      • Optionalcallback: null | ((results: CastResult[]) => void) = null

        A callback function that will accept the raycast results.

        • null
        • (results: CastResult[]) => void
            • (results: CastResult[]): void
            • Interface

              Parameters

              • results: CastResult[]

                An array with query results. An empty array if no results.

              Returns void

      • Optionalopts: null | CastRaySettings = null

        Settings object to customize the query.

      Returns null | CastResult[]

      • Returns an array of cast results (empty array if no result). Will return null, if not using CastRaySettings.immediate mode.
      // Cast a 10 meters ray from (0, 5, 0) straight down.
      const origin = new Vec3(0, 5, 0);
      const dir = new Vec3(0, -10, 0);
      const results = app.physics.castRay(origin, dir, null, { firstOnly: false });
      if (results.length > 0) {
          // do something with the results
      }

    • Creates a shapecast query to the physics world.

      Note, that a callback function is optional when running physics on main thread. When using a web worker, the method will not return any results directly, but will send them to your callback function instead once the frontend gets the worker's response. It also means that when using a web worker a callback function is no longer optional and is required.

      Parameters

      • shapeIndex: number

        Shape index number. Create one using createShape.

      • position: Vec3

        World point where the cast is originated from.

      • rotation: Quat

        Shape rotation.

      • dir: Vec3

        Non-normalized ray direction. The magnitude is ray's distance.

      • Optionalcallback: null | ((results: CastResult[]) => void) = null

        A callback function that will accept the raycast results.

        • null
        • (results: CastResult[]) => void
            • (results: CastResult[]): void
            • Interface

              Parameters

              • results: CastResult[]

                An array with query results. An empty array if no results.

              Returns void

      • Optionalopts: null | CastShapeSettings = null

        Settings object to customize the query.

      Returns null | CollideShapeResult[]

      import { SHAPE_SPHERE } from './physics.dbg.mjs';

      // Do a 10 meters cast with a 0.3 radius sphere from (0, 5, 0) straight down.
      const shapeIndex = app.physics.createShape(SHAPE_SPHERE, { radius: 0.3 });
      const pos = new Vec3(0, 5, 0);
      const dir = new Vec3(0, -10, 0);
      const results = app.physics.castShape(shapeIndex, pos, Quat.IDENTITY, dir, null, {
          ignoreSensors: true
      });
      if (results.length > 0) {
          // do something with the results
      }

    • Check if a world point is inside any body shape. For this test all shapes are treated as if they were solid. For a mesh shape, this test will only provide sensible information if the mesh is a closed manifold.

      Note, that a callback function is optional when running physics on main thread. When using a web worker, the method will not return any results directly, but will send them to your callback function instead once the frontend gets the worker's response. It also means that when using a web worker a callback function is no longer optional and is required.

      Parameters

      • point: Vec3

        World position to test.

      • Optionalcallback: null | ((results: Entity[]) => void) = null

        Function to take the query results.

        • null
        • (results: Entity[]) => void
            • (results: Entity[]): void
            • Interface

              Parameters

              • results: Entity[]

                An array of entities that the point collided with. Array will be empty, if no entities collided.

              Returns void

      • Optionalopts: null | QuerySettings = null

        Query customization settings.

      Returns null | Entity[]

      • An array of entities that the point collided with (empty array if no result). Will return null, if not using QuerySettings.immediate mode.
      // get all entities that overlap a world position (0, 5, 0)
      const results = app.physics.collidePoint(new Vec3(0, 5, 0), null, { ignoreSensors: true });
      if (results.length > 0) {
          // do something with the results
      }

    • Gets all entities that collide with a given shape.

      Note, that a callback function is optional when running physics on main thread. When using a web worker, the method will not return any results directly, but will send them to your callback function instead once the frontend gets the worker's response. It also means that when using a web worker a callback function is no longer optional and is required.

      Parameters

      • shapeIndex: number

        Shape index created with createShape.

      • position: Vec3

        World position of the shape.

      • Optionalrotation: Quat = Quat.IDENTITY

        World rotation of the shape.

      • Optionalcallback: null | ((results: CollideShapeResult[]) => void) = null

        Callback function that will take the query results.

      • Optionalopts: null | CollideShapeSettings = null

        Query customization settings.

      Returns null | CollideShapeResult[]

      import { SHAPE_BOX } from './physics.dbg.mjs';

      // create a box with a half extent (1, 1, 1) meters (now we can use the same shape for
      // different casts, but simply modifying its scale during the cast)
      const shapeIndex = app.physics.createShape(SHAPE_BOX, { halfExtent: Vec3.ONE });

      // get all entities that intersect a box with half extent (0.2, 0.5, 0.2) at world position
      // (0, 10, 0)
      const scale = new Vec3(0.2, 0.5, 0.2);
      const pos = new Vec3(0, 10, 0);
      const results = app.physics.collideShape(shapeIndex, pos, Quat.IDENTITY, null, { scale });
      if (results.length > 0) {
          // do something with the results
      }

    • Allows to create collision groups. Note, that collision groups are more expensive than broadphase layers.

      The groups are created by giving an array of numbers, where each element adds a group and its number represents the count of subgroups in it.

      Parameters

      • groups: number[]

        Collision groups.

      • Optionalopts: ImmediateSettings

        Customization options.

      Returns void

      // Create `2` groups. The first group has `3` subgroups, the second `5`.
      app.physics.createGroups([3, 5]);

      For additional information, refer to Jolt's official documentation on Collision Filtering.

    • Creates a shape in the physics backend. Note, that the shape is not added to the physics world after it is created, so it won't affect the simulation.

      This is useful, when you want to use a shape for a shapecast, or want your kinematic character controller to change current shape (e.g. standing, sitting, laying, etc).

      Once you no longer need the shape, you must destroyShape to avoid memory leaks.

      Parameters

      Returns number

      Shape index (uint).

      import { SHAPE_CAPSULE } from './physics.dbg.mjs';

      // create a 2m high and 0.6m wide capsule.
      const shapeIndex = app.physics.createShape(SHAPE_CAPSULE, {
          halfHeight: 1,
          radius: 0.3
      });

      ShapeComponent.shape for available shape type options.

    • Allows to manually interpolate the bodies when you step physics yourself. Requires JoltInitSettings.manualStep and JoltInitSettings.useMotionStates to be true. This will update entities positions and rotations to their interpolated representations. See step for example usage.

      Parameters

      • alpha: number

        Fixed step fraction to interpolate to.

      • stepped: boolean

        Whether to use new position and rotation of a body as a base for interpolation.

      Returns void

    • Destroys an existing physics system in Jolt backend and creates a new one. You may want to use this for a deterministic start.

      Note, that you should destroy all existing entities with physics components before calling a reset.

      Returns void

    • Allows to manually step the physics, if you control the time yourself. Requires JoltInitSettings.manualStep to be true. Will always step once with JoltInitSettings.fixedStep size. This will update the entities positions and rotations to the same as they are in the physics world.

      Note: If you use JoltInitSettings.useMotionStates (true by default), the isometries of the entities will not be updated to the physics world positions. They will be read from their motion states. In order to update the motion state, and as a result the entity isometry, you need to call interpolate.

      Returns void

      update(dt) {
          time += dt;
          const fixedStep = app.physics.fixedStep;

          let stepped = false;
          while (time >= fixedStep) {
              app.physics.step();
              time -= fixedStep;
              stepped = true;
          }

          app.physics.interpolate(time/fixedStep, stepped);
      }

    • Toggles a collision between 2 subgroups inside a group.

      Parameters

      • group: number

        Group index number.

      • subGroup1: number

        First subgroup number.

      • subGroup2: number

        Second subgroup number.

      • enable: boolean

        true to enable, false to disable collision.

      • Optionalopts: ImmediateSettings

        Query customization options.

      Returns void

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods