Gameplay

3D physics

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: 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.

pubspec.yaml
hooks:
  user_defines:
    just_jolt:
      build: true
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.

PlatformJolt (just_jolt 0.2.0)
Windows x64built and tested
Android arm64-v8a, x86_64built by the hook (NDK r26 or newer)
Linux, macOS, iOSshould build; untested
Webnot 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.

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.

Collider3DShapeSized by
box (default)size, the full size along X, Y and Z (1 m)
sphereradius (0.5 m)
capsuleradius and height, along Y, caps included
cylinderradius and height, along Y
convexHullthe convex hull of a model's vertices: model (a .glb or .gltf) and optionally meshName
mesha model's triangles; static and kinematic bodies only
heightFieldterrain from heights, heightFieldSize samples a side (at least 4) and cellSize; static bodies only
matchShapethe 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.

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.

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.

JointWhat it does
FixedJoint3DComponentholds two bodies rigidly together
PointJoint3DComponentholds them at one point, free to turn (a ball joint)
HingeJoint3DComponentturns about axis, with optional limits (useLimits, minAngle, maxAngle), friction and a motor; reports angle
SliderJoint3DComponentslides along axis, with optional limits, friction and a motor; reports position
DistanceJoint3DComponentkeeps anchor and connectedAnchor between minDistance and maxDistance, with springFrequency and springDamping
SixDofJoint3DComponenteach 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.

This page as Markdown