Boardgame.io: an engine for creating turn-based games using JavaScript

Go to the projects page on the docs site

It would be great to save time on the implementation of board game rules engines. Unfortunately the fine folks at FFG are really bad at figuring out what the rules actually are and telling people :(

"turn the canvas you authored into finished, consistent art"

Like a jpeg? Otherwise I don't understand your question.

" a way to turn natural language rules into correct code"

And this is straight impossible, as natural language is by definition ambigious in meaning and code is not. Try your luck with LLM's, they come closest.

(a subset of natural language might work, but this is kind of a complex research topic)

What do you mean by stealth? I looked at the website and nothing about it makes it look like it would necessarily be free or open source.

[flagged]

The way I wanted to implement this in my turn-based game engine:

If you implement the deterministic update pattern to handle state synchronisation you can add "event" inside the logic that handles updates that pause the processing allowing your animations to be played. In JS, for example:

    async function handleUpdate(update) {
        if (update.type == "sell-items") {
            this.player.inventory[update.itemId] -= 1;

            await emitEvent("itemSold");

            this.player.money += 10;

            await emitEvent("moneyGain");
        }
    }

Client-side, the UI can listen to those events to pause the updating of the game state to see the intermediary state of the game and play animations. When the animation is done, it can resolve the promise, resuming the game updating logic.

If an update arrives while an update is being handled, it can be queued so it can be played after the current update finishes.

I toyed with an approach once that separated animations from game state updates.

Every player action could cause a cascade of updates, which would all be resolved “instantly” to the point no more cascaded updates were left to be processed.

While this is happening, any update that includes an animation pushes that to an “animation stack”, then the animations are played back one by one to show the player what happened. In this animation state most input in disabled and the game is effectively on hold until the animations complete (or are skipped by the player).

The “animations” were basically commands that the Model used to update the View, just with the option to apply them one by one over time. So the model is always up to date as fast as possible as possible, and the view just lags behind a bit and catches up.

The way I did this was to design a more-or-less monadic container `Result<A>` for all my game logic functions. It batches a sequence of animation steps with a result. It can also model error conditions (like not having enough resources for example). I can then instantiate it any concrete result type, such as a full game state or just the result of individual computations. It was very nice to concisely write complicated game logic with animations while retaining the happy path.

https://github.com/sjrd/barrage/blob/main/src/main/scala/be/...

In my experience, the way to solve [1] and [2] is to design a game state that can also _fully_ describe the state of the UI, including animation cues.

(game dev) What I did in the past was having actions generate both a new state, and a stack of 'instructions' that update the UI, which was deliberately not a 1:1 representation of the game state for the exact reasons you described.

Then you can 'execute' the stack within a command VM of some sorts, where instructions can move sprites around, play sounds, etc. You can have 'high level' instructions ("display the enemy's death") implemented as a combination of low level instructions ('reduce that health bar count until it goes to zero' -> 'change entity X's sprite to dead sprite' -> 'give player 200 gold as reward' -> 'play sound' -> 'change text in the text bar to something' -> ...)

It ended up working waaay better than what I was expecting, felt very easy to reason about, wasn't hard to maintain, and scratched that itch of implementing an interesting solution. :)

I remember someone making a card game GALGA [1] in Haskell and compiling a high-level "rules" DSL to a low-level "animation" DSL and "primitive" DSL for handling animations and state changes respectively.

[1] https://roganmurley.com/2021/12/11/free-monads.html

I agree fully with [1], having recently experienced the pain of implementing a custom drag-and-drop UI in React.

I ended up using ref's heavily to avoid stale closure and async re-render issues. Which basically amounts to circumventing React and interacting with the DOM directly.

I think I have a good example from Magic: the Gathering.

There’s a card called “Fact or Fiction”. You reveal the top five cards of your deck. Then your opponent splits the cards into two piles. Then you pick one of the two piles to take into your hand.

You’ll need to store structures representing the choices that are intermediary steps (split cards, pick stack) in your state, which is basically function calls and their params (a call stack). This example could get hairier - Magic also features cards with branching logic “choose 1: do a or b”. I can imagine designing cards with large and convoluted possible execution paths.

You could have the card define a schema for state transitions/params and represent all these choices as JSON encoded POJOs, but as a developer it sounds a lot nicer to just be able to suspend an async function every time a choice is made.

That's the exact approach I'm considering for the new engine I mentioned!

Although that strategy enables you to store and recover the state of a game, it doesn't give you the ability to inspect a snapshot of that state. How can you print the card which has just been played, if that data only exists as an argument in the call stack of a suspended async function? In the same way that you can't inspect the local variables captured by a closure, mainstream languages also provide no way to inspect a suspended stack frame.

This problem interferes with debugging, consistency checks (e.g. hashing the game state to check that two clients are in sync), and unit testing.

boardgame.io only runs game logic on the server, and it censors the State just before sending it to each client. This strategy makes the UI feel less responsive, but it keeps things simple.

The Swords and Ravens blog post recommends resolving actions on the client when they don't require secret information, but resolving other actions on the server. You'd also need to resolve actions on the server when they involve RNG.

boardgame.io was created as a personal open-source project while I was employed at Google. It is not an official Google product.

You say this like a joke, but that would bring a lot of usability and convenience improvements compared to a physical board game. Just moving stuff out of and back into the box can take a lot of work.

It's easy to overlook rules that a computerized game automatically handles for you, though. For example, I'm part of a group that plays Heat ( https://boardgamearena.com/gamepanel?game=heat ) every week. An important part of that game is moving the game-controlled cars, and since the platform handles that, only one person in the group. This is potentially quite bad for strategy, depending on the rules you don't know. Another issue that comes up in the same game is people losing track of the size of their deck. The game is very generous about the allowable timing of deck-manipulation effects, but if you're not actively paying attention you can draw through your deck and trigger a reshuffle, wiping out your discard pile, when you wanted to do something special before the reshuffle. This isn't a mistake it's possible to make while using a physical game.

a tad further: a central phone or tablet as a main board that you interact with via touch and where you can then transfer over to your handheld device over the network to manage your hand. I've not seen this yet, and it would be a pretty great experience I think. No clean up