02 code patterns

Planted: Mar 2025

Status: seed

Intended Audience: Creative coders, Front-end developers

The game will have two types of scenes - when the player is piloting their ship, traveling to different locations and another when at a location. This requires two different UIs (user interfaces):requirements

▪ A canvas-based UI for piloting the ship. Rendered 3D planets, space stations, other ships etc...
▪ A DOM-based UI for each location rendering images and text.

State machines will manage both.

Moving between UIs

To prototype the player's transition between piloting their ship and exploring a location, we'll create a state machine with two states:implementation

▪ space, representing piloting the ship.
▪ location, representing exploring a location.

When the player switches between these states, we need to update the DOM by adding or removing HTML elements. XState actions are perfect for this, as they allow us to trigger side effects when state transitions occur. Each state will have entry and exit actions that call functions to update the UI accordingly. To keep the prototype simple, the UI will display the state's name and a button to switch between states.

Managing complexity

The prototype's state machine is simple, but in the full game, it will become much more complex. With multiple locations, each requiring their own logic, managing everything in a single machine would be unmanageable. To keep things organized, I've split the system into two state machines:refactor

▪ gameMachine to manage the overall game state.
▪ locationMachine to handle logic of an example location.

By using XState's invoke, we can start or stop locationMachine by entering or leaving the location state. This approaches prevents gameMachine from becoming bloated with location-specific logic and maintains a clear seperation of concerns. The UI can send events directly to locationMachine without needing to go through gameMachine.

Canvas UI

The canvas UI will be rendered using three.js. While it might seem convenient to store three.js objects, like THREE.Vector3 or THREE.Mesh, in the state machine, it creates a problem: they aren't serializable. They can't be converted to and from JSON without losing meaning. Data that is serializable includes string, number, boolean, object and array.

One advantage of keeping a machine serializable is persistence—the ability to save and restore a machine's state. This enables:

▪ saving and loading game progress,
▪ time-travelling, allowing us to jump to different points in the game for easier development.

To have this benefit, we need to separate state management from three.js logic. The state machine will define what should happen, while three.js handles how.

Example

In this prototype, the ship's movement follows a strategy-game-style approach rather than a flight simulator. Players click on a position in space, and the ship moves there automatically. The scene contains a cube representing the player's ship, managed by a state machine with two states:

▪ idle, the ship is stationary.
▪ moving, the ship is moving towards a position.

Two buttons allow the player to move the ship to different positions. When clicked, a destination position is stored in the machine, and the state changes to moving.

Within onFrame, a function that renders each frame of the three.js scene, the state is checked. If moving, a function onFrameMoveMeshShip is called that gradually moves the ship towards the destination. Once the destination is reached, that function sends an event destinationReached to the machine which changes the state back to idle.