Skip to main content

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​

PartWhat it doesIn ParticlePlayground2D
Node modelsData 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 viewsViews 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 modelThe root of the scene graph. It builds the scene out of node models and handles interactions between nodes.ParticlePlayground2DSceneModel
Scene viewHolds 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 controllerConnects 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.tsxThe 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
Try it in the tutorial

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 isolatedThat node's model class
The creation or removal of new nodes, or interactions between nodesThe scene model
Input / user interaction, or defining what views to use for each modelThe scene controller
Drawing one modelThat 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:

  1. The controller's onAnimationFrameCallback calls this.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.
  2. A common pattern is to have your scene model's timeUpdate(t) call timeUpdate(t) on each top-level node. This isn't automatic, though; you need to call it.
  3. 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).
note

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.

Try it in the tutorial

Where to go next​