State Machines

A state machine is a general programming term that describes a system that can only be in one of a few known states, and the states it can change into are also all known and defined.

For example, you could define a Jack-in-the-Box as a state machine, with the following states:

• Resting
• Winding up
• Popped out
• Resetting

It might help if you think of these states as animations that play on a 3D model.

By default, the Jack-in-the-Box is resting. But if you start winding it up, it can transition into the Winding Up state.

At this point, it could either go back to resting, or it can go to popped out!

Once it's popped out, we can't go back to resting or winding up. But we can push it back into the box (resetting), which then puts it back into the Resting state.

We can imagine these states as a graph, with the transitions between states defined:

Resting <--> Winding Up --> Popped out --> Resetting
    ^                                       |
	|---------------------------------------*

You can go from Resting to Winding Up, from Winding up to Popped out, but you can't go from Popped out to Winding up.

Components as state machines

Now that you (hopefully) understand state machines, we can relate this to components in an ECS.

While some components are mostly static or just update as data changes (like a component that holds the player's current Walk Speed), other components might be a little bit more complex.

Imagine we had a car that we want to drive from point A to point B, then from point B to point C, then from C to D, etc. How do we store what point the car is currently at, and which to go to next?

This is where treating your component as a state machine come in. You can have your component data represent a state in a state machine, and your system code progresses that component one step forward, into the next state.

Our Car component could have an array of Vector3s in it, the points we want to visit:

world:spawn(Car({
	destinations = {Vector3.new(0, 0, 0), Vector3.new(10, 0, 5), Vector3.new(-5, 2, 3)}
}))

In our system code, we can drive the car towards one of the points, and when it reaches its destination, remove that item from the list and start going towards the next.

for id, car, model in world:query(Car, Model) do
	local currentPosition = model.model.PrimaryPart.Position

	if (currentPosition - car.destinations[1]).magnitude < 2 then -- Arrived
		table.remove(car.destinations, 1)

		if #car.destinations == 0 then
			world:despawn(id)
			continue
		end
	end

	model.model.PrimaryPart.BodyPosition.Position = car.destinations[1] --example
end

In this way, our system "steps" our component forward in time, modifying it when necessary.

Adding another layer

We can make this a little bit more complicated if we make the car wait at each destination once it arrives.

world:spawn(Car({
	destinations = {Vector3.new(0, 0, 0), Vector3.new(10, 0, 5), Vector3.new(-5, 2, 3)},
	mode = "driving"
}))

-----

for id, car, model in world:query(Car, Model) do
	if car.mode == "waiting" then
		if os.clock() - car.startedWaiting > 5 then -- Wait 5 seconds
			world:insert(id, car:patch({
				mode = "driving",
				startedWaiting = Matter.None
			}))
		end
	elseif car.mode == "driving" then
		if #car.destinations == 0 then
			world:despawn(id)
			continue
		end

		local currentPosition = model.model.PrimaryPart.Position

		if (currentPosition - car.destinations[1]).magnitude < 2 then -- Arrived
			table.remove(car.destinations, 1)

			world:insert(id, car:patch({
				mode = "waiting",
				startedWaiting = os.clock()
			}))

			continue
		end

		model.model.PrimaryPart.BodyPosition.Position = car.destinations[1] --example
	end
end

Now, we've added another layer to our Car component: a mode property, that tells our code if the car is waiting or driving. You can see how this could get even more complex, adding other modes, arrays to drain, and other state that allows our system to "step" our component forward in time.