GioCities - dev

Graph Paper Lindenmeyer Systems

2025-11-02T00:00:00-05:00

When I was a kid I learned about Lindenmeyer Systems and the fun tree patterns they create. I even followed a Twitter bot that generated and posted random pretty lsystem renders.

These are similar to fractals, except unlike traditional fractals they don’t usually expand within a fixed space, they either continue to grow or loop back intersecting themselves.

Meanwhile I spent most of my time in school and needed something to occupy my hands with. I did a lot of notebook doodling, except people notice those. But I did have graph paper. And graph paper gives you enough structure to draw lsystems by hand. So I did, a lot.

I probably went through a notebook every two years, and I can’t remember once ever drawing an actual graph. This was when I was a child in childish ways and hadn’t yet learned about dot paper. Oh, misspent youth....

There are a couple interesting things about this mathematically.

First, there’s only really one interesting space-filling pattern to draw on graph paper, which is forking off in two 45 degree angles. Anything that doesn’t fit on the coordinate grid (like incrementally decreasing line lengths) becomes irregular very quickly. The main option to play with different patterns is by setting different starting conditions. (Seems like it’d get boring quick, right? I spent the rest of the time trying to apply the Four color theorem in an aesthetically satisfying way. Still haven’t solved that one.)

Second, drawing on a coordinate grid means using Chebyshev Geometry, where straight lines and diagonal lines are considered the same length. So a circle (points equally far apart from a center point) is a square. This is also sometimes called chessboard geometry, because it’s how pieces move on a grid.

Also, because I’m drawing this by hand, I can only keep track of visible tips. So if tips collide I count them as “resolved”, even if mathmatically they’d pass through each other.

But I kept hitting the end of the graph paper.

I was bored in a work meeting this week and ended up doing the same thing, and it made me wonder about the properties of the pattern. Did it repeat? Did it reach points of symmetry? I thought it would be fun to whip up a tool to run my by-hand algorithm to see.

There are lots of web toys for lsystems but none are designed with these graph paper constraints. So just as an exercise I built my own from scratch, and it’s pretty good at drawing my high-school pattern.

The answer to the pattern question is: it depends on the starting position! If you start with one line you start to see radial symmetry, but if you start with two lines facing away from each other (as in the animation) it’s more interesting. Neat.

Each generation is considered a state frame that keeps track of lines (for rendering), buds (for growing the next iteration), bloomed_buds (for bud collision) and squares (for line collision).

For the Chebyshev geometry I just keep every line at a 1.0 length and let the trigonometry functions round up.

I didn’t actually implement a parser for formal Lindenmeyer syntax, I just defined everything recursively in pure Javascript, using a definition to encapsulate details about the pattern:

const definition = {
  at(bud) {
    const lines = []
    const buds = []

    for (let angle of [
      bud.r - 0.25,
      bud.r + 0.25
    ]
    ) {
      const rads = Math.PI*angle
      let len = 1
      let xy = [bud.x + len*Math.sin(rads), bud.y + len*Math.cos(rads)]
      if (chebyshev) xy = xy.map(Math.round)
      lines.push(xy)
      buds.push({x: xy[0], y: xy[1], r: angle})
    }
    return {lines, buds}
  }
}

Then rendering is done recursively:

function get_frame(generation) {
  if (generation < 0) throw Error(`Invalid generation ${generation}`)

  if (!frames[generation]) {
    const frame = structuredClone(get_frame(generation - 1))

    const old_buds = [...frame.buds]
    const new_buds = []
    const new_squares = []
    for (const i in old_buds) {
      ...
    }
    frame.bloomed_buds = [...frame.bloomed_buds, ...old_buds]
    frame.squares = [...frame.squares, ...new_squares]
    frame.buds = prune_buds(new_buds, frame.bloomed_buds)

    frames[generation] = frame
  }

  return frames[generation]
}

There’s a slight complication to doing this cheaply with lines: on paper, there are cases where lines intersect, and in those cases I stop at walls, even if it means drawing a partial line. Doing that kind of collision detection here in vector space would be very complicated! And without it the pattern loops back on itself and doesn’t look as good, and definitely doesn’t match my notebooks:

The solution for this was very simple collision detection. The final program keeps tracks of which squares are “occupied” and breaks branches any time they’d collide.

I uploaded it to my stash if you want to play with it. As an added constraint I wrote everything by hand in one single-file html page.

The one problem with the tool (besides being bare-bones) is it renders the output as an SVG instead of a bitmap on a canvas. This “feels right”: they’re lines, might as well make them vectors. But on high values browsers have performance issues rendering very large quantities of DOM elements.

I’d rewrite the renderer to draw to a canvas instead except I like the idea of the infinite SVG canvas specifically. The point was to escape the edges of the graph paper, remember?

But I’d already abstracted line drawing so the line coordinates were stored in state frames, so it was easy to write an alternate renderer using the canvas API.

https://stash.giovanh.com/toys/lsys.html

Illustration by Cmglee - Own work, CC BY-SA 4.0, Link ↩

FSE sprite compression

2025-01-03T00:00:00-06:00

This was originally published 2020-07-07 as a reward for sponsors of Befriendus

A Domain-Specific Compression Algorithm — as I later found out this is called — is a compression algorithm that uses the specific nature of the target data as a way to efficiently compress it. The more you know about the structure of the data you’re compressing and what tools you have to reconstruct data, the more efficient the system can be.

I wrote a script for the Fansim Engine that does this with character sprites. It takes character poses, identifies the parts that have changed and the parts that stay the same, and creates identical Ren’py displayables that take up dramatically less room.

Why?

For a little background on why I wanted to do this at all, let me show you how Hiveswap Friendsim handles character sprites.

Hiveswap Friendsim is big.

Given that it’s a fairly simple visual novel with static sprites and a few music tracks, it’s huge. The final version on Steam (with all the DLC and updates) clocks in at 1.3 GB. Pesterquest is also stupid big at 1.43 GB.

Cursory inspection shows that the bulk of this space is taken up by RPA (Ren’Py Archive) files, as is to be expected. You can unpack those, though, which shows what’s taking up all this space:

There are two culprits here: inexplicably uncompressed WAV files (50 MB for a 5 minute loop? what on earth) and character sprites. Both of these stand out as obvious mistakes, because they’re both easily compressible.

I’m not an audio engineer, so I won’t try to explain the WAV thing in-depth, but those files are enormous and could have been compressed down to less than a tenth of their size without any noticeable loss in quality. So, uh, that really should have been done.

What I can speak to personally is the character sprites. Character poses in many visual novels — but particularly Hiveswap — tend to look like this:

The keen-eyed may have already noticed that there is some redundant data being stored here. This is the same character, in the same pose, with a different facial expression. Now, my complaint isn’t that this is somehow “lazy art”; this looks fine in gameplay. The problem is when you’re storing an identical “body” section for every pose, you’re going to end up wasting a ton of space. Which they do.

We can do better.

Sprite compression

If you’ve ever gone on spriters-resource.com (which you probably have done) or opened up a chunk of game memory in yy-chr (which you probably have not done), you’ve probably noticed that sprites aren’t stored as large, copied images, but small pieces that the game puts together at runtime. Like this, or this.

This is especially true for “big” sprites that are significantly larger than the tile size. (Although in ren’py, there isn’t a “tile size”, the principle still stands.) When your space is limited, you want to avoid storing the same thing multiple times if at all possible. Space is always limited, but bad programmers like to pretend it’s not on modern PCs, grumble.

I wanted to create something that took and compressed sprites that were already drawn, in a way that wouldn’t impose extra limits on the artists or really require any additional work.

How it works

To explain the technical details of how I implemented this, I’ll walk through running the program on Mituna’s sprites from Befriendus. This is — mostly — a recreation of how I actually handled Mituna’s sprites for the game proper.

If you’re interested in the nitty-gritty, the source code is available on the Fansim Engine github repo, although that project is no longer in active development.

Basic principles

First, I build a tree of poses. Each pose can have “children”, which are the original pose with a small “patch” somewhere to create a second pose. Ren’py will happily treat a logical “displayable” defined in code like this as an image, and even let you continue making edits recursively, so this design pattern matches perfectly.

Put simply, we can make a full sprite of Mituna frowning by putting a “frowning” segment over the standard idle pose. We don’t need to keep duplicating the whole body pose.

We can simply take the “frown” part and composite it over its base, the idle pose:

Ren’py will do this composite operation at runtime very efficiently if we just tell it what images to composite and where. This requires storing far fewer “pixels” on disk, at the cost of some slight runtime processing.

For convenience, I want all the child poses of a parent to have the same image dimensions. First, I remove any extra whitespace from the sides of the poses, and then I add whitespace until each pose is the same size, centered at the middle.

There’s another gotcha here, too: I can’t just composite the new bit on top of the old sprite, because it’s possible the new pose is transparent in a place the old one wasn’t, and image composition gets that wrong. Instead, I have to “cut a hole” in the base pose by cropping it into 5 pieces, removing the “middle piece”, and replacing it with the patch.

Step by step

I start with a big folder of sprites. Mituna’s sprites look like this:

By default, the “tree” is built based on the filenames of the sprites, although there’s optionally a way to specify a tree manually. After some renaming based on the actual logic of the poses and expressions, the program can interpret the files and build a tree fairly easily:

$ python3 makechars.py --make-demo --character-dirs mituna
INFO: Loaded 30 poses from directory 'mituna'
INFO: Remove old rpydiff_out/characterp/mituna
INFO: Remove old rpydiff_out_demo/characterp/mituna
INFO: Building pose hierarchy...
INFO: Global parent <Pose mituna idle v1* of None>
INFO:  - <Pose mituna idle v1* of None>
INFO:    - <Pose mituna idle frown v1* of !mituna idle>
INFO:      - <Pose mituna idle frown talk v1* of !mituna idle frown>
INFO:    - <Pose mituna idle smile v1* of !mituna idle>
INFO:      - <Pose mituna idle smile talk v1* of !mituna idle smile>
INFO:    - <Pose mituna idle spark v1* of !mituna idle>
INFO:      - <Pose mituna idle spark talk v1* of !mituna idle spark>
INFO:    - <Pose mituna idle talk v1* of !mituna idle>
INFO:    - <Pose mituna angry v1* of !mituna idle>
INFO:      - <Pose mituna angry spark v1* of !mituna angry>
INFO:        - <Pose mituna angry spark talk v1* of !mituna angry spark>
INFO:      - <Pose mituna angry talk v1* of !mituna angry>
INFO:    - <Pose mituna confused v1* of !mituna idle>
INFO:      - <Pose mituna confused talk v1* of !mituna confused>
INFO:    - <Pose mituna cry v1* of !mituna idle>
INFO:    - <Pose mituna defensive v1* of !mituna idle>
INFO:      - <Pose mituna defensive blush v1* of !mituna defensive>
INFO:    - <Pose mituna explode v1* of !mituna idle>
INFO:    - <Pose mituna frustrated v1* of !mituna idle>
INFO:      - <Pose mituna frustrated spark v1* of !mituna frustrated>
INFO:        - <Pose mituna frustrated spark talk v1* of !mituna frustrated spark>
INFO:      - <Pose mituna frustrated talk v1* of !mituna frustrated>
INFO:    - <Pose mituna grin v1* of !mituna idle>
INFO:    - <Pose mituna nervous v1* of !mituna idle>
INFO:      - <Pose mituna nervous alt v1* of !mituna nervous>
INFO:        - <Pose mituna nervous alt talk v1* of !mituna nervous alt>
INFO:      - <Pose mituna nervous spark v1* of !mituna nervous>
INFO:        - <Pose mituna nervous spark alt v1* of !mituna nervous spark>
INFO:          - <Pose mituna nervous spark alt talk v1* of !mituna nervous spark alt>
INFO:        - <Pose mituna nervous spark talk v1* of !mituna nervous spark>

Here, idle frown is a subpose of idle. angry is also a subpose of idle, because here idle is the global root. There needs to be a global root for the tree, which by default is idle or neutral or a variation thereof.

