Node class

The humble node.

Overview

Nodes are the buildings 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 should be written in such a way that it can be run multiple times. To facilitate this, build internally tracks every node added and every signal subscribed inside that method call. If you create resources that should be disposed, place it into the trash to prevent leaks.

Lastly, the rebuild method is provided as a way to "reboot" the internals of any node. This method will remove added nodes, unsubscribe from signals, and process the trash. Then, it will call build again.

Do not make build async. An asynchronous build breaks engine invariants in multiple, devastating ways.

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. Although unintuitive, this queue allows the engine to mitigate modification during iteration, and improves performance by batching the 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 the world changes out from under a live tree, the scene walks it calling reassemble. Unlike update and render, the walk ignores the enabled flag, so even disabled nodes are asked.

Currently, the walk runs in two, distinct situations:

• Whenever the SceneWidget reassembles in the Flutter tree.
• Whenever Ignis.cache changes, such as via the local asset bundle.

Each node answers for itself, and the default answer is nothing, so a save leaves a running game exactly as it was.