flutter3d_plugin_runtime 1.0.0-rc.2
flutter3d_plugin_runtime: ^1.0.0-rc.2 copied to clipboard
Plugins loaded while a game runs: data plugins read from a .f3dplugin document, and sandboxed Wasm modules on a deterministic interpreter, held to the permissions granted.
1.0.0-rc.2 #
-
Breaking: every file a data plugin fetches is pinned, and plain http is refused. Only Wasm modules from a URL were pinned by their hash; a material, a section's file or an expression source was read as whatever the server answered. Each remote file now needs its SHA-256, under its declaration's
sha256(ExpressionSystemSpec.sha256is new) or the document's newintegritymap (DataPluginDocument.integrity), andhttp:is refused except from localhost. -
A key the format brought later is not read from an older document.
DataSections.runtimeKeysSincesays the version each runtime key came in; a document older than a key keeps its copy inextra, written back as it was, so junk an old file carried cannot gain a meaning. -
A Wasm runtime says the highest ABI it links.
WasmRuntime.maxAbianswers 3 unless a runtime says more, the engine's two answerwasmPluginAbiMax, and a module above a runtime's number is refused at install, naming both: a runtime from outside stays right when the engine brings ABI 4. -
A Wasm plugin is held to the id rules when it is made.
WasmPluginchecksPluginManifest.idProblem,f3dincluded, before it is installed. -
A Wasm system declares the fields it touches. It was added to the loop with no
reads:orwrites:, so two modules writing one field with nothing ordering them were never named. It now reads each field it declares and writes those markedwrite, byWorldFields.stateOf(world_field.heat), and the loop names such a pair. -
A render module on the browser's runtime is held by a clock. The browser's WebAssembly counts no fuel, so
WasmLimits.fuelPerFrameheld nothing there; now a frame's call on a runtime that is not metered is timed, and one longer thanWasmRenderNode.frameTimeLimit(50 ms by default) switches the node off as a trap does. CONTRACTS says the browser is the exception to counting fuel. -
A Wasm render module's memory is held to one rule on every runtime. One that imports
param_floatsexports its memory, and one with a memory declares a maximum within its limits'memoryPages: refused by name at decode and when itsWasmRenderNodeis made, where the browser runtime refused both only at the first frame and the interpreter never. -
New:
DataSections.reservedKeys, andvertexLayoutsrefused. A.f3dpluginnaming a key reserved for a later minor is refused when it is read, naming it, and no section may take one: a plugin's own vertex layouts, which nothing of the engine binds yet, were read and ignored, and the minor that binds one would have changed what such a plugin draws. -
A world field's name taken is a
NameTakenException.WorldFields.addrefused it with anArgumentError, naming both owners; it still names both. -
Breaking:
DataSections.registerisadd. A registry's verb isadd, as every other registry's is, with the sameRegistrationin answer.dart fixrenames the calls and the overrides. -
Breaking: a time in a
doublesays seconds in its name.WasmRenderImports.timeisWasmRenderImports.timeSeconds; the value and its unit are what they were.dart fixcarries each rename out. -
Breaking: Wasm render modules, ABI 3. A
.f3dplugin'swasmRendersection declares a module that drives one of its render steps frame by frame (WasmRenderSpec, run as aWasmRenderNode): decoded as a render module, so it may compute inf32and needs nof3d_step, run in an instance of its own outside every save and digest, its commands imports with scalar arguments (param,param_floats,draw,time,view_size,light_code) naming what the declaration lists by index, and metered per frame (WasmLimits.fuelPerFrame). A trap switches the node off with the plugin named, and the frame is drawn. The browser's own WebAssembly runs it as the interpreter does.wasmPluginAbiMaxandwasmRenderAbiare 3, andDataSections.runtimeKeysgainswasmRender. -
Breaking: a render module's imports are a final class the runtime makes.
WasmRenderImportsis made over a declaration's parameter count and light names, runs each frame's callduringthe frame it is handed, and turns what the frame refuses into a trap; a runtime calls its members, one per import, and nobody extends it. It hands the frame eachparamandparam_floatsas oneRenderParameterWrite. -
Breaking: a module from a URL is pinned by its hash.
WasmSystemSpecandWasmRenderSpectake asha256, whose keyWasmSystemSpec.keysgains; a module fetched from anhttps:URL without one, or whose bytes hash to another, is refused before anything is installed (wasmIntegrityRefusal). A module of the plugin's own directory is not checked. -
A data section's name already taken is a
NameTakenException.DataSections.registerrefused a second section under one name with anArgumentError; it is thePluginExceptionevery registry throws for a name already taken now, naming the name. A name the runtime reads itself is still anArgumentError, since no plugin can ever have it. -
A plugin's entries keep the keys a later minor gave them.
DataPhase,DataEventDeclaration,ExpressionSystemSpecandWasmSystemSpechold what theirkeysdo not name inunknownand write it back, so a tool of this build saving a later.f3dpluginkeeps what that build said inside each phase, event and system. -
The Wasm plugin ABI's vocabulary is a file.
api/wasm_abi.vocabularyholds the newest ABI and the oldest a host runs (1, through 1.x), and every import and export with the ABI it arrived in;dart run tool/wasm_vocabulary.dartwrites it, a test keeps it current, and a structure rule holds it to the base recorded at the tag, so an import added under an ABI a 1.0 host already runs is caught. -
A Wasm system orders itself against another of its plugin's by the name the document gives it.
wasm[].afterandwasm[].beforenaming a system of the same document are filed under<id>., as its phases are; any other name is the loop's as written, so a document that already wrote<id>.blowreads as before. -
Render nodes are a capability their export names, not an ABI number set aside.
wasmRenderAbiis the lowest ABI they can arrive in, one pastwasmPluginAbiMax; the release that implements them names the ABI they arrived in, as an import's, so a minor that only adds a simulation import takes the next number without them. -
Breaking: a Wasm module's save has one shape, whichever runtime wrote it.
globalsholds each mutable global the module exports by its export name, where the interpreter wrote every global as a list and the browser its exported ones; the interpreter writes the rest asinternal, which a digest leaves out and the browser ignores, andWasmSystem.savenames theruntime(new:WasmSystem.runtime,digestible). A run the browser recorded is replayed by the interpreter to the same digests. A data plugin's snapshot part is at version 2. A simulating module is refused a runtime that counts no fuel under a bit-exact profile, naming both: one that runs out traps only on the interpreter a replay steps it on. -
Breaking: a Wasm runtime and its instances take one context per call.
WasmRuntime.instantiatetakes aWasmInstantiation(new) with the module, its imports and its limits, andWasmInstance.stepaWasmStep(new) with the step and its length in Q16.16, which the system reuses from step to step so a step allocates nothing. A runtime written outside (wasmtime, a JIT) then keeps compiling when a minor hands it more.WasmImportskeeps the ABI's own shapes. -
Breaking:
.f3dpluginversion 4 files a phase under the plugin. A phase a document declares is added to the loop as<id>.<name>, as its events and Wasm systems already were, and so is everyafter,before,wasm[].phaseandexpressions[].phasethat names one of the document's own phases; the engine's and other plugins' are named as written. A version-3 phase already written as<id>.<name>is lifted to<name>, so it is not filed twice. An entity type a document declares is in its namespace (glow.vent), as every name a plugin registers is. -
Breaking:
DataPluginDocument.sectionsholdsDataPluginSections (new), a class withreaderandsection, where it held a record, so a later minor can say more of a section read. -
Breaking:
WasmModuleno longer shows the interpreter's compiled code.functions,data,functionTypesandglobalswere of types the package does not export; a runtime from outside compilesbytes. -
A data section and a world field a plugin adds are in its namespace.
DataSectionsandWorldFields.addrefuse a plugin's bare name with aPluginException, as every registry does. -
wasm.trappedis declared once for the engine and kept, rather than by the first module that needed it and withdrawn with it. -
Render nodes have a reserved ABI.
wasmRenderAbi(3) andwasmRenderNodeExport(f3d_render_node) name the Wasm plugin ABI that brings render nodes. No host runs it yet: a module that says ABI 3 is refused with the range named, as before, and ABI 1 and 2 modules are unchanged. -
The runtime depends on the plugin API alone.
entityKinds,materialsandrenderStepsare sections likeeffects, read by the package that owns what they install through the plugin API'sDataSectionRegistry:entityKindsSectionandDataEntityKindare inpackage:flutter3d_sim/data_plugins.dart;materialsSection,renderStepsSection,renderDataSections,DataMaterial,DataRenderStep,RuntimeShaders,RuntimeRenderStep,RuntimeShadersException,RuntimeBackends,runtimeMaterialBundle,spliceMaterialWgsl,fullscreenMaterialWgslandruntimeShaderSdkare inpackage:flutter3d_core/data_plugins.dart.DataPluginDocumentlosesentityKinds,materialsandrenderSteps(they are insectionswhen read, inextrawhen not), andflutter3d_core,flutter3d_sim,flutter3d_shaders,flutter3d_physicsandflutter3d_hardwareleave the pubspec: a server replaying a run with a data plugin no longer resolves the render core. -
ScriptRuntimeis gone, andscriptsisexpressions. No script runtime ever shipped; the expression language covers what a script was for.ScriptRuntime,ScriptProgram,ScriptContext,ScriptSystem,ScriptSystemSpec,ScriptException,ScriptFormatExceptionandinstallScriptSystemgo;ExpressionSystemSpecandDataPluginDocument.expressionstake their place. The format is at version 3, whose migration reads a version-2scriptsentry as an expression system with itssourcekept, and the v3 fixture is minted. This build reads expression systems and refuses, by name, to install a plugin that brings one. -
A Wasm module's state is checked before it is restored. The interpreter and the browser runtime refuse with a
WasmFormatExceptiona negative or out-of-range page count, memory that is not base64 or does not fit its pages, and globals of the wrong count or not whole numbers, and leave the module's memory and globals as they were; they used to wipe the memory first. -
Breaking: the subsystems read their own sections.
effects,physicalMaterialsandmaterialPairsare read by the sectionsflutter3d_particlesandflutter3d_matterregister in aDataSectionRegistry(DataSectionshere), handed toDataPluginLoader(sections:)and toDataPluginDocument.parse. The document'seffects,effectSources,physicalMaterials,materialPairs,DataPluginDocument.requiresPhysicalMaterialsandDataPlugin.placeDataEventare gone: a section read is inDataPluginDocument.sections, andDataPlugin.numbersOfDataEventis what an event places an effect by. This package no longer depends onflutter3d_particlesorflutter3d_physics. The file format is unchanged; a section no reader takes is kept as written, and the plugin's notes say so. -
Data plugins declare physical materials. A
.f3dplugin'sphysicalMaterials(andmaterialPairs) are read with the catalogue's codec, checked for plausible SI numbers and a source per group, and registered under the plugin's id; a document with them requiresf3d.physicalMaterials. -
Breaking: every thrown type is named
*Exception(decision H):PermissionRefusedisPermissionException,ScriptRefusedScriptException,WasmRefusedWasmException,WasmTrapWasmTrapExceptionandRuntimeShadersRefusedRuntimeShadersException, each with the same members. -
A data plugin's outside-world state is in the loop's snapshots. Installed, a plugin with Wasm systems or scripts adds what they keep (
DataPlugin.save) as a part under its id, so a rewind, a rollback and the double-step check cover it. -
Breaking:
RuntimeShaderstakesaddMaterialsas a function returning aRegistration,renderer.renderSteps.addMaterials, and noremoveMaterials: cancelling the registration takes a library out. The renderer's ownaddMaterialsandremoveMaterialsare gone. -
Breaking: a boolean reads as a question, and no
boolis positional.WasmInterpreter.meteredisisMetered;WasmRuntime.meteredisisMetered.dart fixcarries the renames. -
Breaking: American spelling in identifiers, as Flutter and Dart use.
normaliseisnormalize. Only the Dart names changed: a file keeps the keys it was written with, anddart fixcarries the renames. -
Breaking: a render step can stand at another plugin's anchor.
DataRenderStep.anchoris the anchor's name (aString, where it was aRenderAnchor), and the engine resolves it through the renderer (RendererSteps.anchorNamed) when the plugin is installed, so an anchor a plugin added withRendererSteps.addAnchoris one a data plugin can name. An engine anchor is still checked when the document is read; a plugin's is checked at install, against the side of tone mapping its engine anchor is on, and a name the renderer does not have is refused there with the list of anchors it does. -
Breaking:
.f3dpluginis version 2, in the format envelope. A document starts{"format": "f3d.plugin", "version": 2, ...}(DataPluginDocument.format) instead of{"f3dplugin": 1}. No section changed; a build from before refuses a version-2 document as having no version rather than misreading it. Version 1 documents still read. -
A Wasm host runs a range of ABIs.
wasmPluginAbiMin(1) towasmPluginAbiMax(2);wasmPluginAbiis the newest. A module outside the range is refused with the range named, so a module built for ABI 1 keeps loading. -
Imports are feature-detected. Each host function names the ABI it arrived in (
wasmImportSince); a module that imports one newer than the ABI it declares is refused naming it (wasmAbiRefusal), and one that leaves an optional import out is fine.WasmModule.importNameslists what a module asks for, andWasmInstance.abiwhat it said. -
A field says its unit and its scale.
WasmFieldSpec.unit("m","K") andfractionBits("fraction"in a document, 16 by default): Q16.16 holds ±32 768, which is not a world position, and 8 bits hold ±8 388 608 m at 4 mm. ABI 2'sf3d.field_fractells a module what it was given, and a field declared with anything but 16 is refused to an ABI-1 module at install.FixedPointconverts at any number of fraction bits;Fixed16is its 16-bit case. -
Breaking: declarations throw typed exceptions instead of
dart:core'sFormatException:WasmFormatExceptionfor a Wasm system, its fields, its limits and a module's saved state;ScriptFormatExceptionfor a script;DataPluginFormatExceptionfor an entity kind.WasmImportsgainsfieldFractionBitsandWasmInstancegainsabi, both with defaults. -
The run-time plugins' refusals are
PluginExceptions.PermissionException,ScriptException,WasmExceptionandWasmTrapExceptionextend it and inherit itsmessage.DataPluginFormatExceptionextendsFlutter3dFormatException, andRuntimeShadersExceptionextendsCapabilityException, because a platform that cannot compile shaders at run time lacks a capability. All of them sit underFlutter3dExceptionfromflutter3d_plugin_api. -
A render step written in the material language. In a
.f3dplugin,"shaders": {"material": "fog.f3dmat"}is afullscreensource built for whichever backend the engine draws with,RuntimeRenderStep.materialStage. On WebGPU it is written as WGSL whole (fullscreenMaterialWgsl) at the locationRuntimeShaders(webGpuFullscreenUvLocation:)gives. On the software backend and WebGL2, a material'svertexblock becomes its vertex stages at run time. On WebGPU at run time, the vertex block, the scene depth and the hooks are refused with the reason, and the build compiles them. A premultiplied blend andviewDepthare spliced in. A compute kernel is refused at run time on every backend. -
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. -
Plugins loaded while the game runs. A
.f3dplugindocument is a plugin written as data: loop phases, events, entity kinds, materials, render steps, Wasm systems and scripts.DataPluginLoaderreads it and every file it names, and theDataPluginit returns installs through the same host as a compiled plugin, switched at a step boundary and journalled like one. The format is versioned (f3dplugin1, with a fixture), reads older documents through a migration list, refuses a newer one with the version that reads it, and keeps the keys it does not know. -
Permissions are enforced where access is handed out. A permission a run-time plugin uses must be declared in its manifest and granted by the application (
PluginGrants). The plugin's own files need nothing; a URL needsnetworkand the application'sfetch; a path outside the plugin's directory needsfilesand the application'sreadFile. A permission declared and not granted refuses the plugin before any file is read. -
Wasm modules as step systems, under an ABI of their own. Wasm plugin ABI 1 is 32-bit integers only, so a module gives one answer on the VM, in a browser and on a replaying server; it reaches the world through four imports (
field_len,field_get,field_set,publish) and has no I/O at all. A plain Dart interpreter decodes, validates and steps a module on every platform, metered by fuel, so running out lands on the same instruction in every replay. The browser's own WebAssembly is there on the web, unmetered. A trap latches the system off and publishesWasmTrapped; its state, latch included, saves and restores. -
Materials and render steps compiled at run time, where they can be.
RuntimeShadersbuilds a material in the material language for the software backend, WebGL2 and WebGPU, and a raw GLSL ES render step for WebGL2. On WebGPU no compiler runs:spliceMaterialWgslwrites the material's body as WGSL into the engine's own compiledUnlitstage, whichflutter3d_webgpu'swebGpuMaterialHost()hands over aswebGpuHost, and its uniforms become aMaterialParamsblock at the next free binding. A material with alightblock, one readinginstance, or one sampling a map other than the base colour is refused there with the reason and built fromassets_src/instead. Impeller compiles shaders ahead of time, so on it the material or step is switched off with the reason, and the rest of the plugin installs. -
A plugin's effects load.
.f3dplugin'seffectsnames.f3dfxdocuments bysourceor carries them in place; the loader reads them with the rest of the plugin's files and installs them into the engine'sParticleEffects, as<plugin id>.<name>, with their triggers on the bus. A trigger naming one of the plugin's own events listens for it under the plugin's prefix, and aPluginDataEventwhose first values are a position in Q16.16 places the effect (DataPlugin.placeDataEvent). An entry that is neither a source nor a document is kept as written, as version 1 kept the whole section, and the plugin's notes say so. -
The world's fields, by name.
WorldFieldsis the registry an application fills with the fields a run-time plugin may reach, andFixed16converts their doubles to Q16.16 exactly on every platform. -
Interpreted Dart is an interface.
ScriptRuntimeis what a script runtime implements, held to a Wasm module's rules. None ships:dart_evalwas evaluated and not adopted, for the reasons intasks/0.9-plugins.md.