We then iterate through the tree, starting at the leaves, and create patches.

INFO: Expanding canvases...
INFO: Generating patches...
INFO: Creating patch of <Pose mituna idle frown talk v1* of !mituna idle frown>
INFO: Creating patch of <Pose mituna idle smile talk v1* of !mituna idle smile>
INFO: Creating patch of <Pose mituna idle spark talk v1* of !mituna idle spark>
INFO: Creating patch of <Pose mituna angry spark talk v1* of !mituna angry spark>
INFO: Creating patch of <Pose mituna angry spark v1* of !mituna angry>
INFO: Creating patch of <Pose mituna angry talk v1* of !mituna angry>
INFO: Creating patch of <Pose mituna confused talk v1* of !mituna confused>
INFO: Creating patch of <Pose mituna defensive blush v1* of !mituna defensive>
INFO: Creating patch of <Pose mituna frustrated spark talk v1* of !mituna frustrated spark>
INFO: Creating patch of <Pose mituna frustrated spark v1* of !mituna frustrated>
INFO: Creating patch of <Pose mituna frustrated talk v1* of !mituna frustrated>
INFO: Creating patch of <Pose mituna nervous alt talk v1* of !mituna nervous alt>
INFO: Creating patch of <Pose mituna nervous spark alt talk v1* of !mituna nervous spark alt>
INFO: Creating patch of <Pose mituna nervous spark alt v1* of !mituna nervous spark>
INFO: Creating patch of <Pose mituna nervous spark talk v1* of !mituna nervous spark>
INFO: Creating patch of <Pose mituna nervous alt v1* of !mituna nervous>
INFO: Creating patch of <Pose mituna nervous spark v1* of !mituna nervous>
INFO: Creating patch of <Pose mituna idle frown v1* of !mituna idle>
INFO: Creating patch of <Pose mituna idle smile v1* of !mituna idle>
INFO: Creating patch of <Pose mituna idle spark v1* of !mituna idle>
INFO: Creating patch of <Pose mituna idle talk v1* of !mituna idle>
INFO: Creating patch of <Pose mituna angry v1* of !mituna idle>
INFO: Creating patch of <Pose mituna confused v1* of !mituna idle>
INFO: Creating patch of <Pose mituna cry v1* of !mituna idle>
INFO: Creating patch of <Pose mituna defensive v1* of !mituna idle>
INFO: Creating patch of <Pose mituna explode v1* of !mituna idle>
INFO: Creating patch of <Pose mituna frustrated v1* of !mituna idle>
INFO: Creating patch of <Pose mituna grin v1* of !mituna idle>
INFO: Creating patch of <Pose mituna nervous v1* of !mituna idle>

For each patch, the algorithm takes a “base” image and an “updated” image, and tries to find the smallest rectangle of “difference” between the images. The patch is then a note of the rectangle from the updated image that needs to placed over the base image to recreate the updated image.

There are fuzzing options, of course, so very small compression differences go ignored. There are also cases where the “different” area is so large that it makes more sense to just treat the updated pose as a new pose, rather than an awkward edit of the parent. The result should be intuitive as well as efficient.

We then get a new tree made of patches and normal poses:

INFO:  - <Pose mituna idle v1* of None>
INFO:    - <Pose mituna angry v1* of !mituna idle>
INFO:      - <Pose mituna angry spark v1* of !mituna angry>
INFO:        - <PatchPose mituna angry spark talk v1* of !mituna angry spark@314,195>
INFO:      - <PatchPose mituna angry talk v1* of !mituna angry@314,195>
INFO:    - <Pose mituna cry v1* of !mituna idle>
INFO:    - <Pose mituna explode v1* of !mituna idle>
INFO:    - <Pose mituna frustrated v1* of !mituna idle>
INFO:      - <PatchPose mituna frustrated spark v1* of !mituna frustrated@155,169>
INFO:        - <PatchPose mituna frustrated spark talk v1* of !mituna frustrated spark@327,219>
INFO:      - <PatchPose mituna frustrated talk v1* of !mituna frustrated@327,219>
INFO:    - <Pose mituna grin v1* of !mituna idle>
INFO:    - <Pose mituna nervous v1* of !mituna idle>
INFO:      - <Pose mituna nervous spark v1* of !mituna nervous>
INFO:        - <PatchPose mituna nervous spark alt v1* of !mituna nervous spark@310,112>
INFO:          - <PatchPose mituna nervous spark alt talk v1* of !mituna nervous spark alt@324,224>
INFO:        - <PatchPose mituna nervous spark talk v1* of !mituna nervous spark@314,195>
INFO:      - <PatchPose mituna nervous alt v1* of !mituna nervous@310,112>
INFO:        - <PatchPose mituna nervous alt talk v1* of !mituna nervous alt@324,224>
INFO:    - <PatchPose mituna idle frown v1* of !mituna idle@248,45>
INFO:      - <PatchPose mituna idle frown talk v1* of !mituna idle frown@323,221>
INFO:    - <PatchPose mituna idle smile v1* of !mituna idle@311,148>
INFO:      - <PatchPose mituna idle smile talk v1* of !mituna idle smile@324,224>
INFO:    - <PatchPose mituna idle spark v1* of !mituna idle@159,148>
INFO:      - <PatchPose mituna idle spark talk v1* of !mituna idle spark@324,224>
INFO:    - <PatchPose mituna idle talk v1* of !mituna idle@324,224>
INFO:    - <PatchPose mituna confused v1* of !mituna idle@214,45>
INFO:      - <PatchPose mituna confused talk v1* of !mituna confused@312,236>
INFO:    - <PatchPose mituna defensive v1* of !mituna idle@228,45>
INFO:      - <PatchPose mituna defensive blush v1* of !mituna defensive@343,272>

You can see here, for instance, that “angry” was so different from “idle” that it was treated as a separate pose. Looking at the poses together, this makes perfect sense:

The program also (optionally) creates visualizations of the process so you can review the decisions and tweak the settings as needed.

Here, the areas that are the same are in black (or pink), and the differences are highlighted. There are so many spaces that the new patch would have to be almost as large as the original image, and so there is not a significant performance benefit in creating a patch for these two.

Between angry and angry talk, though, there is only a slight difference in the mouth area. This is a prime candidate to compress.

We then get two pieces of output. First, a new set of image files, but only the pieces used by the revised pose tree:

You can see that these have a dramatically reduced size. All we have here are the pieces we need: in Mituna’s case, some base poses that include the whole body, and subsections of his face for expressions.

We also get this middle layer; a Ren’py file that defines the displayable image files:

image !mituna idle = Image("{{assets}}/characterp/mituna/idle.png", yanchor=0.95)
image !mituna angry = Image("{{assets}}/characterp/mituna/angry.png", yanchor=0.95)
image !mituna angry talk = Composite(
    (780, 780),
    (0, 0), Crop((0, 0, 780, 195), "__p__mituna angry"),
    (0, 195), Crop((0, 195, 314, 309), "__p__mituna angry"),
    (314, 195), "{{assets}}/characterp/mituna/angry_talk 314,195.png",
    (462, 195), Crop((462, 195, 780, 309), "__p__mituna angry"),
    (0, 309), Crop((0, 309, 780, 780), "__p__mituna angry"), yanchor=0.95
)
...

mituna idle and mituna angry are fairly standard definitions (“Just show this image”). mituna angry talk is a complex object made up of sliced sprites. This is the “cut a hole” system mentioned earlier. The top, bottom, left, and right are just subsections of the original mituna angry pose, but in the middle, there’s a patch inserted. You can see how this would be completely impractical to do at hand, at scale.

The results

This method frees up a significant amount of space. Using the Mituna example, his original sprites were about 4.3M all together:

$ du -sh mituna/
4.3M    mituna/

After compression, his sprite folder was almost half that, at 2.2M:

$ du -sh rpydiff_out/characterp/mituna/
2.2M    rpydiff_out/characterp/mituna/

(This doesn’t include the mituna.rpy character definition file, which is a negligible 9.41 kb.)

That’s a 50% compression compression ratio that losslessly encodes a character worth of sprites in just a few seconds. And, once the compression is done, the performance benefit for all the users is free.²

At first I thought that the RPA format Ren’py uses to store assets might be smart enough to do some of this compression for me, but a quick test revealed that… not so much.

$ du -sh *
2.1M    mituna_compressed.rpa
4.2M    mituna_uncompressed.rpa

I think there is a much better reason to use RPA archives than just naive copy-protection though, which is the game delivery pipeline. If your renpy build is properly configured, different archives can contain data for different portions of the game. That structure, combined with a smart content updating system like Steam, can let developers push incremental updates that only have to change a few files, instead of having to redownload the whole game from scratch.

Conclusion

This is… really good? Astonishingly good, considering that the program can do the work without intervention. This all took a few days and about 800 SLOC of python that’s available as a script in my Fansim Engine github repo. Hopefully it makes sense; the application logic (especially the recursion) can get very complex in code. This also isn’t optimized at all; it’s all done single-threaded and synchronously, the code that finds the smallest bounding box is native python that looks like this:

    for x in range(w):    # for every col:
        for y in range(h):    # For every row
            op = originalp[x, y]
            up = updatep[x, y]
            same = (op == up) or (op[3] == 0 and up[3] == 0)
            if not same and distance(op, up) > fuzz:
                x1 = min(x1, x)
                y1 = min(y1, y)
                x2 = max(x2, x + 1)
                y2 = max(y2, y + 1)

I guess my takeaways here are:

Think about sensible ways to do things
Choosing not to optimize your game files is rude
Befriendus is good, go play it.

Caveats

There are a few things I have to mention here:

Performance cost

The tradeoff here is between the space savings and a slight performance cost. When Ren’py starts up, it caches the images at runtime, which involves doing image processing essentially on-the-fly. As far as I can tell, the performance cost here is negligable on modern systems, although I haven’t found a reliable way of actually testing that.

Side effects

I have had a single report of a case where Ren’py didn’t stitch the textures together properly, pictured here:

As far as I can tell, what’s happening here is this: When Ren’py starts in full screen (or any nonstandard resolution), it resizes the textures internally and caches them at the desired resolution. What’s happening here, I think, is that the resize is happening before the texture stitching, leading to visual artifacts around the edges. This would be similar behavior to something I saw with the very first version of Befriendus, where the frame background was scaled and aliased before the texture was tiled, leading to subpixel artifacting:

The slightly hacky workaround for the subpixel scaling issue was to simply add a 1-pixel border around the edge of the tiled area, so when it aliased, it would blend to black instead of yellow. This isn’t the best fix, but it works, and rendering is so low-level in Ren’py that it’s probably more stable to leave it alone when possible.

These are made using Wiztree, which is a very good way of looking at disk space consumption. ↩↩
See Performance cost ↩

Jinja2 as a Pico-8 Preprocessor

2022-12-11T00:00:00-06:00

Pico-8 needs constants

The pico-8 fantasy console runs a modified version of lua that imposes limits on how large a cartridge can be. There is a maximum size in bytes, but also a maximum count of 8192 tokens. Tokens are defined in the manual as

The number of code tokens is shown at the bottom right. One program can have a maximum of 8192 tokens. Each token is a word (e.g. variable name) or operator. Pairs of brackets, and strings each count as 1 token. commas, periods, LOCALs, semi-colons, ENDs, and comments are not counted.

The specifics of how exactly this is implemented are fairly esoteric and end up quickly limiting how much you can fit in a cart, so people have come up with techniques for minimizing the token count without changing a cart’s behaviour. (Some examples in the related reading.)

But, given these limitations on what is more or less analogous to the instruction count, it would be really handy to have constant variables, and here’s why:

-- 15 tokens (clear, expensive)
sfx_ding = 024
function on_score()
  sfx(sfx_ding)
end

function on_menu()
  sfx(sfx_ding)
end

-- 12 tokens (unclear, cheap)

function on_score()
  sfx(024)
end

function on_menu()
  sfx(024)
end

