Creating an RPG backend - a scheme tutorial

My road to Scheme started in 2013. It took me many years to understand how to use Scheme well. I want to help you to get there faster. Also I’ll describe my mistakes, so you can learn from them without repeating them.

I will do it in the way which works best for me: By building a roleplaying system backend.

We will build a library and commandline tool to decide the results of interaction in roleplaying systems: Skill tests, challenges person against person, single battle actions and resolving a battle in one roll.

The commandline tool will also provide minimal description of the battle actions, as flavor for a game, and the library will provide information needed to give feedback to the player.

We’ll implement the 1d6 rules, because they are free licensed — and because I created them. That’s not a good reason to choose a ruleset in general, but it is a way for me to fill two needs with one deed, because I also need a clean implementations of those rules for dryads wake, a game I started a while back.

As syntax I’ll use wisp, also known as srfi-119, because it looks easier for non-lispers — and to fill two needs with one deed again.

The first step is to build the data structures. They also describe the outcome of the functions we create.

When I started with Scheme, I used primitive data structures for most things: mainly singly linked lists and hash maps. This is the approach I knew from Python. But in Scheme, the cleanest way to structure data is to use records, standardized across implementations in srfi-9. They are equivalent to named tuples in Python. In Java you’d call them data classes.

Let’s start. The minimal data class we need is the result of a roll.

import : srfi srfi-9
define-record-type <roll-result>
  roll-result face value
  . roll-result?
  face roll-face
  value roll-value

Note: Creating a record type has low overhead, but it is not completely free (though it could be made to be free by keeping more info outside the record). See the appendix Cost of records in memory and time for empiric results. Here we just need to know that the overhead is less than factor 4, which we’ll ignore.

Defining a record type creates functions for the record which you can then use to create instances of such records. This is about the same as for named tuples in Python, just with more convenience.

So we have the first data structure: a roll-result which has a face (the face of the die which faced up) and a value (what the face means). Also there’s an accessor function to test whether something is a roll-result (roll-result?).

Note the angle-brackets (<>) around the first element — the name. These are required.

The second element in a record definition is the constructor. It receives values.

The third element is a predicate — the name of a function which can test whether something is of this type.

The rest of the arguments are the constructor-arguments with accessor functions. We can access the face as roll-face x (note that I dropped the result-suffix for brevity) and the value as roll-value x, with x as a roll-result object.