just_game_engine_3d library

3-D for just_game_engine: graphics drawn by just_graphics_engine on Flutter GPU, and physics simulated by Jolt through just_physics_engine.

Give the engine the services a game uses: EngineConfig(services: [Graphics3D(), Physics3D()]). A game without them is 2-D only: no GPU device, no shaders, no Jolt — and the code here is dropped from its build.

Graphics:

Physics:

Units are metres; +Y is down, like the rest of the engine, so gravity is (0, +9.81, 0).

Classes

Aabb3
A mutable axis-aligned box [min, max].
Animation3DSystem
Moves animation time on and places sockets: for every entity with an AnimationPlayerComponent and a ModelComponent, advances its clip (looping or holding at the end) and its crossfade; then moves each SocketComponent entity to its node in its parent's posed model.
AnimationPlayerComponent
Plays the animations (glTF clips) of the entity's ModelComponent.
Arch3DComponent
A curved band standing up in its entity's XY plane: angle of a ring of radius (outside) and thickness, depth deep. Half a turn, the default, is an arch with its feet on the ground.
AssetCollider3DGeometry
Triangles from the engine's loaded ModelAssets. A model not loaded yet is loaded through assets (a renderer such as just_graphics_engine registers the loader for AssetType.model).
BloomSettings
The glow around bright things (HDR only).
Body3DSettings
Everything about a new body but its shape.
Box3DShape
A box of half extents hx, hy, hz about its centre.
CameraCollision3DComponent
Keeps a virtual camera out of walls: on the same entity as an OrbitFollowComponent (or any body stage), it pulls the camera in towards its target when something solid is between them, and eases it back out once the way is clear.
CameraCollision3DStage
Finalizes a CameraCollision3DComponent camera: a sphere cast from the point the camera circles to where the body stage put it, the target's own body ignored. Registered by Physics3D.
Capsule3DComponent
An upright capsule: a cylinder with a half ball on each end, height tall overall (never less than its width) and of radius.
Capsule3DShape
A capsule along Y about its centre: a cylinder halfHeight each way with a hemisphere of radius on each end.
Character3DContact
Something a character touches.
Character3DContacts
What a character touched, packed: count contacts, each the body and the character touched (one of them 0), stride floats — position (3), normal toward the character (3), velocity of the point touched (3), distance (1) — and two flags, with no object per contact (Physics3DWorld.readCharacterContacts).
Character3DSettings
How a character is made: a capsule standing on its position.
Character3DState
A character after a step. A world refills one it is given.
CharacterBody3DComponent
A character controlled by gameplay rather than forces: a capsule that walks on ground, slides along walls, climbs steps and slopes, and rides moving platforms (Jolt's CharacterVirtual). Its entity's position is its feet.
Collider3DComponent
The shape of its entity's RigidBody3DComponent — or, without one, of a static body made for it. It follows the entity's scale. Set to Collider3DShape.matchShape it takes the shape its entity is drawn as.
Collider3DGeometry
Where mesh and convex-hull colliders get their triangles.
Collider3DShapes
Turns Collider3DComponents into physics-engine Shape3Ds, following the entity's scale. Mesh and hull shapes are kept by model, mesh and scale, height fields by their heights and scale, and shapes matching an entity's look by that look's key and scale, so every body asking for the same one gets the same lists — and the physics engine shares one native shape between them. Each kind keeps its most recently used few (modelLimit, fieldLimit, solidLimit); a shape dropped is made again when next asked for.
CollisionEnter3DEvent
Two entities' bodies started touching. Fired on the world's event bus by Physics3DSystem after the step:
CollisionExit3DEvent
Two entities' bodies stopped touching.
CollisionStay3DEvent
Two entities' bodies are still touching after a step. Only fired when the service was made with reportContactStay: true.
Compound3DShape
Several shapes as one: a staircase of boxes, an arch of hulls. Each part is placed in its body's space — a Transformed3DShape for one that is not at the body's origin. Any body type may have one, a dynamic body included, so a concave thing made of convex parts can tumble.
Cone3DComponent
A cone of radius at its base and height, its tip up.
ConvexHull3DShape
The convex hull of points (x, y, z each).
Cube3DComponent
A box width × height × depth: a cube when they are equal.
Cylinder3DComponent
An upright cylinder of radius and height, segments round.
Cylinder3DShape
A cylinder along Y about its centre.
Directional3DLight
The sun: light travelling along direction.
DistanceJoint3DComponent
Keeps two anchors within a distance range: a rope, a chain link, a spring.
DynamicResolution
Renders fewer pixels while frames run slow, and more again when there is time to spare: a scale between minScale and maxScale on top of the renderer's own, stepped by what the last second of frames took.
Environment
The sky and the light that doesn't come from lights.
EnvironmentComponent
The sky and the ambient light of a 3-D scene. The first enabled one in a scene is used.
EnvironmentMapData
What lights a scene from all round, ready for the GPU: a small cube map of what surrounds it — level 0 the sky itself, each smaller level blurred for a rougher surface (GGX, prefiltered here on the CPU) — and its diffuse light as nine spherical-harmonic coefficients.
FixedJoint3DComponent
Holds two bodies rigidly together.
Frustum
The six planes bounding what a camera sees, each facing inwards.
GpuDevice
A GPU the renderer draws with.
GpuEnvironmentMap
An EnvironmentMapData on the GPU: its levels in one half-float cube texture, its spherical harmonics beside it. Give it to Environment.map and lit surfaces take their ambient light and reflections from it; with Environment.skybox the sky shows it.
GpuMaterial
A material's textures and settings, ready to bind.
GpuModel
A model uploaded to the GPU: its primitives' buffers, its materials' textures, and the data it came from (without its images' pixels, which live on the GPU now).
GpuPrimitive
One primitive's vertex and index buffers.
GpuTexture
An image on the GPU.
Graphics3D
3-D graphics for an engine. Give one to the engine and its 3-D components — ModelComponent, Light3DComponent, EnvironmentComponent, AnimationPlayerComponent, SocketComponent and the shapes from Cube3DComponent to Polygon3DComponent — are saved, loaded, offered in the editor's 3-D scenes and drawn:
Graphics3DDefinitions
How the 3-D model components (models, animation players, sockets) are saved and shown in an editor. Lights, materials and shapes have their own (Lighting3DDefinitions, Material3DDefinitions, Shape3DDefinitions).
Graphics3DModelAsset
The engine's view of a model loaded by just_graphics_engine: its bounds and triangles in engine axes (+Y down), for picking and mesh colliders.
Graphics3DModelLoader
Creates Graphics3DModelAssets for the engine's asset manager.
Graphics3DModels
The models a game's scenes use, each loaded once per asset path: read from bundle, parsed, uploaded with uploader.
Graphics3DSceneRenderer
Draws a world's 3-D components (Model, the shapes, Light, Environment) from the engine's camera — the SceneRenderer a Graphics3D adds.
Graphics3DShapes
The GPU side of the shapes (Primitive3DComponent): meshes made from their sizes and materials from their looks, uploaded once and shared by every shape alike — twenty equal crates are one mesh and one material, drawn in one instanced draw.
HeightField3DShape
Terrain: a square grid of heights. Static bodies only.
HingeJoint3DComponent
Lets two bodies turn about one axis: a door, a wheel, a lever.
Joint3DComponent
What a joint holds its entity's body to. The joint is on one entity (A) and names the other (connectedBody, B); none joins A to the world.
Joint3DSettings
How a joint is made. Points and axes are in world space, as the bodies are when it is made.
JoltPhysicsEngine
Jolt Physics (through just_jolt) as a Physics3DEngine.
Light3DComponent
A light at its entity's transform. A Light3DKind.directional light shines from far away along the entity's forward (+Z) axis (the sun), a Light3DKind.point light from its position in every direction, and a Light3DKind.spot light in a cone from its position along that axis.
Light3DData
KHR_lights_punctual: a light pointing down its node's -Z.
Lighting3DDefinitions
How the 3-D lights and the environment are saved and shown in an editor. Every one is a 3-D component (Dimensions.threeD).
LinearColor
sRGB colours as the linear RGB the 3-D renderer lights and blends in.
Material3DData
A glTF metallic-roughness material, with the extensions this renderer reads (KHR_materials_unlit, KHR_materials_emissive_strength, KHR_texture_transform).
Material3DDefinitions
How the 3-D material components are saved and shown in an editor.
Material3DFile
A material saved in its own file (*.material.json), which 3-D shapes and models refer to by path: change it once and everything drawn with it changes.
Material3DLibrary
The material files (*.material.json) the scene's shapes and models draw with, read once each and made into GPU materials.
Material3DOverride
Changes to one material; a null field keeps the file's value.
Material3DOverridesFieldType
An entity's own values for the 3-D material files it is drawn with — MaterialOverrides3DComponent.values — saved as a map by key, whose channels are the numbers in it a timeline can key, a pair as key#0 and key#1. (A colour is changed from code: keyed as one number it would not blend as a colour.)
MaterialChain
Walks a variant's parents and lays each file over the one before.
MaterialOverrides3DComponent
An entity's own values for the material files it is drawn with — its shape's (Primitive3DComponent.material) or its model's (ModelComponent.materials): a glow pulsing, a colour fading, a texture sliding. By key from Material3DFile.animatableKeys, shaped as a material file saves them (color an ARGB number, tiling [x, y]).
MaterialSlots
Where an entity's material file goes: its shape's Primitive3DComponent.material, or — for a model — the file drawn for every one of its materials (* in ModelComponent.materials). What painting a material on, and picking one up, work through.
Matrix4
4D Matrix. Values are stored in column major order.
Mesh3DShape
A triangle mesh: three indices per triangle into positions. Static bodies only: a body that moves needs a convex shape, or a Compound3DShape of them.
MeshBuilder
Builds a Shape3DMesh a vertex and a triangle at a time. Each triangle is wound to face the way its vertices' normals point, whichever order it was given in.
MeshData
One glTF mesh.
MeshInstance
One primitive drawn somewhere in the world.
ModelComponent
Draws a 3-D model (glTF 2.0, .glb or .gltf) at its entity's transform. The model's own +Y-up axes are turned into the engine's.
ModelData
A model, ready for the GPU: meshes as interleaved vertices and indices, materials, encoded images, the node tree and its lights. In the file's own axes (glTF: +Y up); the renderer corrects axes once, at the root.
ModelImportSettings
How a model file is imported: what an editor saves beside it as <model>.import.json (see ModelImportSettings.sidecarOf) and what cooking it (cookModel) applies.
ModelUploader
Uploads ModelData to a GpuDevice.
Physics3D
3-D physics for an engine. Give one to the engine and its 3-D physics components — RigidBody3DComponent, Collider3DComponent, CharacterBody3DComponent and the joints — are saved, loaded, offered in the editor's 3-D scenes and simulated:
Physics3DDefinitions
How the 3-D physics components are saved and shown in an editor. Every one is a 3-D component (Dimensions.threeD), in the Physics group the 2-D ones are in — a body and a collider grouped, labelled and described as RigidBody2DComponent and Collider2DComponent are.
Physics3DEngine
A 3-D physics engine: makes Physics3DWorlds.
Physics3DEvent
One event from a step. Begin and stay events carry a contact point, the normal pointing from bodyA to bodyB (zero for sensors) and how deep they overlap.
Physics3DEvents
Events from steps, packed: count events, each a type, two bodies and stride floats — the contact point (3), the normal from the first body to the second (3) and how deep they overlap (1) — with no object per event (Physics3DWorld.readEvents).
Physics3DHit
A query's hit, with the entity whose body it hit.
Physics3DQueries
Rays, sweeps and overlaps against a Physics3DWorld, answered in entities. Physics3D.queries is one.
Physics3DSystem
Steps a Physics3DWorld and keeps it in step with the ECS: the 3-D counterpart of the engine's 2-D Physics2DSystem (a 3-D game leaves that one out), split the same way into bodies, joints, characters and contacts.
Physics3DWorld
One simulation: bodies, joints and characters that see each other.
Physics3DWorldSettings
How a world is made.
Plane
The plane of points p with normal · p + constant = 0.
Plane3DComponent
A flat rectangle width × depth lying on its entity's ground plane, seen from both sides. Its collider is a slab 0.1 m thick just under it.
PointJoint3DComponent
Holds two bodies at one point, free to turn about it (a ball joint).
Polygon3DComponent
An outline drawn on the ground, raised height: a floor, a wall or a platform of any shape. Each of its points is (x, z) in its entity's space — Offset.dx is x, Offset.dy is z.
Primitive3DComponent
A 3-D shape made from its own sizes rather than a model file — the base of Cube3DComponent, Sphere3DComponent, Plane3DComponent, Cylinder3DComponent, Capsule3DComponent, Cone3DComponent, Torus3DComponent, Ramp3DComponent, Stairs3DComponent, Arch3DComponent and Polygon3DComponent.
PrimitiveData
Triangles with one material.
Punctual3DLight
A point or spot light.
Quaternion
A mutable rotation quaternion (x, y, z, w), Hamilton convention.
Query3DFilter
What a query looks at.
Query3DHit
A query's hit.
Ramp3DComponent
A wedge rising towards +Z: flat underneath, height tall at its back, nothing at its front — something to walk up.
Ray3D
A half-line from origin along direction: the 3-D twin of the engine's Ray2D.
Render3DScene
Everything the renderer draws in one view.
Render3DStats
What the last frame did.
Render3DView
The camera a frame is drawn from, in the renderer's conventions: +Y down, clip y down, depth 0..1 (Matrix4Transforms.setPerspectiveYDown).
Renderer3D
Forward renderer for Render3DScenes: physically based lighting from a sun (with two cascades of shadow maps), up to 8 point/spot lights and a hemisphere ambient; skinned meshes; a gradient sky; HDR with 4x MSAA and ACES tonemapping where the device can.
RenderProvider<C extends Component>
Turns a component the renderer does not know — a terrain, a scatter of grass, a swept road — into meshes and batches it draws.
RenderProviderContext
What a RenderProvider builds with: the uploader that makes GPU meshes, the models and the shapes' materials it may share, and the stand-in textures.
RenderProviderOutput
What a RenderProvider hands the renderer for one entity: meshes and batches placed in the entity's own space — the renderer moves them with the entity.
RenderProviders
The RenderProviders of one engine: what its 3-D renderer draws beyond models and shapes. An engine's are context.renderProviders.
RigidBody3DComponent
Makes its entity a rigid body that Physics3DSystem simulates. It needs a Collider3DComponent on the same entity for its shape.
SamplerData
glTF sampler state (GL enum values).
Scene3DView
Draws scene seen from camera with renderer, every frame.
SceneEditorAids
What an editor shows in its views of the scene beyond what the game draws: what it hides, the selection's outline, a view mode and a slice. Set by the editor (Graphics3DSceneRenderer.aids), never by a game, and left out of the plainViews — the game's own camera seen in the editor.
SensorEnter3DEvent
Something entered a sensor (a RigidBody3DComponent with isSensor): a body, or a detectable character.
SensorExit3DEvent
Something left a sensor.
ShadowSettings
How the sun's shadows are drawn.
Shape3D
The shape of a body, a query or a character, as plain data a backend turns into its own.
Shape3DDefinitions
How the 3-D shapes are saved and shown in an editor. Each is a 3-D component (Dimensions.threeD) in the 3D Shapes group: its sizes, its detail, then its material.
Shape3DMesh
A 3-D shape's triangles on the CPU, in its own space: the renderer's axes (+Y down), metres. Front faces wind counter-clockwise seen from outside, as glTF's do once turned into engine axes.
Shape3DUv
How a shape lays its texture out.
SixDofJoint3DComponent
Each of the six degrees of freedom free, limited or fixed — anything the other joints cannot express.
SkeletalAnimationTarget
Plays an animator graph's states on a 3-D model's skeleton: an entity with an AnimatorComponent, a ModelComponent and an AnimationPlayerComponent (which it drives). A transition's duration crossfades; a blend tree blends its motions, weighted by the graph's parameters every update. It sets what the player plays at run time (playingClip, playingSpeed, playingLoop), never what it saves.
SkeletalClipTrack
A timeline track playing clips on the bound entity's 3-D model (its AnimationPlayerComponent): each block names a clip, plays at the block's speed, and loops as the block says. Entering a block crossfades over the player's crossfade; between blocks the model goes back to what it was playing before — what was authored, unless something (an animator) had taken it over, a blend tree's blend included. Scrubbing puts the clip exactly where the block says it should be: wrapped into it when the block loops, held at its end when not, from its end when the block plays it backwards. It sets what the player plays at run time, never what it saves.
SliderJoint3DComponent
Lets two bodies slide along one axis: a drawer, a piston, a lift.
SocketComponent
Pins its entity to a node of its parent's model — a joint, for a sword in a hand or a hat on a head. The entity must be a child (it has a ParentComponent) of an entity with a ModelComponent; each update it is moved to that node, keeping its own scale.
Sphere3DComponent
A ball of radius, segments round and rings from pole to pole.
Sphere3DShape
A sphere of radius about its centre.
Stairs3DComponent
A flight of steps solid steps rising towards +Z, width wide, height tall and depth long overall.
TextureData
A texture: an image and how to sample it.
TextureRef
A material's use of a texture.
Torus3DComponent
A ring lying flat: a tube of tubeRadius bent round a circle of radius (to the middle of the tube).
Transformed3DShape
shape moved by (x, y, z) and turned by the unit quaternion (qx, qy, qz, qw) in its body's space: a collider's offset.
Vector2
A mutable 2-D vector.
Vector3
A mutable 3-D vector.

Enums

AlphaMode
How a material treats alpha.
Body3DType
How a body moves.
Collider3DShape
The shapes a Collider3DComponent can be.
Ground3DState
Whether a character stands on something.
Joint3DKind
The kind of a joint.
Light3DKind
The kind of a 3-D light: what a model's light (Light3DData) is, what the renderer draws (Punctual3DLight), and what just_game_engine's Light3DComponent saves (by value name).
Material3DAlpha
How a Material3DFile treats what is behind it.
Material3DKind
What a Material3DFile is.
Material3DUv
How a Material3DFile's maps are laid over a surface.
Motion3DQuality
How carefully a moving body checks for collisions.
Motor3DState
What drives a hinge or slider.
Physics3DEventType
What happened between bodies during a step.
Render3DViewMode
How the renderer draws the scene: as it looks, flat-lit to read shapes by, or as lines only.
SixDofAxis3DMode
What a six-degrees-of-freedom joint lets one axis do.
TextureCompression
How cooked textures are stored.
UvMode
Where a material's textures are read.

Extensions

ContextGraphics3DModels on EngineContext
The models of the Graphics3D running on the engine whose context this is: for what knows only the context — a timeline scrubbing a clip needs its length.
ContextRenderProviders on EngineContext
The RenderProviders an engine's context keeps.
EngineGraphics3D on GameEngine
The engine's 3-D graphics.
EnginePhysics3D on GameEngine
The engine's 3-D physics.
Matrix4Transforms on Matrix4
Transforms on Matrix4: translate-rotate-scale builders, products, point and direction transforms, and the engine's projections.
Shape3DMeshGeometry on Shape3DMesh
A Shape3DMesh as the engine's ModelGeometry, for picking and colliders.

Constants

kSkinFloats → const int
Floats per vertex in PrimitiveData.skin: four joint indices (as floats) and their four weights, which sum to 1.
kVertexFloats → const int
Floats per vertex in PrimitiveData.vertices: position (3), normal (3), tangent (4, w = handedness; all zero when the file had none), uv (2), colour (4).

Functions

createGpuDevice({void onUnsupported(String reason)?}) → GpuDevice?
On the web there is no Flutter GPU: always null, with the reason given to onUnsupported.
loadModelData(Uint8List bytes, {required String name, ModelFetch? fetch}) → Future<ModelData>
Reads a glTF model — .glb or .gltf — into ModelData.
modelClipNamesOf(Uint8List bytes) → List<String>
The names of the clips the model file bytes (.glb or .gltf) has, in its order, as loadModelData names them: an animation's own name, or animation <index> for one with none; an animation that moves nothing the loader animates makes no clip. A .glb's bytes may end after its JSON chunk: only the JSON is read.

Typedefs

ModelFetch = Future<Uint8List> Function(String path)
Fetches a file a glTF refers to, by its path relative to the model (the URI the model used, decoded).
Scene3DFrameCallback = void Function(Duration elapsed, Size size)
Called before Scene3DView draws a frame: move the camera, animate the scene. elapsed is the time since the view started ticking; size is its size in logical pixels.

Exceptions / Errors

Physics3DUnsupportedError
3-D physics cannot run here: the web (no dart:ffi), a 32-bit Android ABI, or an app that did not ask for Jolt to be built. message says which, and what to change when something can be.