Skip to main content

flutter3d_effects 1.0.0-rc.2 copy "flutter3d_effects: ^1.0.0-rc.2" to clipboard
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.dispose takes the fires' particles out of the frame, and Elements.dispose calls 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.listen answers a Registration that stops hearing the liquid, as every listen does; unlisten stays, and a call that ignored the answer compiles as before.

  • Breaking: the sky the water mirrors is in nits. LiquidLook.sky and Elements.sky take the zenith's luminance in 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 as glow is. 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.sun and SeabedLook.sun take the sun's color and its illuminance in lux, as a directional LightNode does, where they took "colour times intensity" in the renderer's own scale; Liquid.glow and LiquidLook.glow are each channel's luminance in nits, as an emissive material's is. Both are turned into the renderer's scale inside. LiquidParameters and SeabedParameters, which wrote the shader's scale, are the package's own now. A colour written in the old scale is the same picture at illuminance: LightNode.defaultIntensity, or times 1843.2 nits for a glow.

  • Breaking: a heat release is in watts. FireView.plumeDepth takes a fire's power in W, and FireView.watts is FireView.power; Blackbody.color and efficacy name their parameter temperature.

  • Breaking: Elements.listen(listener) answers a Registration, where the getter and setter Elements.listener held one listener.

  • Breaking: Elements.addBody takes orientation: and angularVelocity:, where it took turn: and spin:. dart fix renames the arguments.

  • Breaking: no public late final setter. LiquidView.sheetNode and LiquidView.surfaceNode are 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. placeKernelLiquid asks FrameCompute.placeHosted where flutter3d_physics_native's liquid kernels run and builds its KernelLiquid there: 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 as NativeLanes, stating KernelLiquid.nativeTolerance, and its rule decides when they run.

  • Breaking: results that were records are final classes. Elements, FireView and LiquidView answered or held a record, which can never gain a field. Each answers a final class now, with the record's field names (a positional $1 has a name of its own), == and hashCode. A field read compiles as before; a destructuring pattern names the class, and flutter3d_build:migrate rewrites the $1 reads.

  • Breaking: LiquidLayerMesh is a class, and collides: a CollisionFilter. The layer-and-mesh pair liquidMeshes answers is a final class with the record's layer and mesh, == and hashCode; Elements.addBody and follow take collides: as flutter3d_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 a ComputeWorkload: 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, ClothWorkload and FluidWorkload (new) are the physics core's visual systems as compute workloads, each the system it steps (NativeParticleCloud, DebrisSystem, ClothSystem, FluidSystem): handed to a renderer with addWorkload, 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. LiquidView hands 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, update leaves the surface, the sheet and the spray as they were last drawn; the first update after 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 and LiquidLook.sun's light, SeabedLook.sun's, sky's zenith and horizon, LiquidLook.glow and Liquid.glow. The generated LiquidParameters and SeabedParameters are over a MaterialParameters and keep vectors, the in-place buffers the shader reads.

  • LiquidView.update takes dt: by name.

  • Breaking: ElementsViewPlugin is flutter3d_effects.elements by default, where it was elements.view: elements is an area of the engine's events, which no plugin id may take.

  • Breaking: colours in are LinearColors. Blackbody.color answers one; SeabedLook.under takes the floor's neighbour's colour as one, and FireView.watch its fresh and charred (still blended through their sRGB encoding, as a person sees char spread).

  • Breaking: Audible takes named arguments (key:, at:, loudness:, rate:).

  • The fire's glow reads the material's emissiveStrength instead 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: import flutter3d_elements beside this. Elements, ElementsViewPlugin, ElementsQuality, Liquid and 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.look is elements.lookOf(body); WaterBody.view and WaterBody.look are elements.viewOf(water) and elements.waterLookOf(water). A water dug with setGround is drawn on its new bed from the next frame.

  • liquidMeshes, LiquidLayerMesh, jetMesh and particleMesh come here from flutter3d_core: a liquid in a vessel and a jet, drawn, are views of the physics, and the core no longer depends on it.

  • FireView.plumeDepth is SmokePlume.depth of flutter3d_elements, which the simulation's seenThroughSmoke reads too; the numbers are unchanged.

  • Systems run in LoopPhase.fields, the elements phase's new name, and Portable and the vector_math crossings come from flutter3d_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. Pose is ElementPose, Heightfield is ElementHeightfield, and the body the elements made or track is TrackedBody (ElementBody is the hook's handle on a core body, which already had the name). A game that imports this and flutter3d_sim together no longer hides Pose, Body or Heightfield. 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 on flutter3d_build: a game that depends on the effects resolves no MCP server, dart_mcp or editor core through them.

  • Breaking: one suffix for settings, Settings, and Descriptor in the HAL. LiquidParams is LiquidParameters, MistOptions is MistSettings, SeabedParams is SeabedParameters. Every settings class is final with a const constructor and a copyWith over every field; a nullable field is reset with copyWith(clearX: true). dart fix carries the renames.

  • Breaking: American spelling in identifiers, as Flutter and Dart use. colour is color, sunColour is sunColor. Only the Dart names changed: a file keeps the keys it was written with, and dart fix carries the renames.

  • Breaking: the elements split into a simulation and a view. ElementsSimulation steps the world, the flames and every element with no device or renderer; Elements draws it (draw) and still steps it in update. ElementsSimulationPlugin steps it in a loop's elements phase with its state a snapshot part, and ElementsViewPlugin draws it in the frame. Elements.over draws a simulation something else steps.

  • Breaking: ElementFields is backend-neutral. An element's step reads and writes bodies as ElementBody and places as WorldPosition; NativeElementFields is the core's, with its fires and waters beside.

  • SeabedParameters and LiquidParameters: typed accessors generated from the two materials, which SeabedLook and LiquidLook now 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 ElementHook steps in its own phase (elements.<id>, after the engine's elements and before rules), reading and writing the world's heat, water, wind and forces through ElementFields with Portable arithmetic; draws once a frame through view; and keeps what the world's snapshot does not through save and restore. installElement puts one into an EngineLoop and ElementPlugin makes one a plugin. Elements.addElement adds one to the elements' own update, and saveElements/restoreElements carry every element's state, the flames still held among them. Elements runs its fire and water through the same hooks, in the order it always ran them, so nothing it draws or steps moves.

  • ElementsSteps switches plugin elements too. elements holds a switch per element id, isOn asks one, withElement sets one, and ElementsSteps.none switches every unnamed element off. A switched-off element is not drawn or heard and still steps, as fire and water are. ElementSwitches is the engine's registry of the switches elements declare, and refuses one id twice.

  • The elements speak on the bus. Elements.publishTo publishes the world's events as ElementEvents by kind, with what plugin elements publish from their steps. ElementEventKinds holds the core's kinds and the ones plugins add with NativeEventKind.plugin, and refuses a code or a name claimed twice, naming both claimants. ElementsListener.toBus makes the listener that publishes each callback as its event (ElementCaught, ElementOut, ElementBurntOut, ElementWetted, ElementBurnerOut, ElementExploded, ElementsOverBudget, ElementFireSeen, ElementFireLost); Elements.listener stays the field it is set on. ElementExploded is a PlacedEvent, so an effect document triggered by elements.exploded goes 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's gravityMagnitude rather than a 9.81 of their own, so a world set on the Moon has Moon embers, a quieter falls and more mist. mistShare and MistSettings.shareAt take the world's g and the liquid's viscosity (water's preset when none is given); LiquidView takes the liquid's properties, which Elements.addWater hands it, and weighs its mist by that density; PhysicsHearing.listen defaults 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. FireView works the air's density out of the world's airTemperature and airPressure as 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 is atAirTemperature, and Elements.addWater pours it at the world's airTemperature — Liquid.heatIn(world). One given a temperature, or a heat of its own through copyWith, keeps it.

  • Smoke as dark as its fuel makes it. FireView draws each fire's smoke with the soot its fuel makes, the core's NativeFire.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.plumeDepth takes a sootYield, 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.share is 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, propaneTorch and pilot, from NBS Monograph 173, Williamson's lighter flames and the FAA's fire-test burners, with copyWith (doc/igniters.md).

  • Every step of the elements can be switched off, in any combination, and they tell the game what happens. Elements.switches takes an ElementsSteps — 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, an ElementsListener, is called from update in 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). heatFluxAt gives the radiant heat on a point from every fire (Modak's point source, capped by the soot's σT⁴), burnDoseRate ISO 13571's burn dose for it, waterAt the water standing at a point, and seenThroughSmoke how much light gets through the plumes between two points.

  • Water, fire and bodies in a few lines. Elements owns an effects world, steps it, keeps each look on its body, draws and hears it: addWater lays a pond or a river over a Heightfield with a Liquid and a Bed whose roughness is Chow's Manning n, and WaterBody fills a basin, pours, adds springs, weirs and drains, and sets its edges and walls; addBody makes a Solid of a material by its density; follow pushes water and fire with a game's own object and is never moved back, so replays stay as they were; fires lights a body by holding an Igniter to it for its time, feeds burners, sets charges off and douses. Elements.adopt does the same over a world a game steps itself.

  • Fires sized and lit by their own heat. FireView takes 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. FireLights lights 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. LiquidOptics is one pair of absorption and backscatter coefficients, 1/m, shared by the surface and SeabedLook; ripples steepen with the wind as Cox and Munk measured and fade as they shrink below a pixel. MistSettings sets the mist where a fall lands by its droplets' size, not by hiding a node. HearingScale is the game's to set.

  • Water that ends at its shore and does not tile. LiquidView draws 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 with LiquidLook too: 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. PhysicsHearing reads 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 by tool/make_sounds.py, ship in assets/.

  • A sea floor lit through its surface, and a surface seen from below. SeabedLook draws 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.under dresses 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. LiquidView draws one water of flutter3d_physics_native: its surface with the LiquidLook material — 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. FireView draws 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 as LiquidLook.asset.

0
likes
140
points
196
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

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.

Topics

#effects #water #fire #graphics

License

MIT (license)

Dependencies

flutter3d_build_hooks, flutter3d_core, flutter3d_elements, flutter3d_foundation, flutter3d_hardware, flutter3d_matter, flutter3d_particles, flutter3d_physics, flutter3d_physics_native, flutter3d_plugin_api, flutter3d_shaders, hooks, vector_math

More

Packages that depend on flutter3d_effects