gemini://gem.hexandcounter.org/gemlog/posts/shuffle.gmi

Most people say CYOA when they mean gamebook. Some say solo adventures (hello fans of Tunnels & Trolls). Swedes call them soloäventyr. Numbered sections that you read and then follow references to other sections. A game in the shape of a book. If they are digital only they are often referred to as choice-based interactive fiction (hello Twine fans) and usually do away with the section numbers.

Ordering the sections in a gamebook is more difficult than it seems. My old attempts were to just randomly shuffle everything into whatever order. That works fine with small test files. It also works on a screen if a format is used that only displays a single section at a time. It does not work so well when many sections are visible, like on a typical generated PDF. It also does not work so well when printed on paper.

You do not want sections to be too close together. If section 10 has a difficult choice, you do not want the outcomes to be visible in sections 11 or 12. Ideally the outcomes of choices will not be on the same page (or spread) as section 10 at all. It can be equally bad if different choices lead you to two sections that are too close to each other. If you can go from 10 either to 144 or to 146 it is too easy to accidentally see both outcomes after you pick one. Too tempting to cheat. It can make re-reading the book less fun as you already know what would have happened if you picked the other choice.

You also do not want a section to have a link to a section too far away. Not when you read in a printed paper book. A good gamebook PDF or EPUB has cross-references you can click to instantly go anywhere in the book. Books printed on paper do not have that luxury. Jumping from section 10 to 733 back to 35 is not fun.

Going back and forth too much too fast can also spoil the story. If 10 links to 45 that links back to 12 there is a high risk that when reading 10 the reader accidentally sees something in 12 that gives away what lies ahead. In general it is better if there is nothing anywhere near 10 (on the same spread) that is too closely connected to it (counting distance in number of links followed).

To make it even worse, a section can be far away (in number of links, again), but still contain a spoiler. There could be something that is mentioned, or displayed in an illustration, that gives away something that it would be good if the player do not see yet. So just looking at the section-links and trying to guess how far apart two sections should be will not necessarily work well.

My first idea was to try to optimize it by randomly moving sections around and calculate some kind of score for how good the order is. Switch places of two random sections and check if the new order is better than the old one. Repeat a million times or so. Sounds easy, but that does not have a good chance of handling the last case with sections that are not linked but should still be far apart. Theoretically there could be some kind of special mark-up for the author to use to describe what sections should not be too close, but that could get ugly and confusing.

Instead I found a much simpler algorithm. So simple that it was originally designed to be used manually, on paper. It was described in 1986 in an internal document written for authors of Tunnels & Trolls solo adventures. It is available in a PDF that can be bought from DrivethruRPG, collecting various internal documents from Flying Buffalo (the company that publishes T&T). First sections are ordered in a sensible story-order, more or less from the beginning to the end. Of course since books can have loops and all sorts of short-cuts there is rarely an easy beginning to end order. Then numbers are assigned, in order, giving the first section 1, the next 1+n, the next 1+2n, then 1+3n and so on. A worksheet is included in the original document that the author can use to quickly fill in numbers to map from original order to the new numbers. When reaching a too high number (as decided by the author) the numbers wrap around to the lowest free number (so not quite modulo, in general). Obvious in hindsight, but easier and better than what I was thinking of doing.

What is n? If I remember correctly the original 1986 version of the algorithm used 15. Guess it depends on how many sections per page there will be. I have to experiment a bit to see what a good default is. It depends on how long sections there are and how big pages. My tool is a Pandoc filter that is oblivious to what output format there is, so there is no way to know for sure, but the author has to pick something that works well for a certain book.

I implemented the algorithm in Pangamebook tonight, but not really setting out to exactly replicate the original algorithm. It was a few weeks ago since I last even read that old article. There may be some details that differ, but I think it ended up being mostly identical. It seems like a good method. Results so far are promising. I need to do some more testing and maybe rewrite the documentation more before pushing a new version to GitHub.

It is probably a good thing that the sections are ordered using such a simple and predictable method. There should be at least a sporting chance for the author to tweak output order by just moving sections around in the input document and guessing what the result will be. At least that is how I hope it works.

Not sure what other popular methods there may be, if any. Have not looked for patterns in any old gamebooks. Probably going to do that now that I started thinking about this. Maybe spend some time staring at the SVG graphs on Project Aon.

Maybe a question is why to shuffle at all? Why not let the author decide. That works as well, but it is kind of boring to edit a file and try to also keep track of where each section should go. It is convenient to keep sections that logically belong together close. By using the method described above sections being close together means they will end up dispersed in the generated book, which is what you probably want. There is a setting in Pangamebook to not shuffle at all though, only using the filter to change all the section headers and links to numbers. It is also possible to just assign a number to a section to manually force it to have that number, which can be used when everything else fails to move something around (but it is going to affect where other sections end up as well).

How to Shuffle a Gamebook