Board game state machine design? Need some help planning

[vck3000]

Hi there,

I have read this, however I have a slightly different variation on this question.

I am rewriting a game engine for an online board game. At the moment it uses a very crude self-built state machine, however I thought it would be great to formalise the logic and make it more maintainable using xstate.

I have the following "state diagram" of the game. In normal mode, there is a simple Pick, Vote and End phase. However the game is customisable with different roles, different intermediate states, and different logic flows. (Green arrows represent some of the main events that cause transitions)

This is what a standard game looks like. It has a simple Pick, Vote and End phase.

Now this is what a standard game with two extra roles looks like. If there is an Assassin role in play (a player entity), then the state machine should go to the assassin state before ending the game. Similarly, if there is a Lady card in play (a non-player entity), then the state machine should go to the Lady state before returning back to the Pick state.

Essentially, I want to somehow be able to make the Game machine include an optional state without hard coding it into the base Game machine, so that it is extendable when new roles are added.

I thought about two possible ways to do this via xstate, however I've been running into some issues. I'm not sure if my approach is correct, or whether xstate is suitable for this, so please let me know what you think.

1. I could try to use a child actor model where the Game machine (parent) will invoke these child machines. Each entity would be its own machine, and each Player entity would also hold events for when their vote is received and store that information within itself. However, as the child machines aren't supposed to be able to easily share information with their parent before terminating, I find it hard to easily extract each players' votes and do the calculations for the conditional transition to game end or to the next pick state.

This approach also makes it difficult for a child machine to "override" the Game machine's state. For example the Assassin machine needs to be able to override the Game machine's state and make it the Assassin state, until the child machine is satisfied (i.e. when the assassin makes their selection).

2. I could try to use a Game Machine factory that would store each entity's state (if it has one) into a hierarchical machine by using the spread operator, and have the entities themselves stored in the Game Machine's context. That way everything is shared together.

I have a few concerns about this approach however:

• As more branches come out of each state, each conditional transition's location or ordering in the list of actions/transitions must be manually written, as sometimes the assassin takes priority over game end, sometimes the lady of the lake takes priority over other entities. This would mean that each role's addition would have to be written in the factory code, potentially making this very long. I'm not sure if xstate has a way to include an optional priority argument in the conditional transitions to check in a certain order.
• When a pick is made, it will by default transition to the Vote state. If I have a special entity that needs to intercept this, I will need to mutate the base Pick state's target to the new temporary state. Such a modification would not be maintainable or scaleable in the future... Is there a way I can insert a state in between two states without getting into the nitty gritty?

How should I go about approaching this? Is there something I have missed? Or perhaps I am using xstate in a way that it initially wasn't designed to be used? Thank you for the help.

[Andarist]

I am rewriting a game engine for an online board game.

Out of curiosity - what board game? I'm a #bgg 😅 Looks like some variation of Mafia/Werewolf/Avalon?

---

As to the topic itself - I think your first intuition might be right: make players separate actors and communicate with the game through events.

However, as the child machines aren't supposed to be able to easily share information with their parent before terminating

This is not true - actors (so including parent and its children) are able to communicate through events at any time! So it's perfectly fine to have long-lived player actors and exchange events between them and the game actor during the game.

As to the customizability - a question would be: how many roles do you plan to have there? do roles have to be pluggable? or is it a single game that has its strict rules and it just happens that not all roles are involved in a particular play?

I think the latter might be the case and if it is then I wouldn't complicate this too much - I would actually hardcode all of this within the game machine. It would get more lengthy but it would be actually IMHO more readable (as it would be less abstract). Unless... you really want to create an engine for this type of games - then I would craft carefully "placeholders" in the core game machine and go with a factory approach. So basically let caller define extra "rules"/states/etc and inject them into those placeholders with the factory function. This is a more complex solution and requires more thought on your side as only you know how much customizability you would like to have there and what exact requirements do you have.

[vck3000]

Out of curiosity - what board game? I'm a #bgg sweat_smile Looks like some variation of Mafia/Werewolf/Avalon?

It's Avalon! :D.

---

We have many roles currently, up to 11 entities (roles and cards) with unique abilities. Some of them are passive in that they just provide extra information to those holding those entities, and others are active in that they actually modify the game state diagram. It would be great if I could make it as abstract and pluggable as possible.

