# 3D physics

_Gameplay_ · Opt into Jolt-based 3D physics with Physics3D, then use RigidBody3DComponent, Collider3DComponent and CharacterBody3DComponent, which mirror the 2D components.

3D physics runs on Jolt Physics and is opt-in. A game without it is 2D only, and its release build carries no 3D code and no Jolt. The components mirror [2D physics](/docs/physics-2d): `RigidBody3DComponent` says how a body moves, `Collider3DComponent` gives it a shape, and the events and queries have the same names with `3D` for `2D`.

## Turn it on

Import `package:just_game_engine/just_game_engine_3d.dart` and give the engine a `Physics3D`. Jolt is native code, so the app's own `pubspec.yaml` must also ask for it to be built. An app that gets Jolt only through another package builds nothing.

```yaml pubspec.yaml
hooks:
  user_defines:
    just_jolt:
      build: true
```

```dart lib/main.dart
import 'package:flutter/foundation.dart' show debugPrint;
import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_engine/just_game_engine_3d.dart';

Future<Engine> createEngine() async {
  final engine = Engine(
    config: EngineConfig(
      defaultSystems: DefaultSystems.all,
      // Left out where Jolt cannot run, such as the web.
      services: [if (Physics3D.isSupported) Physics3D()],
    ),
  );
  await engine.initialize();
  if (engine.physics3D == null) {
    debugPrint('No 3D physics here: ${Physics3D.unsupportedReason}');
  }
  return engine;
}
```

As the engine is made, `Physics3D` registers the 3D components, so scenes holding them load and save, and adds a camera stage that keeps cameras out of walls. As the engine initializes, it starts Jolt and adds `Physics3DSystem` to the world. The physics world itself is made only when the first 3D body or character appears, so a game whose 3D scenes come later pays nothing until then. `engine.physics3D` is the `Physics3D` you passed, or null.

## Where it runs

Where 3D physics cannot run, `initialize()` fails with an `EngineInitException` whose `cause` is a `Physics3DUnsupportedError`. That happens on the web, on 32-bit Android ABIs, and in an app whose pubspec did not ask for Jolt. Ask first with `Physics3D.isSupported`, and read why with `Physics3D.unsupportedReason`, as the sample above does.

| Platform | Jolt (`just_jolt` 0.2.0) |
|---|---|
| Windows x64 | built and tested |
| Android arm64-v8a, x86_64 | built by the hook (NDK r26 or newer) |
| Linux, macOS, iOS | should build; untested |
| Web | not available |

The component classes are plain data with no native code. Where Jolt cannot run, `Physics3D.registerDefinitions(engine.context)` registers them without simulating them, which is what a tool that reads and writes 3D scenes uses.

> **Tip:** On Windows, Jolt builds inside the app's `.dart_tool` folder, so keep the app's folder path under about 175 characters.

## Units and settings

Units are metres, seconds and radians, and +Y is down, so gravity is (0, 9.81, 0) unless you pass `Physics3D(gravity: ...)`. The other options are `workerThreads` (below 0: cores minus one, the default), `maxBodies` (10240), `reportContactStay`, `reportActivation`, `addSystem` (true; false leaves adding `system` to the game) and `engine`, a `Physics3DEngine` of your own.

## Bodies and colliders

