SceneNode class base

A node in the scene graph: a name, a place in the hierarchy, and a transform.

Deliberately narrow. Geometry, cameras and lights are subclasses that add their own payload, which keeps this base from growing into an object that knows about everything.

World transforms are never stale

three.js and Babylon both need an explicit update pass (updateMatrixWorld, computeWorldMatrix); forgetting it yields a frame of lag, which is a classic and annoying bug. Instead every node carries a globally unique version stamp, and worldMatrix compares its parent's current stamp against the one it last saw. A mismatch means recompute, walking up to resolve ancestors first.

The consequences are worth spelling out:

There is no update pass to forget. A stale world matrix cannot be observed.
Moving a node costs O(1); it does not walk its subtree to set dirty flags.
Version stamps come from one global counter, so they are unique across nodes. That matters on reparenting: a per-node counter could hand the new parent the same number the old one had, and the change would go unnoticed.
worldVersion doubles as a cheap invalidation key for anything derived from the transform — world bounds, view matrices, normal matrices.

Implemented types

AnimationTarget

Implementers

Constructors

SceneNode({String? name})

Properties

children → List<SceneNode>: no setter
childrenView → List<SceneNode>: Direct access for internal traversal, avoiding the unmodifiable copy.
no setter
hashCode → int: The hash code for this object.
no setterinherited
inverseWorldMatrix → Matrix4: The world-to-node transform, cached on worldVersion.
no setter
layerMask ↔ int: Bitmask filtered against a render view's mask, in the manner of three.js layers. Bit 0 is the default layer.
getter/setter pair
localMatrix → Matrix4: no setter
name ↔ String?: getter/setter pair
parent → SceneNode?: no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scene → Scene?: The scene this node currently belongs to, if any.
no setter
visible ↔ bool: Whether this node and its subtree are drawn.
getter/setter pair
visibleInHierarchy → bool: True when this node and every ancestor is visible.
no setter
worldMatrix → Matrix4: The node-to-world transform, always current.
no setter
worldVersion → int: Changes whenever worldMatrix changes. Use it as an invalidation key.
no setter

Methods

add(SceneNode child) → void: Adds child, keeping its local transform (so it moves with this node).
attach(SceneNode child) → void: Adds child while preserving its current world transform.
bindToScene(Scene? scene) → void: Binds this node's subtree to scene. Called by Scene for its own root; user code attaches nodes with add instead.
findByName(String target) → SceneNode?: First descendant with a matching name, or null.
lookAt(Vector3 target, {Vector3? up}) → void: Points the node's local -Z at target, given in world space.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onAttachedToScene(Scene scene) → void: Hook for subclasses to register themselves in the scene's flat registries.
onDetachedFromScene(Scene scene) → void
readPosition([Vector3? out]) → Vector3: Reads the local position into out to avoid allocating.
readRotation([Quaternion? out]) → Quaternion
readScale([Vector3? out]) → Vector3
readWorldPosition([Vector3? out]) → Vector3
remove(SceneNode child) → void
removeFromParent() → void: Detaches this node from its parent.
setLocalForward(Vector3 direction, {Vector3? up}) → void: Aims the node's local -Z along direction, expressed in the parent's space.
setLocalMatrix(Matrix4 value) → void: Replaces the local transform by decomposing a matrix.
setPosition(double x, double y, double z) → void: override
setPositionFrom(Vector3 value) → void
setRotation(Quaternion value) → void: override
setRotationYawPitchRoll(double yaw, double pitch, double roll) → void: Yaw about Y, then pitch about X, then roll about Z — the order that reads naturally for cameras and turntables.
setScale(double x, double y, double z) → void: override
setUniformScale(double value) → void
toString() → String: A string representation of this object.
override
translate(double dx, double dy, double dz) → void
traverse(void visit(SceneNode child)) → void: Walks this node and its descendants.

Operators

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