The first excerpt is a design pattern I use all the time. You’ll probably recognize it as the simplest possible implementation of an enum, using global variables. All pico-8’s data — sprites and sounds, and even builtins like colors — are keyed to numerical IDs, not names. If you want to draw a sprite, you can put it in the 001 “slot” and then make references to sprite 001 in your code, but if you want to name the sprite you have to do it yourself, like I do here with the sfx.

Using a constant as an enumerated value is good practice; it allows us to adjust implementation details later without breaking all the code (e.g. if you move an sfx track to a new ID, you just have to change one variable to update your code) and keeps code readable. On the right-hand side you have no idea what sound 024 was supposed to map to unless you go and play the sound, or label every sfx call yourself with a comment.

But pico-8 punishes you for that. That’s technically a variable assignment with three tokens (name, assignment, value), even though it can be entirely factored out. That means you incur the 3-token overhead every time you write clearer code. There needs to be a better way to optimize variables that are known to be constant.

What constants do and why they’re efficient in C

I’m going to start by looking at how C handles constants, because C sorta has them and lua doesn’t at all. Also, because the “sorta” part in “C sorta has them” is really important, because the c language doesn’t exactly support constants, and C’s trick is how I do the same for pico-8.

In pico-8 what we’re trying to optimize here is the token count, while in C it’s the instruction count, but it’s the same principle. (Thinking out loud, a case could be made that assembly instructions are just a kind of token.) So how does C do it?

In C, constants are handled “at compile time”, meaning after you’re finished writing the program but before a computer is actually running it. C’s “compile time” is actually a process involving a number of programs consuming each others’ outputs:

from Cornell University

What we care about here is that first step, where square.c is processed into square.i by the preprocessor. The preprocessor is a program that processes C source code into an intermediate format, which importantly is still human-readable C code, before sending that through the rest of compilation. Here’s an extremely simple example with constants:

// Before preprocessing
#include <stdio.h>
#define THE_VAR 5

int main() {
  printf("The value is %d", THE_VAR);
  return 0;
}

// Output: "The value is 5"

// After preprocessing
#include <stdio.h>


int main() {
  printf("The value is %d", 5);
  return 0;
}

// Output: "The value is 5"

The C preprocessor is extremely powerful and handles a lot of this “templatizing” for C code, but as you can see above, what it’s essentially doing is just a find/replace. If we can do that same thing in Pico-8, I’m happy.

Writing a new preprocessor

I looked into writing a feature for picotool for a while that would add support for a feature like this, but ultimately decided against it. Picotool was attractive because it already understood p8 syntax and could build syntax trees, but preprocessing like this didn’t end up fitting well. And then I quickly decided against writing a preprocessor from scratch at all.

Rigging up a preprocessor I already had lying around someplace

Jinja is a generic text file templating language that can easily do what we want here and quite a bit more. It’s usually used for HTML (or sometimes yaml, in ansible) but it’s completely generic and will happily process pico-8 carts out of the box.

We can use Jinja to render out p8 files from p8.j2 templates. This turns the runnable .p8 text file into an intermediate artifact rather than the original source code. So, instead of writing and running file.p8 (and possibly later minifying that to file.min.p8), you write file.p8.j2, run Jinja to create the derivative file file.p8, and run that in the console. It adds a processing layer.

Here it is

j2 · GitHub

j2 is actually a script I have on my path for generically rendering all kinds of templates, but I tweaked it slightly to add a “pico-8 mode” flag that makes minor syntax changes.

As demonstration, here are some example cases from my recent game Heart&:

-- p2 before j2
--% set sfx_dmg = 000
--% set invuln_frames = 20
--% set fpb = (60/(13/(120.4/8))) | round
--% set render_debug = False

function t_soul:dmghit(dmg)
  self.invuln = "{{ invuln_frames }}"
  sfx("{{ sfx_dmg }}")
end

local t_pattern = entity:extend{
 lifespan = "{{ fpb * 4 }}"
}

function pat_circthrow:coupdate()
 local arena = self.stage.arena
 --% with r = 50
 local n = self.numbullets
 local rotn = rndi(4)/4
 for i = 1, n do
  self:addchild(b_thrown(
    vec("{{ r }}", 0):rotate(i/n + rotn)
   ))
  yieldn(2)
 end
--% endwith
end

function actor:drawdebug()
 --% if render_debug
 if debug then
  local spx, spy = self._apos:unpack()
  line(spx, spy,
   mrconcatu(self.pos, 4))
 end
--% endif
end

-- p8 after j2 (newlines added)

function t_soul:dmghit(dmg)
  self.invuln = 20
  sfx(0)
end

local t_pattern = entity:extend{
 lifespan = 276.0
}

function pat_circthrow:coupdate()
 local arena = self.stage.arena

 local n = self.numbullets
 local rotn = rndi(4)/4
 for i = 1, n do
  self:addchild(b_thrown(
    vec(50, 0):rotate(i/n + rotn)
   ))
  yieldn(2)
 end

end

function actor:drawdebug()

end

I’ll go over these cases one by one in a moment, but for now, notice that the rendered output is shorter than the source file on the left. This is unusual for templating languages; usually the goal is to generate a complex output document with a concise template, but here we’re trying to compress information.

This does way more than constants!

There are a few obvious examples of constant-like removing-the-name right away. sfx_dmg is a simple constant; this is the id of the sfx used for the damage noise.

invuln_frames looks like another example of this, but it’s also a gameplay setting. This way, all the variables for properties you want to tweak during testing can be moved to the top of your file (or wherever you want them) without wasting a name on a variable in the final version. Templating can be used to remove these single-assignment variables without loss of clarity, which is important. This technique works on any single-token or single-use variable that never gets reassigned.

fpb stands for frames per beat, which is a nightmare even just to estimate. The song itself (which I’m counting at 8 notes per beat) plays at a speed of “13”. “Speed”, as handled by Pico-8, seems to be a multiplier on the length of each note in samples. In practice, it comes to 1/120.4 seconds.

so fpb = (fps/(speed/(120.4/bpm)))
or fpb = ( 60/( 13/(120.4/ 8)))

I don’t want to be computing that at runtime, but I also don’t want to lose my logic if I tweak something later. So I keep the expression but put it in a template. Note also that arithmetic is done inline at lifespan = "{{ fpb * 4 }}" before rendering!

--% with r = 50 creates a local variable scoped within the with block. This is essentially the same function as previous — treating a value as a setting variable without wasting a name — but scoped within a block, so I don’t worry about any weird side effects of having a set r variable later.

Finally, render_debug lets me optionally disable large hunks of debug-only code before I compile the final version. There are debug graphics and things that don’t need to be in the final game at all — they would just be wasting space — and so the toggle flag lets me remove the tokens themselves without having to manually delete and re-insert code at dozens of different points every time I test.

“What’s that bit there about quotes? Shouldn’t it just be print({{ THE_VAR }})“

Because I want to be able to colorize and lint my templated code too, I want to make sure that all p8.j2 code is syntatically correct pico-8 code, even if it won’t properly. But consider the following:

--% set THE_VAR = 2 + 3
print("the value is " .. {{ THE_VAR }})