In addition, we are also thinking about extending it to other game modes such as Hunter or Original Resistance (cards), but the underlying Pick, Vote, End structure is shared between all three game modes, so I'd like to be able to reuse some code here.

My current game engine requires each Role and Card that modifies the state diagram to have a checkSpecialMove() function, which would hard set the parent game object's state (I called it phase in my old write up), to the temporary state. Then when the appropriate gameMove() was received, that temporary state would be released and continue on. In that sense, it was extremely pluggable, but just not formalised into a state machine I guess.

I haven't fully explored how the data flow between machines via events looks yet. It may be nicer than I think it would be.
But I think the customisability and pluggability is a must in this rewrite of my game engine :(. I don't think it's appropriate for me to hard code for a single game mode...

For example, in my current engine, I first route the gameMove() to the correct phase (or state) to process the event, and then I checkRoleCardSpecialMoves().

https://github.com/vck3000/ProAvalon/blob/master/gameplay/game.js#L630

Each role and card may have an optional special move function that will hard modify the game's phase (state) to its own if a certain criteria is met.

https://github.com/vck3000/ProAvalon/blob/master/gameplay/avalon/roles/assassin.js#L42

In this link^, the assassin role will divert the game's state to assassination phase (state) if some conditions there are met. It's currently pretty pluggable and customisable, but is a very messy, difficult to serialise and un-serialise, and is pretty old and terrible haha.

What do you think?

Unless... you really want to create an engine for this type of games - then I would craft carefully "placeholders" in the core game machine and go with a factory approach. So basically let caller define extra "rules"/states/etc and inject them into those placeholders with the factory function

I think this is how I'd have to go if I want to use xstate. Do you know of any examples I could take a look at for inspiration or guidance? :)

[Andarist]

Unfortunately i dont have any good examples for this. I would start from modelling the core logic - without ability to customize anything and just add customizable things one by one later.

If you develop this in the open - feel free to ping me for reviews or brainstorming. Seems like a cool project and i could help you a little bit with it on the conceptual level.

[vck3000]

No worries and sounds good :). I'll let you know if I continue to work on this. Thanks!

[vck3000]

Hey @Andarist! I spent a while developing the first idea of using child actors for each player and here's what I've come up with to make it as modular. If you had a spare moment, I would appreciate any feedback very much :).

Edit: I've replaced the child actors with an ECS model. I found that the player actor machines only had one state, and just contained a raw JSON object in context. Essentially every entity is given components that shape it's overall behaviour. For example a Player entity has CPlayer in it's components. If the player can pick, they have a CPickTeam component. Systems are the actual functions that operate on the entities, and these are added to the machine on game start configuration.

To handle the special states such as assassination, I've created a parallel state node for the game. When special is in idle, the standard game machine is run (pick, vote...). On each entry into any standard game state, runSystems() will be called. This will run all the systems present in the machine on all the entities and if a system decides it's time to transition from special.idle to special.active state, it will fire an event to the machine. When it's in special.active, no normal transitions can happen.

Here's what it looks like:

How does that sound overall? I have read somewhere on this repository that it isn't great to send events from an action (as they "set and forget" or "run and forget" style, but I couldn't figure out a way to branch off the main game state easily).

I found some difficulty running a function on each event in a hierarchical state node despite setting the transition to be external. At the moment, I've just put runSystems() in each standard state.

Currently to make a lot of these actions happen in the correct places, I'm using XState's XState.actions.pure() function.

Here's a sandbox link for the state machines: https://codesandbox.io/s/github/vck3000/ProAvalon/tree/newPA_staging/packages/backend?file=/src/rooms/game-engine/room/room-machine.ts

Lastly, when I enter a new state, on entry I'm doing an action. The state that is given to the action is the previous state. It looks like it's running the entry action before the machine has completed the previous transition coming into this state... Is there a way I can access the post-transitioned state in an entry action?

Here's a test file I wrote that demonstrates some of the special state functionality.

How does it look at the moment? Any feedback would be greatly appreciated!
Thank you!

Edit: I just thought about making the special states a machine service that is simply invoked and waited until it reaches it's final state... Is that a smarter idea instead? Are events sent to the main room machine forwarded to the invoked service first before bubbling up to larger states as in the hierarchical state nodes?