As in 2D, a `Collider3DComponent` alone is a static body, and a `RigidBody3DComponent` beside it says how it moves. `RigidBody3DComponent` has the 2D fields: `bodyType` (`Body3DType.static`, `kinematic` or `dynamic`, the default), `mass` (0 works it out from the collider's volume), `friction` (0.5), `restitution` (0), `linearDamping` and `angularDamping` (0.05), `gravityScale`, `isSensor`, `lockRotation`, `continuousCollision`, `canSleep`, `layer`, `initialVelocity` and `initialAngularVelocity`. Changing `bodyType`, `mass`, damping, `isSensor`, `canSleep` or `lockRotation`, or adding or removing the `RigidBody3DComponent`, rebuilds the body.

Push a body with `addForce` (N), `addTorque`, `addImpulse` (N·s), `addAngularImpulse`, `setVelocity`, `setAngularVelocity` and `wakeUp`, all applied before the next step. After each step it holds `linearVelocity`, `angularVelocity` and `isAwake`. Move a kinematic or static body by writing its transform. A 3D body has only a `layer`: there is no `collidesWith` or `groupIndex`, so the project's layer grid decides what collides. A grid edited while a scene plays (a new `engine.context.physicsLayers`, as the editor's Physics Layers dock sets) reaches the running world at the next update.

| `Collider3DShape` | Sized by |
|---|---|
| `box` (default) | `size`, the full size along X, Y and Z (1 m) |
| `sphere` | `radius` (0.5 m) |
| `capsule` | `radius` and `height`, along Y, caps included |
| `cylinder` | `radius` and `height`, along Y |
| `convexHull` | the convex hull of a model's vertices: `model` (a `.glb` or `.gltf`) and optionally `meshName` |
| `mesh` | a model's triangles; static and kinematic bodies only |
| `heightField` | terrain from `heights`, `heightFieldSize` samples a side (at least 4) and `cellSize`; static bodies only |
| `matchShape` | the 3D shape the entity is drawn as, such as `Cube3DComponent` or `Stairs3DComponent`; concave ones are made of convex parts, so they work on dynamic bodies too |

Each shape has its own `offset`, `rotation` (Euler angles) and `scale`, and follows the entity's scale. Models load through the engine's assets. Bodies have no look of their own: draw them with [3D graphics](/docs/graphics-3d).

```dart lib/room.dart
void buildRoom(World world) {
  // A floor: a collider alone is static. +Y is down, so -2 is above it.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0, 0.5, 0)),
    Collider3DComponent(size: Vector3(20, 1, 20)),
  ], name: 'Floor');

  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0, -2, 0)),
    Collider3DComponent(),
    RigidBody3DComponent(),
  ], name: 'Crate');

  // A coin: a static sensor.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(4, -1.2, 0)),
    Collider3DComponent(shape: Collider3DShape.sphere, radius: 0.3),
    RigidBody3DComponent(bodyType: Body3DType.static, isSensor: true),
  ], name: 'Coin');

  // A door on a hinge that swings to 1 radian. Jointed bodies still
  // collide, so the frame stands clear of the door.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(-0.5, -1, 0)),
    Collider3DComponent(size: Vector3(0.2, 2, 0.2)),
  ], name: 'Frame');
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0.6, -1, 0)),
    Collider3DComponent(size: Vector3(1, 2, 0.1)),
    RigidBody3DComponent(gravityScale: 0),
    HingeJoint3DComponent(
      connectedBody: const EntityTarget.name('Frame'),
      anchor: Vector3(-0.5, 0, 0),
      motor: Motor3DState.position,
      motorTarget: 1,
    ),
  ], name: 'Door');
}
```

## Characters