That would compile to what I want, but it’s not valid lua as written (you can’t just have {{ there!), so it can’t be cleaned up properly in template form. That won’t do, but these quote-brackets solve the problem.

In the same way, the inline syntax is changed to --% in order to clearly designate a command, but one that parses to lua as a comment. You can even write a highlighting rule to detect and colorize it for you.

Expression evaluation

Here’s something tricky: Jinja2 evaluates expressions, which C’s preprocessor doesn’t, even though the outcome is usually the same:

// Before preprocessing
#include <stdio.h>
#define THE_VAR 2 + 3

int main() {
    printf("The sum is %d\n", THE_VAR);
    return 0;
}

// Output: "The sum is 5"

// After preprocessing
#include <stdio.h>


int main() {
    printf("The sum is %d\n", 2 + 3);
    return 0;
}

// Output: "The sum is 5"

-- p8 before j2
--% set THE_VAR = 2 + 3
print("the sum is " .. "{{ THE_VAR }}")
-- output: "the sum is 5"

-- p8 after j2

print("the sum is " .. 5)
-- output: "the value is 5"

This is exactly what we want! If we did arithmetic in a constant declaration, but it substituted in all the tokens in the expression instead of the expression’s value, that wouldn’t save all the tokens available. Phew!

Moving weirdness to templates is better practice than unreadable code

The optimization document I mentioned earlier, PICO-8-Token-Optimizations, reads

seleb / PICO-8-Token-Optimizations | github.com A few of these are pretty obvious, a few of them are not that obvious. Almost all of them make your code more unreadable, harder to edit, and would generally be considered “bad practice” in a less constrained system.

Making your code unreadable with optimizations is bad practice. We can’t change the constraints of Pico-8 (yet!) but we can take the manual labor out of the process.

Implementation!

So, when I sit down to write code, my current setup is something like this:

One terminal window running the background, running the alias react j2demo.p8.j2 "j2 j2demo.p8.j2 --pico8", which waits for the file to change and re-runs j2 as soon as it does. (Implementation of that alias is weird, and out of scope of this article.)
- Alternatively, if you have an editor with configurable save hooks, you can rig up j2 to run automatically when you save .p8.j2 files.
Sublime Text configured as a Pico-8 IDE
- Configured with a debug build command that opens the current .p8 file in a new pico-8 window (with a cmd instance, to work around Pico-8 not playing with streams properly)
- Editing my .p8.j2 file in the editor in one pane, letting react regenerate the .p8 file in the other pane within a second or two of saving
- Ctrl+r in pico-8 running the .p8 cart to refresh after saving

You can pick up j2 for yourself if you want.

Gio Flavored Markdown

2022-11-19T00:00:00-06:00

“How can I show someone how my blog articles actually render?”

It sounds like it should be super easy, but it turns out it really isn’t. I write in Markdown (and attach the source to all my posts if you’re interested) that then gets rendered as HTML on-demand by Pelican. (More on this on the thanks page.) But that means there’s no quick way to demo what any given input will render as: it has to run through the markdown processor every time. Markdown is a fairly standard language, but I have a number of extensions I use — some of which I wrote myself — which means to get an authoritative rendering, it has to actually render.

But I want to be able to demo the full rendered output after all the various markdown extensions process. I want a nice simple way to render snippets and show people how that works, like a live editor does. The CSS is already portable by default, but the markdown rendering is done with python-markdown, which has to run server-side somewhere, so that’s much less portable.

So I spent two evenings and wrote up gio-flavoured-markdown.glitch.me, which does exactly that. You can view the live source code here if you want to follow along.

Glitch is a fantastic service for running all kinds of websites. They have an editor for simple static websites (they specifically advertise “Glitch in Bio” as a replacement for something like carrd, for instance) but they’ll also host more complex websites like Node and React that require server-side processing.

It’s pretty buried in their documentation, but Glitch can be convinced to run Flask, which is a Python webserver. That’s perfect, because my rendering code is all in Python, so it and Flask can understand each other. That’s just enough to put together something approaching a live editor.

I’m trying to make as thin a wrapper as possible for this, which means no copy-pasting code from my local configuration to the app. The logic needs to be super simple. It is, essentially:

Set up the requirements for vanilla flask and python-markdown
Get the latest version of my peliplugins and mdexts repos, which contain the custom logic for my pelican plugins and markdown extensions
Run a flask server that does two things
- Respond to requests on /render by parsing the markdown code passed, rendering it into HTML, and returning that rendered HTML. (The main logic)
- Sets up a page with a code editor on the left for code input and an iFrame on the right that’ll contain the rendered code

There is a pelicanconf_markdown.py file I have to synchronize from my local (private) repo if I need to change the configuration, but that’s it.

That iframe business might sound a bit fishy. I should probably be doing something like sending a fetch request to the /render endpoint and updating an iframe’s srcdoc with the response. Instead, all I’m doing is

function updateiframe() {
  const value = view.state.doc.toString();
  const uri_component =
    window.LZString144.compressToEncodedURIComponent(value);
  
  try {
    iframe.setAttribute("src", "/render?q=" + uri_component);
  } catch {}
}

I’m only doing this because it’s super-simple reused logic from another project that had to deal with CORS. CORS shouldn’t be an issue here, but this works well enough.

The only tricky thing is that there’s a hard limit on how long the encoded query argument can be in the URL, which is why I’m compressing it with pieroxy / lz-string in the browser and decompressing with eduardtomasek / lz-string-python in Flask. The first time around I tried using marcel-dancak / lz-string-python but it appears to be unapologetically broken. Oh well.

The editor formats the output like an article by templating it like a very simple article and loading the css directly from the blog’s main production link.

What I’m not doing is actually using Pelican for this process. It’s a good static site generator, but it’s totally superfluous for this. I just had to move the pelican import to register() so I could import the file without issue. (I was also bamboozled the first time around because I was using a walrus operator, but it turns out Glitch only supports Python 3.7, so I had to rewrite that.) In server.py you can see I also have a few dummy objects I use so I can do things like call pelican_init on a pelican extension and have it properly update the settings object even without a real pelican installation.

This is especially useful for these fun little widgets, for instance

The main logic, meanwhile, outsources as much as possible to the various dependencies it pulls in. Again, this is in order to make sure the editor doesn’t have to be updated along with the main blog code; it needs to keep itself working. python-markdown handles the main logic of markdown rendering, with extensions pulled in from other dependencies and repos. Essentially, I’ve scooped the guts of the logic out and I’ve put it back together very generically and with a very, very thin wrapper.

Originally I just had a simple <textarea> as the left-hand side’s editor, but I decided to polish it up and use Codemirror, which is slightly harder to interface with for something this simple but does provide some nice QOL editing features that turned out to be worth it.

Again on the polish side, I copied over some of my markdown test cases as text files and added quick templating buttons to populate the live editor with that code.

And that’s the long and short of it so far! I may keep tinkering with it but for now you can mess around with gio-flavoured-markdown.glitch.me if you’re interested. I may end up using it myself for a few things.

Positioning Things in Ren'py

2021-05-17T00:00:00-05:00

As is common in Python, the mechanical process of displaying something on screen in Ren’py is at once easy to execute and deceptively complicated to execute correctly.

The Ren’py documentation does a fine job of defining the specifications of position properties, but intuitively understanding how to use those properties can still be hard because it doesn’t include much in the way of examples or elaboration, so here are some of those.

Your basic properties

These names come directly from atl transform on the documentation. Note that these are generally parallel with the style properties of the same names.

`pos` - tuple of `(position, position)`

The position of the anchor relative to the top-left corner of the containing area (usually the whole screen).

pos is a coordinate point in the form of (position, position). This will look like (0, 0) or (600, 300) or (0.5, 1.0) or even (-20, 0.5)

The first coordinate is the x coordinate (horizontal) and the second is the y coordinate (vertical). You can set these individually with xpos and ypos, which each take a single position.

Note that pos takes a position rather than a “number”. positions in Ren’py come in two forms, and have two different uses.

If a position is an integer (a number without a decimal point) it’s a number of pixels. (100, 200) is 100 pixels from the left, 200 pixels from the top.

If a position is a float (a number with a decimal point), it’s treated as a percentage. 1.0 is 100%, 0.0 is 0%, 0.5 is 50%. In pos, this percentage is of the total screen, so (0.5, 1.0) is 50% from the left, 100% from the top.

Note that 1.0 and 1 are treated differently! It’s critical that you understand this.

You can mix and match position types. Here’s (0.5, 20):

`anchor` - tuple of `(position, position)`

The position of the anchor relative to the displayable image itself.

anchor is a coordinate point in the form of (position, position), like pos. Again, xanchor and yanchor manipulate the two numbers separately.

For this example, let’s say we have a simple rectangle with a pos of (0.5, 0.5):

This is the default, with anchor = (0, 0). The anchor (still the red dot) is at pos = (0.5, 0.5), the displayable (the grey rectangle) is positioned with its anchor at the rectangle’s top-left anchor = (0, 0)

Here’s anchor = (0.5, 0.0):

Now it’s completely horizontally centered, both relative to the screen and itself.

A nice baseline for a visual novel might be pos = (0.5, 1.0), anchor = (0.5, 1.0), which positions the entire displayable at the bottom center:

Since yanchor = 1.0, the rectangle starts at the anchor and “goes up”, instead of “going down”.

`offset` - tuple of `(int, int)`

The last real value! offset is a simple one, it just nudges the displayable by the given number of pixels. And they’re just integers this time, no need to worry about percentages. Again, xoffset and yoffset manipulate the two components separately.

Here’s a nice little offset figure:

pos = (0.5, 0.5)
anchor = (0, 0)
xoffset = 50

The shortcut ones

Like I said, that was the last real position property! The rest are all shorthand for changing those three.

xcenter = x sets xpos to x and xalign to 0.5
ycenter = y sets ypos to y and yalign to 0.5
align = (x, y) sets both pos and anchor to (x, y)

You may have noticed an obvious pitfall here: there are a lot of different ways to display exactly the same image! Changing anchor by a few pixels looks the same as changing offset, but animates totally differently.

That’s why it’s critical to keep the way you animate things consistent, and think through animations carefully rather than just bashing your code with a hammer until it produces an image that looks good. If you don’t, you’ll find it very easy to write yourself into a corner where animations don’t work correctly and you can’t get ease or other interpolations to do what you want, because you’ve accidently spread a single design decision across three sets of numbers.

Here are my design recommendations, I suppose:

Keep a default align for characters of (0.5, 1.0)
Adjust xpos as needed to move them around the screen.
Have a default offset of (0, 20) so there’s room for the character to move up a few pixels
Just use offset for animations (jumping up and down, sitting, general fx). You should always be able to clamp offset back to near-zero and still have the character in the right area.
If your characters are standing, you probably don’t ever need to touch ypos or yanchor!

How we made Befriendus Ludicrously Accessible

2021-04-13T00:00:00-05:00

Befriendus; everybody’s favorite visual novel about making alien friends. It’s got trolls, yes, but it also has a slew of accessibility options. You can adjust everything: color, font, motion, even spelling. It’s clean, it’s easy, and it works. Here’s how we did it.

When I was designing the basic accessibility framework I had these principles in mind:

Accessible scripts must be easy to write; work should never be duplicated
- Demanding people write multiple versions of work is bad design and encourages accessibility to eventually be dropped in favour of efficient production
Humans should never do postprocessing tasks
- We’re writing software; a computer should do any and all mechanical work, not writers
Accessibility options should have as granular control as possible
- Whenever possible, players should be able to select exactly what they need, not be forced to use something that doesn’t match their needs.
- Options should be compatible with each other whenever possible
- Just pushing out transcripts is not accessible design.

The best way to explain these is probably to explain what we ended up doing, and how each design choice was made carefully in accordance with those principles.

Colour

We knew from the moment we started putting together logic for character colours that we wanted an optional high-contrast mode. One of the first characters written was Mituna, whose light yellow text doesn’t show up super well against our grey textbox:

This is good enough for most cases, but we definitely need a way to turn colors off. Black-on-grey has much more contrast and pops nicely for the high-contrast folks:

This is handled by the Hemospectrum subsystem, a part of FSE.

Characters’ colours are defined with their characters are (mituna, name=Mituna, hemocolor=gold) and processed by the dialogue system when characters speak. Colours are defined semantically and handled correctly at the appropriate stage in the pipeline. (As opposed to some horrible hack, like binding a listener to the option and manually editing every character’s colour in storage every time it’s changed.)

Anytime a color (gold, orange, #f00, #a20000, whatever) needs to be resolved (in the dialogue box, mainly), it’s passed to the hemospectrum function, which resolves colour names and colour codes to universal colour codes.

The logic there is for name resolution, but we also use this entry point to handle contrast logic. Whenever this lookup is made we check if the high contrast user setting is enabled. If it is, we return either black or white, depending on the tone of the colour requested. Since all the colour logic was in one place already, it was easy to add extra logic here. This also gives us the tools to make contextual decisions further down the line — a very light color might pop better as light grey or white, for instance.

Typing Quirks

Characters in the source material, Homestuck, have what are called “typing quirks”. Typing styles, basically. Characters type in different styles, ranging from semi-mundane style choices (lowercase, all caps) to incredibly elaborate (elaborate puns, ending every line with an emote, alphanumeric replacement). I could write a lot about how interesting these are and how they give characters a feeling of tone that the written word rarely conveys, but I’ll save that for another discussion. Brass tacks, we want our characters to do this, and that requires some work.

Now, to my eye, this looks like a build artifact. The “source code” is the script, and once the script is written there’s postprocessing replacement step that has to get done before we publish.

The alternative is for writers to write with quirks to begin with (WH1CH 1N 50M3 C4535 15 UNT3N4BL3) or to run a search-and-replace over the script every time they changed the script. From what I can tell, this is how Homestuck and pretty much every fanfic operate.

Fortunately for us, though, we’re running on a software engine! We can do better.

First, some groundwork. The main gameplay in Ren’py consists of dialogue in script files. Script text looks like this:

show !mituna at speaking

!mituna confused talk "she wouldnt leave without an ip adaptor that was the ONE thing i told her to bring"

!mituna idle frown talk "unless she was an idiot and just didnt. which i guess is unfortunately possible" (show_hashtags="#name of my autobiography: #\"unfortunately possible\"")

show !mituna idle

We don’t care about the stage directions here, let’s look at that dialogue:

On the first line of dialogue mituna is the character speaking, confused talk is his “pose” (the sprite displayed, if omitted it just uses the previous one), and the rest is the text that shows up in the dialogue box. When the story gets to this line, the character mituna says his line with a pose. (Remember that the character does the saying, this will come up later.)

The second line is pretty much the same thing, except you can see there’s some extra data called “show_hashtags” at the end. In Befriendus, the character dialogue boxes have an optional second line of text called hashtags, and this just tells the engine about that.

Here’s what that should look like:

But if you get Befriendus and play with all the default settings, here’s what you actually get:

There’s some trickery going on here! Mituna’s text has its alphanumeric substitutions. Where did this happen?

Here’s the trick: all befriendus characters automatically modify their dialogue based on the currently set options. When the mituna character got the line, it changed the line to this:

"{quirk=mituna}unless she was an idiot and just didnt. which i guess is unfortunately possible{/quirk}"

That bit in brackets is a tag. Ren’py uses text tags as internal control commands for things like text speed or text style like boldness and italics, but it also lets you define your own tags to operate on the text. That’s what we’re doing here.

This notes that the quirk with the name mituna should be applied to the text if quirks are enabled, but it hasn’t actually done it yet. At the beginning of the route, when we first defined the mituna character in the first place, we added this line once:

init python:
    QuirkStore["mituna"] = [(c, "31073107"[i]) for i, c in enumerate("ELOTelot")]

The specifics of the right-hand side are the instructions for how to translate Mituna’s text and are black magic. What matters is we’ve told something called the QuirkStore how to apply the mituna quirk. Now every time text is rendered, as part of the engine’s default tag parsing (alongside bold, italics, links, etc…), the {quirk} tag checks whether quirks are enabled in options and applies them on-the-fly.

This lets us do some great stuff. We’re able to quirks anywhere we want (title screen tags, route titles, hashtags) without having to worry about extra cases: there’s no M*N problem since all the logic is handled in one place.

Keeping the semantic, pre-process copy of the text around has obvious benefits when it comes to translation or text-to-speech. Since the dialogue is stored correctly it’s easy for text-to-speech to read from the original text, rather than try to stumble through alphanumeric replacement or some other slurry.

Puns

I mentioned earlier that some quirks involve puns. While you could do this with regular expressions, (or write two copies of every script, yikes) we took a better approach and just piggybacked off the tags system again.

Here’s what Meenah’s dialogue looks like:

!meenah pissed "but HELLO we ended up getting busted {pun=halfwave}halfway{/pun} through and its only cuz of MY quick {pun=sinking}thinking{/pun} that we got here at all" (show_hashtags="#had to {pun=finprovise}improvise{/pun} like MAD")

!meenah snarky "{pun=betides}besides{/pun} i gave you my trolltag didnt i"

The {pun} tag is another Befriendus original. The text inside the tag is the original word, and the text after the = is the pun version. As with quirks, this lets the decision of what text to use be made at runtime, and globally. Tags hook into the global text system, so the pun and quirk systems are availible anc consistent anytime we display text.

Mix-and-match

I really can’t emphasize this enough: all the text features work together. You can toggle quirks independent of color, you can adjust puns independent of quirks, everything. Because everything is structured correctly, this is exceedingly easy to write for.

Motion

Unfortunately, “don’t duplicate work” has its limits, and animation is one of them. All our motion-intensive animations and flashing lights have to be written out twice; one full, one reduced. There’s a simple flag in the options menu that determines which one plays in the game.

While ATL has some support for conditionals, I haven’t found that to work consistently enough for our purposes, so we do have some icky logic mixed in with the script.

Here’s what Mituna’s flashing effect looks like:

# FLASH VARIANTS
image !psionicborder_flash:
    block:
        parallel:
            "{{assets}}/psionics_01.png"
            pause(0.08)
            "{{assets}}/psionics_02.png"
            pause(0.08)
            "{{assets}}/psionics_03.png"
            pause(0.08)
            repeat
        parallel:
            zoom 1.0
            ease 2 zoom 0.8
            ease 2 zoom 1.0
            repeat

transform __p__psionicoverlay_flash_template(fadedur=1.0, pausedur=2.4):
    contains:
        "#F20000"
        alpha 0.0
        linear fadedur alpha 0.22
        pause pausedur
        linear fadedur alpha 0.0
        pause pausedur
        repeat

    contains:
        "#003BFF"
        alpha 0.22
        linear fadedur alpha 0.0 
        pause pausedur
        linear fadedur alpha 0.22
        pause pausedur
        repeat

image !psionicoverlay_flash:
    __p__psionicoverlay_flash_template(fadedur=1.0, pausedur=2.4)

image !psionicoverlay_noflash:
    __p__psionicoverlay_flash_template(fadedur=2.4, pausedur=2.4)

# NO-FLASH VARIANTS
image !psionicborder_noflash:
    "{{assets}}/psionics_01.png"
    zoom 1.0
    alpha 1.0
    linear 1 alpha 0.8
    pause 1.0
    linear 1 alpha 1.0
    repeat

image !psionicoverlay_noflash:
    "#F2000022" with Dissolve(4.4)
    pause 4.6
    "#003BFF22" with Dissolve(4.4)
    pause 4.6
    repeat

# This should allow players to change the setting at any time
# This shouldn't ever leave the old version on the screen
image !psionicborder = ConditionSwitch(
    "persistent.flash", "__p__psionicborder_flash",
    "not persistent.flash", "__p__psionicborder_noflash"
)

You can see we tried to eliminate duplication as much as possible using subanimations here, and we even have a ConditionSwitch there at the end. But still, when we trigger the effect in-game, it looks like

if persistent.flash:
    show !psionicoverlay_flash #<- flash variant
else:
    show !psionicoverlay_noflash
with dissolve
hide !mituna with easeouttop

Fortunately, there are only a few cases of this in the game.

Juicy Builtins

Ren’py has plenty of built-in accessibility features that we make sure to expose to the player:

As shown you can replace the fonts, adjust text size and spacing, and even turn on automatic text-to-speech.

This didn’t require any real work on our part, except for communicating to the player that this menu exists, which we do at the bottom of the options menu:

As mentioned previously, it was also important for voicing that we kept the original english script around instead of preprocessing the whole thing into quirks.

Translation

Ren’py also makes it easy for fans to make and distribute dialogue translations. All our hashtags, menu text, and dialogue use the translation system to make this as easy as possible. Things like pun and quirk tags also make it easier to translate non-words by exposing the intent behind them.

Transcripts

I can’t take any credit for this one either; Alien and Robin maintain incredibly detailed transcripts for all the routes and features on the game page using a web of google docs. I wrote a utility to pull transcripts from Friendsim, but we don’t use that because we have access to all the original scripts. This makes making transcripts for Befriendus is much easier than fan transcripts for, say, Pesterquest.

Alien and Robin actually maintain two distinct sets of transcripts. Alien makes traditional text transcripts of the routes (with colours and quirks) that are as close to gameplay as possible, while Robin makes transcripts that are as accessible as possible, with quirks and colours removed and with added text descriptions of effects, poses, and animations.

Unlike other accessibility features, these aren’t mix-and-match; any changes need to be manually propagated through all the transcripts. Transcripts, though, aren’t part of the prototyping cycle; they’re put together at the very end, sometimes even after the route releases.

Warnings

We have a warnings page with individually spoiled content warnings for each route. There’s a large button for this on the main menu, so players who are interested won’t miss it. We also try to include appropriate content warnings without spoiling the route, which can be a tricky balance.

This isn’t a traditional accessibility feature, but it does make the game more accessible.

Well, that’s what we’ve done so far. There’s more game yet to go, though; if we add some other major accessibility feature I’ll try to remember to come back to add it here.

I don’t have any groundbreaking takeaways here that I didn’t give away in the first paragraphs. Design your engine in a way to prevent humans doing duplicate work; let the data do the lifting for you. If humans have to do everything twice, no they won’t. Give players control; let them tweak their experience precisely to their liking. If done well, it doesn’t have to be all-or-nothing. Accessibility is necessary, and it doesn’t have to be hard if it’s designed properly.

ACNH Printer - a writeup!

2020-11-05T00:00:00-06:00

This is a writeup of a project I did in April but never released. Well, I’ve definitely released it now, if you want to give it a try!

Instead of a real introduction, here’s a video demo, with camcorder LP technology from 2005:

I am not going to buy a capture card

Ever since Wild World, Animal Crossing has had a pattern system, where players can design their own textures and use them as clothes or decoration. New Horizons has one, but since it doesn’t have a stylus you have to either use the directional pad to mark individual pixels or draw with your fingertip.

I thought it would be fun to find a way to automate that. Now, granted, it takes a while, but it’s still much faster than trying to copy pixels over by hand.

The USB bit

Using work done by shinyquagsire23’s Switch Flightstick project, you can use a Teensy board to simulate a controller and send commands programatically.

The Teensy only has a tiny amount of memory, though, so any program program has to be pretty small. This rules out, say, loading a 32x32 png file and some commands to the board; you need to generate a compressed instruction set on a computer and compile that.

The engine I wrote for the Teensy is fairly simple: I define a series of steps in a large array, and then iterate through that:

#include "types.h"
uint8_t step[] = {
    8, 8, 1, // X (SetDrawingF) x 1
    0, 0, 1, // HAT_UP x 1
    4, 8, 1, // A (SetTool) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 8, 1, // NONE x 1
    4, 8, 1, // A (ResetPalette) x 1
    0, 8, 1, // NONE x 1
    0, 2, 1, // HAT_RIGHT x 1
    4, 8, 1, // A (SetTool) x 1
    ...

(It also appends some boilerplate for setting up the controller, like pressing the triggers together.)

My code treats each group of 3 uint8s as a logical frame, and sends one frame every 12 cycles. This times to just about 30 fps.

The logical frame itself is extremely compressed: I never need to touch the analog stick, just the buttons and the hat. The first number is the data set for the hat, the second number is the data sent for the buttons, and the last number is the number of times that frame is repeated. Button data and hat data here are, of course, bitmasks, using the descriptors in types.h.

When the Teensy is flashed and plugged in to the Switch via USB, it starts pressing buttons, until it has pressed all the buttons, and then it stops.

That’s enough for the Teensy to run simple programs, so long as I can write and compile them.

Generating the program

So, with that working, you still need to do all the logical work of figuring out what buttons to press, and in what order.

First, a breakdown of how patterns actually work:

The canvas¹ is 32x32, and you can draw on it with a number of simple, MSPaint style tools. For this project, I use the pencil and the global fill tool, along with the “mirror” option. There are likely more optimizations you could do by using more tools, but I haven’t done that yet.

In the New Horizons pattern designer, you can define your own color palette. You get 15 color slots to work with, and each color is defined by hue, saturation, and value. There are 30 hue increments, and 15 increments each for saturation and value.

Now, the first thing you need to do, strictly speaking, is generate a 32x32 image file with only 15 unique colors. I don’t automate that, I just use Paint.NET. Then you open that file with makesteps.py, which is where all the logic for the program lives.

The general system for generating the instruction set is thus:

Load an image
Create a virtual 32x32 canvas and set it to the defaults the game uses
Generate a game-ready palette
Incrementally edit the virtual canvas using the tools available in the game, recording each step
Convert that series of steps to button presses
Flash the Teensy and let it run

1. Load an image

When I load the image, I validate it. It needs to be 32x32, it needs to have a palette of 15 colors or fewer, etc.

2. Create a virtual canvas

In order to make sure I draw the image correctly — and so it’s easy to check for errors — I make a virtual canvas and simulate the entire drawing process.

The actual virtual canvas is a simple python object:

class ACCanvas():
    def __init__(self, width, height):
        super(ACCanvas, self).__init__()
        self.w = width
        self.h = height
        self.canvas = [[None for x in range(width)] for y in range(height)]
        self.palette = None
        self.steps = []

Here, the pixel values are stored in self.canvas, which is just a two-dimentional list initialized to all Nones. The ACCanvas class is also where I store helper functions that work on the canvas array, like genPalette to determine what colors are on the canvas, or toImage to create a PIL.Image version I can save as a png.

This is especially nice because it lets me export the finished image locally. Because of the color limitations of the game, the colors in the original image will be clamped somewhat, and the virtual canvas lets me test what that looks like.

ACNH also uses the 6xBRZ scaling algorithm for displaying patterns in-game. 6xBRZ is a pixel-scaling algorithm, so instead of pixel art, the final pattern is made of curves and triangles. The pixels are replaced with lines and shapes that are meant to better represent the meaning of the shape.

Here is an example, where the input file is pixel art of a horse fighting a football player:

3. Generate a game-ready palette

Now I take all the colors in the input image and put together a palette that can be used in the game.

The first and most obvious step is converting the colors: as mentioned before, ACNH has 30 possible hues and 15 possible saturations and values, whereas the input image has 256 possible states for each. The first order of business, then, is reducing the bits on these.

Here’s what that looks like:

import colorsys

# Zero index
HUES = 30 - 1
SATS = 15 - 1
VALS = 15 - 1

def percToInt(max):
    def c(val):
        return round(val * max)
    return c


def rgbaToACColor(pixel):
    if pixel[3] == 0:
        # Transparent, bad
        # raise NotImplementedError
        return (-1, -1, -1)
    # Get RGB values from pixel tuple
    r, g, b, *_ = pixel
    # Convert to HSV 
    h, s, v = colorsys.rgb_to_hsv(r, g, b)
    # Colorsys returns V as an int from 0-255, so turn that into a percentage.
    # s and v are already floats from 0.0-1.0, so no correction needed.
    v /= 255
    tup = (percToInt(HUES)(h), percToInt(SATS)(s), percToInt(VALS)(v))
    return tup

This gives us a nice hsv tuple with the game’s drastically reduced domain.

(The steps for this, by the way, are hideous: hundreds of individual ticks to configure the sliders exactly right for each color.)

This isn’t good yet, though, because there are a number of compression steps to do:

Set all colors with V=0 to the same hue (they’re white/grey/black)
Set all colors with S=0 to the same hue and vividness (they’re black)

Otherwise, we might waste multiple color slots on identical colors.

In the future, it might be possible to some sort of optimization by putting colors that frequently appear adjacent to each other in the image closer together on the palette, to reduce the number of color swaps.

4. Incrementally edit the virtual canvas

This is, by far, the most complicated part of the program, because we don’t just have to mark each pixel correctly, we need to do it efficiently. Otherwise it’ll take a very long time to run, or else it might not fit on the Teensy at all.

All our drawing methods are stored in a class called Printer; every actual printer is a class that inheirits from this. It has functions like moveTo to move the cursor to a pixel, setColor to change the selected color, setTool to set the selected tool, etc. More on the printer implementation in section 5.

The very simplest implementation of this is NaivePrinter, which simply visits every pixel on the canvas and marks it:

class NaivePrinter(Printer):

    def drawImageCustom(self, source):
        new_steps = []

        for x, y in self.smartTraverse(source):
            new_steps += self.markPixel(x, y, source.canvas[x][y])
        return new_steps

This isn’t quite as bad as it sounds, because smartTraverse tries to be somewhat sensible in how it traverses the canvas: by default it snakes around, so as to traverse the full canvas in one continuous line without wasting time by covering any spots it already visited: (4x4 canvas to demonstrate):

Now, I’ll be honest with you, I’m lousy² with algorithms. Algorithms are obtuse, horrible little things that should be buried away in functions and never looked directly at. So, instead of doing any incredibly robust analysis of the source image to determine what method would correctly print the full image in the fewest number of steps, I just try a lot of different methods and check afterwards to see which one is fastest. Because each step takes a logical frame, it’s easy to quickly time this.

In addition to the NaivePrinter shown above, here are some other methodologies I use:

ScreenPrinter prints one color at a time:

class ScreenPrinter(Printer):

    def drawImageCustom(self, source):
        new_steps = []

        for color in source.palette:
            for x, y in self.smartTraverse(source):
                if source.canvas[x][y] == color:
                    new_steps += self.markPixel(x, y, color)
        return new_steps

This can save a significant amount of time depending on the source image, as changing color midway through the image can be expensive.

SpiralPrinter starts in the middle of the canvas (where your cursor defaults to) and traverses the canvas in a spiral outward.

There are also other settings I permute through, like smartTraversing vertically instead of horizontally, or setting the game’s “Mirror” mode to print two spaces at once, or using the “Fill All” tool at the beginning of the print.

5. Convert that series of steps to button presses

Each of these functions that edits the virtual canvas also yields a list of steps. In the python script, steps are stored as enums that represent button presses, with their values being (button, hat) tuples, as such:

class Step(enum.Enum):
    NONE = (0x0, 0x08)
    Y = (0x01, 0x08)
    B = (0x02, 0x08)
    A = (0x04, 0x08)
    ...
    HAT_UP = (0, 0x00)
    HAT_RIGHT = (0, 0x02)
    ...

As I edit the canvas, I collect those movements into a list, and at the end of the process I serialize that list to the teensy steps format, as described earlier.

class Printer():
    ...

    def toSteps(self):
        new_steps = []
        self.source.genPalette()

        new_steps += self.setPalette(self.source.palette)
        new_steps.append(Step.NONE)
        new_steps += self.drawImage(self.source)
        return new_steps

Except I don’t just do that, because that would be extremely slow. If you did every step sequentially, you would end up wasting a ton of time, because there are a lot of steps that can run in parallel. By the time you actually press the A button and write the pixel, everything needs to be set properly. However, before then, multiple steps can be folded together.

Take, as an example, needing to mark a pixel that is 4 pixels away and 5 colors away. Moving the cursor uses the hat only, and changing the color uses the trigger buttons.

Instead of doing

Right x4 (move cursor)
LR x5 (change color)
A x1 (mark pixel)

sequentially, you can collapse the steps into

Right + LR x4 (move cursor & hange color)
LR x1 (change color)
A x1 (mark pixel)

See how this dramatically improves performance:

gantt
    axisFormat %S
    section Sequential
    Set color       :a1, 0, 5s
    Move cursor     :a2, after a1, 4s
    Mark spot       :a3, after a1 a2, 1s

    section Parallel
    Set color       :b1, 0, 5s
    Move cursor     :b2, 0, 4s
    Mark spot       :b3, after b1 b2, 1s

This algorithm actually implements step folding:

from itertools import zip_longest

def foldSteps(step1, step2):
    if step1.value[0] != 0x0 and step2.value[0] != 0x0: 
        # Both steps contain a button press, cannot fold
        return [step1, step2]
    if step1.value[0] == Step.LR.value[0] or step2.value[0] == Step.LR.value[0]:
        # At least one step contains LR, cannot fold
        return [step1, step2]
    if step1.value[1] != 0x8 and step2.value[1] != 0x8: 
        # Steps contain different hat directions, cannot fold
        return [step1, step2]
    else:
        return [PseudoStep(step1).plus(step2)]


def foldStepSeqs(steps1, steps2):
    if not steps1:
        return steps2
    if not steps2:
        return steps1

    new_steps_compressed = []   
    for xstep, ystep in zip_longest(steps1, steps2, fillvalue=Step.NONE):
        new_steps_compressed += foldSteps(xstep, ystep)
    return new_steps_compressed

In addition to this postprocessing, there’s additional compression and optimization throughout the step generation process. Printer.moveCursorTo(x, y) uses zip to group steps together and use diagonal hat movement when possible. Setting commands like setMirrored and setTool use state to keep track of the setting, and don’t require a step if the option is already set correctly.

6. Flash the Teensy and let it run

And I’m done! Just plug the teensy into the switch at the right moment and it will print the pattern autonomously.

That’s, uh, all I’ve got, really. If you’ve got a Teensy or $20 and want to print your own patterns, or you just want to take a closer look at how this was done, you’re welcome to grab the code.

Technical Demo

The program itself runs something like this:

$ python3 makesteps.py --help
usage: makesteps.py [-h] [--dump | --no-dump] [--gen | --no-gen] [--preview | --no-preview] [--bogo | --no-bogo]
                    [--make | --no-make]
                    infile

positional arguments:
  infile        Input pattern file

optional arguments:
  -h, --help    show this help message and exit
  --dump        Save pattern (Default: True)
  --no-dump     Save pattern (Default: True)
  --gen         Generate steps file (Default: True)
  --no-gen      Generate steps file (Default: True)
  --preview     Generate scaled preview file (Default: True)
  --no-preview  Generate scaled preview file (Default: True)
  --bogo        Find fastest solution (Default: True)
  --no-bogo     Find fastest solution (Default: True)
  --make        Automatically run make after completion (Default: False)
  --no-make     Automatically run make after completion (Default: False)

And, running it: (this is the configuration used in the demo video, with SpiralPrinter temporarily disabled)

$ python3 makesteps.py s/despair.png --make
(32, 32)
Generated preview at scalepreview.png
<class '__main__.NaivePrinter'> (00100) printed pattern in 1582 steps (593.25 bytes) (~5m 16s runtime)
BEST!
<class '__main__.NaivePrinter'> (00101) printed pattern in 1582 steps (593.25 bytes) (~5m 16s runtime)
<class '__main__.NaivePrinter'> (00110) printed pattern in 1106 steps (414.75 bytes) (~3m 41s runtime)
BEST!
<class '__main__.NaivePrinter'> (00111) printed pattern in 1110 steps (416.25 bytes) (~3m 42s runtime)
<class '__main__.NaivePrinter'> (01000) printed pattern in 1512 steps (567.0 bytes) (~5m 2s runtime)
<class '__main__.NaivePrinter'> (01001) printed pattern in 1512 steps (567.0 bytes) (~5m 2s runtime)
<class '__main__.NaivePrinter'> (01010) printed pattern in 1047 steps (392.625 bytes) (~3m 29s runtime)
BEST!
<class '__main__.NaivePrinter'> (01011) printed pattern in 1047 steps (392.625 bytes) (~3m 29s runtime)
<class '__main__.NaivePrinter'> (10100) printed pattern in 1246 steps (467.25 bytes) (~4m 9s runtime)
<class '__main__.NaivePrinter'> (10101) printed pattern in 1253 steps (469.875 bytes) (~4m 10s runtime)
<class '__main__.NaivePrinter'> (10110) printed pattern in 933 steps (349.875 bytes) (~3m 6s runtime)
BEST!
<class '__main__.NaivePrinter'> (10111) printed pattern in 941 steps (352.875 bytes) (~3m 8s runtime)
<class '__main__.NaivePrinter'> (11000) printed pattern in 1469 steps (550.875 bytes) (~4m 53s runtime)
<class '__main__.NaivePrinter'> (11001) printed pattern in 1469 steps (550.875 bytes) (~4m 53s runtime)
<class '__main__.NaivePrinter'> (11010) printed pattern in 1031 steps (386.625 bytes) (~3m 26s runtime)
<class '__main__.NaivePrinter'> (11011) printed pattern in 1031 steps (386.625 bytes) (~3m 26s runtime)
<class '__main__.ScreenPrinter'> (00100) printed pattern in 1641 steps (615.375 bytes) (~5m 28s runtime)
<class '__main__.ScreenPrinter'> (00101) printed pattern in 1634 steps (612.75 bytes) (~5m 26s runtime)
<class '__main__.ScreenPrinter'> (00110) printed pattern in 1115 steps (418.125 bytes) (~3m 43s runtime)
<class '__main__.ScreenPrinter'> (00111) printed pattern in 1108 steps (415.5 bytes) (~3m 41s runtime)
<class '__main__.ScreenPrinter'> (01000) printed pattern in 1749 steps (655.875 bytes) (~5m 49s runtime)
<class '__main__.ScreenPrinter'> (01001) printed pattern in 1735 steps (650.625 bytes) (~5m 47s runtime)
<class '__main__.ScreenPrinter'> (01010) printed pattern in 1085 steps (406.875 bytes) (~3m 37s runtime)
<class '__main__.ScreenPrinter'> (01011) printed pattern in 1071 steps (401.625 bytes) (~3m 34s runtime)
<class '__main__.ScreenPrinter'> (10100) printed pattern in 1283 steps (481.125 bytes) (~4m 16s runtime)
<class '__main__.ScreenPrinter'> (10101) printed pattern in 1277 steps (478.875 bytes) (~4m 15s runtime)
<class '__main__.ScreenPrinter'> (10110) printed pattern in 980 steps (367.5 bytes) (~3m 16s runtime)
<class '__main__.ScreenPrinter'> (10111) printed pattern in 974 steps (365.25 bytes) (~3m 14s runtime)
<class '__main__.ScreenPrinter'> (11000) printed pattern in 1697 steps (636.375 bytes) (~5m 39s runtime)
<class '__main__.ScreenPrinter'> (11001) printed pattern in 1691 steps (634.125 bytes) (~5m 38s runtime)
<class '__main__.ScreenPrinter'> (11010) printed pattern in 1063 steps (398.625 bytes) (~3m 32s runtime)
<class '__main__.ScreenPrinter'> (11011) printed pattern in 1057 steps (396.375 bytes) (~3m 31s runtime)
<__main__.NaivePrinter object at 0x000001F4576CCE20>
{'startfill': True, 'usemirror': True, 'vertical': True, 'horizontal': False, 'adjpalette': False}
makefile:59: warning: overriding recipe for target 'clean'
../LUFA/LUFA/Build/DMBS/DMBS/gcc.mk:182: warning: ignoring old recipe for target 'clean'
 [GCC]     : Compiling C file "nextreport.c"
avr-gcc -c -pipe -gdwarf-2 -g2 -mmcu=at90usb1286 -fshort-enums -fno-inline-small-functions -fpack-struct -Wall -fno-strict-aliasing -funsigned-char -funsigned-bitfields -ffunction-sections -I. -DARCH=ARCH_AVR8 -DF_CPU=16000000UL -mrelax -fno-jump-tables -x c -Os -std=gnu99 -Wstrict-prototypes -DUSE_LUFA_CONFIG_HEADER -IConfig/ -I. -I../LUFA/LUFA/.. -DARCH=ARCH_AVR8 -DBOARD=BOARD_NONE -DF_USB=16000000UL  -MMD -MP -MF obj/nextreport.d nextreport.c -o obj/nextreport.o
 [LNK]     : Linking object files into "Joystick.elf"
avr-gcc obj/nextreport.o obj/Joystick.o obj/Descriptors.o obj/HIDParser.o obj/Device_AVR8.o obj/EndpointStream_AVR8.o obj/Endpoint_AVR8.o obj/Host_AVR8.o obj/PipeStream_AVR8.o obj/Pipe_AVR8.o obj/USBController_AVR8.o obj/USBInterrupt_AVR8.o obj/ConfigDescriptors.o obj/DeviceStandardReq.o obj/Events.o obj/HostStandardReq.o obj/USBTask.o -o Joystick.elf -lm -Wl,-Map=Joystick.map,--cref -Wl,--gc-sections -Wl,--relax -mmcu=at90usb1286
 [OBJCPY]  : Extracting HEX file data from "Joystick.elf"
avr-objcopy -O ihex -R .eeprom -R .fuse -R .lock -R .signature Joystick.elf Joystick.hex
g++   -c steps.c
g++   -c nextreport.c
g++  -o test.exe nextreport.o test.o
 [INFO]    : Begin compilation of project "Joystick"...

avr-gcc.exe (GCC) 4.8.2 20131010 (prerelease)
Copyright (C) 2013 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

 [OBJCPY]  : Extracting EEP file data from "Joystick.elf"
avr-objcopy -O ihex -j .eeprom --set-section-flags=.eeprom="alloc,load" --change-section-lma .eeprom=0 --no-change-warnings Joystick.elf Joystick.eep || exit 0
 [OBJCPY]  : Extracting BIN file data from "Joystick.elf"
avr-objcopy -O binary -R .eeprom -R .fuse -R .lock -R .signature Joystick.elf Joystick.bin
 [OBJDMP]  : Extracting LSS file data from "Joystick.elf"
avr-objdump -h -d -S -z Joystick.elf > Joystick.lss
 [NM]      : Extracting SYM file data from "Joystick.elf"
avr-nm -n Joystick.elf > Joystick.sym
 [SIZE]    : Determining size of "Joystick.elf"

avr-size --mcu=at90usb1286 --format=avr Joystick.elf
AVR Memory Usage
----------------
Device: at90usb1286

Program:    4858 bytes (3.7% Full)
(.text + .data + .bootloader)

Data:       1495 bytes (18.2% Full)
(.data + .bss + .noinit)


 [INFO]    : Finished building project "Joystick".
Waiting for AT90USB1286...

(the bitmasks in parenthesis are permutations of settings)

And the generated steps.c file, for those curious:

#include "types.h"
uint8_t step[] = {
    8, 8, 1, // X (SetDrawingF) x 1
    0, 0, 1, // HAT_UP x 1
    4, 8, 1, // A (SetTool) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 8, 1, // NONE x 1
    4, 8, 1, // A (ResetPalette) x 1
    0, 8, 1, // NONE x 1
    0, 2, 1, // HAT_RIGHT x 1
    4, 8, 1, // A (SetTool) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 12, // HAT_LEFT x 12
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 9, // HAT_LEFT x 9
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR1) x 1
    0, 8, 1, // NONE x 1
    0, 4, 2, // HAT_DOWN x 2
    0, 6, 14, // HAT_LEFT x 14
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR2) x 1
    0, 8, 1, // NONE x 1
    0, 6, 1, // HAT_LEFT x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 2, 1, // HAT_RIGHT x 1
    0, 4, 2, // HAT_DOWN x 2
    32, 8, 1, // R (ColorR3) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 12, // HAT_LEFT x 12
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 7, // HAT_LEFT x 7
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR4) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 12, // HAT_LEFT x 12
    0, 4, 1, // HAT_DOWN x 1
    0, 2, 2, // HAT_RIGHT x 2
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR5) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 11, // HAT_LEFT x 11
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 1, // HAT_LEFT x 1
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR6) x 1
    0, 8, 1, // NONE x 1
    0, 4, 2, // HAT_DOWN x 2
    0, 6, 5, // HAT_LEFT x 5
    0, 4, 1, // HAT_DOWN x 1
    32, 8, 1, // R (ColorR7) x 1
    0, 8, 1, // NONE x 1
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 11, // HAT_LEFT x 11
    0, 4, 2, // HAT_DOWN x 2
    32, 8, 1, // R (ColorR8) x 1
    0, 8, 1, // NONE x 1
    0, 2, 7, // HAT_RIGHT x 7
    0, 4, 1, // HAT_DOWN x 1
    0, 2, 2, // HAT_RIGHT x 2
    0, 4, 1, // HAT_DOWN x 1
    0, 6, 1, // HAT_LEFT x 1
    0, 4, 1, // HAT_DOWN x 1
    4, 8, 1, // A x 1
    8, 8, 1, // X (SetDrawingF) x 1
    0, 6, 1, // HAT_LEFT x 1
    0, 4, 1, // HAT_DOWN x 1
    4, 8, 1, // A (SetTool) x 1
    0, 8, 2, // NONE x 2
    16, 8, 6, // L (ColorL2) x 6
    8, 8, 1, // X (SetDrawingF) x 1
    0, 4, 4, // HAT_DOWN x 4
    4, 8, 2, // A (SetTool) x 2
    8, 8, 1, // X (SetDrawingF) x 1
    0, 0, 4, // HAT_UP x 4
    4, 8, 1, // A (SetTool) x 1
    32, 7, 4, // HAT_UP_LEFT+R (ColorR6) x 4
    128, 7, 1, // HAT_UP_LEFT+ZR (SetMirrorT) x 1
    0, 7, 10, // HAT_UP_LEFT x 10
    4, 7, 1, // HAT_UP_LEFT+A x 1
    4, 4, 10, // HAT_DOWN+A x 10
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 10, // HAT_UP+A x 10
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 10, // HAT_DOWN+A x 10
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 10, // HAT_UP+A x 10
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 9, // HAT_DOWN+A x 9
    128, 4, 1, // HAT_DOWN+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 1, // HAT_UP+A x 1
    128, 0, 1, // HAT_UP+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 8, // HAT_UP+A x 8
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 8, // HAT_DOWN+A x 8
    128, 4, 1, // HAT_DOWN+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    4, 2, 1, // HAT_RIGHT+A x 1
    128, 0, 1, // HAT_UP+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 9, // HAT_UP+A x 9
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 10, // HAT_DOWN+A x 10
    16, 4, 2, // HAT_DOWN+L (ColorL4) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 4, 2, // HAT_DOWN+A x 2
    32, 4, 1, // HAT_DOWN+R (ColorR5) x 1
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL4) x 1
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 1, // HAT_DOWN+A x 1
    0, 3, 1, // HAT_DOWN_RIGHT x 1
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 1, // HAT_DOWN+A x 1
    4, 0, 1, // HAT_UP+A x 1
    32, 0, 1, // HAT_UP+R (ColorR5) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL4) x 1
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    32, 0, 1, // HAT_UP+R (ColorR5) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR7) x 1
    32, 8, 1, // NONE+R (ColorR7) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL4) x 1
    16, 8, 2, // NONE+L (ColorL4) x 2
    4, 8, 1, // A x 1
    4, 0, 5, // HAT_UP+A x 5
    32, 0, 1, // HAT_UP+R (ColorR6) x 1
    32, 8, 1, // NONE+R (ColorR6) x 1
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 8, // HAT_UP+A x 8
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 6, // HAT_DOWN+A x 6
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    16, 8, 2, // NONE+L (ColorL3) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 4, 4, // HAT_DOWN+A x 4
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR7) x 1
    32, 8, 3, // NONE+R (ColorR7) x 3
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL5) x 1
    16, 8, 1, // NONE+L (ColorL5) x 1
    4, 8, 1, // A x 1
    4, 4, 2, // HAT_DOWN+A x 2
    16, 4, 1, // HAT_DOWN+L (ColorL4) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR5) x 1
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL4) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 1, // HAT_UP+A x 1
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR4) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 0, 10, // HAT_UP+A x 10
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR6) x 1
    32, 8, 2, // NONE+R (ColorR6) x 2
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 6, // HAT_UP+A x 6
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 5, // HAT_DOWN+A x 5
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    16, 8, 2, // NONE+L (ColorL3) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 4, 5, // HAT_DOWN+A x 5
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 3, // NONE+L (ColorL0) x 3
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    32, 8, 3, // NONE+R (ColorR4) x 3
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 4, 2, // HAT_DOWN+A x 2
    4, 3, 1, // HAT_DOWN_RIGHT+A x 1
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR4) x 1
    4, 8, 1, // A x 1
    4, 0, 6, // HAT_UP+A x 6
    32, 0, 1, // HAT_UP+R (ColorR7) x 1
    32, 8, 2, // NONE+R (ColorR7) x 2
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL4) x 1
    16, 8, 2, // NONE+L (ColorL4) x 2
    4, 8, 1, // A x 1
    4, 0, 8, // HAT_UP+A x 8
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR6) x 1
    32, 8, 2, // NONE+R (ColorR6) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    128, 0, 1, // HAT_UP+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 4, // HAT_UP+A x 4
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 4, // HAT_DOWN+A x 4
    16, 4, 1, // HAT_DOWN+L (ColorL3) x 1
    16, 8, 2, // NONE+L (ColorL3) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    32, 8, 3, // NONE+R (ColorR4) x 3
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 3, // NONE+L (ColorL0) x 3
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    32, 8, 3, // NONE+R (ColorR4) x 3
    4, 8, 1, // A x 1
    4, 4, 2, // HAT_DOWN+A x 2
    32, 4, 1, // HAT_DOWN+R (ColorR7) x 1
    32, 8, 2, // NONE+R (ColorR7) x 2
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL5) x 1
    16, 8, 1, // NONE+L (ColorL5) x 1
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL4) x 1
    4, 8, 1, // A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 3, // NONE+L (ColorL0) x 3
    4, 8, 1, // A x 1
    128, 4, 1, // HAT_DOWN+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    128, 4, 1, // HAT_DOWN+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR4) x 1
    32, 8, 3, // NONE+R (ColorR4) x 3
    4, 8, 1, // A x 1
    4, 2, 1, // HAT_RIGHT+A x 1
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL1) x 1
    16, 8, 1, // NONE+L (ColorL1) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 1, // NONE+R (ColorR3) x 1
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    128, 0, 1, // HAT_UP+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR4) x 1
    32, 8, 3, // NONE+R (ColorR4) x 3
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    32, 0, 1, // HAT_UP+R (ColorR5) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL4) x 1
    4, 8, 1, // A x 1
    4, 0, 2, // HAT_UP+A x 2
    16, 0, 1, // HAT_UP+L (ColorL3) x 1
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    4, 0, 2, // HAT_UP+A x 2
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 2, // NONE+R (ColorR3) x 2
    128, 8, 1, // NONE+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 2, // NONE+R (ColorR3) x 2
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    128, 0, 1, // HAT_UP+ZR (SetMirrorT) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR6) x 1
    32, 8, 2, // NONE+R (ColorR6) x 2
    4, 8, 1, // A x 1
    4, 0, 4, // HAT_UP+A x 4
    16, 3, 1, // HAT_DOWN_RIGHT+L (ColorL0) x 1
    16, 4, 5, // HAT_DOWN+L (ColorL0) x 5
    128, 8, 1, // NONE+ZR (SetMirrorF) x 1
    4, 8, 1, // A x 1
    32, 4, 3, // HAT_DOWN+R (ColorR3) x 3
    4, 4, 1, // HAT_DOWN+A x 1
    0, 4, 3, // HAT_DOWN x 3
    4, 4, 2, // HAT_DOWN+A x 2
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR3) x 1
    32, 8, 2, // NONE+R (ColorR3) x 2
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR1) x 1
    4, 8, 1, // A x 1
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 1, // HAT_DOWN+A x 1
    32, 4, 2, // HAT_DOWN+R (ColorR3) x 2
    4, 4, 1, // HAT_DOWN+A x 1
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 1, // HAT_UP+A x 1
    16, 0, 2, // HAT_UP+L (ColorL1) x 2
    4, 8, 1, // A x 1
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    4, 8, 1, // A x 1
    4, 0, 2, // HAT_UP+A x 2
    32, 0, 1, // HAT_UP+R (ColorR1) x 1
    4, 8, 1, // A x 1
    4, 0, 3, // HAT_UP+A x 3
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    4, 8, 1, // A x 1
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 2, // NONE+R (ColorR3) x 2
    4, 8, 1, // A x 1
    4, 0, 4, // HAT_UP+A x 4
    16, 0, 1, // HAT_UP+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    0, 0, 1, // HAT_UP x 1
    4, 0, 2, // HAT_UP+A x 2
    4, 2, 1, // HAT_RIGHT+A x 1
    32, 4, 2, // HAT_DOWN+R (ColorR3) x 2
    32, 8, 1, // NONE+R (ColorR3) x 1
    4, 8, 1, // A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR3) x 1
    32, 8, 2, // NONE+R (ColorR3) x 2
    4, 8, 1, // A x 1
    4, 4, 4, // HAT_DOWN+A x 4
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    16, 8, 2, // NONE+L (ColorL0) x 2
    4, 8, 1, // A x 1
    4, 4, 5, // HAT_DOWN+A x 5
    32, 4, 1, // HAT_DOWN+R (ColorR1) x 1
    4, 8, 1, // A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    4, 8, 1, // A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    32, 1, 1, // HAT_UP_RIGHT+R (ColorR1) x 1
    4, 8, 1, // A x 1
    4, 0, 11, // HAT_UP+A x 11
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 1, // NONE+R (ColorR3) x 1
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    16, 0, 1, // HAT_UP+L (ColorL1) x 1
    16, 8, 1, // NONE+L (ColorL1) x 1
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    32, 0, 1, // HAT_UP+R (ColorR3) x 1
    32, 8, 1, // NONE+R (ColorR3) x 1
    4, 8, 1, // A x 1
    4, 0, 1, // HAT_UP+A x 1
    16, 0, 1, // HAT_UP+L (ColorL1) x 1
    16, 8, 1, // NONE+L (ColorL1) x 1
    4, 8, 1, // A x 1
    4, 3, 1, // HAT_DOWN_RIGHT+A x 1
    4, 4, 9, // HAT_DOWN+A x 9
    16, 4, 1, // HAT_DOWN+L (ColorL0) x 1
    4, 8, 1, // A x 1
    32, 4, 1, // HAT_DOWN+R (ColorR1) x 1
    4, 8, 1, // A x 1
    4, 4, 2, // HAT_DOWN+A x 2
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 3, // HAT_DOWN+A x 3
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 3, // HAT_UP+A x 3
    0, 0, 4, // HAT_UP x 4
    4, 0, 7, // HAT_UP+A x 7
    32, 0, 1, // HAT_UP+R (ColorR6) x 1
    32, 8, 4, // NONE+R (ColorR6) x 4
    4, 8, 1, // A x 1
    4, 0, 2, // HAT_UP+A x 2
    0, 3, 1, // HAT_DOWN_RIGHT x 1
    4, 4, 2, // HAT_DOWN+A x 2
    16, 4, 2, // HAT_DOWN+L (ColorL1) x 2
    16, 8, 3, // NONE+L (ColorL1) x 3
    4, 8, 1, // A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    0, 4, 5, // HAT_DOWN x 5
    4, 4, 3, // HAT_DOWN+A x 3
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 3, // HAT_UP+A x 3
    32, 1, 1, // HAT_UP_RIGHT+R (ColorR8) x 1
    32, 0, 6, // HAT_UP+R (ColorR8) x 6
    0, 0, 2, // HAT_UP x 2
    4, 0, 1, // HAT_UP+A x 1
    16, 4, 7, // HAT_DOWN+L (ColorL1) x 7
    0, 4, 2, // HAT_DOWN x 2
    4, 4, 4, // HAT_DOWN+A x 4
    4, 1, 1, // HAT_UP_RIGHT+A x 1
    4, 0, 2, // HAT_UP+A x 2
    32, 0, 7, // HAT_UP+R (ColorR8) x 7
    0, 0, 2, // HAT_UP x 2
    4, 0, 2, // HAT_UP+A x 2
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 1, // HAT_DOWN+A x 1
    16, 4, 7, // HAT_DOWN+L (ColorL1) x 7
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 4, // HAT_DOWN+A x 4
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 3, // HAT_UP+A x 3
    32, 0, 7, // HAT_UP+R (ColorR8) x 7
    0, 0, 1, // HAT_UP x 1
    4, 0, 1, // HAT_UP+A x 1
    16, 3, 1, // HAT_DOWN_RIGHT+L (ColorL1) x 1
    16, 4, 6, // HAT_DOWN+L (ColorL1) x 6
    0, 4, 1, // HAT_DOWN x 1
    4, 4, 3, // HAT_DOWN+A x 3
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 0, 3, // HAT_UP+A x 3
    4, 2, 1, // HAT_RIGHT+A x 1
    4, 4, 3, // HAT_DOWN+A x 3
    4, 1, 1, // HAT_UP_RIGHT+A x 1
    4, 0, 2, // HAT_UP+A x 2
    16, 7, 1, // HAT_UP_LEFT+L (ColorL0) x 1
    0, 7, 1, // HAT_UP_LEFT x 1
    0, 6, 13, // HAT_LEFT x 13
 0 };
