The Scene Model, Controller, and Scene Graph
The scene model builds the scene and handles what happens between nodes, the controller turns input into calls on the model, and the scene graph is the tree of nodes they manage.
The scene model
The scene model is the root of the scene graph and where world coordinates live. It does four things, in this order:
| Method | When it runs | What goes in it |
|---|---|---|
initAppState(appState) | First, before assets load and before the control panel is drawn | Add all control-panel controls to the app state, usually by calling each node class's static SetAppState(appState). |
async PreloadAssets() | Next | Load files (images, SVGs, sounds, shaders), usually by calling each node class's static PreloadAssets(). Call super first. |
async initScene() | After assets load | Create the top-level nodes and add them with this.addNode(node). |
timeUpdate(t) | Every frame (called by the controller) | Call each top-level node's timeUpdate(t), then handle interactions between nodes. |
ParticlePlayground2D's scene model, in full (minus comments):
export class ParticlePlayground2DSceneModel extends ASceneModel2D{
playground!: LabCatParticlePlaygroundModel;
initAppState(appState: AppState){
super.initAppState(appState);
LabCatParticlePlaygroundModel.SetAppState(appState);
}
async PreloadAssets(): Promise<void> {
await super.PreloadAssets();
await LabCatParticlePlaygroundModel.PreloadAssets();
}
async initScene(){
this.playground = new LabCatParticlePlaygroundModel();
this.addNode(this.playground);
}
timeUpdate(t: number){
this.playground.timeUpdate(t);
}
onKeyDown(key: string){ this.playground.onKeyDown(key); }
onKeyUp(key: string){ this.playground.onKeyUp(key); }
}
ParticlePlayground2D has no interactions between nodes, so its scene model only connects things. In more complex scenes, the scene model is where logic dealing with multiple nodes would go. This could include checking collisions between the player and the enemies, spawning new enemies, deciding when someone wins, etc. See Interactions between nodes.
Selecting/Filtering for groups of node models
You can query your scene model for groups or sets of nodes.
Finding Nodes by Type. Instead of keeping your own arrays of nodes, you can ask the scene model for every node of a class:
for(const enemy of this.getNodesOfType(EnemyModel)){
// ...
}
Tagging Nodes & Finding Nodes by Tag. You can also tag node models in your scene and retrieve all nodes with a given tag later.
// Tagging, e.g. when a node is created in initScene()
enemy.addTag("enemy"); // a tag with the value true
enemy.setTagValue("team", "red"); // a tag can also hold a value
// Finding, e.g. in the scene model's timeUpdate(t)
for(const enemy of this.getNodesWithTag("enemy")){
// ...
}
const redTeam = this.getNodesWithTag("team", "red"); // only nodes whose "team" tag is "red"
Use removeTag("enemy") to remove a tag. Tags are saved with the node, and the engine itself never reads them, so you can use any names you like.
addNode on the scene modelUse sceneModel.addNode to add node models directly to the scene model (i.e., the root of the scene graph). When adding node models as children of other node models, use nodeModel.addChild. Calling this.addChild(...) on a scene model will throw an error to remind you of this.
The scene controller
The controller registers model–view specs, defines interaction modes, and runs the frame loop. Input handlers should forward to a model when appropriate, rather than implementing model-specific behavior themselves. ParticlePlayground2D's controller doesn't know what keys actually do:
export class ParticlePlayground2DSceneController extends ASceneController2D{
// ... a typed `model` accessor and initModelViewSpecs() (see Node Models and Views) ...
async initScene(){
await super.initScene(); // call super FIRST: it sets the clear color to white
this.setClearColor(Color.Black());
}
initInteractions(){
super.initInteractions(); // registers the default pan/zoom mode
this.createNewInteractionMode("Main", {
onKeyDown: (event: AInteractionEvent, interaction: AKeyboardInteraction)=>{
this.model.onKeyDown(event.key);
},
onKeyUp: (event: AInteractionEvent, interaction: AKeyboardInteraction)=>{
this.model.onKeyUp(event.key);
},
onClick: (event: AInteractionEvent)=>{
// Clicking the canvas gives it keyboard focus. Without focus, key presses never arrive.
this.eventTarget.focus();
},
});
this.setCurrentInteractionMode("Main");
}
}
What belongs in a controller is covered in more depth in Interaction: keyboard and mouse input, picking, and interaction modes.
The scene graph
Or, Node Diggity, Node Doubt...
Your scene is a tree of nodes, with the scene model at the root. A child's transform is relative to its parent, so moving a parent moves all of its children.
this.addNode(parent); // in the scene model: add a top-level node, together with its whole subtree
parent.addChild(child); // works before or after parent is in the scene
child.reparent(newParent); // move a node under a different parent
parent.removeChild(child); // detach child (and its subtree), keeping it so it can be added again later
child.release(); // delete child, its descendants and their views, attached or not
- Adding a node adds its subtree. A node can build its children in its constructor, and they all get views when the node is added to the scene.
removeChilddoesn't delete. A detached node still exists and still holds its resources. To get rid of a node for good, callrelease()on it.- For things that come and go often, hide them instead of creating and releasing them every frame (see Showing and hiding).
- Reparenting changes what a transform means. A node's transform is relative to its parent, so after
reparentthe node jumps unless you adjust its transform. To keep a node where it is on screen, set its new local transform tonewParent.getWorldTransform().getInverse().times(node.getWorldTransform()), computed before reparenting.setTransformkeeps the node's kind of transform (see Using aMat3), so the node'sprsastill works afterwards. AttachAndDetach does this when you click a moon.
Group nodes
A group node (AGroupNodeModel2D, drawn by AGroupNodeView) draws nothing itself. Use one to move, rotate or hide several nodes together, or, as ParticlePlayground2D does, to bundle a few nodes and their shared behavior into one class. HierarchyAndAnimation's OrbitGroupModel rotates a group, which carries its three children around in a circle: the group's rotation does the orbiting, and the children's own positions only set the radius. Remember that a subclass of AGroupNodeModel2D needs its own spec (see Every labeled class needs its own spec).