A `CharacterBody3DComponent` is a capsule that gameplay moves rather than forces (Jolt's `CharacterVirtual`). It walks on ground, slides along walls, climbs steps and slopes, and rides moving platforms. Its entity's position is its feet, and it needs no `RigidBody3DComponent` or `Collider3DComponent`. The defaults are a character 1.8 m tall with a 0.3 m radius, `maxSlopeAngle` 50°, `stepHeight` 0.4 m, `stickToFloor` 0.5 m, `mass` 70 kg and `pushStrength` 100 N.

```dart lib/hero_3d.dart
class Hero3DControlSystem extends System {
  static const double speed = 4; // m/s

  @override
  int get priority => SystemPriorities.playerControl;

  @override
  List<Type> get requiredComponents => [InputComponent, CharacterBody3DComponent];

  @override
  void update(double deltaTime) {
    forEach((entity) {
      final input = entity.getComponent<InputComponent>()!;
      final body = entity.getComponent<CharacterBody3DComponent>()!;
      final move = input.vector('move'); // y is down: "up" is -1
      body.moveVelocity.setValues(move.dx * speed, 0, -move.dy * speed);
      if (body.isGrounded && input.wasPressed('jump')) body.jump(5);
    });
  }
}
```

With `useGravity` on, only the horizontal part of `moveVelocity` counts; the system adds gravity and the ground's own velocity, and `jump` makes the jump. Turn it off and `moveVelocity` is the whole velocity, for flying, swimming or ladders. After each step read `velocity`, `groundState` (a `Ground3DState`), `isGrounded`, `groundNormal`, `groundVelocity` and `groundEntity`. A `detectable` character is seen by sensors and hit by rays.

To resize a character for a while, a crouch say, set `heightOverride` rather than `height`: the capsule is `effectiveHeight` tall (the override, or else `height`), and the override is never saved, so a level saved meanwhile keeps the height it was authored with. Set it back to `null` to stand up.

Gravity is the same, as in 2D: to change it for a while, set `gravityScaleOverride` on the `CharacterBody3DComponent` or `RigidBody3DComponent` rather than `gravityScale`. It falls by `effectiveGravityScale` (the override, or else `gravityScale`), and the override is never saved; set it back to `null` for the authored scale.

## Joints

Every joint sits on one entity and names the other with `connectedBody`, an `EntityTarget`; leave it as `EntityTarget.none` to join the body to the world. `anchor` is in the joint entity's own space, and `enabled` switches the joint off. The joint is made where the bodies are when both exist, and made again when a setting changes. Jointed bodies still collide with each other: leave a gap between them, or put them on layers that do not collide.

| Joint | What it does |
|---|---|
| `FixedJoint3DComponent` | holds two bodies rigidly together |
| `PointJoint3DComponent` | holds them at one point, free to turn (a ball joint) |
| `HingeJoint3DComponent` | turns about `axis`, with optional limits (`useLimits`, `minAngle`, `maxAngle`), `friction` and a motor; reports `angle` |
| `SliderJoint3DComponent` | slides along `axis`, with optional limits, `friction` and a motor; reports `position` |
| `DistanceJoint3DComponent` | keeps `anchor` and `connectedAnchor` between `minDistance` and `maxDistance`, with `springFrequency` and `springDamping` |
| `SixDofJoint3DComponent` | each of the six axes `SixDofAxis3DMode.free`, `limited` or `fixed` |

A motor is `Motor3DState.off`, `velocity` (a target speed) or `position` (a target angle or position), set by `motorTarget` and capped by `motorMaxTorque` or `motorMaxForce`.

## Events and queries

The events fire on `world.events` after the step, with the 2D fields: `CollisionEnter3DEvent` and `CollisionStay3DEvent` (`entityA`, `entityB`, `point`, `normal`, `depth`), `CollisionExit3DEvent`, and `SensorEnter3DEvent` and `SensorExit3DEvent` (`sensor`, `other`). Stay events fire only with `Physics3D(reportContactStay: true)`.

`engine.physics3D!.queries` is a `Physics3DQueries`: `raycast`, `raycastAll`, `sphereCast`, `shapeCast`, `overlapSphere`, `overlapBox` and `overlap`. Like the 2D queries, each takes `layerMask`, `ignore` and `includeSensors`, and a hit (`Physics3DHit`) names its `entity`, `point`, `normal` and `distance`. For example, `queries.raycast(Vector3(0, -10, 0), Vector3(0, 1, 0), maxDistance: 50)` looks straight down (+Y is down). Until the first 3D body exists every query finds nothing.

To keep a third-person camera out of walls, add `CameraCollision3DComponent` to the camera entity beside its `OrbitFollowComponent`; see [Cameras](/docs/cameras).