static int numsteps = 476;

For standard patterns, which is all I’ve done so far ↩
“Lousy” here meaning “poor” (re: performance) rather than “overrun with”, although an argument could be made for either. ↩

Tabs or Spaces?

2020-07-12T00:00:00-05:00

“Tabs or spaces” is one of these age-old computer science preference issues (like whether you use Vim or Emacs¹) that gives people a binary preference they get to pick and then get very attached to, due more to sunk costs and personal identity than anything else. (Good thing that only happens with unimportant stuff.)

I was thinking about this the other day, and I realized that I have an opinion about this, but it’s actually the opposite of what I do. And it’s not because of filesize, or encoding, or anything like that.

(First off, because I’ve actually heard this, nobody is actually physically hitting their spacebar four times. Any decent editor is going to have “spaces mode” where hitting the Tab key inserts four (or two, or whatever) spaces.)

There are many argumments people have come up with on both sides of the issue. Tabs and spaces are both in ASCII, so whether your file is encoded in ASCII, UTF-8, or something bad, both characters take up the same amount of space. When we indent with spaces, though, we use four spaces, not one, so using spaces to indent makes the indentation four times as large to store. This argument is a bit silly, but it’s got numbers in it, and people like that².

Why you should actually use tabs to indent files

If you’re writing a Real Professional Document in Microsoft Word™, and you indent your paragraphs by just pressing space until you think the line looks indented enough, your editor will send your document back with a note saying “You’re incompetent, go back to baby school for babies”, or somesuch. If you want to indent a section, you indent it, you don’t add spaces; spaces and indentation represent fundamentally different things. “Spaces” are different than “space”.

