Node class

Overview

Nodes are the building block of Ignis. They are organized in a directed, acyclic tree, with children ordered by priority. Nodes may be assembled into subtrees using add and remove any number of times.

Building

Nodes should initialize children, connect signals, and add tick behavior in their build method. build is called every time a node is mounted to a live scene, or as the root of its own scene with mount.

build must be safe to run more than once. It tracks every node added and every signal subscribed inside it. Resources needing disposal go in the trash.

Lastly, a reload reboots the internals of every node: added children are removed, signals unsubscribed, the trash processed, and build run again. What survives is the node itself, and whatever it named with Live.keep.

Do not make build async.

Signals

Nodes communicate time-sensitive events through signals: named, type-safe message emitters. Use one to report an event to consumers, or as an input to react to external events.

Conventionally, signals are prefixed with the word on. For example, the signal a collider emits on contact is named onCollisionStart. This allows consumers to have a natural-reading constructor, e.g. onCollisionStart(/* do stuff */);.

Scenes

Nodes may be mounted to a Scene, which drives them with a game loop. When mounted, the scene will propagate through the entire subtree emitting the onMount signal on each node, from top to bottom. Unmounting does the reverse, emitting the onUnmount signal from the leaves upward.

Tree

Before being mounted, the add, remove, and priority tree operations take effect immediately, allowing a subtree to be freely assembled long before it goes live.

Once mounted, however, the same calls are instead merely enqueued. The scene applies pending changes right before the next update. As a result, operations for live node trees are always delayed a frame. The queue avoids mutation during iteration and batches changes.

Dependency Injection

Nodes come integrated with a type-based dependency injection (DI) system. A node may provide a value to its entire subtree, keyed by its type. read resolves the nearest match, checking the node itself before its ancestors.

Reassembly

When code is reloaded, the scene walks the tree rebuilding every node. Unlike update and render, the walk ignores the enabled flag, so even disabled nodes are rebuilt. It runs whenever the SceneWidget reassembles in the Flutter tree.

By default nothing rebuilds. A Live node rebuilds, keeping only what Live.keep names.