SceneModel class Widgets

A declarative imported model: loads a .glb and mounts it as a node.

The widget owns a wrapper Node carrying the transform props; the imported content attaches under it when loading completes. While loading, placeholder (a scene-widget builder, not 2D UI) is mounted in its place; on failure, error is mounted instead. For a single reveal of a whole scene, prefer gating the enclosing SceneView with its loading arguments over per-model placeholders.

variant selects a named KHR_materials_variants material variant, and can change on rebuild for interactive switching (a product configurator). Null keeps the model's default materials.

animations declares which imported animations play and how (see SceneAnimationSpec); rebuilding with changed specs applies the differences to the underlying clips.

Models are cached and shared: widgets whose sources have equal cache keys load and import once, and each mounts its own clone of the shared template (geometry, textures, and materials stay shared on the GPU). The template is evicted when the last widget using it unmounts.

SceneModel(
  'models/shoe.glb',
  variant: selectedColorway,
  animations: [SceneAnimationSpec('Spin', speed: 0.5)],
  position: Vector3(0, 1, 0),
)

Inheritance

Constructors

SceneModel(String assetPath, {Key? key, String? variant, List<SceneAnimationSpec> animations = const [], WidgetBuilder? placeholder, Widget error(BuildContext context, Object error)?, void onLoaded(Node modelRoot)?, String? name, Vector3? position, Quaternion? rotation, Vector3? scale, Matrix4? transform, bool visible = true, List<Component> components = const [], SceneNodeController? controller, List<Widget> children = const []}): Loads the model from the asset bundle at assetPath.
SceneModel.from(SceneModelSource source, {Key? key, String? variant, List<SceneAnimationSpec> animations = const [], WidgetBuilder? placeholder, Widget error(BuildContext context, Object error)?, void onLoaded(Node modelRoot)?, String? name, Vector3? position, Quaternion? rotation, Vector3? scale, Matrix4? transform, bool visible = true, List<Component> components = const [], SceneNodeController? controller, List<Widget> children = const []}): Loads the model from an explicit SceneModelSource.
const

Properties

animations → List<SceneAnimationSpec>: The animations to play, declared by name. See SceneAnimationSpec.
final
children → List<Widget>: Scene widgets describing this node's children.
finalinherited
components → List<Component>: Engine-side behavior attached to the node. Diffed by identity: keep a component instance stable across rebuilds to keep its state.
finalinherited
controller → SceneNodeController?: Imperative handle to the managed node.
finalinherited
error → Widget Function(BuildContext context, Object error)?: Builds scene widgets mounted when loading fails.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
name → String?: The node's name, for lookups and debugging. Defaults to ''.
finalinherited
onLoaded → void Function(Node modelRoot)?: Called with the imported model root after it mounts. Use it to reach imported content imperatively (play animations, look up nodes).
final
placeholder → WidgetBuilder?: Builds scene widgets mounted while the model loads.
final
position → Vector3?: Local translation. Identity when null.
finalinherited
rotation → Quaternion?: Local rotation. Identity when null.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scale → Vector3?: Local scale. One when null.
finalinherited
source → SceneModelSource: Where the model bytes come from. Diffed by SceneModelSource.cacheKey.
final
transform → Matrix4?: Full local transform. Mutually exclusive with the decomposed props.
finalinherited
variant → String?: The KHR_materials_variants variant to select, or null for the model's default materials. Unknown names log a warning and keep the defaults.
final
visible → bool: Whether the node (and its subtree) renders.
finalinherited

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<SceneModel>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

debugClearModelTemplateCache() → void: Clears the shared model template cache (tests only).
debugEvictModelTemplateCache(String cacheKey) → void: Evicts the shared model template cache entry for cacheKey, as a hot reload would, without going through the asset hot-reload machinery (tests only). Live holders keep their clones; a later acquire under the same key installs a new entry alongside them.