flutter3d
Showcase Changelog 62 packages API reference

Glossary

Every word below is a type or a file in this repository, not a general graphics term. Where a word is used differently elsewhere, the entry says so.

Drawing #

Backend
One implementation of flutter3d_hardware. There are four: flutter3d_impeller on the GPU, flutter3d_webgl in a browser, flutter3d_cpu in plain Dart, and flutter3d_webgpu in a browser that hands out an adapter. An application usually names none of them: flutter3d_app depends on the ones its platform draws with and opens the first that starts
HAL
The hardware abstraction layer, flutter3d_hardware: GraphicsDevice, CommandEncoder, formats, handles. It names no graphics API, which is what lets the renderer be written once
Pass
One beginRenderPass and everything drawn before it is submitted. A frame here is shadows, sky, scene, then post, each in its own command buffer
Draw item
One mesh, one material, one transform, sorted into the render list by a packed key. Culling decides which nodes become one
Contributor
A PassContributor: something that draws inside somebody else's pass without editing the renderer. Particles are the first user
Batch
An InstancedMeshNode: one mesh at many places in one call, a transform and a colour per instance. Culled, sorted and picked as one thing
Lightmap
A Lightmap: the light a brush level's walls throw on each other, baked by gathering and stored beside the level as RGBM. Sampled at a second coordinate that rides in the vertex colour, so it costs no new layout
Visibility table
A LevelVisibility: the empty space of a brush level cut into cells, and a bit per pair saying whether they see each other. Baked once, stored beside the level, and used to leave out the rooms behind the walls

Materials #

One material type is for an application: RenderMaterial in code and Material3D in a widget tree, which makes a RenderMaterial and changes it in place. The others below have material in their names because they describe a surface or a substance somewhere else in the engine, and an application reaches them only through a file or a decoder.

RenderMaterial
How a surface is drawn: a lighting model, a base colour in linear light, metallic and roughness, emission in nits, the maps. What a MeshNode holds and what you change between frames. The one to use
Material3D
The widget for a RenderMaterial: the Mesh3Ds below it that name no material of their own are drawn with it, and a rebuild writes into the same object, so one Material3D over many meshes stays one batch
SurfaceMaterial
What a model file says about a surface, in the form every decoder produces (glTF's metal-rough; OBJ's Phong approximated). Turned into a RenderMaterial when a ModelAsset is built. Not for applications: read it only to inspect a file
MaterialDocument
A .fmat file: a SurfaceMaterial with images named by path, an optional program and its parameters, so a look is authored once and worn by many models. Not for applications: a tool or an editor writes it, and the loader reads it
PhysicalMaterial
What a thing is made of, not how it looks: density, friction, restitution, how it conducts heat and sound, each number citing its source, in flutter3d_matter's catalogue. The physics, the audio and the particles read it. Not for drawing: a RenderMaterial may name one by id

Lighting and shadows #

Lighting model
A LightingModel: one compiled fragment shader. Six ship (unlit, Lambert, Blinn-Phong, PBR, toon, normals), and switching one switches pipeline, which is why the draw sort puts pipeline first
Cascade
One tile of the directional light's shadow map. Three tiles covering near, middle and far beat one large tile covering everything
Cube atlas
Where point and spot shadows live: six faces across, one row per shadowed light, six lights at once. Sized by ShadowSettings.cubeResolution, which is not the cascade's resolution
Static / dynamic atlas
Two cube atlases. The static one holds what never moves and is drawn once at load; the dynamic one is redrawn as things move. The shader samples both and keeps the nearer occluder
Shadow casting mode
A ShadowCastingMode on a mesh node: on, off for a floor or a view model, doubleSided for leaves, shadowsOnly for a stand-in that casts for a mesh too expensive to draw six times
Normal offset
How far a shadow lookup moves along the surface normal before it measures, in texels of the face it lands on. It clears the width of one texel, which grows with distance. A fixed offset in metres is why a floor once shadowed itself
Penumbra
The soft edge. Estimated from how far the blocker is, which is why the filter searches before it filters

Assets #

