Data flow in Dyslexic Character Sheets (Patreon)

This post is quite technical. If you're just here for the pretty character sheets, move along.

The attached flow chart details how data will be handled in the new process. I need to have this process documented before I start on phase 8 - or even on phase 7, which is about preparing for phase 8 by refactoring everything. See my post on software dependencies. to understand more about the changes coming in phase 8.

All those boxes probably don't mean a lot to people who aren't me, so let me break it down a little.

Phases

The most notable feature is the big dividing line in the middle, separating the build phase from the  run phase; this separation is what phase 8 will be all about.

The build phase happens on my computer. It takes hundreds of little files, processes them in various ways, and produces a tidy library.

The run phase happens on a web server, but it could also happen on your computer, in an Electron app, or even on a phone or tablet. It takes a character request and produces a character sheet from it.

Library

The library contains the code needed to build a character sheet. It consists of core functions like the zone composer, and a registry of elements for rendering all the pieces a character sheet is made of: pages, sections, headings, fields, calculations etc.

The source for this is a big pile of little JavaScript files, which get combined and transpiled into a single JavaScript library file.

JavaScript is an odd language. It's old, burdened by a lot of messy history, and by most measures, not very good, yet by dint of its position within web browsers it's taking over the world. The modern versions of JavaScript have a lot of nice features and improvements, but you also can't take those for granted with software that might end up running on an older device.

"Transpiling", a version of "compiling", is the process of taking code written in one programming language and turning it into code in a different language. In this case, we'll be turning modern, shiny JavaScript into more rudimentary JavaScript that can run anywhere. At the same time it gets optimised and minimised, removing anything unnecessary from it.

Game Data

The most important file outside the core library is the data for the specific game, in this case Pathfinder Second Edition. Game data consists of units, which are the elements you select: classes, ancestries, background, feats, options, etc. Some units are large, such as the base of Pathfinder 2; others are small, like individual feats.

Units consist of a YAML file summarising all the visual elements, whether whole pages or simply units 

Each unit can have a stylesheet, though of course most won't. This is necessary because there will always be some elements that just look non-standard.

There's another output from the this: a game data summary file that's used to build the web form you use to design your character.

Assets

There are a number of files that need to be included in one form or another, and each is treated a little differently.

The resulting character sheet is a single file, without any external links. That means all the stylesheets, images etc are embedded into that file.

• Stylesheets belong to units. They're written in SASS, which gets compiled into CSS, and then included in units. 
• Fonts are part of the visual look. They're binary files, so they need to be base64-encoded before embedding into the CSS.
• Icons are similar to fonts, but being SVG (which is an XML format, not a binary one) means they shouldn't be base64-encoded.
• Logos are pictures that get included at the top of the cover page. They get scaled to a reasonable size and then base64-encoded.
• Iconics, the pictures of your character, come in a variety of formats and sizes. Many are on a white background. Each of them needs to be processed to cut out the white background, and then two sizes are made, the full size version used for printing and the smaller version used on the web form.

Character request

When you click the "Download" button on the website, what it produces is a character request. This is (or will be) a JSON document listing your choices, from classes, colours, language, iconic selection etc.

This request is broken into a list of units, and a listing of other information. The units are combined by the zone composer to produce a complete element tree. This is then rendered into HTML.

Those units that contain stylesheets are also combined, and the result is then processed, first to shift all the colours, and then to embed images in it. Finally the stylesheet is embedded into the HTML document to produce the final character sheet.

Translations

People across the world play Pathfinder, and these character sheets should be available to them all, so the ability to translate them has to be part of the process.

Another output from the units is a translation template (pot) file, listing all the strings that could be translated. This gets whisked away and fed into the translation system, where the translation teams for all the languages can work on it.

The result of all that hard work is a set of translations (po) files, each of which gives all the translated strings for a given language. This gets fed into the later stages, before the character sheet gets rendered.

Note that I plan to re-use the translations from Pathfinder 1 wherever possible, but that it shouldn't always assume they're the same.