When Adobe killed Flash Player in 2020, I didn't want my Flash games to disappear forever.
I've been making games on and off my whole life, but people seemed to like the Hapland ones in particular, so I thought it might be nice to fix them up for a Steam release. I could draw some better graphics, improve the frame rate and resolution, and maybe add some extra secrets and such.
The problem is, the Hapland games are very much Flash games. The graphics are drawn in Flash, the code was written in Flash, all the animations are done in the Flash timeline. These games have Flash in their bones.
How was I going to do this?
Failed attempt #1
The first thing I tried was having Flash export the games as executables. This would have made this a very short article but it fails because performance is about as bad as it was in 2005. I want to make a good thing that runs at contemporary frame rates. I wanted to be free of Flash Player.
Failed attempt #2
Secondly, I spent far too much time fiddling around with Adobe AIR, a desktop runtime for Flash, and Starling, a library that draws your Flash scene on the GPU.
I gave up on this in the end, partly becase AIR is buggy and terrible, but also because I don't really want to end up with a weird Adobe thing at the end of all this; I want to have my own thing that I can do what I want with. What if I want to port to Linux? I don't want to have to care about Adobe's opinion about whether I should be able to do that or not.
The way forward was obvious; I'd have to make my own Flash player.
The plan
Here's how Hapland works. There's a tree of sprites. In Flash, animated sprites can have code attached to certain frames, which runs when the playhead gets there. Hapland uses this a lot. The walk paths of the game characters are all just big long timeline animations, and characters often have frame actions saying, when you get to the door, open it if it's closed, or when you get to the landmine, trigger it if it hasn't exploded yet.
Fortunately, .fla files are just XML. I just had to parse this, export the relevant data to a simple custom format1 and write a player to read it, draw the scene, handle input, and run the animations. I'd also have to do something about the ActionScript.
Hapland would stay a Flash project, written and maintained in the Flash editor; only Flash Player would be replaced.
Rasterizing vectors
Flash is all about vector graphics. It does support bitmaps, but it's really designed for vectors. That's how Flash movies managed to load so fast even on dialup connections, back in the day. All the Hapland graphics are vectors.
GPUs don't really like drawing vector graphics. They like big batches of textured triangles. So, I needed to rasterize these vectors.
I decided to rasterize them offline and pack the raster files into the game. It would have been fun to have the game rasterize them at runtime, and have it be this tiny executable, but I didn't want to have those extra moving parts. I like having as much of my code as possible run on my own dev machine, where I can keep an eye on it.
Flash stores its vector graphics in XML format. You might argue that XML is a poor choice for graphics data, but you weren't a product manager at Macromedia. Behold:
Hey, I'm not complaining, it makes my job easier.
Even though I didn't have access to a spec, rasterizing this wasn't such a hard problem. The bezier-spline model of vector graphics is all-pervasive, ever since PostScript. All these APIs work the same way. After a bit of trial and error to figure out what ! and [ and so on meant2, I wrote a program to parse these shape definitions and render them out to PNGs using the Mac's CoreGraphics library.
CoreGraphics was a dubious choice. I picked it because I was working on a Mac, and it was there, and dependencies are hard. But that did make it so I always had to rasterize the graphics on a Mac, even for Windows builds. If I do this kind of thing again I might pick a cross-platform library.
After rendering these PNGs, the exporter then assembles them into atlases, quite naively. It just sorts everything by height and lays it all out row by row like text in a document. This is far from optimal but it's good enough.
To keep things simple, the atlases are 2048×2048 pixels, the minimum required texture size that OpenGL 3.2 implementations have to support.
Rasterizing the shapes is pretty slow, so to keep build times reasonable I needed to skip rendering things that hadn't changed. The zipped XML format that Flash uses does have last-modified fields for each file, but Flash doesn't seem to use them properly and so you can't rely on them.3
Instead, I just hash the XML of each shape and only rebuild if it's changed. Even that fails, because Flash sometimes likes to rearrange the XML tags in objects that haven't changed, but again, it's good enough.
Using an assembler to write binary files
The exporter writes the animation data to a custom binary format4. It just goes frame by frame through the timeline and writes out all the changes for each frame.
One thing I came up with here, which I rather like, is the idea of writing to an assembly listing rather than straight to a binary file. There's no CPU instructions, just data. This makes debugging easier, because I can look through the assembly file to see what was generated, rather than picking through bytes in a hex editor.
09 DD BE DE : C9 5A 1D 36
3F C0 4E 31 : 52 FD 41 C6
8B 5D C0 20 : 19 1F 5F 1F
54 97 8C 27 : 34 1F 30 EA
A9 A9 E0 55 : 40 29 A3 19
89 BC 5F 24 : 3A 98 FD B9
DE 15 F2 D4 : 2A B7 41 2C
4E 9D 37 D9 : E2 13 4B 01
36 3F 40 08 : AC 3C FF 84
E9 AE C5 2C : 11 2F 69 CF
63 CE 85 D1 : A7 CB B1 1A
5F 5B 60 1A : 77 99 71 B0
60 6E C4 C7 : 73 1F EA 1F
31 0D 0C 39 : B0 86 70 42
; Left Side
timeline_132:
; --- Left Side, Frame 0 ---
.frame_0:
; --- Left Side, Frame 0, Layer 22 ---
db Quad
dd 0.152926, 0.162029, 0.184475, 1.000000 ; color
dd 799.599976, -20.950001
dd 799.599976, 556.650024
dd 46.000000, 556.650024
dd 46.000000, -20.950001
; --- Left Side, Frame 0, Layer 21 ---
; instance of shape [Left Side] [Wall Shadows] [Frame 0]
dd Shape
dw 1560 I could have just had the exporter write out the bytes to one file and a separate text listing to another file at the same time, without using the assembler, but I didn't do that because 1) assemblers already exist, 2) I don't have to debug them and 3) they support labels.5
The rest of the exporter is mostly not interesting; it just walks the tree and converts things like transformation matrices, colour effects, and so on as it finds them. Onward, then, to the game program itself. I chose to write this in C++ because I already know it and new things scare me.
Scene graph
Hapland is a great fit for a scene graph6. This is the model that Flash used and Hapland was designed around it, so there was no sense in trying to use a different model.
I store the scene in memory as a boring tree of Nodes, each of which has a transform and can draw itself and accept mouse clicks. Each game object with behaviour of its own is an instance of its own class, deriving from Node. Object-orientation is not fashionable right now in gamedev circles, but I'm using Flash so I clearly don't care about that.
Flash features that Hapland used, like colour transforms and masking, are present, although instead of implementing arbitrary masking like Flash did, I just implemented rect clipping and edited all my graphics so all the masks were rectangles.
Frame scripts
Almost all of the Hapland logic is in bits of ActionScript attached to timeline frames. How was I going to export all this? I didn't want to include an ActionScript interpreter in my game.
In the end, I settled for a bit of a hack. My exporter reads the ActionScript from each frame and applies a bunch of regexes to attempt to turn it into C++. For instance, crate.lid.play() might become crate()->lid()->play();. The two languages are similar enough syntactically that this works out fine for a lot of the simpler frame actions, but it still left a fair bit of broken code, and there was nothing for it but to go in and manually rewrite all the remaining frame actions.
With all the frame scripts in C++, they are extracted at build time and become methods on each symbol's Node subclass. A dispatch method is also generated to call them at the right time, which looks something like this:
void tick() override {
switch (currentFrame) {
case 1: _frame_1(); break;
case 45: _frame_45(); break;
case 200: _frame_200(); break;
}
}
One last thing I'll call out here is that the scripting system ended up being sort of statically typed, which was kind of neat, since ActionScript wasn't7. The game objects spit out by the exporter look like this:
struct BigCrate: Node {
BigCrateLid *lid() { return (BigCrateLid *)getChild("lid"); }
BigCrateLabel *label() { return (BigCrateLabel *)getChild("label"); }
void swingOpen() { ... }
void snapShut() { ... }
void burnAway() { ... }
};
So, even though everything was still a sea of string name lookups under the hood, the type-safe veneer would stop you from calling the wrong functions on the wrong objects, saving you from that annoying class of bug you get in dynamic languages where you typo something and only find out about it at runtime.
Aspect ratios
Ah, aspect ratios. Everybody who converts old media to new formats loves these. The original games were browser games that weren't even designed to run in full screen, so they just used whatever aspect ratio I felt like. Each game was different, but they were all around 3:2.
The most common aspect ratio today seems to be 16:9, with 16:10 also popular on laptops. I wanted the game to look good at either of these without any black bars or stretching. The only ways to do this are either to cut bits off the originals, or to add bits on.
So, I drew two rectangles in each game, one proportioned at 16:9 and the other at 16:10. The game then interpolates between them based on the screen's aspect ratio, and uses the interpolated rectangle as the camera view bounds. As long as all important game elements are inside the intersection of these rectangles, and their common bounding rectangle doesn't go off the edge of the scene, this works great.
The only difficult part here was adapting the scenes themselves to accommodate the extra width; lots of things needed redrawing and rearranging to fit the new aspect ratios, which was a bit of a pain, but I got it all done in the end.
Colour space nightmare
After a bit of testing, I discovered that Flash does its alpha blending and colour transforms in perceptual space, not linear space. This is mathematically dubious, but on the other hand I get it; a lot of drawing programs work like this, and you want your consumer tool to work the way people expect, even if it annoys those head-in-the-clouds mathematicians who don't know anything about business. But on the first hand again, it's wrong! It causes problems with things like antialiasing.
When you rasterize vector graphics, and you ask for antialiased output, your rasterizer will output alpha values that are so-called “coverage values”. This means that if a given pixel is half-covered by the vector shape, that pixel will be output with alpha=0.5.
But in Flash, when something has alpha of 0.5, that means it is perceptually halfway between the foreground and background colours.
This is not the same thing!8
A half-coverage white pixel drawn on top of an opaque black pixel should not be a perceptual 50% grey. That isn't how light works, and it isn't how vector rasterization can ever work. (A rasterizer can't say “this pixel should be perceptually X% between background and foreground colour” without knowing the background colour.)
So, we have our antialiased rasterized shapes using one definition of alpha, and our Flash-exported alpha transparency, gradients and colour transforms using another. But we only have one alpha channel in our rendering pipeline. So how should the renderer interpret alpha values? If it interprets them as perceptual blending factors, the semi-transparent objects will look right but the antialiased edges of everything will look wrong. If it interprets them as coverage values, the inverse will be true. Something will always look wrong!
There are I think only two rigorous solutions here: 1) have two alpha channels, one for coverage and one for perceptual blending, or 2) rasterize all shapes without AA, draw everything to a very large framebuffer, and then scale it down with filtering.9
I must admit, I didn't do either of these. I just accepted that semi-transparent things look different in Flash and in the game, and tweaked the graphics incrementally until the game looked good. Transparent objects were never going to look exactly how I designed them in Flash, but there aren't very many of them and it just isn't a big problem.
To make sure I'd got everything else right, I made a “colour test” graphic with a bunch of colours of different intensities, hue rotation effects10, and so on, had the game show it, and made sure it looked the same in the game as in Flash.
Frame rate
The original Flash games run at a nominal 24FPS, but really, they run at whatever frame rate Flash Player feels like running them at. With Flash, you might ask for 24FPS and get 15FPS, so then you'd ask for 30FPS and suddenly you'd get 24FPS. It was kind of silly.
I wanted 60FPS for the remake, which meant doing something about the fact that the Hapland animations were authored expecting to be played back at about 24FPS. (Flash's animation tools are based around discrete frames, not continuous time.)
I started by having my exporter double all the frames. So, for each timeline frame, it exports two frames11. This gets us easily from 24FPS to 48FPS, but that still isn't quite 60, so animations were still going to run 25% faster. The solution was good old-fashioned elbow grease. I just played through the games and manually added in extra frames to animations that now seemed too quick.
I now had a pretty good C++ conversion of the Hapland games that would surely run on contemporary computers for at least another decade or two. But I just couldn't shake the feeling that I should try to deliver a bit of extra value, so I added a couple of things. Aside from redrawing a lot of the old graphics and animations, I made a couple of major changes.
Save states
This was an idea I came up with to make Hapland 3 a bit less overwhelming. The correct path in that game is quite long, and there are many ways to screw it up and have to start all over again. Maybe this was fun in 2006 but we're grownups now, we haven't got time for that.
Save states are something that emulators have. You press “save state”, and it remembers the entire state of the game by dumping the console's memory to a file. Then, if you mess up, you press “load state” and you're back exactly where you were to try again.12
It wouldn't have been feasible to implement save states in the original Flash games, because Flash doesn't give the programmer access to its whole state. But since I'm using all my own code this time, it is possible.
I have this thing called a Zone, which is just an allocator that allocates all its memory inside a fixed-size chunk. All scene nodes are allocated inside the current Zone.
To implement save and restore, I simply have two Zones, the active zone and a separate “save state zone”. To save a state, I memcpy the active zone to the save state zone. To load a state, I memcpy back the other way.
Second Quests
The Hapland games aren't particularly long, and although there are three of them, I still wanted to give people a few more hours of play time. I decided to give each game a “Second Quest”—a modified version of the game where the layout and puzzles are slightly different. Making such a Second Quest is less work than making a whole new game, but still delivers some extra value.
Creating the second quests meant digging back into Flash puzzle game development for the first time in about fifteen years, and, honestly, I quite liked it.
The vintage Flash UI is great. Buttons have edges. Icons look like things. Space is well-used. It's amazing! Using old UIs makes me feel like an archaeologist discovering some sort of forgotten Roman technology. The lost art of UI design. It's neat.
And although Flash is buggy, slow, and missing extremely basic features, I mostly didn't hate using it. I certainly don't know of a contemporary program that I'd have preferred to use.
To stop the Second Quests looking too similar to the First Quests, they get new backgrounds, and the entire scene is also flipped horizontally.
Music
I knocked together a quick ambient soundtrack for each game, using stock sounds and a couple of recordings I made. Once when I was on holiday in Japan I took a field recording at the top of a hill for no reason in particular and it was nice to be able to use it for something. I hired a musician from the Internet to do the title screen music, and recorded some guitar chords myself for the end credits, drowned in effects so you can't tell I'm bad at guitar.
I use Logic or Live for music, depending. I find Logic better for recording, and Live better for sound design.
Achievements
I get the feeling players expect achievements in Steam games. This is annoying because it should be up to the game designer whether achievements are an appropriate grumble grumble, but it's not a big deal.
Uploading achievements to Steam is a pain. You can't just define a list and give it to their command-line tools; you have to laboriously click through the slow, confusing miasma of PHP sadness that is the Steam partner site and add them one by one.
I think if you're a big important game studio you don't have to stand for that and they give you a bulk upload tool, but I'm not one of those so I looked at the HTTP calls it was making, saved my login cookie to a file and wrote my own.
After changing my mind several times, I opted for a modest set of achievements: one for finishing each Hapland game, one for each Second Quest, and a couple for the bigger secrets. Any silly, obscure secrets that nobody will ever find do not have achievements; you just get the satisfaction of seeing what happens.
Notarization
Although I developed the game mostly on my Mac, during development Apple invented this thing called “Notarization” where if you run any app on a new version of MacOS, it'll make a network request to Apple to ask if the app's developer pays Apple a yearly fee. If the developer does not pay Apple a yearly fee, MacOS will pop up a dialog strongly implying the app is a virus and refuse to start it.
For this reason, Windows will be the first and maybe only release platform for this game.
Libraries used
For software that I'm shipping to end-users, I like to keep dependencies to a minimum, but I'm happy to use a few high-quality ones. Other than OpenGL and standard operating system stuff, this is the full list of libraries that the Hapland Trilogy executable ended up linking to:
- Steam SDK
- cute_sound
- stb_vorbis
- stb_image
The end
And that's it! Thank you for coming on this blog post adventure with me. It's been fun. If you do the tech stuff right, players don't notice it at all, so sometimes you just want to say, hey, look, look what I made.
If you'd like to read other things I've written, then you're out of luck because I don't tend to post much writing online. If you'd like to support me, you could buy Hapland Trilogy or my other Steam game from 2020, Blackshift. If you want to play some of my games without paying, I have a bunch of free browser games on my website at foon.uk. The newest ones are Javascript or WASM, and the oldest ones, including the original Haplands, are AS2 Flash, which runs pretty well thanks to Ruffle. The later Flash games are AS3 so they don't run anymore.
If you have any comments or just want to say hi you can email me at r@foon.uk, or if you're into Twitter, I'm @FoonGames. I've got an RSS feed too. And there's been some good discussion at Hacker News.
Take care.
Robin Allen
2022
1. It was tempting to just use SWF, the format that Flash already knows how to export to, but this didn't work out because SWF is a vector format and I didn't want to do rasterization at runtime, and also because it limits your options for what to do with the scripts, and for other reasons that I can't remember.
2. !: Move to point. | or /: Straight line to point. [ Bezier segment to point. S: No idea.
3. That figures, too — Flash takes an age to save large documents, even if you only changed a single thing, so it probably doesn't track last-modified times at all.
4. I like to use binary formats where possible for end-user software; I don't believe in making customers' computers chew through reams of XML.
5. It's often the case when writing binary files that you need to write the location of one bit of data into another bit of data, and these two locations could be in either order in the file. It's just so easy to be able to write out dd mylabel at one end and mylabel: at the other and let the assembler deal with it.
7. ActionScript 3 started moving in that direction, but the Haplands were ActionScript 2 games.
8. Most other image editors also work the same way. Some now have a “do things correctly” button but it's rarely the default. If you want a fun rabbit-hole to go down, look up how most fonts are thinner than they should be because they're designed to be displayed by programs that do alpha blending wrong.
9. This raises the question of what Flash does. The Flash renderer is working with the vector data directly, without a separate rasterization step, so it might be able to do antialiasing directly in perceptual space as it renders, since it can check the background colour. Or maybe it just uses full-screen supersampling.
10. Flash's colour transform effects (hue rotations, brightness adjustments, etc.) are expressed as 5x4 matrices in sRGB space, and it's easy enough to sort out the sRGB/Linear problem for these. For simple matrices, you can just convert them, and for the others, simply export the sRGB matrix and have the game compute srgb_to_linear(ctr * linear_to_srgb(c)) in a fragment shader. It's a few extra GPU cycles but it still all runs fine.
11. The frame doubler is smart enough to interpolate object positions for frames that are part of motion tweens, so those stay smooth.
12. Some people had asked for an “undo button” but, say you fire a projectile, then quickly knock it with something when it's flying, then hit undo, what should happen? It's a case-by-case design decision. And there are a lot of cases. With save states, I don't have to make this judgement call.