NNNNNN in 12 hours

I recently announced my NESdev competition entry for this year: NNNNNN, a multiplayer NES port of the Gravitron from VVVVVV.  Now that it's done, I thought I'd share about the development process.

What to make?

The first question I had was what to make for the competition? Because I'm focusing most of my effort on Halcyon these days, I wanted to think of a game that I could develop really quickly, but still be fun. Treating it like a short game jam, I wanted something that I could take from start to finish in a week's worth of evenings, but still be a reasonably fun game. Honestly, this was the hardest part of the process, which I've been mulling in my brain for months. I have a few ideas (some of which I still might save for next year), but all of them are things that either don't sound fun right now, or would take just a little more work than I'm prepared to invest.

But about 2 weeks ago, it suddenly dawned on me that a NES port of the Gravitron would be tons of fun to play (at least in my opinion), really easy to write, and light on assets (ie I wouldn't need to spend ages fussing with finding new graphics). The only real problem was IP -- what happens if Terry Cavanagh finds out and shuts down my effort?  I debated whether to get permission ahead of time, or to wait and ask forgiveness. But decided that regardless, I'd start on the project and see what I could come up with.

Research

Step 1 is probably the easiest part. Play the game a bunch, and take some notes, to see if it would be as simple as I remembered. There's some Youtube videos out there of people playing the gravitron, which is helpful, and there's a free dedicated Gravitron-only app for mobile. So after spending 20 minutes looking at how the game worked, I was more convinced than ever that I could pull it off.
The most important part of this research bit was thinking through how to make the game match the NES restrictions. The important bits (the top and bottom borders and the timers at the top) could easily be made with background tiles, and the character and obstacles are obviously sprites. There's not too many colors, and not too many sprites on any given horizontal line, which are normally two of the major things that are hard to convert to the NES.

A screenshot of the Super Gravitron from my phone

The aspect ratio was going to be a problem. The original gravitron is really short and wide, which is problematic for the nearly-square nes screen. I'd just have to make do with making a smaller play area (which makes the game a little harder), and going for it.  I was also a little concerned about the animated backdrop. Animated backdrops can be difficult on the NES, and it wasn't completely obvious how I'd be able to pull that off. But I figured that this wasn't a show-stopper, so I'd move forward and figure it out when the time came.

Getting Started: the easy stuff

Now the race has begun, and I wanted to see how quickly I could get this thing off the ground. Because the goal was speed more than cleanliness, I started by copying my entire git repository from Super Homebrew War, and then going through and doing mass amounts of deleting unnecessary code. Within 30 minutes or so, I had a good skeleton of a project, which would start-and-do-nothing without crashing.

I loaded a screenshot of the original game into GIMP and extracted the player and obstacle graphics, and fairly quickly coded up the majority of the main character's behavior in C.  Because the player does nothing but move left and right, and uncontrollably bounce, this was another simple process. I pulled in some existing bitmap fonts (stolen from another old NES game, which, as it turns out, is legal in the US, because bitmapped fonts aren't eligible for copyright!) Using NES Screen tool, I sketched out the general layout of the screen, and had the very basics of the game going without a hitch.

The easy parts are done!  Now I have to start using my brain....

The game also needed music, so I copied over the ggsound library that I've used in previous projects. I had a techno-sounding song lying around that I had previously commissioned from a composer known as Chip Jockey (I had bought the song without having any idea what I'd use it for), so I plugged it into the game, and it sounded great.

Next: Obstacles

I've been doing enough NES game development recently that this type of thing is fresh in my brain and easy enough to churn out. The concept of a handful of obstacles, which merely march across the screen with a simple animation, was really simple. The harder part is figuring out the spawn patterns of the enemies. Back to research mode!

I watched a few videos of the game, and made some notes. The enemies clearly come out in some pre-defined patterns, which seems to randomly selected. That's enough information for now.


But now I actually have to start using my brain. How do I want to store and process the spawn patterns?  I decided on each pattern being a list of pairs of bytes, with each byte being a list that tells enemies spawning that frame, and a timer until the next frame:

pattern1:
.byte %10010000, 10    ;First bit is left or right side
.byte %10001000, 10    ;bits 2-6 are the Y position of which
.byte %10000100, 10    ;enemy to spawn. So this will spawn
.byte %10000010, 40    ;4 enemies in a diagonal line, 10 frames
.byte $ff              ;apart. The $ff marks end of the pattern

This is the first part of the process that took any real debugging and work, making sure my bit shifts and comparisons were correct for each byte in the pattern array.  But with that in place, I had enemies spawning. Using the famous fast rectangle collision routine from AtariAge user Supercat, collisions against the player were simple and fast. Although I only had a couple of test patterns, and the timing and speed of everything was way off, and hitboxes needed to be adjusted, I had the bones of the game in place, after 4 or 5 hours.

Fans of the real game will notice that I have the sprite falling backward (head-first). I didn't notice until significantly later in the process.

Backgrounds

Now things start to get interesting. It's time to see what I can do about the background. First is the timers at the top of the screen. It's easy to put the "current time" and "best time" text as part of the background graphics, as well as the times. But it was also time to think about the animated backdrop. I did a lot of thinking about this during the rest of development.  The big issue is that the NES can only change a handful of background tiles per frame, because you (generally) can only write to the background safely during vblank.  There's not enough to time to rewrite each background tile. And really, using basic 8x8 pixel background tiles is messy for doing a big animated backdrop like the one in the gravitron.

Eventually I decided that I needed to take advantage of the CHR-RAM and redraw the actual tiles every frame.

