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:
- Graphics3D, the service that saves, loads and draws the components.
- Components: ModelComponent, AnimationPlayerComponent and SocketComponent; lights (Light3DComponent, EnvironmentComponent); MaterialOverrides3DComponent; and the shapes (Primitive3DComponent: Cube3DComponent to Polygon3DComponent). Plain data, so scenes holding them load everywhere, the web included.
- Graphics3DSceneRenderer, which draws the world from the engine's camera; Graphics3DModels, the loaded models; Material3DLibrary, the material files; Animation3DSystem, which plays clips.
- What a game names of just_graphics_engine: the renderer (Renderer3D, Render3DScene, Render3DView, Scene3DView), its settings, model and material data, mesh building, and the GPU device and resources the engine hands out. The renderer's plumbing stays in that package.
Physics:
- Physics3D, the service that saves, loads and simulates the components on Jolt Physics.
- Components: RigidBody3DComponent, Collider3DComponent, CharacterBody3DComponent, and the joints FixedJoint3DComponent, PointJoint3DComponent, HingeJoint3DComponent, SliderJoint3DComponent, DistanceJoint3DComponent, SixDofJoint3DComponent.
- Physics3DSystem, which steps the world, and its events on the world's bus: CollisionEnter3DEvent, CollisionStay3DEvent, CollisionExit3DEvent, SensorEnter3DEvent, SensorExit3DEvent.
- Physics3DQueries: rays, sweeps and overlaps answered in entities.
- just_physics_engine's 3-D side: Physics3DEngine, Physics3DWorld, shapes, settings and results.
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.mapand lit surfaces take their ambient light and reflections from it; withEnvironment.skyboxthe 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
Graphics3Dadds. - 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 askey#0andkey#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. BykeyfromMaterial3DFile.animatableKeys, shaped as a material file saves them (coloran 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,
.glbor.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 thePhysicsgroup the 2-D ones are in — a body and a collider grouped, labelled and described asRigidBody2DComponentandCollider2DComponentare. - 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.queriesis 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
pwithnormal · 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.dxis x,Offset.dyis 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,Arch3DComponentandPolygon3DComponent. - 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 the3D Shapesgroup: 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'sLight3DComponentsaves (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
Graphics3Drunning 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 —
.glbor.gltf— into ModelData. -
modelClipNamesOf(
Uint8List bytes) → List< String> -
The names of the clips the model file
bytes(.glbor.gltf) has, in its order, as loadModelData names them: an animation's own name, oranimation <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.
elapsedis the time since the view started ticking;sizeis 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.