fscene library

Classes

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.
AssetRef: A reference to an external asset by its source-path key.
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.
ComponentSpec: A serialized component: a stable type name plus a typed property bag.
CuboidGeometrySpec: A box of the given extents, optionally with per-corner debug colors.
DocumentId: A 128-bit document identifier, minted once when a document is created.
DoubleValue: A floating-point scalar value.
EmptyEnvironment: An empty (black) environment.
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.
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.
GradientSkySpec: The built-in stylized gradient sky.
IdAllocator: Mints fresh LocalIds for one editing session of a document.
IntValue: An integer value.
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.
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.
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.
PlaneGeometrySpec: A flat plane in the XZ plane.
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.
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.
PropertyValue: A typed value carried by a component field, a material parameter, or a prefab override.
QuaternionValue: A rotation quaternion (x, y, z, w).
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).
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.
SphereGeometrySpec: A UV sphere.
StageMetadata: Scene-wide, non-spatial render settings (lights and cameras are per-node components, not stage data).
StringValue: A string value.
StudioEnvironment: The built-in procedural studio environment.
TextureResource: A texture sourced either from an embedded payload chunk or an external image asset.
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.
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.
Handedness: The chirality of the coordinate system a document's positions and geometry are expressed in. Drives the scene-root mirror the realizer applies, kept as metadata rather than a literal node transform.
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.
UpAxis: The up axis convention a document was authored in.

Constants

currentFsceneVersion → const int: The current .fscene format version this build reads and writes.
kFscenebVersion → const int: The current .fsceneb container version this build reads and writes.
supportedFeatures → const Set<String>: The format feature flags this build understands. A document that lists a feature outside this set in its featuresRequired is refused.

Functions

composeScene(SceneDocument document, {required PrefabResolver resolve}) → 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}) → 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.
defaultComponentRegistry() → FsceneComponentRegistry: Returns a registry preloaded with the built-in component 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.
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.
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, 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}) → Future<void>: Applies document's stage render settings to scene: environment, environment intensity, exposure, tone mapping, skybox, and sky lighting.
realizeViews(SceneDocument document, Scene scene, Node root) → void: Realizes document's serialized render views into scene's view list.
registerBuiltinComponentCodecs(FsceneComponentRegistry registry) → void: Registers the component codecs the format ships with (mesh, directional light, camera) into registry.
reloadScene(Node liveRoot, SceneDocument oldDocument, SceneDocument newDocument, {FsceneComponentRegistry? registry, AssetBundle? bundle}) → Future<SceneDiff>: Patches the live graph rooted at liveRoot (as returned by realizeScene, or loadScene) from oldDocument to newDocument in place.
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's stage.
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.
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.
PrefabResolver = SceneDocument Function(AssetRef ref): Resolves a prefab AssetRef to its (uncomposed) SceneDocument.

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).

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

flutter_scene package

fscene library