.f3d
This engine's binary mesh container. About 360× faster to load than the same geometry as OBJ text, which is the whole reason it exists
.fmat
A material as a file, so a look can be authored once and shared. MaterialDecoder is the seam for formats the engine does not ship
Environment map
A prefiltered cube built by EnvironmentMap.prefilter: the specular chain plus a diffuse level. What image-based lighting samples
LOD group
A LodGroup: several versions of one object, chosen by how much of the viewport it covers rather than by distance, because the same object at the same distance is worth different detail through different lenses

The level document #

A level is JSON. These are its parts, and a game reads all of them through LevelLoader.

Brush
A Brush: a box with a material. Walls, floors, ledges, ramps. The geometry of a level is a list of these
Entity
An EntityDef: a type name and some properties. torch, monster, key. The engine does not know what any of them mean
Entity kind
An EntityKind in a game's registry: what that type name is worth. This is where a game says monster spawns an actor with this brain and that health
Fixture
A Fixture: an entity that has been placed and given a mechanism. What the bridge turns into something you can see
Mechanism
A Mechanism: the behaviour behind a fixture. A door that opens, a light that flickers, a platform that moves
Level light
A LevelLight: type, colour, range, intensity, and whether it casts. A fixture can dim the one it owns by name
Breach
A hole in a brush, kept by Breaches. A box minus a box is at most six boxes, so the mesh and the collision change together and the snapshot carries the hole as six numbers

Simulation #

Fixed step
The simulation advances in equal slices, whatever the frame rate. Two machines fed the same intents reach the same place; the frame interpolates between the last two steps
Intent
What a player asked for, in a game's own words: jump, fire, dash. A GameAction, which is a value class rather than an enum, so a genre adds one without editing the engine
Actor
An Actor: an entity and a handle, with every part of it optional. A monster carries a body, health and a brain; a barrel carries no brain, and isAlive stays true with no health, because nothing to kill is not the same as dead
Brain
A Brain: what an actor decides each step. States, targets, a path to walk
Snapshot
Everything a save needs, taken from the simulation and restored into it. Not the tuning: a save that carried the balance patch would restore a car built by an older one
Replay / tape
A recording of intents, not of positions. Replayed through the same fixed step it reproduces the run exactly, which is what makes a bug in a race reproducible
Demo
A Demo: a level name, the snapshot a run started from and the tape of every step after. A save plus a tape, and the file the dungeon writes when a run ends
Rewind buffer
A RewindBuffer: a demo with its middle kept, one keyframe a second and a tape entry a step for the last few seconds. What a kill camera plays back
Automap
An Automap: the navigation grid, remembered. Revealed by a walk from the player's cell, so a closed door keeps the room behind it dark
Sound occlusion
A SoundOcclusion in the bridge: the share of a sound that gets through the walls between it and the ear. The rest becomes a muffle, a low-pass filter on that voice

Physics #

Broadphase
The cheap pass that decides which pairs are worth testing properly. A uniform grid here
Sweep
Moving a shape along a path and stopping at the first thing in the way, instead of teleporting it and asking what it overlaps. What keeps a fast body from passing through a wall
Character controller
A CharacterController: kinematic, sweeps and slides, and nothing ever pushes it. That is what a first-person game feels as solidity
Layer mask
Which things collide with which. A bullet passes through a pickup and stops at a wall because their masks say so

Racing, since it has its own vocabulary #

Track spline
A TrackSpline: the road as a curve with widths and banks, not as geometry. A car is placed by where it is along the curve, which is what lets a circuit run to a kilometre
Slip angle
The gap between where the car points and where it is going. What makes a tyre generate a cornering force, and what makes it stop when the gap gets too wide
Slip ratio
The gap between how fast the wheels are turning and how fast the road is passing. Traction and wheelspin are the same number with different signs
Grip circle
One budget shared between cornering and braking. Spend it all on stopping and there is none left to turn, which is why trail braking works
Ghost
A recorded lap played back as places, not inputs, so it survives the car being retuned

Testing #

Golden
A reference image a scene is compared against. There are three complete independent sets (Impeller, software and WebGL2), each held to zero differing pixels against its own, with a fourth being recorded for WebGPU
Parity fixture
One scene drawn by two backends and compared as a grid of average brightness. Answers "do these two draw the same picture", which a golden cannot
Conformance
The suite a backend has to pass before it counts as one. Split in two: what needs no shaders, and the rest
Structure rule
One of 173 scans in tool/structure.dart. They read source text and hold the architecture: that a genre package stays out of another genre, that the documents' numbers are true

Next #