Tabs specify an indentation level, NOT physical space. They’re higher level abstractions, in that sense, than spaces. The tab key was originally for tabulation, or specifying a column in a table. When you specify tabs, you’re not talking about the physical distance (whether in units of pixels or characters) of the next character from the left side of the window, you’re talking about a hierarchical level.

But the biggest argument in favour of tabs is accessibility. Since tabs represent a conceptual indentation level, text editors can render them however the user wants. Some people are comfortable with two-space tabs, some people might require more than four characters worth of space. Some people might want something fancy, like dropped lines signifying the indentation level. I’ve even seen some very clever things done with hanging tabstops, where indented lines are positioned dynamically based on other lines, rather than arbitrarily positioned away from the start of the line.

Why I don’t

I’m a python developer, and in python, whitespace is a big deal. Whitespace is semantic in python (which is wonderful, by the way), and so it matters a great deal how your lines are indented. Take this code example:

def getItems(obj):
    for itemList in obj['items']:
        for item in itemList:
            yield item

Say someone edits this method so it uses yield from syntax, instead:

def getItems(obj):
    for itemList in obj['items']:
		yield from itemList

This is better written, except that it won’t run, because “someone” indented⁴ line 3 there with tabs instead of spaces, which doesn’t match the line above it, and that’s a full-on syntax error³ in python. The python compiler⁵ won’t even run the file.

