swift-boardgame-toolkit

A framework for modeling, prototyping and simulating boardgames.

Motivation

Designing boardgames is a task that typically involves many tools; spreadsheets, graphics applications and others. But, most of these tools have the same inherent problem: they do not inspire confidence when changing things.

This framework proposes that you ditch all those tools and instead work entirely in code!

Don't buy that premise? Then swift-boardgame-toolkit is probably not for you.

Otherwise, read on.

Features

• Layout and design components in a declarative DSL
• Author print-and-play distributions automatically, in many configurations
• Model your game to simulate and test game state scenarios

Here's a bite-sized example to whet your appetite:

let card =
    Component(width: 2.5.inches, height: 3.5.inches) { parts in
        Box(covering: parts.full)
            .border("black", width: 0.25.inches)
        Text("Adventurer")
            .top(parts.safe.top)
            .left(parts.safe.left)
    }

try Sheet().document(
    target: .pdf(to: URL(fileURLWithPath: "output.pdf")),
    configuration: .portrait(on: .a4, arranging: [
        Layout([card], method: .natural(orderedBy: .skippingBacks)),
    ])
)

Behind the scenes, swift-boardgame-toolkit utilizes WebKit as a powerful rendering backend.

Installation

swift-boardgame-toolkit requires Swift 5.3 or later.

Swift Package Manager

Add swift-boardgame-toolkit as a package dependency:

dependencies: [
    .package(url: "https://github.com/jhauberg/swift-boardgame-toolkit.git", from: "0.3.0")
]

Then, for any target, add BoardgameKit as a named dependency:

.target(
    name: "my-target",
    dependencies: ["BoardgameKit"]
)

Motivation, continued

Still here? Cool. Now, "entirely in code" is of course a bit on the nose. There's nothing wrong with keeping spreadsheets or using graphical design tools to create amazing art. However, there are, without question, very real benefits to using a sound programming language to "build" your game:

• Easy version control and better collaboration because of it
• Confidence to make changes; tests and compilation will point out issues immediately
• Formal definition of "how to build" your game

The benefits might be more obvious if you're already a programmer, but i'm sure others can relate to the dread one might feel when something changed in your spreadsheet, but you're not sure what, and suddenly every cell is erroring out.

This is similar in regard to layout; with a declarative approach you can be confident that elements are laid out as intended, because it is formally and exactly described how to. A slip of the mouse in a graphics tool could move stuff around unintentionally and not be noticed until it's too late.

This is not a novel idea, and swift-boardgame-toolkit shares many similarities with tools like nanDeck and Squib. These are amazing and well-established tools, by the way.

Though the goals behind this implementation might go a bit further, it all boils down to act as a sort-of glorified build script; define and model all parts of your game, simulate scenarios to validate game/balance and finally design and layout the physical components and arrange them on printable pages for human playtesting.

Disclaimer

Finally, it's important for me to note that this project is an experiment and absolutely a work-in-progress; it's very likely that there are things it can't (or won't) do, and I can't say with confidence that this is the way for everyone to build boardgames. It is, however, how I'd like to do it.

Learn More

• Read the Documentation (not available yet)
• Try the Examples
• Join the Discussion