flutter3d_effects 1.0.0-rc.2
flutter3d_effects: ^1.0.0-rc.2 copied to clipboard
The elements' water and fire, drawn: a lit water surface, a waterfall with its spray, bubbles and froth, flames, smoke, embers and firelight, and a liquid in a vessel.
1.0.0-rc.2 #
-
FireView.disposetakes the fires' particles out of the frame, andElements.disposecalls it. A view's smoke, flames and embers were added to the renderer and never taken out, so a game that left a level kept drawing them. -
Breaking:
PhysicsHearing.listenanswers aRegistrationthat stops hearing the liquid, as everylistendoes;unlistenstays, and a call that ignored the answer compiles as before. -
Breaking: the sky the water mirrors is in nits.
LiquidLook.skyandElements.skytake the zenith'sluminancein nits beside the two colours, which give the hue and the horizon's brightness against the zenith, and turn it into the renderer's scale asglowis. The colours were handed to the shader raw beside a sun scaled from lux, so a 100 000 lux sun left the sky where a 15 000 lux one would. -
Breaking: the elements' sun is in lux and a liquid's glow in nits.
Elements.sun,LiquidLook.sunandSeabedLook.suntake the sun'scolorand itsilluminancein lux, as a directionalLightNodedoes, where they took "colour times intensity" in the renderer's own scale;Liquid.glowandLiquidLook.gloware each channel's luminance in nits, as an emissive material's is. Both are turned into the renderer's scale inside.LiquidParametersandSeabedParameters, which wrote the shader's scale, are the package's own now. A colour written in the old scale is the same picture atilluminance: LightNode.defaultIntensity, or times 1843.2 nits for a glow. -
Breaking: a heat release is in watts.
FireView.plumeDepthtakes a fire's power in W, andFireView.wattsisFireView.power;Blackbody.colorandefficacyname their parametertemperature. -
Breaking:
Elements.listen(listener)answers aRegistration, where the getter and setterElements.listenerheld one listener. -
Breaking:
Elements.addBodytakesorientation:andangularVelocity:, where it tookturn:andspin:.dart fixrenames the arguments. -
Breaking: no public
late finalsetter.LiquidView.sheetNodeandLiquidView.surfaceNodeare getters over a private field: the setter they had worked once and threw the second time, and every read compiles as it did. -
The spilt liquid's pair loops are placed like any compute.
placeKernelLiquidasksFrameCompute.placeHostedwhereflutter3d_physics_native's liquid kernels run and builds itsKernelLiquidthere: the native lanes where the run need not replay, otherwise the first device that computes and reads back in the same turn, and only the CPU kernel under a bit-exact profile, where a GPU is passed over for its division and square roots. The native lanes are handed to the hardware layer asNativeLanes, statingKernelLiquid.nativeTolerance, and its rule decides when they run. -
Breaking: results that were records are final classes.
Elements,FireViewandLiquidViewanswered or held a record, which can never gain a field. Each answers a final class now, with the record's field names (a positional$1has a name of its own),==andhashCode. A field read compiles as before; a destructuring pattern names the class, andflutter3d_build:migraterewrites the$1reads. -
Breaking:
LiquidLayerMeshis a class, andcollides:aCollisionFilter. The layer-and-mesh pairliquidMeshesanswers is a final class with the record'slayerandmesh,==andhashCode;Elements.addBodyandfollowtakecollides:asflutter3d_elements'CollisionFilter, where it was a record. A field read compiles as before; a record literal names the class. -
A shallow water can be stepped on a GPU.
ShallowWaterWorkload(new) is the physics core's shallow water substep as aComputeWorkload: on WebGPU's compute or the wgpu sidecar its columns are stepped there, the core keeping the bodies, the springs and the spray round them; where neither is, the core steps them as before. Additive. -
Particles, debris, cloth and a fluid tank on a GPU.
ParticleCloudWorkload,DebrisWorkload,ClothWorkloadandFluidWorkload(new) are the physics core's visual systems as compute workloads, each the system it steps (NativeParticleCloud,DebrisSystem,ClothSystem,FluidSystem): handed to a renderer withaddWorkload, the hardware layer runs its kernels on the GPU that draws or on the compute sidecar, or leaves it to the core's own system, bit for bit. On a GPU a read answers what was read back a frame or two before. They replace the physics core's own GPU passes. Additive. -
A river's surface is built where its water is stepped.
LiquidViewhands its water's step to the renderer (steppedOn) and, where the hardware layer puts it on a device that computes, builds the surface there in two kernels and draws it from the buffer they wrote, the CPU writing only the air of the bubbles. Nothing here says, asks or reports where that is. On WebGPU a river's main-thread script fell from about 15 ms a frame to about 11. -
LiquidView.inSight: a liquid out of the picture is stepped and not drawn. While it is false,updateleaves the surface, the sheet and the spray as they were last drawn; the firstupdateafter it is true again redraws all of it. A game that keeps water just past the edges of its picture no longer rewrites and uploads it every frame. Additive: nothing that worked against 1.0.0-rc.1 changes. -
Drawing a liquid writes and sends less. The surface rewrites only what moves (height, normal, depth, flow, froth), the froth is not worked out at all with no bubbles in the water, the falling sheet clears and sends only as far as this frame or the last drew it rather than all of its capacity, and a bubble cloud's size settles without building a matrix per try. What is drawn is the same, vertex for vertex.
-
Breaking: the effects' colours are
LinearColors.Elements.sun's andLiquidLook.sun'slight,SeabedLook.sun's,sky'szenithandhorizon,LiquidLook.glowandLiquid.glow. The generatedLiquidParametersandSeabedParametersare over aMaterialParametersand keep vectors, the in-place buffers the shader reads. -
LiquidView.updatetakesdt:by name. -
Breaking:
ElementsViewPluginisflutter3d_effects.elementsby default, where it waselements.view:elementsis an area of the engine's events, which no plugin id may take. -
Breaking: colours in are
LinearColors.Blackbody.coloranswers one;SeabedLook.undertakes the floor's neighbour's colour as one, andFireView.watchitsfreshandcharred(still blended through their sRGB encoding, as a person sees char spread). -
Breaking:
Audibletakes named arguments (key:,at:,loudness:,rate:). -
The fire's glow reads the material's
emissiveStrengthinstead of assuming its default, and no longer names the pre-1.0 photometric constants: the gains are written as what they were tuned to. -
Breaking: the elements' simulation moved to
flutter3d_elements, and this package keeps the views.ElementsSimulation,Fires,WaterBody,TrackedBody,Follower,Igniter,Solid,Bed,ElementHeightfield,ElementsListener,ElementsSteps,FireSteps,LiquidSteps,ElementsSimulationPlugin, the plugin element's hook, its registries and every element event are declared there and not re-exported here: importflutter3d_elementsbeside this.Elements,ElementsViewPlugin,ElementsQuality,Liquidand the views stay. New in 1.0, so no 0.8 code names them. -
Breaking: what draws a body or a water is kept by
Elements.TrackedBody.lookiselements.lookOf(body);WaterBody.viewandWaterBody.lookareelements.viewOf(water)andelements.waterLookOf(water). A water dug withsetGroundis drawn on its new bed from the next frame. -
liquidMeshes,LiquidLayerMesh,jetMeshandparticleMeshcome here fromflutter3d_core: a liquid in a vessel and a jet, drawn, are views of the physics, and the core no longer depends on it. -
FireView.plumeDepthisSmokePlume.depthofflutter3d_elements, which the simulation'sseenThroughSmokereads too; the numbers are unchanged. -
Systems run in
LoopPhase.fields, the elements phase's new name, andPortableand thevector_mathcrossings come fromflutter3d_foundation. -
The seabed's sunlight takes the refracted path. The way down is d / cos θt, cos θt = √(1 − (1 − cos²θi)/n²), and the caustics start from the refracted ray's offset; it was d / cos θi, which at a sun 30° up made the path 2.0 d instead of 1.32 d and the red at three metres some 40 % too dark. The sun's blur is σ = w/4 of its width, a disc's Gaussian.
-
Firelight breathes as its flames do, at 1.5/√D Hz over the fire's base, light-weighted over a cluster, where it was 1.5 Hz for any fire. The flames' ≈29× emissive gain is a named constant beside the light's ≈91×, and both are documented, with the 4.56 of the tongues' rise and the two flame-length correlations.
-
Breaking: the elements' names no longer repeat the simulation's.
PoseisElementPose,HeightfieldisElementHeightfield, and the body the elements made or track isTrackedBody(ElementBodyis the hook's handle on a core body, which already had the name). A game that imports this andflutter3d_simtogether no longer hidesPose,BodyorHeightfield. New in 1.0, so no 0.8 code calls them. -
The build hook depends on
flutter3d_build_hooks, the material compiler on its own, and no longer onflutter3d_build: a game that depends on the effects resolves no MCP server,dart_mcpor editor core through them. -
Breaking: one suffix for settings, Settings, and Descriptor in the HAL.
LiquidParamsisLiquidParameters,MistOptionsisMistSettings,SeabedParamsisSeabedParameters. Every settings class isfinalwith aconstconstructor and acopyWithover every field; a nullable field is reset withcopyWith(clearX: true).dart fixcarries the renames. -
Breaking: American spelling in identifiers, as Flutter and Dart use.
colouriscolor,sunColourissunColor. Only the Dart names changed: a file keeps the keys it was written with, anddart fixcarries the renames. -
Breaking: the elements split into a simulation and a view.
ElementsSimulationsteps the world, the flames and every element with no device or renderer;Elementsdraws it (draw) and still steps it inupdate.ElementsSimulationPluginsteps it in a loop'selementsphase with its state a snapshot part, andElementsViewPlugindraws it in the frame.Elements.overdraws a simulation something else steps. -
Breaking:
ElementFieldsis backend-neutral. An element's step reads and writes bodies asElementBodyand places asWorldPosition;NativeElementFieldsis the core's, with its fires and waters beside. -
SeabedParametersandLiquidParameters: typed accessors generated from the two materials, whichSeabedLookandLiquidLooknow set their uniforms through. Neither look's API changed. -
1.0.0 is a promise: strict semver from there. This release candidate already keeps it. A patch fixes bugs and breaks nothing, a minor adds, and a break waits for a major. The whole public API is stable, with no experimental exceptions, and is held to the snapshot in
api/. A deprecated name stays until the next major and for at least six months, and says what replaces it. CONTRIBUTING.md has the rules, and SUPPORT.md says which releases get fixes and on which platforms. -
The liquid and seabed bundles are rebuilt against the engine's headers, which now read the sun's shadow map in whichever way round it keeps its depth —
A2.8. -
A new element is a Dart hook over the world, and fire and water are two. An
ElementHooksteps in its own phase (elements.<id>, after the engine'selementsand beforerules), reading and writing the world's heat, water, wind and forces throughElementFieldswithPortablearithmetic; draws once a frame throughview; and keeps what the world's snapshot does not throughsaveandrestore.installElementputs one into anEngineLoopandElementPluginmakes one a plugin.Elements.addElementadds one to the elements' own update, andsaveElements/restoreElementscarry every element's state, the flames still held among them.Elementsruns its fire and water through the same hooks, in the order it always ran them, so nothing it draws or steps moves. -
ElementsStepsswitches plugin elements too.elementsholds a switch per element id,isOnasks one,withElementsets one, andElementsSteps.noneswitches every unnamed element off. A switched-off element is not drawn or heard and still steps, as fire and water are.ElementSwitchesis the engine's registry of the switches elements declare, and refuses one id twice. -
The elements speak on the bus.
Elements.publishTopublishes the world's events asElementEvents by kind, with what plugin elements publish from their steps.ElementEventKindsholds the core's kinds and the ones plugins add withNativeEventKind.plugin, and refuses a code or a name claimed twice, naming both claimants.ElementsListener.toBusmakes the listener that publishes each callback as its event (ElementCaught,ElementOut,ElementBurntOut,ElementWetted,ElementBurnerOut,ElementExploded,ElementsOverBudget,ElementFireSeen,ElementFireLost);Elements.listenerstays the field it is set on.ElementExplodedis aPlacedEvent, so an effect document triggered byelements.explodedgoes off where the charge did. -
The effects fall by their world's gravity. Embers drop, falling water is heard and mist is thrown up by the
NativeWorld'sgravityMagnituderather than a 9.81 of their own, so a world set on the Moon has Moon embers, a quieter falls and more mist.mistShareandMistSettings.shareAttake the world'sgand the liquid'sviscosity(water's preset when none is given);LiquidViewtakes the liquid'sproperties, whichElements.addWaterhands it, and weighs its mist by that density;PhysicsHearing.listendefaults to water's preset density. The air density in the mist law stays the 1.2 kg/m³ the handbook's correlation was fitted in, as part of that law. A world with the Earth's gravity draws and hears to the bit what it did. -
An ember is dragged through its world's air.
FireViewworks the air's density out of the world'sairTemperatureandairPressureas an ideal gas, ρ = p M / (R T), each frame, in place of a fixed 1.18 for air at 300 K: a fire in a cold world drags its embers harder, one up a mountain less. In the standard world that is 1.204, so embers lag their gas a little more than they did, which moves every frame with embers in it: the effects' fire goldens are re-recorded before the release. -
Water poured into a world is as warm as that world's air.
Liquid.water()without a temperature isatAirTemperature, andElements.addWaterpours it at the world'sairTemperature—Liquid.heatIn(world). One given a temperature, or a heat of its own throughcopyWith, keeps it. -
Smoke as dark as its fuel makes it.
FireViewdraws each fire's smoke with the soot its fuel makes, the core'sNativeFire.sootYield, in place of wood's for every fire: a tyre's plume is three times as dark as a crate's, glowing charcoal sends up none.FireView.plumeDepthtakes asootYield, wood's when it is not told; 8.7 m² a gram stays for every fuel (doc/smoke_plume.md). -
Mist as much as the fall makes.
MistSettings.shareis no longer needed: left out, the share of landing water that goes up as mist is the airborne fraction measured off falling water at the speed it lands, 3·10⁻⁴ at 10 m/s and rising as the speed to the 3.3, at most 1.5 %, and its droplets 14.8 µm, that spill's Sauter mean (doc/mist_share.md,mistShare). The demos no longer set a hundredth by hand. -
Igniters that were measured.
Igniter.match,lighter,propaneTorchandpilot, from NBS Monograph 173, Williamson's lighter flames and the FAA's fire-test burners, withcopyWith(doc/igniters.md). -
Every step of the elements can be switched off, in any combination, and they tell the game what happens.
Elements.switchestakes anElementsSteps— the fires'FireSteps(flames, smoke, embers, firelight, charring), the waters'LiquidSteps(surface, falling sheet, drops, mist, bubbles) and sound — each on its own; a step switched off costs nothing and leaves nothing of itself drawn or heard, and the world steps the same.Elements.listener, anElementsListener, is called fromupdatein the order the core said things: caught, out, burnt out, wetted, burner out, exploded; a step drawing less than it wanted (budget); a fire coming into or leaving the camera's picture (seen,lost).heatFluxAtgives the radiant heat on a point from every fire (Modak's point source, capped by the soot's σT⁴),burnDoseRateISO 13571's burn dose for it,waterAtthe water standing at a point, andseenThroughSmokehow much light gets through the plumes between two points. -
Water, fire and bodies in a few lines.
Elementsowns an effects world, steps it, keeps each look on its body, draws and hears it:addWaterlays a pond or a river over aHeightfieldwith aLiquidand aBedwhose roughness is Chow's Manning n, andWaterBodyfills a basin, pours, adds springs, weirs and drains, and sets its edges and walls;addBodymakes aSolidof a material by its density;followpushes water and fire with a game's own object and is never moved back, so replays stay as they were;fireslights a body by holding anIgniterto it for its time, feeds burners, sets charges off and douses.Elements.adoptdoes the same over a world a game steps itself. -
Fires sized and lit by their own heat.
FireViewtakes each fire's base, the share of its body alight and its reach from the core, so one view draws a candle and a burning hall alike, with no width to set.FireLightslights by the lumens a blackbody at the soot's temperature radiates (Blackbody, the CIE 1931 observer against Planck's law), in its colour, gathered per fire, per cluster or not at all, with nothing capped. A watched look goes black by the share of it the core's char covers and glows at the char's temperature, and stays charred once the fire is out. A tongue of flame is as bright as the soot in it, a blackbody at its temperature through the flame's emissivity, cooling as it rises by McCaffrey's centreline excess. The smoke is as dark as its plume carries soot, τ = 2K_mṁ_s/(πbu) across it, thickest over the flame and thinning as z^(−2/3) as it climbs (doc/smoke_plume.md). -
Water's look from its optics.
LiquidOpticsis one pair of absorption and backscatter coefficients, 1/m, shared by the surface andSeabedLook; ripples steepen with the wind as Cox and Munk measured and fade as they shrink below a pixel.MistSettingssets the mist where a fall lands by its droplets' size, not by hiding a node.HearingScaleis the game's to set. -
Water that ends at its shore and does not tile.
LiquidViewdraws a dry cell at the shore level with the water beside it, not down at its ground, so the surface runs flat into the bank and ends where it meets the ground — over voxels in steps a metre high there are no more glassy wedges along every edge. A film on a step whose ground stands over the water below it is drawn as that water's bank, so no slanting sheet crosses the step's face, while a river running down a slope or from its shallow side to its deep middle is left whole. Where the water stands over a dry cell, at a drop or a flat shore, it thins out short of halfway when it is a film and at halfway when it is deep, further into a bay of wet cells than past a lone corner, so the edge is not a staircase of cells.LiquidLook's ripples are nine waves, 3.1 m down to 23 cm, in no ratio of small whole numbers and mostly running with the wind, over a plane bent at two scales and roughened in drifting gusts, so the pattern never repeats; they are gentler than the six they replace and calm where the water thins. Water hides the bed as much as the refracted ray's length through it says, the sky turns gently from horizon to zenith in it so a ripple at a low angle does not flash between the two, the sun's glint is as strong as Fresnel lets it be, and the last six centimetres of depth fade out, so a film at the shore is all but unseen, not the pale rim it was. Froth drifts in flecks a hand's breadth across that the flow carries, also where water deep enough to break runs fast, and the thin front of water arriving over dry ground shows the ground through it, a wet sheen rather than a pale slab.SeabedLook's caustics follow the same nine waves. -
Falling water that falls.
LiquidView's sheet off a lip is drawn withLiquidLooktoo: clear and glassy at the lip, mirroring the sky; torn into streaks down the fall, with lumps running down them as the flow pulses, the pattern riding with the water; whitening streak by streak as air is torn in. A strand that plunges into water goes in whole; one the core parts into drops in the air frays through over the last of the twelve e-folds its ripples grow to part it (Grant and Middleman), and goes on falling as a veil of those drops, so no strand stops short in mid-air. A liquid that lets no light through falls in its own colour and glow. -
Drops, mist and bubbles drawn as the light they stop. Millimetre drops a few metres off are far under a pixel, and a falls' spray is what they hide together: each piece of drops the core throws is drawn as a cloud spread over the cell and the step it came from, as deep as van de Hulst's extinction makes its drops — twice their cross-section for spray, next to nothing for drops far finer than light — thinning out normally to a rim it reaches nothing at, so the pieces add up to an even veil rather than a few beads. The mist where drops land and the bubbles a plunge drives down are drawn the same way, the bubbles kept under the surface; the mist is carried out over the pool the way the water was going, in billows, not heaped in one dome over the foot. The froth the bubbles bring up spreads round in a plume that fades into the pool, not a square of cells.
-
The physics heard.
PhysicsHearingreads off a world what a listener would hear: a source for each fire as loud as its watts, for falling water as loud as the power it gives up falling, and a splash where a watched body enters a liquid as loud as the energy it enters with, each on a logarithmic scale, as hearing is, and a little lower in pitch the bigger it is. No audio here: a game plays them. A fire, falling water and a splash, synthesised bytool/make_sounds.py, ship inassets/. -
A sea floor lit through its surface, and a surface seen from below.
SeabedLookdraws a floor with the caustics the surface's own ripples focus on it — geometric optics, 1/|det(I + a·H)| with a = d·(1 − 1/n), blurred by the sun's half degree — and the colour water takes out of the light, red first, on the way down and back up to the eye. Over the floor the light averages to what fell on the surface.LiquidLook's surface, seen from under it, is Snell's window: the sky in a cone of 97°, a mirror of the water outside it.SeabedLook.underdresses anything else under the same sea — a rock, a hull, a diver — in its own colour with the floor's stages and parameters, so one update moves the caustics on all of it and the water reddens it away with distance as it does the floor. -
The physics core's water and fire, drawn, in a package of their own.
LiquidViewdraws one water offlutter3d_physics_native: its surface with theLiquidLookmaterial — ripples the flow carries, Fresnel's sky, the sun's glint, colour by depth, froth where there is air — and the sheet off a lip as one sheet, its drops and its bubbles.FireViewdraws every fire of a world: tongues risen at the speed of a flame's gas along the core's leaning axis, lit smoke at the plume's speed, embers, firelight, and the watched bodies charring as they burn. Plain Dart, with the material shipped compiled asLiquidLook.asset.