For those non-NESdev folks reading this, the NES handles graphics by taking pre-made 8x8 tiles, and arranging them on the screen. A lot of games use CHR-ROM, which means the actual tile graphics are on a ROM chip in the cartridge, and can't be changed. Others use a RAM chip for the graphics, and copy the graphics from the game's main program ROM to the video ram at run time. There are advantages and disadvantages of both methods, but by using CHR-RAM, I can, on every single frame, redraw the handful of 8x8 tiles that make up the backdrop.

I sketched it out and determined that I'd need to redraw 16 different backdrop tiles in order to animate this properly. That's 256 bytes of data that would need to be written during vblank, (about 1800 free cycles after OAM DMA finishes)  That's doable, but would definitely require me to optimize things. First, I decided that the millisecond part of the timers (At the top) could be sprites, so I wouldn't have to update them as background elements, saving a little time. (I could cheat for the seconds and minutes, and just skip updating the backdrop when I update them, which wouldn't be noticeable at one missing frame every second)

Then, I needed to optimize and unroll all the background tile updated during vblank. A naive way of re-drawing a tile during vblank might use a loop like this:


;first tell the NES what video ram address you 
;want to write to.
  lda #TILE_VIDEO_RAM_ADDRESS_HI_BYTE         ;2
  sta PPUADDR                                 ;4
  lda # TILE_VIDEO_RAM_ADDRESS_LO_BYTE        ;2
  sta PPUADDR                                 ;4

;then do a loop to write from a ram buffer to the tile
  ldx #16                                     ;2
top:
  lda buffer,x                                ;4
  sta PPUDATA                                 ;4
  dex                                         ;2
  bpl top                                     ;3 

That's 13 cycles per byte, plus 14 cycles of setup (minus 1 cycle for the last bpl). If I did my math right, that's 221 cycles per tile, or over 3500 cycles. About double what I have available.  But hardcoding addresses and unrolling things saves a ton of time:

  lda #TILE_VIDEO_RAM_ADDRESS_HI_BYTE         ;2
  sta PPUADDR                                 ;4
  lda # TILE_VIDEO_RAM_ADDRESS_LO_BYTE        ;2
  sta PPUADDR                                 ;4

  lda buffer+0                                ;4
  sta PPUDATA                                 ;4
  lda buffer+1                                ;4
  sta PPUDATA                                 ;4
  lda buffer+2                                ;4
  sta PPUDATA
  ;etc, 13 more times



Using this method, it's 140 cycles per tile. That still comes to 2240, which is too much, but we're getting there. Luckily, due to the pattern of how the backdrop updates, a few of our tiles are the same thing repeated vertically, so we can optmimize them further:

  lda #TILE_VIDEO_RAM_ADDRESS_HI_BYTE         ;2
  sta PPUADDR                                 ;4
  lda # TILE_VIDEO_RAM_ADDRESS_LO_BYTE        ;2
  sta PPUADDR                                 ;4

  lda buffer                                  ;4
  sta PPUDATA                                 ;4
  sta PPUDATA                                 ;4
  sta PPUDATA                                 ;4
  sta PPUDATA                                 ;4
  sta PPUDATA                                 ;4
  ;etc, 11 more times    
   
That's only 56 cycles!  It's enough to balance things out, and let us fit into the limited time during vblank.

To verify, I used Mesen's event viewer to see if all of my writes to video memory occurred during vblank, and it looks good!

All those dots at the bottom are writes. And they're all in that big blank space at the bottom, where they belong.

Now let's see what the tiles look like when animated:

Trippy!

So the finished effect, which probably took more time than any other single element of the game, at about 3 hours, looks like this:

 

Making it match the real thing

At this point, I felt like I had all the features in place, so it was time to play it back to back with the real thing and see what needed to be adjusted. I knew my speeds/timings were all off, and I had none of the real patterns from the game.

So I opened up a youtube video of someone playing the game, resize it to match my emulator size, and started adjusting things to match the speed. After a few minutes, I had the movement speeds all close enough.

There were a few other minor things that I had forgotten (the enemies change color, and the top and bottom trampoline borders changed color when you hit them). These were fairly simple changes based on how the NES uses palettes.

The one important thing that I had forgotten was warnings about upcoming enemies. These are small arrows that appear on the sides, and warn when an enemy is about to spawn there. They're crucial to surviving, particularly if you take advantage of wrapping around the screen to dodge obstacles.

Unfortunately, adding these warnings wasn't quite as straightforward as everything else in the process.  Because they appear about half a second before the actual obstacle, they could be part of the same pattern as currently-spawning obstacle, or the next pattern, or even (for very short patterns), 2 patterns ahead of the current obstacle.

Previously, I had been only tracking the "current" pattern, and when that pattern finished, I'd randomly pick a new one. But now I had to keep a short queue of patterns.  The pattern a half second in the future, the currently spawning pattern, and any patterns in between.  So I basically have to have a few things:

- A queue of pattern ids
- A pointer to where in the queue we're at for the "warnings".
- A pointer to where in the queue we're at for the "current"
- A pointer to where within the "warning" pattern we're curretly at
- A pointer to where within the "current" pattern we're curretly at

It wasn't overly complicated, but was just enough logic and fiddly indirection that it actually took some real debugging, as opposed to most of the rest of the project.

After I finally had that working, I sat down with a piece of paper and the youtube video (set to 1/4 speed), and wrote down all the enemy patterns that spawned. To this day, I'm still not sure whether every single pattern was pre-generated, or if some of them were completely randomized. But to simplify the game, I limited it to a handful of the patterns that I saw during the first few minutes of the video.  Transcribing them to the source code took another hour, but after that, the game was in pretty good playable shape!  At this point (around 9-10 hours), I was confident that I had a viable entry for the competition.

This was also the point where I decided that I should probably check about getting actual permission for this project.  With much fear and trembling, I send Terry Cavanagh a message (on twitter) with a screenshot, telling him that I had made the game, and asking if I could release the rom. His response: "Sure!"  WHEW.  That worry was resolved.

Title Screen

Next up was a title screen. I lucked out by the fact that I had (by complete accident) included my font in just the right place in video memory so that the tile id of each glyph was the same as its ASCII code. That meant that I could actually use C strings for text! I whipped together some routines in C to write text to the screen (which were horribly slow, but because they run during couple frames of black screen before the title appears, nobody would notice). With those, I threw together a primitive title screen, but it was ugly and needed something.

The title screen for the mobile Super Gravitron had these cool-looking little rectangles flying around in the background, so I stole that idea. Using sprites, I generated a bunch of them to randomly fly around. And because they have no logic other than flying across the screen before reappearing randomly somewhere else, they were painless to create.

Multiplayer

Now really what I had been hoping to add all along (but not sure if I'd have time) was multiplayer. I'm a huge fan of 4-player simultaneous games (which are sorely lacking on the NES). And the chaos of this game would be perfect for multiplayer madness.

For the most part, adding extra player characters was straightforward, but two things are worth mentioning.

First, I did something goofy for the main character logic -- instead of handling each character's input and updates in a loop, I copied the player update logic 4 times.  Why?  Becuase I wrote it in C, but the 6502 C compiler is notoriously bad about handling loops where you loop through elements repeatedly in arrays. Instead of storing the loop counter in a register (x or y), it stores it in a variable, then reloads it to x every time you try to look up a value in an array.

So to keep the performance from being stupid, I really needed to either rewrite the routine in assembly, or copy/paste the routine 4 times and let it hard code the addresses.  I chose copy/paste because I was at around 11 hours and wanted to be finished.

The other painful thing was handling player deaths. When a player dies, everything pauses, the player changes color for half a second, then the remaining enemies do a cool extra-fast flyaway, then it starts over. Somehow, even though it seems really simple, I had a difficult time getting the logic right to handle deaths for all 4 players.  I just kept introducing bugs when trying to manage the "make the player stop moving and change color while dying" state for some players but not all players were dead. I don't know why I had so much trouble with it (the logic isn't complicated!) but I wasted a good hour on it.

Finished?

Now everything was done.  Except one small thing. There's a sound effect that occurs when you die, and I wanted it in the game. And I wanted it to sound somewhat like the real thing. And I'm terrible at making sound effects.

There's a great program out there, FamiTracker, for working with NES audio. But I'm not very good at using it. And certainly not good at trying to reproduce an existing sound. But there was no other way to do it, so I used my last hour fiddling with instrument settings in FamiTracker until I got this sound reasonably close to the real thing.

Finished!

So, after about 12 hours of work (spread out throughout the week), I was done!  I loaded it onto a cart (which is always scary, as it usually never works right on hardware), and (thanks to the accuracy of Mesen), it worked on the first try! I gathered my family around and forced them to test it out with me. Our family average was somewhere around 3 seconds per life.  Success!

All in all, I'm pretty happy with how it turned out. There's definitely some things that could be slightly closer to the real thing (better analysis of how the patterns were generated, making sure speeds matched the real thing, making fonts match, etc), but I feel like it captures the fun energy of the original game and successfully adds a multiplayer element.  And I managed to pull off a reasonable competition entry in a week.

You can download the game here. If you try it, let me know your best time!
 

Seeker missiles revisited

If you follow me on twitter, you saw back in February that I was attempting to get enemy-seeking missiles working correctly. At the time, I felt like I got all the bugs worked out, and they were good to go. But now that I'm at the point in content-creation of the game that the player actually GETS the seeker missiles, I'm not quite satisfied with how they behave, so it's time to revisit them.

The thing about seeker missiles (or any sort of "move an entity directly toward another entity at a set speed) behavior is that it's not as simple to get right on the 6502. (at least if you care at all about performance and would like to get more than 1 frame per second in your game).

The reason why is because of trigonometry.

There are two parts to making good enemy-seeking missiles. First is to select which enemy to target (usually the closest, although you might have a priority system instead to that they always target the most dangerous enemy or something. For this post, I'll assume we're targeting the closest enemy)

The way you'd do this on modern hardware is by first finding the closest enemy by using the Pythagorean theorem -- distance is the square root of x² * y². You can even omit the square root if you only care about finding the closest -- just find the sum of squares of the x and y distances for each enemy, and the closest is the smallest.

Unfortunately, arbitrary multiplication is slow on the 6502. Without a multiply instruction, you're stuck adding in a loop, (or bit shifts for multiplications times a power of 2). If the x distance is 74, that means adding 74 to itself 74 times in a loop.

That would look something like this (squaring a single 8-bit value into a 16-bit value):

  ldx val        ;3 cycles
  lda #0         ;2
  sta result     ;3
  sta result+1   ;3  (11 cycles for loop setup)
:
  lda result   ;3 
  clc          ;2
  adc val      ;3
  sta result   ;3
  lda result+1 ;3
  adc #0       ;2
  sta result+1 ;3
  dex          ;2
  bpl :-       ;3  (24 per each time through loop)

  ;11 + (24 * 74) = 1787 cycles 

I scribbled that down without checking it, so it may be off by 1 or something, but it's something like 6% of a frame just to do that single 74*74 calculation. Good luck trying to also do y², then computing this for each possible enemy. So we need a better way.

To be honest, I haven't found a perfect solution for this. Luckily, for this part of the problem, we don't really have to be exact. If the missile targets an enemy that's not exactly the closest, I don't really care.  So for this first step, I just compare x + y instead of x² * y². Sure, that overestimates how far away enemies are that are more diagonal from the missile, but ... I don't care.

The more interesting part is the second half of the problem. Doing the math to determine the X and Y components of movement to move the missile toward the target.

The easiest solution is just to move at full speed horizontally until your x component matches the target, and also move at full speed vertically until your y component matches the target.  The problems with this are obvious though: the missile moves too quickly in a straight diagonal, until it gets even with the target in one dimension, then moves straight until it hits it.  This is a fairly obviously ugly movement.  It's fine in some cases, particularly if the entity is moving fast enough that you don't really pay attention to the movement itself.  I used this method in Super Homebrew War when a player gets the "swap everyone's location" power.  I didn't have the programmer time or rom space for something more complicated, so I just went with this. The swapping all happens so quickly that you don't really notice that it's ugly.

Another solution would be to use to a constant TIME instead of constant VELOCITY.  If you assume that the missile will always take approximately a second to reach the target, you can divide the x distance into 64 pieces (dividing by 64 is fast with bit shifts), and divide the y distance into 64, and move each by that amount every frame.  That will produce a nice even movement, BUT the speed will change based on the total distance traveled. A missile will take the same amount of time to reach enemy A as enemy B, which may be undesired.

The REAL solution involves trigonometry, which is hard on the 6502. You find the angle (the arctan of y / x). Then to find each frame's x and y components of movement, you use cos(angle) * vel = x.  (or sin to find y).  It's simple high school trigonometry. Easy if you have a calculator or a modern processor. Not as easy on the 6502.

But for Halcyon, I want things to look nice and polished, so I wasn't happy with either of the two previous solutions. So trigonometry it is.

For the arctan, I found a pre-written routine that does a pretty good fast estimation of arctan that was written by one Johan Forslöf. I don't pretend to understand the math behind it (he claims it simply "uses logarithmic division to get the y/x ratio and integrates the power function into the atan table"), but it does what I need it to do.

For sin and cos, the trick (like many things on the 6502) is just to use pre-computed tables. If you assume that the angle is a 1-byte value, then there are only 255 possible sin values you have to compute. So you can compute them ahead of time (using a python script or something similar), and just put them into your rom as a lookup table. The cartridge rom that I'm using for Halcyon has plenty of rom space, so a 255-byte table is no big deal.  Then to compute the sin, you just look up the precomputed value for any angle. Table lookups are one of the things that the 6502 does best, so this is nice and fast:

ldx angle      ;3
lda sinTable,x ;4 (7 cycles total)

For cosine, you can take advantage of the fact that cosine is just sine rotated by one quadrant, so you add (or is it subtract? I never remember) 64 from your angle and use the same table.

So with these tricks, you can have a pretty nicely functioning enemy-seeking missile, without using too much CPU time.

Now if I could only figure out why it's not working, and my missile is just bouncing along in a goofy-looking sine wave pattern.

Scrolling glitch

For an 8-way scrolling engine with 4 nametables (ie 4 in-memory screens for the camera to pan across), it's easy to end up with a lot of small glitches in the background. Scrolling diagonally across the seam of screens, it's easy to get some of the PPU memory address math wrong, and end up writing to the wrong spot on the screen. But it might only happen when the screen is aligned exactly wrong, so it can take awhile to find and fix all the glitches.

The gray outline shows what's actually on screen. The rest is video memory that's not shown.

Over the past couple of years of working on this project, I've gradually worked through what I thought was every single scroll glitch, and fixed them. Mesen, the NES emulator that I use, has some wonderful features for debugging this sort of thing. You can play through the game, and when you notice a rare, hard-to-reproduce bug like this, you can save your game history, then go back and replay the whole history through the debugger, stepping through what you did, rewinding if you went too far, and watching updates as they happen. It's amazing.

Despite all this, there's one scrolling glitch that, until tonight, I've never been able to reliably reproduce enough to find and fix. It only seems to happen in one particular room, and then, only rarely, even if I do the exact same movement when I enter the room.

The room that gave me all the trouble. Depending on some random numbers, you can end up with 7 enemies going at once, which has the potential to slow things down.

Luckily, tonight I caught the glitch in the emulator!  I went to quickly hit the "save history" button, and I accidentally pressed "reload save state" and jumped back to some previous point in the game, and lost it.   ARRGH!

But, I had the good fortune of being able to reproduce it again fairly soon after, and this time I managed to save the history, and replayed it over and and over and over again.

It didn't make any sense -- as I was scrolling diagonally through the room, it would just skip updating the background for a single frame. So instead of writing new tiles at the edge of the screen, garbage tiles would just scroll in instead. I couldn't figure out why it was skipping an update.

After about the 30th time I replayed it, though, I noticed something. My frame counter was jumping from $1d to $1f when I advanced a single frame. That's not right! 

To make a long story short (too late), I tie some of my scroll logic to the frame counter (to alternate between a few types of updates). In the rare case that too much is happening in a single frame, you can end up with that dreaded NES slowdown, which means that you hit vblank before you finish your frame's logic (ie you get 2 screen draws per logical frame, cutting your game to 30fps instead of 60).  During the screen draw interrupt (NMI) is when I advance my frame timer. 

You can use a grayscale bit in the video settings as a poor-man's profiler. The gray shows how much of my CPU time I'm using this frame.

So this one single room has enough enemies to very occasionally cause a slowdown (usually only for 1 or 2 frames so I never even notice), BUT during those slowdowns, my frame timer advances twice per logical frame. So my scrolling updater (which depends on that timer) fails.

It was an easy fix once I realized what was happening -- I now just use a separate counter for the background updates, and only increment it after actually doing an background update. It wastes a byte of ram, but this is the NES, which has a whopping 2k of ram! What's a wasted byte?

So now, for maybe the 100th time, my git commit message said "Fixed what was hopefully the last scroll glitch."  Maybe I'm actually right this time?

Who needs enemies?

One of the things I keep thinking as I'm building content in Halcyon is "does this room really need any enemies?"  I mean, the fun of the game is supposed to be about exploration. Enemies just slow that down, right?  Or maybe it's just that I'm being lazy and don't want to figure out what enemies to put into a room. Do I need to mix it up for each room, or is it ok to have a few rooms in a row with really similar enemies?  Will the players find this room to be boring, too similar to the last room? 

I have no idea.  But regardless, it sure is tempting to leave a lot of rooms empty.

Enemy names

I realized that I'm not all that creative when it comes to enemy names. For my enemy code, each enemy has a textual name that it's referred to in labels, in the map editor, etc.

Here's a handful of the names so far:

• flapper
• hopper
• walker
• gunner
• diver
• zapper
• spitter

And then some that are even more boring:

• blob
• boss1
• boss2
• boss3
• barrier
• fish

Good thing these names are all secret....

What sort of game is this anyway?

I've said before that I'm making a Metroidvania. A kind of mash-up of Metroid and Blaster Master in this case.  But these days, that Metroidvania label (as well as "rogue-like") gets attached to almost everything under the sun. Dead Cells, a procedurally generated level-based action platformer routinely gets labeled as both a roguelike and a metroidvania (while I would say it is neither).  Even among things that actually could accurately be described as Metroidvanias, there's a huge range of variety in what that can mean, and what sort of thing a game really is. So this post is my attempt to answer the question: "What sort of metroidvania is Halcyon?"

To answer that, there's a number of different aspects that are worth discussing: non-linearity, challenge, and reward structures. Let's dive in.

Linearity

The first question is how linear is the game? At the far non-linear side of the spectrum are games with a big open world where you can really go anywhere in any order you want. The recent NES homebrew game Lizard by Brad Smith is a good example of this, as is Super Pitfall. There's a big giant world, and it's yours to explore. You can really do things in just about any order you want.

You can go any way you want in Super Pitfall, but mostly you just die. A lot.

Then there are games that have a little more linearity to them: the original Metroid is a good example. You can't really progress until you find the missiles and bombs. But when it comes down to it, you can go kill Ridley or Kraid in either order, without ever finding a number of the other powerups.  There may be a recommended order to do things, but you're not always doing everything in the same order.  (The original Legend of Zelda was very similar in it's non-linearity. There was an order to the dungeons, and some of them required items from other dungeons. But there's not much preventing you from doing some of them out of order(and we did so when we were first exploring the game as kids....if you got stuck on level 6, you went on to try level 7 instead).

Next up are games that are slightly more linear, like Super Metroid. Advanced players know how to exploit the game and can do things out of order, but the average player will end up doing things in mostly the same order every time. Sure, there's plenty to explore, and plenty of secret passages that you may or may not find. But the general order ("find this powerup to open the way to the next section. Find another and then you can go back through that other section") is generally the same for each player. (assuming they aren't purposely going back and trying to break the game sequence).

Despite the awesome Metroidvania-style map, Circle of the Moon was a huge disappointment to me. Each colored section was a distinct "level" that you had to play through in order.

At the far linear end of the Metroidvania genre are games like Castlevania: Circle of the Moon. Although it's one big world, it's divided into clear level-like areas. You beat the boss of the first to get an item that lets you explore the next. Beat that next level, and you get rewarded with the power that lets you explore the 3rd section. And so forth. These are the least interesting to me: although they pretend to be big contiguous-world metroidvanias, they're really not much different than a linear level-based game.

Where does Halcyon fit into this spectrum? I'm attempting to place it somewhere between Metroid and Super Metroid. I'd like the player to have a little bit more freedom in the order of things than Super Metroid, but I found Metroid to be a little too painful in terms of a beginning player not having any idea of where to go. A few parts of Halcyon will require you to go get powerup X right now to continue, but there will be other parts of the game where you can decide which way you want to go, with a number of different areas to explore and routes to take.

As a side tangent -- the world in Halcyon is a euclidean contiguous world. There are no warps between worlds or front/back (like Goonies 2) or weird non-euclidean layouts like Blaster Master. It (like Metroid) is just one large mappable world.

Difficulty

I've made some hard games in the past. My friends who have played my original Robo-Ninja for Android may have had some unkind words about me at times. Robo-Ninja (also a metroidvania) was designed to be HARD. The world wasn't big or complicated, but each room was a challenge.

Robo-Ninja -- possibly the world's first tap-to-jump metroidvania?

When I'm talking about a difficulty spectrum here, I'm talking not about how big or confusing the world is, but how difficult the enemies, obstacles, and other "platformer skill" elements are. The original Metroid was a pretty tough game, particularly at the beginning when you didn't have many energy tanks). Lizard is HARD -- you die A LOT. Blaster Master had a weird difficulty curve -- some levels were really easy, but some levels (and bosses) made you want to punch the screen.

The game was fun and easy-going until you had to fight THIS GUY.

Super Metroid, on the other hand, wasn't a very hard game. There were a couple parts that were tricky, but you really didn't die all that much. The fun of the game was exploring and figuring out where to go, and looking for secrets. The enemies were mostly just there to keep you on your toes.

Symphony of the Night was also like that. Other than that one boss (I don't remember his name, but I'm sure if you played it, you know who I mean), it was a fairly easy game, mechanically. The joy of the game wasn't in the finesse of fighting and jumping.

Unlike Robo-Ninja, this time I'm going easy. Halcyon is (hopefully) going to be more like Super Metroid or Symphony of the Night in this regard. If I can get the difficulty set the way I want, you might die a couple times, just enough to keep you interested and careful. But the combat isn't supposed to be hard. Anybody with moderate video game skill should be able to take their time and explore and enjoy the game.

Reward

One of the things that I want from Halcyon is for exploration to feel rewarding. Super Pitfall had a giant world with lots of areas to explore, but it was just a vast mostly-empty world. There was nothing that made you feel rewarded when you went this way vs that way. You'd explore a route and die, without having found anything interesting. You'd try a different route and die. You never seemed to make any sort of progress.

Lizard also had a fairly brutal reward system (in my opinion). There were coins scattered around the world, but you had no idea what they were for, and you'd lose them if you died. If you explored a lot, you could find a new power (a new lizard costume), but you didn't get to keep it. Even defeating a boss just mostly felt confusing to me.  These were all purposeful design decisions that Brad made (as opposed to just poorly-designed flaws), but playing it helped me figure out what sort of feeling of reward I wanted to put into Halcyon.

This screenshot from Lizard sums up how I felt most of the time.

First, I wanted a map screen that would be permanently revealed as you explored. (Like Super Metroid, Symphony of the Night, or many other newer games). With a revealed map, you always feel like you're making progress. Even if you get fairly lost, and don't discover where to go, your adventurous route is marked on your map. There's some internal feeling of reward in uncovering the map. You did something permanent. You got here once and you know how to get here again.

Second, I wanted a lot of powerups scattered throughout the world. Heart containers in Zelda and missile packs in Metroid were great -- they could distribute them freely all over the place, giving you lots of minor rewards throughout the game. I love Super Metroid's method of putting a minor reward behind some secret passage. The real thrill was finding the secret passage, but they gave you a permanent upgrade as a reward once you found it. To make this happen, I have a number of types of powerups in Halcyon, so that I can hand them out like candy. There are a few major ability powerups (which are the keys to unlocking content and progressing), but there are also new alternate weapons, max health increases, weapon power increases, energy increases, etc.  If it was ONLY health increases, I think they would quickly become boring and lose their sense of reward. So my goal is to have all sorts of types of things to find to keep it feeling rewarding.

A tiny sliver of Halcyon's minimap

Hopefully my describing where Halcyon fits in along each axis will help provide a better picture of "just what is this game all about, anyway?" But just a few more bullet points might be helpful:

- There's a little bit of story/plot, but not much. If all goes to plan, and
  we can get the details ironed out, there will be an opening story sequence, a tiny bit of plot along the way, and and ending story. But this won't be a story-driven game. You won't be talking to lots of people, getting clues in towns, or interacting with a lot of characters and dialog.

- Like Blaster Master, there will be a dynamic of getting in and out of your
  vehicle to explore different areas that are better handled on foot or in-vehicle. Unlike Blaster Master, there are no overhead sequences. The world is one single contiguous side-scrolling map.

- There will be secret passages and hidden items. More Metroid than Blaster
  master in this regard. Some will be pretty obvious. Others might be rather difficult to find. (dare I say obtuse?) My goal (if I pull it off well, which I may not) is that all of the secret passages necessary to win the game will be fairly intuitive to find, while many of the optional routes or powerups will be better hidden.

 If you have any questions, I'd love to hear from you! Pester me on Twitter or email at nathan@bitethechili.com.

Asset Pipeline

One of the biggest tasks in marking a video game with a significant amount of content is managing your asset pipeline. What is an asset pipeline? It's the process of getting assets (graphics, music, maps, dialog scripts, or any other sort of content) into the game. In smaller games, you can usually get by without much of a pipeline. If there's not much content, you can usually find a way to manually shoehorn it into your game. Or even manually hack or hardcode the data into the game. But with more content, that quickly becomes unmanageable.

Modern platforms like unity have a lot of built-in editors and tooling that manage a lot of the pipeline for you, and the more powerful target platforms (ie your PC) can afford to work with a lot more options of data formats. But on old systems like the NES, it can be a lot of work getting your assets into a format that is usable and efficient.

For example, most Atari games store their sprite graphics upside-down in ROM. This lets you save a few cycles in your rendering kernel (because on the 6502 counting down to 0 is faster than counting up to an arbitrary number, so you count backwards when rendering most things). You can manually enter your sprite graphics backwards by hand, or you can draw your graphics in a user-friendly tool, and let it take care of turning them upside-down.

For the NES, there's a huge range of ways that people manage the asset pipeline. I know folks who design things on paper, then manually enter hex data into their editor.  I know a guy who built an editor entirely as a NES game itself so that you can just press save in the editor, and everything is ready in a NES-friendly format.

My philosophy is this: I want all my assets to be saved in the most easy-to-edit and user-friendly format. That way I can work with them easily during development. Then I want the build process to automatically convert them all into the right format for the game when I compile. I specifically DON'T want to deal with a separate export step during editing -- that usually ends up with a situation where you forget to save or export something, and your exported version differs from the original asset, and you aren't sure which is correct. Instead, I want the original asset to always be the authoritative version. So any conversion or export steps must be automatically done at build time.

So, let's get into examples. Text data is probably the simplest pipeline. I have a number of dialog boxes in the game. I want to be able to write my dialog text in any text editor, and save it as a text file that's tracked in git. So I have a separate text file for each dialog script.

One text file for each dialog

At build time, my makefile runs a python script to convert each of these into the format that my game wants: It converts each character to the value of the graphic tile id that displays that character. It converts special control characters (like line-breaks, special non-ascii glyphs like button icons, etc) to the correct codes. Then it generates symbol tables of both the address of that script, and the text length of the script. So if I want to change any text, I only have to change the text file and recompile, and I'm good to go.

Now, let's get into the more substantial example: backgrounds, metatiles, and map data.

NES background graphics are made of 8x8 pixel tiles of 3 colors plus a solid background color. Different palettes can be applied to those 3 tiles (with all sorts of rules that I won't get into here), but at the core, NES graphics can be represented by a 4-color image.  Frankengraphics (the artist I'm working with) likes to use a program called NES Screen Tool for making the graphics.  Screen Tool generally saves data in a NES-native graphics format, which most people really like. This goes against my core philosophy though, as it's a hard-to-use format. You can't see a preview of the graphics in your operating system's window manager, or pop open any old graphics tool and make quick changes. It doesn't help that Screen Tool is windows-only, and feels REALLY buggy and janky running in WINE on Linux. So when I get graphics from her, I immediately load them into Screen Tool once, and export them to 4-color indexed png format.  During the build process, I have a python script that goes back and converts the png format to the NES-native graphic format (as well as generates address symbols based on the file name) This has the added benefit of making it easier to have arbitrarily-sized chunks of graphic data that I can refer to directly.

NES Screen Tool.  A lot of people swear by this thing.

Then, Halcyon makes maps out of 32x32 pixel "metatiles" -- logical map tiles built out of 16 graphic tiles. So I need a way to define those.  Since there aren't standard ways of representing metatiles (and since each engine has its own requirements for what data is bundled with metatiles), I decided to use a format that's both human readable and easy to program against: json. I built a simple (ugly) graphical editor for building metatiles out of graphics tiles. It edits json files, so standard tools (text diffs, git merges, etc) can easily work with the output of my metatile editor.  In my engine, metatiles contain 16 graphical tiles, as well as collision and palette data for the 4 quadrants of the metatile. These are also saved with the json file.  At build time (do you see the pattern here?) a python script converts these json files to striped arrays of binary data (and will also put them into various rom banks to ensure that I don't overflow the amount of space I have in any given bank).  The other resulting file is a temporary graphical file that re-assembles the actual graphical tiles into the metatiles, which I use for designing maps. This graphics file is never used in the final build -- it's only a convenience to make map design easier.

Speaking of janky, my metatile editor is JANK-O-RIFFIC. But it gets the job done.

So now, on to maps. While there's not one single standard file format or tool for maps, there is a well-known open source program that I'm a big fan of: Tiled. Tiled is a general purpose tile-map editor. It's fairly flexible and configurable, and the author is a really friendly guy who's very invested in making it a well-run open source project.  Tiled saves and loads maps in a simple easy-to-read text format (either based on xml or json), which is perfect for my philosophy of assets.

So I load a tileset graphics file into Tiled and build my maps, saving them in Tiled's native format. At build time, a python script processes all of my map files, and converts them all to the right format for Halcyon. (which is a big array of properties about each map, with pointers to arrays of the actual map data, and arrays of enemy spawn information). Then the script builds a giant index of all my maps, and makes a big lookup table that lets me find the address of a room based on its X,Y coordinates.

Tiled is the best thing ever.

Now that I've talked about HOW I do the asset pipeline for levels, it's worth giving a few more reasons for WHY I do it this way. I mentioned a few above, but I like to repeat myself, so:

- Editing is MUCH easier when you use text formats as much as possible, and
  standard well-known formats for non-text

- Version control (ie git) is a lot more useful with text files, as you can
  easily see a diff of what changed

- Building from the original source asset at compile-time prevents the "out of
  sync" problems you can get with manual exports

- Using a script at build time lets you change the engine's expected format
  without having to touch each of your assets again. For example, at one point I made an optimization in my sprite rendering that required sprites to be stored offset by 32 pixels. To accommodate this, I only had to change my build script without touching each sprite definition. Or if I go back and decide to add compression on graphics, I can do it without having to manually handle each graphics file.

- Using a script lets you automatically build secondary derived assets from
  your assets.  For example, I automatically generate a minimap based on my actual maps without having to manually build a minimap to match the actual map. I also automatically build some reference notes for myself -- a text file that includes notes about the location of every powerup and the id's that I've assigned to them. I love not having to manage that notes file by hand.

  I could talk about all the other types of assets (enemy definitions -- which I've blogged about previously, music, palettes, etc), but I'd start to sound pretty redundant I think. I just do my best to folow the guiding philosophy: store in the most editor-friendly format, and convert everything at build time. Manual exports are NOT allowed.

Scrolling Camera Tweaks

One of the subtle things that can really impact how a scrolling platformer feels is how the camera works. Does the character stay centered, or does the camera feel a bit looser? If it's loose, when does it scroll, and how quickly?  There are tons of articles out there about this, and they can describe it much better than I can, but it's a decision you have to make when designing a scrolling game.


In Halcyon, when moving horizontally, the camera tries to "stay ahead" of the player, by scrolling quickly until most of the screen is ahead of the direction the player is facing. That gives you plenty of time to think about upcoming obstacles and enemies.

This works really nicely for most of the game.

Until it doesn't.

One scenario that happens in Halcyon is that you will get out of the tank, use your grenades to destroy some walls, then get back into the tank. To work around limitations of the NES, destroyable walls regenerate when they go off the screen. This leads to situations like this, where you turn around to get back into your tank, and the destroyed wall immediately goes offscreen as the camera hurries to move ahead of you.

This is a tricky situation. Basically, I want my scrolling to work differently in this subjective situation. But how to define that and codify it into something that actually does what I want?

Tonight's attempt is some simple hackery:  Add a 4-second timer after destroying any block. During those 4 seconds, the camera won't scroll horizontally unless you get a lot closer to the screen edge in the direction you're wanting to scroll. 

This works great for the scenario in question:

The real question will be whether it causes annoying behavior in other parts of gameplay. That will remain to be seen....

Crazy crashing bug

Normally after I test on an emulator for awhile, I eventually throw the game onto hardware, and get frustrated at it not working.

THIS TIME, however, I ran into something new. The game was working on my primary-use emulator, Mesen (which is accurate, easy to use, has a wonderful debugger, and an author who is always adding new features). It worked fine on hardware. But this week I was away from my computer a bit, and wanted to do some testing, so I threw it on my phone (which is using the quite common emulator, fceux).  And on my phone, it now won't run AT ALL.

fceux is a pretty good emulator. Not quite as 100% accurate as Mesen, but usually good enough.  What could cause the game to crash on it but not Mesen or real hardware?

As I usually do when I get stumped with a hard-to-debug issue, I did a git bisect. Git bisect is the one feature of git that, for a single-developer project, makes it better than subversion. It helps you quickly run through past changes, and find the one specific change you made that causes a behavior to happen. I won't go into detail here about it, but if you haven't used it, you're missing out.

Anyway, I did a git bisect, and discovered that the breaking change was just adding a new room to my game. No new code, no new features.  With some experimentation, it turned out that adding ANY new room would break it. Which sounds like maybe I was pushing something over a bank boundary in my rom.  So I dug up my assemblers map file, and no. Nothing was being pushed out of place.

So what could it be? fceux has a debugger, but for some reason, I can't understand how to use it. Did I really need to learn its debugger just for this?

Well, because the problem happened somewhere on startup, the next thing to try (before learning the new debugger) was to insert a bit of code that would turn the screen blue and then infinitely loop. I'd add that at my first line of code, compile and test.  It turned the screen blue on fceux, as it should. Which meant I was getting that far in my code.  For the next few hours, I moved that snippet of code forward and back, trying to find the exact function call that was crashing.

The result?  It turns out I was calling the update function of the music engine (ggsound) before ever calling the initialization function of the library.  Ok, that's bad.  But why would it work on hardware and Mesen but not fceux?  Suddenly it occurred to me.  Mesen and hardware start up with mostly random values in ram.  Fceux starts with zeros. I'm sure that some branch somewhere in the music engine branches on zero, and breaks.  The chance of that piece of memory being 0 in Mesen or hardware are just 1 in 256. So I never saw it crash on those platforms.

That said, I still have no idea why it didn't happen until I added one more room to the game. Probably some dark voodoo. I don't want to know.

Prep for testing

My goal is to have the first area of the game ready for a few folks to sanity check and test for me soon. The goal of this first round of testing is just to make sure I'm not completely off-track. Does it actually run properly for other humans? Is it playable? Is the difficulty completely out of wack? What about the controls?

That means that before I hand it over to folks I need to add just enough polish on everything that it's not a frustrating experience. There are tons of things that aren't done, but that's ok. It just needs to be enough that you get to experience the game properly.

I've been playing through the first area a few times to make sure if feels ok to play to me. It's not very big -- only about 20 different rooms. But that's enough to take a few minutes exploring. And enough to get frustrated by if it doesn't play well. I've already had to change a few rooms that ended up being annoyingly hard.

The other thing that I spent some time on was getting saving/loading working. I fully expect my testers to die a couple times, even this early. I don't want them to have to start completely over every time they die, which means getting game saves working. I have another blog post I need to write about how flash saves work on the mapper I'm using. But I had that part working. What I didn't have working was everything that interacts with actually saving: What happens when you die? How do you load a saved game? How do you start over instead of continuing from your saved game? Does everything get loaded properly when you resume (answer: NO)

I think I finally have all that debugged and working. Tonight was the final piece of it: adding a simple UI for letting the player choose to Start or Continue. Which means title/menu work. Which always takes significantly longer than you expect, and is really boring. Yeehaw.

I'm almost there though. Time to do some more playthroughs.

Now it's a fairly short list of things that I hoped to have in this demo but are missing, and probably won't make it to this first testing round:

• Super NES controller support (there's a lot of "hold down + A" type things in the game. If the player has a SNES to NES controller adapter, they can use dedicated buttons for those)
• New Enemy Graphics (I'm using tons of placeholders)
• The ability to shoot upward at an angle once you find the tank
• Fix buggy behavior with the health-hungry blob enemy

Pseudo-fixed bank

I wrote about bank switching a few years ago when working on Atari Anguna. The idea being that the 6502 (or worse, the 6507 which is the variant of 6502 in the Atari) can only address a certain amount of ROM memory, so larger cartridges use multiple "banks" where you can switch which bank of ROM you're using. Nintendo cartridges used the same technique, so bank switching is important on both consoles.

Many variants of cartridge hardware (commonly known as mappers) divide ROM space into 2 (or more) sections. One that always stays active, and a second section that you can switch. This is a lot easier than switching the entire ROM space at once, as you can control things from the fixed bank, and just load data or call routines from the swappable banks as needed.

The mapper that I'm using for Halcyon (GTROM) doesn't have a fixed bank. Like Atari Anguna, it swaps out the entire bank all at once. Which means that you have to have special code to call a routine in a different bank. You put a stub of code (commonly called a trampoline) in the same place in both banks (or in RAM, which doesn't get swapped). You call that stub, it changes banks, then calls the new routine.

That's worked well for me so far on Halcyon. But now I've realized I have about 15 subroutines that I call a lot and from all sorts of different banks. I decided it would be faster (both in terms of writing code, and in execution) to avoid trampolines for those, and instead, duplicate just those routines into every bank that uses them.

Unfortunately, cc65 (the compiler/assembler suite I'm using) doesn't have direct support for duplicating routines multiple times in different places. So instead I'm doing some ugly hacks.

First, I compile the whole project once, leaving blank space in the places where the code should be duplicated to. One of the linker outputs is a nice map file, which tells the address of every piece of code in the final assembled output. So I have a python script that analyzes the map file, and extracts the portion of compiled binary that should be duplicated in other banks. It writes this to a file, and compiles everything again, this time injecting that extracted binary into each place that it needs to be duplicated.

This worked perfectly until last night when I started getting weird crashes calling code in this duplicated pseudo-fixed bank. Why was it crashing?  After an hour of angry debugging, I discovered the issue:  My python script had an off-by-one error. It was omitting the last byte of the pseudo-fixed bank.  Which means I had half an instruction dangling without the other half. That would do it.