AniGraph
AniGraph is an engine Abe wrote over the past several years for this class's assignments. It combines a model-view-controller (MVC) framework with a scene graph, and it uses React and three.js under the hood. It still has room for improvement, so feedback is welcome.
Please do not share the AniGraph source, as it is not public yet. This may change at the end of the semester, but for now, it is Cornell-only. We will show you how to build a deployable version of your submission that you can post online with obfuscation, but do not post the AniGraph source.
This page gives an overview of how a scene is put together in AniGraph; the pages listed at the end go into detail. Most code excerpts come from ParticlePlayground2D, trimmed for length; a few come from the other example scenes.
Parts of a Scene
| Part | What it does | In ParticlePlayground2D |
|---|---|---|
| Node models | Data models for elements of the scene. Node model classes define a type of thing (data, behavior, assets and controls), and instances represent instances of that thing. Well-designed scenes usually put most of their code in node models. | LabCatParticlePlaygroundModel, PlaygroundParticleSystemModel |
| Node views | Views for elements of the scene. Each one draws one node model. Views read their model and never change it. | PlaygroundParticleSystemView, plus the engine's ASVGLView and AGroupNodeView |
| Scene model | The root of the scene graph. It builds the scene out of node models and handles interactions between nodes. | ParticlePlayground2DSceneModel |
| Scene view | Holds a hierarchy of views that should match the scene model and map it to a three.js scene under the hood. When a node model is added to the scene, the scene view creates a view for it, using the controller's model–view specs. You are unlikely to write any custom scene views, as they are mostly just a container for custom node views. | The engine's AGLSceneView, created by the scene controller |
| Scene controller | Connects the scene model and scene view, and handles user input. It holds the model–view specs, which say which node view class to create for each node model class. The scene controller also runs the frame loop. | ParticlePlayground2DSceneController |
MainApp.tsx | The React component that holds the app. Its import AppClasses from ... line picks which scene runs. You don't need to know React for C1. |
In C1, every scene model extends ASceneModel2D and every scene controller extends ASceneController2D (both in anigraph/starter/Scene2D). These draw using three.js under the hood but are limited to 2D graphics.
Here is how the parts of ParticlePlayground2D connect:
ParticlePlayground2DSceneController input and frame loop; knows nothing about particles
│ key presses, and "update to time t" once per frame
▼
ParticlePlayground2DSceneModel creates the playground and forwards to it
│
▼
LabCatParticlePlaygroundModel all the behavior lives here
├── emitter: ASVGLModel2D Lab Cat, drawn by ASVGLView
└── particleSystem: PlaygroundParticleSystemModel
└── particles drawn by PlaygroundParticleSystemView
The app state
Besides the scene, every AniGraph app has one app state object, of class AppState. It holds data that belongs to the app as a whole rather than to any one node. Most importantly, it holds the current value of every control in the control panel, stored under the control's name. You can reach it from anywhere with GetAppState().
// In a node model class: the names of its controls
static ControlKeys = { Speed: "Speed" };
// In the scene model's initAppState(appState): add a slider to the control panel
appState.addSliderIfMissing(MyModel.ControlKeys.Speed, 1, 0, 10, 0.1);
// Anywhere else, e.g. in a node's timeUpdate: read the slider's current value
const speed: number = GetAppState().getState(MyModel.ControlKeys.Speed);
The scene model's initAppState(appState) is passed this same object when the app starts, and that's where controls are added. The control panel covers adding, reading and reacting to controls.
Where code goes
The short version:
| If the code is about... | Put it in... |
|---|---|
| One node (or a node and its own children): its geometry, materials, assets, per-frame behavior, response to input, controls, responses to other nodes that can be isolated | That node's model class |
| The creation or removal of new nodes, or interactions between nodes | The scene model |
| Input / user interaction, or defining what views to use for each model | The scene controller |
| Drawing one model | That model's view |
In general, if code can be written in a node model class, that's probably a good place to put it. Why? A node model that holds its own behavior can be moved to another scene, or duplicated, without its logic being scattered across three files. It also keeps the scene model and controller short, so that when something goes wrong you know where to look. In ParticlePlayground2D, the scene model and controller are each under 100 lines, and neither knows anything about particles. StarterScene, the template to copy for your own scene, is built the same way.
If a block of code in your scene model only reads and writes one node, consider moving it into that node's model.
The frame loop
AniGraph will redraw the scene in a big loop. If you want stuff to move, you simply update it between the drawing of consecutive frames. It's worth understanding a bit about how these updates work:
- The controller's
onAnimationFrameCallbackcallsthis.model.timeUpdate(this.model.clock.currentTime). The base scene controller,ASceneController2D, does this for you, so your controller doesn't need any frame-loop code. - A common pattern is to have your scene model's
timeUpdate(t)calltimeUpdate(t)on each top-level node. This isn't automatic, though; you need to call it. - Node views listen for changes in their models and redraw when a change is signaled. Transform changes are signaled automatically; other changes, like geometry, need a signal (see Events and subscriptions).
t is the time in seconds. The amount of time that passes between frames might be slightly different from frame to frame, though, so to move something at a steady speed, you should compute how much time passed since the last frame (dt) yourself, and use that to drive motion (e.g., moving by velocity.times(dt)). Time and dt shows how.
Where to go next
- Node Models and Views: base classes,
@ASerializable, what goes in a node model, views, and model–view specs. - The Scene Model, Controller, and Scene Graph: building the scene, finding nodes by type or tag, the controller, and adding, removing and reparenting nodes.
- Controls and Events: adding and reading control-panel controls, events, subscriptions and callbacks.
- Transforms: position, rotation, scale and anchor, using a
Mat3, and world transforms.