Physics3D class final

3-D physics for an engine. Give one to the engine and its 3-D physics components — RigidBody3D, Collider3D, CharacterBody3D and the joints — are saved, loaded, offered in the editor's 3-D scenes and simulated:

Engine(config: EngineConfig(physics3D: Physics3D()));

with Jolt built into the app, in its pubspec:

hooks:
  user_defines:
    just_jolt:
      build: true

A game without one is 2-D only, and its release build carries none of the 3-D code: all of it is reached through this object.

As the engine is made it registers the components and the camera's collision stage (CameraCollisionStage); as the engine initializes it starts the physics engine — PhysicsEngineFactory.create3D (Jolt) unless engine was given — and adds system. The world itself is made only when the first 3-D body or character appears, so a game whose 3-D scenes come later holds no world, worker threads or tables until then.

Where 3-D physics cannot run — the web, a 32-bit Android ABI, an app whose pubspec did not ask for Jolt — initializing the engine fails with an EngineInitException whose stage is service:Physics3D and whose EngineInitException.cause is a Physics3DUnsupportedError naming the reason. isSupported asks first.

The collision layers are the project's (assets/project/physics.json, read into EngineContext.physicsLayers); mesh and hull colliders take their triangles from the engine's loaded models.

Implemented types

Constructors

Physics3D({PhysicsEngine3D? engine, Vector3? gravity, int workerThreads = -1, int maxBodies = 10240, bool reportContactStay = false, bool reportActivation = false, bool addSystem = true}): 3-D physics on engine, or on the platform's physics engine when that is null, with workerThreads threads in its job system (below 0: cores minus one). gravity is (0, 9.81, 0) — down — unless given. addSystem false leaves adding system to a world to the game.

Properties

addSystem → bool: Whether starting adds system to the engine's world.
final
engine → PhysicsEngine3D: The physics engine it simulates on; throws before it starts.
no setter
gravity → Vector3: Gravity the world starts with.
final
hashCode → int: The hash code for this object.
no setterinherited
hasWorld → bool: Whether the world exists yet (it is made with the first 3-D body).
no setter
id → String: Names the extension; one install per context.
no setteroverride
isStarted → bool: Whether the engine started it.
no setter
maxBodies → int: The most bodies the world holds.
final
queries → Physics3DQueries: Rays, sweeps and overlaps, answered in entities; throws before it starts. They find nothing while there is no world yet.
no setter
reportActivation → bool: Whether bodies report falling asleep and waking.
final
reportContactStay → bool: Whether touching pairs fire CollisionStay3DEvent every step.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
system → PhysicsSystem3D: The system stepping the world; throws before it starts.
no setter
workerThreads → int: Threads in the physics engine's job system, when it is the platform's.
final
world → PhysicsWorld3D: The world, made now if it was still waiting for its first body; throws before it starts.
no setter

Methods

install(EngineContext context) → void: Registers what the package brings into context.
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
refresh(EngineContext context) → void: Puts what install registered in place again, from the code as it now is.
override
reloadModel(String model) → void: The model at model was loaded again (its file changed): its mesh and hull colliders take its new triangles (PhysicsSystem3D.reloadModel). Call once the engine's ModelAsset at that path answers with them — a renderer does, when it reloads a model. Does nothing before it starts.
start(ServiceContext context) → Future<void>: Starts the service, once: while the engine initializes (after its world exists, before initialize() completes) in the order the services were declared, or at once when added to an initialized engine. Throwing fails initialize() with an EngineInitException whose stage is service:<Type>.
override
stop() → Future<void>: Stops the service, once: while the engine disposes, after its plugins detach and before its world goes — services in the reverse of their start order — or when it is removed. It must not touch the world after this is called; the engine's dispose() completes once every stop() has.
override
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

isSupported → bool: Whether 3-D physics can run here, so a game can show something else instead of failing to start.
no setter
unsupportedReason → String?: Why 3-D physics cannot run here, or null when it can.
no setter

Static Methods

registerSchemas(EngineContext context) → void: Registers the 3-D physics components into context, so scenes holding them load and save — for tools that read and write 3-D scenes without simulating them. Giving the engine a Physics3D does this already.