swift-boardgame-toolkit

Author print-and-play boardgames straight from Swift.

Motivation

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

This library proposes that you put those tools aside and work entirely in code instead!

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

Otherwise, read on.

Features

• Layout and design boardgame 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")
        .inset(
            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 and Getting Started

swift-boardgame-toolkit requires Swift 5.3 or later.

Swift Package Manager

If you don't already have a project waiting, you can initialize a new one:

$ swift package init --type=executable

This creates a basic project skeleton that has a single executable target (this is typically what you want if you just need to layout some cards).

Then, add swift-boardgame-toolkit as a package dependency:

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

Finally, for each applicable target, add BoardgameKit as a dependency:

.target(
    name: "my-target",
    dependencies: [
        .product(name: "BoardgameKit", package: "swift-boardgame-toolkit")
    ]
)

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 always laid out as intended, because the layout is formally and exactly described. A slip of the mouse in a graphics tool could move stuff around unintentionally and not be noticed until it's too late (of course, there's ways to prevent this - i'm just trying to make a point).

Though the aspirations behind this project might go a bit further, it is not a novel idea; swift-boardgame-toolkit shares many similarities with tools like nanDeck and Squib. These are highly useful tools with well-established communities, by the way.

Fundamentally, 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

It's important to note that this project is an experiment and a work-in-progress; it's very likely that there are things it can't (or simply won't) do.

For example, there are several downsides to this approach:

• Bias toward macOS; Swift just plays better there (Xcode, tooling, etc.)
• Dependence on WebKit and relying on it doing things the expected way (e.g. the print operation that powers PDF generation)
• Dependence on Swift and the expectation of a brighter future. The DSL is based on a Swift feature called @resultBuilder that does not currently provide a pleasant experience (e.g. error in scope? Compiler typically just times out rather than identify the error...).

Learn More

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