You can test this by typing this into the interactive prompt. You won’t even get a chance to call the function, it’ll immediately raise a TabError (or IndentationError on awful garbage versions of python that need to be thrown in the trash).

>>> def getItems(obj):
...     for itemList in obj['items']:
...             yield from itemList
  File "<stdin>", line 3
    yield from itemList
                      ^
TabError: inconsistent use of tabs and spaces in indentation
>>>

This is just one example — and I think it’s a pretty good one — of a case where you need to know if some whitespace is a tab or not.

And that’s the crux of the problem. If I’m working on a file that has tabs in it at all, I need to know what’s a tab and what’s a space while I’m working on it. Both tabs and spaces are non-printing characters, which means my editor is going to have to indicate where the tabs are, somehow. Let’s see how they do that:

Oh. Oh. That’s not good at all. Where did all that dirt come from?

And that screenshot is from Github’s pretty HTML5 code viewer; doing something like this on a terminal, or in an environment that requires any amount of contrast, fills your screen with distracting clutter.

There are Vim settings to replace tab characters with arrow characters, and Emacs comes with a standard whitespace-mode to handle differentiating whitespace characters. That looks like

Oh. There’s a problem here.

The amount of additional visual information you need to have on screen if your document contains tab characters amounts to unnecessary clutter. That’s all extra information you have to be be consciously processing.

