JoltWorld class final

A Jolt Physics world: PhysicsWorld3D on just_jolt's native layer.

Made by JoltPhysicsEngine.createWorld. Handles are the native layer's int64 handles. A world acts only on the bodies, joints and characters it made itself, so one from another world, a dead one, or a character's stand-in body passed to destroyBody or createJoint is passed over. Shapes are shared and reference-counted (JoltShapes).

Destroy worlds through PhysicsEngine3D.destroyAll, not just_jolt's Jolt.destroyAll: a world destroyed behind its back still calls Jolt's body interface through memory that has gone. Use Jolt from one isolate.

The world, its scratch memory and its shapes each carry a NativeFinalizer, so a world dropped without dispose is still freed — in whatever order the finalizers run, which the native layer allows.

Implemented types

• PhysicsWorld3D
• Finalizable

Constructors

JoltWorld(PhysicsWorldSettings3D settings)

Makes a world as settings say. Throws a StateError when Jolt cannot (it was not initialised).

Properties

bodyCount → int

How many bodies it holds.

no setter, override

gravity ↔ Vector3

Gravity, m/s². Setting it wakes nothing; bodies at rest stay asleep.

getter/setter pair, override

handle ↔ int

The native world's handle.

late, final

hashCode → int

The hash code for this object.

no setter, inherited

isDisposed → bool

Whether dispose was called.

no setter, override

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

shapes → JoltShapes

This world's shapes.

final

Methods

addAngularImpulse(int body, Vector3 impulse) → void

Changes body's spin at once (N·m·s).

override

addForce(int body, Vector3 force) → void

Pushes body for the next step (N).

override

addImpulse(int body, Vector3 impulse) → void

Changes body's velocity at once (N·s).

override

addTorque(int body, Vector3 torque) → void

Turns body for the next step (N·m).

override

characterBody(int character) → int

The body that stands in for character (see CharacterSettings3D.innerBody), or 0.

override

characterContacts(int character) → List<CharacterContact3D>

What character touched in its last update.

override

characterState(int character, CharacterState3D out) → void

Reads character's state into out without moving it; a dead character reads as zeros, in the air.

override

createBody(Shape3D shape, BodySettings3D settings) → int

Makes a body of shape; 0 when it cannot be made (a shape that is not Shape3D.isValid, a mesh or a height field on a body that is not static, a layer outside 0–15, a full world).

override

createCharacter(CharacterSettings3D settings, Vector3 position) → int

Makes a character whose feet are at position; 0 when it cannot be made.

override

createJoint(int bodyA, int bodyB, JointSettings3D settings) → int

Joins bodyA to bodyB, or to the world when bodyB is 0; 0 when it cannot be made. Both must be bodies createBody made, not a character's body.

override

debugLines({bool joints = false}) → Float32List?

Every body (and joint, when joints) as lines, seven floats each: x1 y1 z1 x2 y2 z2, then a colour (0xAARRGGBB) stored in the float's bits (read it with ByteData.view(lines.buffer).getUint32(…, Endian.host)). Null when the backend cannot draw (Jolt outside its dev flavour).

override

destroyBody(int body) → void

Destroys body and every joint holding it. Only bodies createBody made: a character's body (characterBody) goes with its character.

override

destroyCharacter(int character) → void

Destroys character.

override

destroyJoint(int joint) → void

Destroys joint.

override

dispose() → void

Destroys the world and everything in it. Safe to call twice.

override

drainEvents() → List<PhysicsEvent3D>

What happened since the last drain, oldest first.

override

isAwake(int body) → bool

Whether body is awake.

override

isBody(int body) → bool

Whether body is a live body of this world.

override

isCharacter(int character) → bool

Whether character is a live character of this world.

override

isJoint(int joint) → bool

Whether joint is a live joint of this world.

override

jointValue(int joint) → double

A hinge's angle (radians) or a slider's position (metres) — body A's, measured from body B (or the world) — the same quantity a position motor drives; 0 for other joints.

override

moveCharacter(int character, double dt, Vector3 velocity, CharacterState3D out, {required Vector3 stepDown, required Vector3 stepUp}) → void

Moves character for one update at velocity: it slides along walls, keeps to the floor (stepDown, pointing down; zero to turn off) and climbs steps up to stepUp (pointing up; zero to turn off). Writes where it ended up into out.

override

moveKinematic(int body, Vector3 position, Quaternion rotation, double dt) → void

Moves a kinematic body so it arrives at position and rotation after dt seconds, giving it the velocity that takes.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

optimize() → void

Rebuilds the broad phase; worth it after adding many static bodies at once (a level loading).

overlap(Shape3D shape, Vector3 position, Quaternion rotation, {QueryFilter3D filter = QueryFilter3D.all}) → List<QueryHit3D>

The bodies shape at position and rotation overlaps, one hit each.

override

raycast(Vector3 origin, Vector3 direction, {QueryFilter3D filter = QueryFilter3D.all, bool allHits = false}) → List<QueryHit3D>

Casts a ray from origin along direction, whose length is the ray's. The closest hit, or every hit nearest first when allHits.

override

readBodies(List<int> bodies, BodyPoses3D out) → void

bodies' poses, in order, into out; dead ones read as zeros.

override

readMovedBodies(BodyPoses3D out) → void

The bodies that moved in the last step — awake bodies, and those that fell asleep since the last read — into out. Static bodies and characters' bodies are left out.

override

setAngularVelocity(int body, Vector3 velocity) → void

Sets body's spin (rad/s), waking it.

override

setBodyPose(int body, Vector3 position, Quaternion rotation, {bool wake = true}) → void

Teleports body. Static bodies are moved this way; kinematic bodies should use moveKinematic so what they touch is carried along.

override

setCharacterPosition(int character, Vector3 position) → void

Teleports character's feet to position.

override

setFriction(int body, double friction) → void

Sets body's friction.

override

setGravityFactor(int body, double factor) → void

Sets how strongly gravity pulls body.

override

setJointEnabled(int joint, bool enabled) → void

Turns joint on or off without destroying it.

override

setJointMotor(int joint, MotorState3D state, double target) → void

Drives a hinge or slider joint.

override

setLayer(int body, int layer) → void

Moves body to another collision layer.

override

setLinearVelocity(int body, Vector3 velocity) → void

Sets body's velocity (m/s), waking it.

override

setMotionQuality(int body, MotionQuality3D quality) → void

Switches body's continuous collision on or off.

override

setRestitution(int body, double restitution) → void

Sets body's bounciness.

override

shapeCast(Shape3D shape, Vector3 position, Quaternion rotation, Vector3 direction, {QueryFilter3D filter = QueryFilter3D.all, bool allHits = false}) → List<QueryHit3D>

Sweeps shape from position and rotation along direction. The closest hit, or every hit nearest first when allHits.

override

step(double dt, {int collisionSteps = 1}) → void

Advances the simulation by dt seconds, in collisionSteps passes (one per 1/60 s is plenty). Characters move in moveCharacter, before it.

override

toString() → String

A string representation of this object.

inherited

wake(int body) → void

Wakes body.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited