fscene library

The .fscene serialized scene format: an in-memory document model, JSON read/write, and realization to and from a live Node graph.

Load a scene with loadFsceneAsset (or build a SceneDocument in code, write it with writeFscene, and read it back with readFscene). Realize a document into a node graph with realizeScene, or serialize a live graph back with serializeScene. Register app-defined component types with a FsceneComponentRegistry.

Classes

AngleRadians
A number stored in radians, displayed and edited in degrees.
AnimationChannelSpec
One animation channel: a keyframe timeline driving one property of one target node.
AnimationSpec
A named animation: a set of channels driving target nodes.
AssetEnvironment
An environment built from an external image asset.
AssetExtensions
Filters an asset picker to the given file extensions (with leading dots).
AssetRef
A reference to an external asset by its source-path key.
Attachment
Grafts a host-scene node (and its subtree) into a prefab instance under one of the prefab's internal nodes. node is a real node in the host document (so it edits and deletes like any other node); parent is the prefab-local node it attaches under, or null to attach under the instance's root.
BoolValue
A boolean value.
BoundsSpec
An axis-aligned bounding box in a resource's local space.
ColorValue
A linear RGBA color.
ComponentCodec
Translates between a serialized ComponentSpec and a live Component of one type.
ComponentField<C extends Component> Assets and loading
One declared property, the const descriptor plus the runtime bindings that connect it to a live component. The descriptor travels (schemas, manifests, MCP); the bindings stay in-process.
ComponentPropertyDef
A declared, editable property of a component type: the single source of truth for its name, carried kind, default, constraints, and docs.
ComponentSchema
A component type's full schema, the unit that travels (dev channel, project cache, package manifests, MCP).
ComponentSpec
A serialized component: a stable type name plus a typed property bag.
ConstantEnvironment
A reflection-free environment with uniform diffuse ambient radiance.
CuboidGeometrySpec
A box of the given extents, optionally with per-corner debug colors.
DeclarativeComponentCodec<C extends Component> Assets and loading
A codec derived from one list of fields: the schema, realization (construct via create, then apply writable fields), and delta serialization (read fields, omit values equal to their defaults) all come from the same declarations.
DocumentId
A 128-bit document identifier, minted once when a document is created.
DoubleValue
A floating-point scalar value.
EmptyEnvironment
An empty (black) environment.
EnvironmentResource
A reusable image-based-lighting environment in the resource pool, referenced by the stage's global environment and by environment-volume components.
EnvironmentSkySpec
Shows the scene's image-based-lighting environment, optionally blurred.
EnvironmentSpec
The image-based-lighting environment for a scene.
FmatSkySpec
A sky .fmat loaded by source path, with optional parameter overrides applied to the loaded sky's parameters by name.
ForeignComponent Assets and loading
An inert data-bag component standing in for a type whose real implementation lives in another process (or an unregistered package). Carries the spec it was realized from, untouched.
FsceneComponentRegistry
A registry of ComponentCodecs, keyed by component type name.
GeometryResource
Mesh geometry, sourced either from a binary payload chunk (imported content) or a procedural descriptor (a runtime primitive). Exactly one source is set. Carries optional local bounds.
GizmoArrow
An arrow from the node origin along a node-local axis.
GizmoColor
A color parameter, a literal linear RGBA or a binding to a color/vec3 property. A null GizmoPrimitive.color means the editor theme's gizmo color (accent when selected).
GizmoCondition
Draws a primitive only when the property at path equals equals, for union-kind properties (a collider's shape variant).
GizmoFrustum
A perspective view frustum opening along node-local +Z (the engine camera looks along its node's local +Z).
GizmoIcon
An unscaled billboard glyph at the node origin, the component's clickable presence when the node has no mesh.
GizmoLines
Literal node-local line segments, consumed as point pairs.
GizmoPrimitive
One drawable unit of a gizmo. Subtypes carry their geometry parameters; the shared fields govern visibility, color, and conditional drawing.
GizmoScalar
A scalar parameter, a literal or a binding to a numeric property.
GizmoSpec
The declarative gizmo block a component schema carries, an ordered list of primitives the editor draws for components of that type.
GizmoWireBox
A wireframe box, sized by literal half extents or a bound vec3 property.
GizmoWireCapsule
A wireframe capsule centered on the node origin, its length along axis.
GizmoWireCircle
A wireframe circle centered on the node origin, in the plane normal to axis.
GizmoWireCone
A wireframe cone with its apex at the node origin, opening along axis.
GizmoWireCylinder
A wireframe cylinder centered on the node origin, its length along axis.
GizmoWireRect
A wireframe rectangle centered on the node origin, in the plane normal to axis.
GizmoWireSphere
A wireframe sphere (three great circles).
GradientSkySpec
The built-in stylized gradient sky.
IcosphereGeometrySpec
A geodesic sphere made by subdividing an icosahedron.
IdAllocator
Mints fresh LocalIds for one editing session of a document.
IntRange
A hard inclusive clamp on an integer value; a null bound is open. Inspector, stepper or slider when both bounds are present.
IntValue
An integer value.
LayerMask32
A 32-bit bitmask (collision layers/masks, render layers). Inspector, a bitmask editor.
ListValue
An ordered list of values.
LocalId
A compact, document-scoped identifier for a node, resource, skin, animation, or payload.
MapValue
A string-keyed map of values (a nested property bag).
MaterialResource
A material: a type (for example physicallyBased, unlit, fmat) plus typed properties. An fmat material references its .fmat source via asset.
Matrix4Value
A 4x4 matrix.
MatrixTransform
A transform stored as an explicit 4x4 matrix.
MinCount
A list must hold at least count entries.
Multiline
A multi-line text field.
NodeChange
What changed about a node present in both documents.
NodeRefValue
A reference to another node in the same document, by its LocalId.
NodeSpec
A node in the document's scene graph.
Normalized
A vector normalized on write (joint axes).
PayloadSpec
A binary chunk in the document's payload manifest: a descriptor plus, when the document's payloads are loaded, the chunk bytes.
PhysicalSkySpec
The built-in physically based daylight sky.
PlaceholderComponentCodec Assets and loading
Realizes and serializes one schema-described type as ForeignComponents.
PlaneGeometrySpec
A flat plane in the XZ plane.
PowerOfTwo
An integer constrained to powers of two within min..max (shadow map resolutions). Inspector, a dropdown of the powers in range.
PrefabInstanceSpec
The data that makes a NodeSpec a prefab instance: a reference to another .fscene plus the per-instance delta (overrides and added/removed content). The prefab composer applies these against the referenced document; a plain node leaves NodeSpec.instance null.
ProceduralGeometry
A procedural geometry the runtime builds from parameters (rather than from baked vertex buffers). Compact and editable; no payload needed.
PropertyConstraint<T>
A single declared constraint on a property value.
PropertyOverride
One per-instance override of a prefab: set the property at path on the node target (in the prefab's local id space) to value.
PropertyReader Assets and loading
Typed access to a component spec's property bag during realize, with schema defaults as fallbacks and former names resolved.
PropertyValue
A typed value carried by a component field, a material parameter, or a prefab override.
QuaternionValue
A rotation quaternion (x, y, z, w).
Range
A hard inclusive clamp on a numeric value; a null bound is open. Inspector, clamped field. Coercion and realize clamp into range.
RealizeContext
Context handed to a ComponentCodec when realizing a ComponentSpec into a live Component. Carries the source document and a resources realizer so a codec (for example a mesh) can resolve referenced geometry and materials.
RenderTextureResource
An offscreen render target a serialized render view draws into and materials sample by id (the runtime RenderTexture).
RenderViewSpec
One serialized view of the scene: a camera node bound to a target and the view's render settings (the runtime RenderView).
ResourceRealizer
Turns a document's resources into live, GPU-backed Geometry and Material objects, memoizing each so a resource shared by many nodes is realized once.
ResourceRefValue
A reference to a resource (geometry, material, texture, ...) in the same document, by its LocalId.
ResourceSpec
A shared, id-keyed resource referenced by nodes (and other resources).
RgbColor
A vec3 that carries a linear RGB color (light colors), edited with a color picker while staying vector-encoded for document compatibility.
SceneDiff
The set of changes between two documents.
SceneDocument
The in-memory .fscene document: a GPU-free, encoding-independent description of a scene that the encoders serialize and the realizer turns into a live Node graph.
SerializeContext
Context handed to a ComponentCodec when serializing a live Component into a ComponentSpec. Carries the destination document so a codec can register resources or mint ids.
SkinSpec
A skin: the joint nodes it drives, its inverse-bind matrices (a binary chunk), and the optional skeleton root.
SkyboxSpec
The stage skybox: the visible background drawn behind all geometry.
SkyEnvironmentSpec
Sky-driven lighting: bakes a shader sky into the scene's image-based lighting on a refresh policy.
SkySourceSpec
What a stage sky looks like, serialized.
SoftRange
The slider range for a numeric value, presentation only; values outside it remain valid, unlike Range.
SortedDescending
A list of objects must stay sorted by strictly descending fieldName (LOD levels by screen size).
SphereGeometrySpec
A UV sphere.
StageMetadata
Scene-wide, non-spatial render settings.
Step
The scrub/step increment for a numeric field.
StringValue
A string value.
StudioEnvironment
The built-in procedural studio environment.
SunLightSpec
A sky-driven analytic sun and its cascaded-shadow configuration.
TextPattern
A soft-validated regular expression on a string (diagnostic, not a rejection).
TextureResource
A texture sourced either from an embedded payload chunk or an external image asset.
TorusGeometrySpec
A torus centered on the origin around the Y axis.
TransformSpec
A node's local transform, stored either as a 4x4 matrix or as a decomposed translation/rotation/scale (TrsTransform). The importer emits TRS for clean diffs; the runtime composes a Matrix4.
TrsTransform
A transform stored as decomposed translation, rotation, and scale.
UnknownConstraint
A constraint tag this build does not recognize, preserved verbatim so a re-encode never drops newer metadata.
Vec2Value
A 2-component vector.
Vec3Value
A 3-component vector.
Vec4Value
A 4-component vector.

Enums

AnimationProperty
The transform channel an animation drives on its target node.
ComponentPropertyKind
The editable type of one component property, used by the inspector to pick a widget, by tooling to validate input, and by the format to know how a value is carried.
GizmoVisibility
When a primitive draws relative to the owning node's selection state.
LoadPolicy
Whether a prefab instance's content loads eagerly with the scene or is streamed in on demand.
PayloadEncoding
How a binary payload chunk's bytes are interpreted.

Constants

currentFsceneVersion → const int Serialization
The current .fscene format version this build reads and writes.
kFscenebVersion → const int Serialization
The current .fsceneb container version this build reads and writes.
supportedFeatures → const Set<String> Serialization
The format feature flags this build understands. A document that lists a feature outside this set in its featuresRequired is refused.
universalComponentProperties → const List<ComponentPropertyDef>
The property every component carries regardless of type: the base Component.enabled flag, applied and serialized by the registry so individual codecs never re-declare it.

Functions

applyPrefabOverride(SceneDocument document, PropertyOverride override) → void
Applies a single override to document by resolving the target node (by its prefab-local id) and mutating the property at override.path.
audioEngineBackendFactory(String id) → AudioEngineBackendFactory? Audio
The registered factory for backend id, or null.
composeScene(SceneDocument document, {required PrefabResolver resolve, Map<LocalId, PrefabMemberOrigin>? memberOrigins}) → SceneDocument
Expands every prefab instance in document, returning a new document with no instance nodes. A document with no instances is returned unchanged.
composeSceneAsync(SceneDocument document, {required AsyncPrefabLoader load, Map<LocalId, PrefabMemberOrigin>? memberOrigins}) → Future<SceneDocument>
Loads every prefab document document references (transitively, breadth first, each source loaded once) via load, then composes synchronously.
decodeBase32(String token) → Uint8List
Decodes a Crockford base32 token to bytes (most significant bit first), the inverse of encodeBase32. Case-insensitive; trailing bits that do not fill a byte are dropped. Throws a FormatException on an invalid character.
decodeComponentSchemas(Object? json) → List<ComponentSchema>
Decodes a schema list, skipping malformed entries.
defaultComponentRegistry() → FsceneComponentRegistry
The process-wide component registry, preloaded with the built-in codecs.
diffScene(SceneDocument oldDocument, SceneDocument newDocument) → SceneDiff
Computes the node-id-keyed diff turning oldDocument into newDocument.
encodeBase32(Uint8List bytes) → String
Encodes bytes as an unpadded Crockford base32 string, most significant bit first. Stays web-safe by never accumulating more than ~13 bits.
encodeComponentSchemas(Iterable<ComponentSchema> schemas) → List<Object?>
Encodes a schema list (a manifest or cache payload).
isLazySubtree(Node node) → bool
Whether node is a lazy prefab placeholder.
isSubtreeLoaded(Node node) → bool
Whether node is a lazy placeholder whose content is currently loaded.
loadFsceneAsset(String assetPath, {FsceneComponentRegistry? registry, AssetBundle? bundle}) → Future<Node>
Loads a .fscene text asset by assetPath and realizes it into a live node graph, loading any external assets / fmat materials it references.
loadFscenebAsset(String assetPath, {FsceneComponentRegistry? registry, AssetBundle? bundle}) → Future<Node>
Loads a .fsceneb binary asset by assetPath and realizes it into a live node graph, loading any external assets / fmat materials it references.
loadFscenebBytes(Uint8List bytes, {FsceneComponentRegistry? registry}) → Node
Parses and realizes a .fsceneb binary container from bytes into a live node graph (synchronously).
loadFscenebBytesAsync(Uint8List bytes, {FsceneComponentRegistry? registry, AssetBundle? bundle}) → Future<Node>
Parses a .fsceneb container from bytes and realizes it, first loading any external assets, encoded image payloads, and fmat materials it references (from bundle, default rootBundle).
loadFsceneString(String source, {FsceneComponentRegistry? registry}) → Node
Parses and realizes a .fscene document from source text into a live node graph (synchronously).
loadSubtree(Node node, {required AsyncPrefabLoader load, FsceneComponentRegistry? registry, AssetBundle? bundle}) → Future<void>
Instantiates a lazy placeholder node's prefab content under it.
nodeRefOf(Node? node) → NodeRefValue? Assets and loading
The serialized reference for node, or null when it was not realized from a document node (a hand-built node has no document id).
physicsBackendFactory(String id) → PhysicsBackendFactory? Physics
The registered factory for backend id, or null.
propertyValuesEqual(PropertyValue? a, PropertyValue? b) → bool
Whether a and b carry the same value, comparing structurally (vectors by components, lists and maps element-wise, refs by id).
readBool(Map<String, PropertyValue> props, String key, bool fallback) → bool
Reads a bool property, or returns fallback.
readColor(Map<String, PropertyValue> props, String key) → Vector4?
Reads a ColorValue as a Vector4 (RGBA), or returns fallback.
readDouble(Map<String, PropertyValue> props, String key, double fallback) → double
Typed readers over a component or material property bag, with fallbacks for missing or mistyped values. Shared by component codecs and the resource realizer. Reads a double property, accepting an int too, or returns fallback.
readFscene(String source, {List<FsceneMigration>? migrations}) → SceneDocument
Parses a .fscene document from source.
readFsceneb(Uint8List bytes) → SceneDocument
Parses a .fsceneb container from bytes into a SceneDocument with each embedded payload's PayloadSpec.bytes attached.
readInt(Map<String, PropertyValue> props, String key, int fallback) → int
Reads an int property, accepting a double too (JSON writers may encode whole numbers either way), or returns fallback.
readString(Map<String, PropertyValue> props, String key, String fallback) → String
Reads a string property, or returns fallback.
readVec3(Map<String, PropertyValue> props, String key, Vector3 fallback) → Vector3
Reads a Vector3 property (a copy), or returns a copy of fallback.
realizeScene(SceneDocument document, {FsceneComponentRegistry? registry}) → Node
Realizes document into a live Node graph.
realizeSceneAsync(SceneDocument document, {FsceneComponentRegistry? registry, AssetBundle? bundle, ResourceRealizer? resources}) → Future<Node>
Realizes document into a live Node graph, first asynchronously loading any external image assets, encoded image payloads, and fmat materials it references (from bundle, default rootBundle).
realizeStage(SceneDocument document, Scene scene, {AssetBundle? bundle, EnvironmentAssetLoader? environmentLoader, FmatSkyLoader? fmatSkyLoader}) → Future<void>
Applies document's stage render settings to scene, including the environment look, post-processing effects, skybox, and sky lighting.
realizeViews(SceneDocument document, Scene scene, Node root) → void
Realizes document's serialized render views into scene's view list.
registerAudioEngineBackend(String id, AudioEngineBackendFactory factory) → void Audio
Registers factory under backend id, replacing any existing entry.
registerBuiltinComponentCodecs(FsceneComponentRegistry registry) → void
Registers the component codecs the format ships with (mesh, directional light, camera) into registry.
registerPhysicsBackend(String id, PhysicsBackendFactory factory) → void Physics
Registers factory under backend id, replacing any existing entry.
registerWidgetSlot(String name, WidgetSlotBuilder builder) → void Widgets
Registers builder under slot name, replacing any existing entry.
reloadScene(Node liveRoot, SceneDocument oldDocument, SceneDocument newDocument, {FsceneComponentRegistry? registry, AssetBundle? bundle, ResourceRealizer? resources}) → Future<SceneDiff>
Patches the live graph rooted at liveRoot (as returned by realizeScene, or loadScene) from oldDocument to newDocument in place.
resourceRefOf(Object? live, SerializeContext context) → ResourceRefValue? Assets and loading
The serialized reference for live (a geometry, material, texture, or environment the resource realizer produced), copying the resource into context's document when it originated in another one. Null for a hand-built object, which has no source resource to reference.
serializeScene(Node root, {FsceneComponentRegistry? registry}) → SceneDocument
Serializes the live Node graph rooted at root into a new SceneDocument.
serializeStage(Scene scene, SceneDocument document) → void
Reads scene's stage render settings back into document, writing the look into the stage's environment resource (creating and linking one when the stage has none).
serializeViews(Scene scene, SceneDocument document) → void
Serializes scene's view list into document's views array, replacing any existing entries.
unloadSubtree(Node node) → void
Detaches a loaded lazy subtree node's content; it can be loaded again with loadSubtree. No-op if node is not a lazy placeholder.
widgetSlotBuilder(String name) → WidgetSlotBuilder? Widgets
The registered builder for slot name, or null.
writeFscene(SceneDocument doc) → String
Serializes doc to canonical .fscene JSON text.
writeFsceneb(SceneDocument document) → Uint8List
Serializes document to a .fsceneb container: the document's JSON manifest followed by one chunk per payload.

Typedefs

AsyncPrefabLoader = Future<SceneDocument> Function(AssetRef ref)
Asynchronously loads a prefab AssetRef's (uncomposed) SceneDocument.
AudioEngineBackendFactory = AudioEngine Function(Map<String, PropertyValue> config)
Creates a fresh AudioEngine for a realized audioEngine component. config is the spec's open backend-specific configuration bag.
PhysicsBackendFactory = PhysicsSimulation Function() Physics
Creates a fresh simulation backend for a realized PhysicsWorld.
PrefabResolver = SceneDocument Function(AssetRef ref)
Resolves a prefab AssetRef to its (uncomposed) SceneDocument.
WidgetSlotBuilder = Widget Function()
Builds the widget subtree bound to a slot name.

Exceptions / Errors

FscenebFormatException
Thrown when a .fsceneb container is malformed.
FsceneFormatException
Thrown when a .fscene document is malformed.
FsceneUnsupportedFeatureException
Thrown when a document requires a format feature this build does not support.
FsceneVersionException
Thrown when a document's version cannot be loaded (newer than supported, or missing a migration step).