Beautiful is better than ugly. Clutter is bad and bad for you. I always end up avoiding the problem altogether by just always using spaces.

At least it’s for an actual reason that simplifies my workflow, such that if I used tabs instead, it would cause actual problems. It’s nice to at least have a reason. Since most of my code is either just for me or part of a codebase that already uses spaces, I don’t feel too bad about it.

the correct answer is emacs, no blog article needed ↩
support hbomberguy on patreon and then watch this video ↩
Technically, tabs and spaces are both allowed in python, but they’re not compatible. Line 2 is indented with 4 spaces, but line 3 is indented with 2 tabs. Python won’t try to convert between the two (which is good), it’ll just note that there’s no “matching” indentation level, because if you start indenting with 2 tabs, you need to have been on 1 tab before. ↩
Pelican would have automatically converted that tab character into four spaces when it rendered the document if not for some elaborate workarounds on my part. Oh well. I guess we know their take on the issue. I also had to manually override tab-width, which is 8 spaces by default for some reason? ↩
Python is a compiled language, the people who told you otherwise were lying and you should tell them so. ↩

GioCities - dev

Graph Paper Lindenmeyer Systems

Related Reading

FSE sprite compression

Why?

Sprite compression

How it works

Basic principles

Step by step

The results

Conclusion

Caveats

Performance cost

Side effects

Jinja2 as a Pico-8 Preprocessor

Pico-8 needs constants

What constants do and why they’re efficient in C

Writing a new preprocessor

Rigging up a preprocessor I already had lying around someplace

Here it is

This does way more than constants!

Expression evaluation

Moving weirdness to templates is better practice than unreadable code

Implementation!

Related Reading

Gio Flavored Markdown

Positioning Things in Ren'py

Your basic properties

pos - tuple of (position, position)

anchor - tuple of (position, position)

offset - tuple of (int, int)

The shortcut ones

How we made Befriendus Ludicrously Accessible

Colour

Typing Quirks

Puns

Mix-and-match

Motion

Juicy Builtins

Translation

Transcripts

Warnings

Related Reading

ACNH Printer - a writeup!

The USB bit

Generating the program

1. Load an image

2. Create a virtual canvas

3. Generate a game-ready palette

4. Incrementally edit the virtual canvas

5. Convert that series of steps to button presses

6. Flash the Teensy and let it run

Technical Demo

Tabs or Spaces?

Why you should actually use tabs to indent files

Why I don’t

Related reading

`pos` - tuple of `(position, position)`

`anchor` - tuple of `(position, position)`

`offset` - tuple of `(int, int)`