gecko's site

Poop Sweeper

2023-12-24T00:00:00+00:00

Now that the game is out, I can finally talk about this!

My magnum opus:

Poop Sweeper is a faithful clone of Minesweeper¹ in the pause menu of Goodboy Galaxy.

It has the following features:

Persistent state (board remains intact when you navigate away from the app)
Extremely low memory footprint (96 bytes of RAM while the app is closed)
Supports flagging and 'chording'
Status bar w/ cute animations
Saves the player's best time and number of wins

This was really fun to make and I got to take a deep dive into Minesweeper mechanics while doing so, so I wanted to talk a bit about how I did it!

Contents

Recap!
Data representation
- Ugly macro usage
- Board utilities
Populating the board
The floodfill algorithm
- Detonation hack
- Auto-removal of false flags
Player input
Rendering the board
Chording
Conclusion

Recap!

Minesweeper is a game of logic and probability. There are a number of mines hidden on the board. The goal is to reveal all squares that don't have mines.

All the while, there's a timer counting up. The faster you win, the better!

You're doin' it! You're winnin' the video game!

Each turn, you reveal a square of your choice:

If the square contains a mine, then you lose!
If the square is touching one or more mines, it tells you how many mines it's touching.
If the square isn't touching any mines, then all squares around it are revealed too.
- This happens recursively, so revealing a safe square in an ocean of safe squares can cause a large portion of the board to be revealed, akin to using the 'floodfill' tool in a painting program.

You can also 'flag' a square if you believe it contains a mine. The game then won't let you reveal it by accident. You can unflag it at any time.

If you lose, the game will reveal all the other mines on the field. The mine that killed you will be marked in red. Additionally, any incorrectly flagged squares will be marked by an 'X'.

Finally, there's a lesser-known technique known as chording. If you click an already-revealed numbered square and it's touching the correct number of flags, then the game will reveal all squares neighbouring it (except for the ones that were flagged). This is a neat time-saver, but it can kill you if you flagged any of the neighbours incorrectly.

Me losing by chording near a falsely flagged cell.

On PC versions of Minesweeper, chording requires you to click with both mouse buttons at the same time, which is probably why it's not well-known by casual players.

Data representation

The trick to having a small global memory footprint is to cram the state for each square into 1 byte.

To do this I used Nim's bitsize pragma, which corresponds to C's bitfield structs. I don't actually like these anymore², would rather do bitwise ops on integers. But oh well, here we are.

type
  Square = object
    isMine {.bitsize:1.}: bool           # there's a mine here
    isRevealed {.bitsize:1.}: bool       # this square has been revealed
    isFlagged {.bitsize:1.}: bool        # this square is flagged
    isDetonated {.bitsize:1.}: bool      # colour us red (we killed the player)
    mineNeighbours {.bitsize:4.}: uint8  # how many mines are we touching

  GameState = enum
    gsFresh
    gsPlaying
    gsDead
    gsWon
    gsResetting

  MinesweeperBoard = object
    squares: array[BoardWidth * BoardHeight, Square]
    gameState: GameState
    gotNewRecord: bool
    gameTime: uint16
    cursorPoint: Vec2i  # position on the board of squares

var board {.ewdata.}: MinesweeperBoard  # declare the board (always in memory)

Each Square holds everything needed to draw itself correctly, which happens to be almost everything needed by the game logic too.

There's also a load of data used only while the app is actually open (dw about it too much!):

type
  SquarePos = object
    x {.bitsize:4.}: uint8
    y {.bitsize:4.}: uint8

  MinesweeperState = enum
    psInactive
    psBegin
    psCopyPopupTiles
    psReady
    psAnimateIn
    psShowing
    psAnimateOut
    psDone

  MinesweeperVars = object
    shouldHide: bool
    state: MinesweeperState
    nextTid: int
    transition: AppTransition
    squaresFlagged: int
    squaresRevealed: int
    pointsToCheck: List[BoardWidth * BoardHeight, SquarePos]  # a stack for the floodfill
    squareObj: ObjAttr
    maxwell: Sprite
    cursor: Sprite
    timerWidget: TimerWidget
    cursorPressed: bool
    cursorPressRangeX: Slice[int]
    cursorPressRangeY: Slice[int]
    timeUntilReset: int
    resetWipeX: int
    resetWipeTicker: int
    messageTid: int
    messageTextBuffer: array[64, char]
    messageTextDirty: bool

var vars: ptr MinesweeperVars  # heap-allocated, uses no memory while app is closed

Ugly macro usage

To save keystrokes while working with all this game state, I use a macro called extract which I stole from PHP (my enemy!!). PHP's version takes a hash table and magically turns all the fields into local variables (at runtime! disgusting!)

My version is a bit different, and can be reasoned about statically:

extract(board)  # now, let's pretend these fields
extract(vars)   #  are all top-level variables!

It aliases all fields of an object, allowing e.g. squares as a shorthand for board.squares. Neatly this means I can heap-allocate MinesweeperVars without making the code any less readable.

The downside is I have to remember that vars could be nil, and the danger is hidden³ because it doesn't look like anything is being dereferenced.

Personally I think the footgun is worth it for the productivty boost, but ymmv. Rust programmers please don't kill me :')

Board utilities

squares is a 1D array that's intended to be treated as 2D, like squares[x + y*w]. I made some convenience procs to access a square by vector or by individual coordinates. These have a var return value, so you can mutate the board with them like get(x,y).isMine = true.

proc get(p: Vec2i): var Square = squares[p.x + p.y*BoardWidth]
proc get(x, y: int): var Square = squares[x + y*BoardWidth]

Also, I commonly needed to act on all 8 neighbours of a square. This is more annoying than it sounds, because you have to consider the edges of the board too. I ended up with a template which substitutes the body of code 8 times...

While writing this post I realised an iterator would be a more idiomatic way to achieve the exact same thing, so let's pretend I did that instead:

iterator neighbours(x, y: int): tuple[nx, ny: int] =
  if x > 0: yield (x-1, y)
  if y > 0: yield (x, y-1)
  if x < BoardWidth-1: yield (x+1, y)
  if y < BoardHeight-1: yield (x, y+1)
  if x > 0 and y > 0: yield (x-1, y-1)
  if x < BoardWidth-1 and y > 0: yield (x+1, y-1)
  if x > 0 and y < BoardHeight-1: yield (x-1, y+1)
  if x < BoardWidth-1 and y < BoardHeight-1: yield (x+1, y+1)

Populating the board

When the player reveals their first square, it would suck if they immediately got a mine and game-overed. Also it'd be unfair if the first square was already neighbouring a mine.

Wow, this sucks!

For this reason, we wait for the player to make their first move before populating the board with mines. While placing mines, we pick random coordinates, but re-roll if we landed within the 3x3 area surrounding the first square. On later iterations it's also possible to pick a square that already has a mine, so we have to re-roll in that case too.

proc startGame(p: Vec2i) =
  reset(squares)

  # setup board:
  var count = 0
  while count < NumMines:
    let x = rand(0, BoardWidth-1)
    let y = rand(0, BoardHeight-1)
    if not (x in p.x-1..p.x+1 and y in p.y-1..p.y+1) and not get(x, y).isMine:
      # Put a mine only if not near the starting square and not already a mine.
      get(x, y).isMine = true
      for nx, ny in neighbours(x, y):
        inc get(nx, ny).mineNeighbours
      inc count

  gameTime = 0
  gameState = gsPlaying
  gotNewRecord = false
  squaresFlagged = 0
  squaresRevealed = 0

The floodfill algorithm

When you reveal a square in Minesweeper, as long as that square is not neighbouring any mines, the game should recursively reveal all neighbouring squares.

Recursion is kinda expensive though! Fortunately, we have our 1st year Computer Science knowledge to fall back on: any time you have a recursive algorithm, you can rewrite it without recursion by using a loop and a stack⁴.

Here's it working in slow motion!

So first up, the stack, which I named pointsToCheck. It holds the coordinates of squares to be revealed (whose neighbours will then be added, and so on). As the board is only 14x6, you can use 4 bits per coordinate (see SquarePos further up), so it ends up very compact!

proc pushPoint(x, y: int) =
  var sp: SquarePos
  sp.x = x.uint8
  sp.y = y.uint8
  pointsToCheck.add(sp)

proc pushPoint(p: Vec2i) =
  pushPoint(p.x, p.y)

proc popPoint(): Vec2i =
  let sp = pointsToCheck[pointsToCheck.len-1]
  result.x = sp.x.int
  result.y = sp.y.int
  dec pointsToCheck.len

If you process all neighbours of a square, then all the neighbours' neighbours, you'll find many of them overlap. This is a problem! If you allow squares to be processed more than once, the algorithm will never end (until you eventually run out of stack space).

So a strategy is needed to ensure each square is only checked once. In my case I noticed isDetonated is never true for any square at this moment in the game⁵, so I aliased it to checking for this code only.

# repurpose `isDetonated` as a way to prevent a square
# from being added twice to the floodfill.
template checking(s: var Square | ptr Square): var bool = s.isDetonated
template `checking=`(s: var Square | ptr Square, v: bool) = (s.isDetonated = v)

With that out the way, here's the code to reveal a square!

proc revealSquare(pos: Vec2i) =
  if get(pos).isMine:
    get(pos).isDetonated = true
    gameOver()
  else:
    # Floodfill
    pushPoint(pos)
    while pointsToCheck.len > 0:
      let p = popPoint()
      let s = addr get(p)
      if (not s.isMine) and (s.mineNeighbours == 0):
        for nx, ny in neighbours(p.x, p.y):
          let neighbour = addr get(nx, ny)
          if (not neighbour.isRevealed) and (not neighbour.checking):
            neighbour.checking = true
            pushPoint(nx, ny)
      if not s.isRevealed:
        inc squaresRevealed
        s.isRevealed = true

      # auto-remove false flags (this behaviour is like GNOME Mines)
      if s.isFlagged:
        s.isFlagged = false
        dec squaresFlagged

    for s in mitems(squares):
      if s.isMine: discard     # keep mines marked as "detonated"
      else: s.checking = false

It basically just reveals whatever square is at the top of the stack, and if it's a blank square, adds all its neighbours to the stack. This is repeated until the stack is empty.

There are two discrepancies which I'll now explain.

Detonation hack

Right at the end, the checking flags are cleared in preparation for the next move.

I said isDetonated will never be true during a floodfill, but that turned out to be not quite right! Chording can cause more cells to be revealed after a mine was detonated.

Since checking uses the same bit as isDetonated, this meant there was a subtle visual bug where mines could become un-detonated. Luckily a mine can never be checking, so we can just not clear that bit for mines.

Auto-removal of false flags

Something not mentioned in any of my reading material was how the floodfill algorithm should interact with falsely-flagged squares. I tested in a few Minesweeper clones, and got different results in each:

I figured this would be worth asking a Minesweeper veteran about. I stumbled across the minesweepergame.com IRC channel on NewNet. Would anyone still be there?

exelotl (quassel@newnet-iis.p62.16.154.IP) has joined #minesweeper
Mode #minesweeper +nt by nyc.newnet.net
Channel #minesweeper created on 2022-05-29 17:54:30 UTC
<exelotl> hi!
<exelotl> I'm making a minesweeper clone, and was wondering if falsely flagged tiles are
          supposed to become automatically unflagged if they get uncovered by the flood-
          fill algorithm?
<exelotl> I've played 2 different games and each seems to handle this case differently
<aradesh> hi
<aradesh> they remain flagged and unopened
<aradesh> but the squares around it open
<aradesh> if you go to the minesweeper rankings website and to official clones
<aradesh> you'll see they all behave the same way
<exelotl> ah, thanks! yep that seems to be the most common behaviour by far

Yes, it turns out! There were people, and I got an answer within a couple of hours! Yay for IRC!

The verdict is, official Minesweeper games will never remove your flags, even if the flags are clearly wrong.

Ultimately I decided to ignore this rule and let the floodfill un-flag them, because spotting and removing them yourself is just busywork. Your speed is already hindered when playing on a GBA with a d-pad, so I figured it won't hurt to cut the player some slack here.

This behaviour also matches the Mines app available in my system package manager, so there you have it. Poop Sweeper may not be a 100% faithful Minesweeper clone but it is a faithful GNOME Mines clone. ;)

Player input

There's some nuance to the controls, the code isn't all that interesting but basically you have to wait until the player releases (A) before making the move. While (A) is held, the avatar in the top displays a 'thinking' face. If another button is pressed while holding (A), it cancels the move, so releasing (A) then does nothing.

For chording, I thought about requiring the player to press both (A)+(B), like on PC, but this felt unnecessarily obtuse.

Therefore, releasing (A) can cause 3 things to happen:

if this is the first move, populate the board then reveal the square
if the square is already revealed, attempt chording
otherwise, just reveal the square

if gameState == gsFresh:
  startGame(cursorPoint)
  revealSquare(cursorPoint)
else:
  let c = get(cursorPoint)
  if c.isRevealed:
    tryChording(cursorPoint)
  elif not get(cursorPoint).isFlagged:
    revealSquare(cursorPoint)

Rendering the board

I just used a hundred sprites, keep it simple. x)

Ok I'll elaborate: The GBA supports tilemaps, which could in principle work for a game like this. We use one for the backing board:

However, we can't easily use tiles for mines, numbers, etc. as GBA tiles are 8x8px, but our squares are 12x12px. There's a trick you can do with layering two maps slightly offset from each other to construct a map with 12x12px tiles. Puyo Pop does this (amazing game btw!), but it seemed like an overcomplicated solution here.

The GBA supports up to 128 sprites. Rendering the entire board requires 84 sprites, and a few more are needed for text labels and some other UI elements. It's tight, but we have just enough resources to pull it off!

Screenshot from NO$GBA showing the contents of OAM.
Each box corresponds to a single sprite on-screen.

Tile arrangement
in Obj-VRAM.

Finally, rendering the title and status bar text is done with Tonc Text Engine which expects you to prepare regions of the map to hold unique tiles. Here's an illustration of how the tiles are arranged:

How tile IDs are arranged for rendering text. (the unlabeled tiles have IDs too, but for
them it's ok if the same tile is reused multiple times, and their order doesn't matter)

Later in Goodboy development I made it possible to define these tile regions during asset conversion, so you don't have to deal with preparing the map at runtime (and can save a bit of VRAM in the process!). Unfortunately Poop Sweeper was too early to benefit from this change, but it's no big deal.

Chording

Aw yeah, finally the secret technique to becoming a Minesweeper pro.

Nothing happens, because we didn't put down the right number of flags...

Let's review the rules on chording:

When you click a square with a number on it...
If the number of flagged neighbours matches the number on the square
Then the game should reveal all neighbouring squares (except for those flagged)

proc tryChording(p: Vec2i) =
  let c = addr get(p.x, p.y)

  # 1. Check that the tile is revealed and has a number on it.
  if c.isRevealed and c.mineNeighbours > 0:

    # 2. Verify number of flags == number of neighbours displayed.
    var numFlags = 0
    for nx, ny in neighbours(p.x, p.y):
      if get(nx, ny).isFlagged:
        inc numFlags

    if numFlags == c.mineNeighbours.int:

      # 3. For each neighbour, force reveal it, as long as it's not flagged.
      for nx, ny in neighbours(p.x, p.y):
        if not get(nx, ny).isFlagged:
          revealSquare(vec2i(nx, ny))

There was another small bug here. As mentioned, I allowed the floodfill to uncover false flags. But you actually don't want that, if the false flag was the reason you lost - you wanna see where you went wrong!

To fix this, before revealing the neighbours, I record the positions of any neighbours that are flagged. Afterwards, if we lost, I set them to flagged just in case their flag got removed:

# Small workaround to preserve falsely-flagged tiles if we lost.
var falseFlags: List[8, SquarePos]
for nx, ny in neighbours(p.x, p.y):
  if get(nx, ny).isFlagged and not get(nx, ny).isMine:
    falseFlags.add SquarePos(x: nx.uint8, y: ny.uint8)

# 3. For each neighbour, force reveal it, as long as it's not flagged.
for nx, ny in neighbours(p.x, p.y):
  if not get(nx, ny).isFlagged:
    revealSquare(vec2i(nx, ny))

# Apply aforementioned workaround.
if gameState == gsDead:
  for sp in falseFlags:
    get(sp.x.int, sp.y.int).isFlagged = true

One could argue I shouldn't allow any flags to be uncovered on the losing move. But this solution was good enough for me, so that's how it is!

Conclusion

I hope you enjoyed this deep dive into 1% of Goodboy Galaxy!

For the most part it's a game about exploring, shooting beasties and making friends, but we did our best to fill it with little surprises like this along the way x)

If that sounds like your cup of tea then please buy the game, tell your friends, and wishlist it on Steam, so we can keep doing more stuff like this!

Testimonials

Poop Sweeper is too addictive. It's perfect. — e9

poopy sweeper is goty on its own already xD — Crystal

Shouldn't you be working on the actual game? — my Dad

This game got me addicted to minesweeper! — Clipper152

Goodboy Galaxy and Witch'n'wiz are not enough for me, even together. But Poop Sweeper is changing everything. — Michal Bernat

Comment on the GBAdev Forums!

Footnotes

[1]	Actually a faithful clone of GNOME Mines due to one subtlety which I'll explain later.

[2]	Compared to bitwise operators, C compilers aren't very good at optimising bitfields. Also, Nim has trouble getting the size of a bitfield struct at compile time. I could achieve readable code without these problems by using distinct types with getters/setters for each bit.

[3]	If you think this is terrible, maybe you wanna try Zig or Hare which go out of their way to ensure such spooky-action-at-a-distance is impossible.

[4]	After all, that's what recursion is — running the same code repeatedly while using the call stack to retain state from previous invocations.

[5]	The purpose of isDetonated is only to colour a mine red, to indicate it was the one that killed you.

Wow, a note!

2022-12-24T00:00:00+00:00

Well, I finally redid my website!

It's gonna be like a blog, but also a place for short updates, and anyone can subscribe via the atom feed if they'd like to hear what I'm up to.

I dug up some old articles of mine from around the web, but they were kinda long, and it felt like whatever I posted next would have to live up to them! But maybe if I were to make a completely underwhelming post like this one, that might break the ice.

Nim Tilengine Bindings

2022-11-01T00:00:00+00:00

Tilengine by Megamarc is a free, cross-platform software rendering engine for retro-style 2D games using tilemaps, sprites and palettes. Many oldschool tricks are supported such as palette-based animation and per-scanline raster effects. The implementation is efficient and can run well even on a Raspberry Pi.

Last month I put together nim-tilengine, allowing you to use Tilengine with the Nim programming language.

These bindings strip away all the cruft from the C API, leading to code that's shorter and more readable than even the official Python bindings, while keeping native performance!

Quick Example

import tilengine

let engine = init(320, 180, numLayers = 4, numSprites = 128, numAnimations = 128)

let map = loadTilemap("assets/map.tmx")
Layer(0).setTilemap(map)

createWindow()
while processWindow():
  drawFrame()

map.delete()
deleteWindow()
deinit()

Tools behind the Goodboy Galaxy demo

2021-08-28T00:00:00+01:00

When I posted about Goodboy Galaxy on the Nim forums, enthus1ast asked:

Can you give a little insight what technologies you've used?

Here's a repost of my answer:

Our Nim GBA library is called Natu, which includes bindings for various C/asm libraries such as:

libtonc for interacting with the hardware and rendering text
posprintf for efficient string formatting
maxmod for music and sound.

We used the devkitARM¹ cross compiler toolchain (though plain old embedded ARM GCC can work fine too, so we'll probably switch to that in the future).

The library itself started as a straight-up C wrapper, but has become more idiomatic since then (more type safe, better naming, using sets instead of ORing together constants, etc.). I'm still trying to clean it up and make it more usable for others, when I can. While a bit outdated already, you can check out my NimConf video from last year if you'd like to see it in action. :)

Natu works with both --gc:none and --gc:arc, though arc didn't exist when I started working on Goodboy Galaxy, but I've had success with it for other small projects. Right now everything in the game is on the stack or statically allocated², which is nice for performance, so the choice of memory management strategy doesn't matter all that much for me. However, I'm envious of the benefits that destructors could bring if I'd written the engine with arc in mind… No more leaks would be great!

While building the game we implemented many of the systems described in Game Boy Advance Resource Management, such as a tile engine and Obj (sprite) VRAM allocator. This article is absolute gold, I don't know where I'd be without it!

For level design we use Tiled. But we can't just parse the XML files at runtime - custom tooling is needed. We devised a level format (in Nim types), and wrote a tool which takes the levels, processes and converts all the maps, tileset graphics etc. and spits out C code and Nim code, allowing that data to be used in the game. Earlier this year I discovered Nim's stdtmpl filter which makes this kind of codegen much more pleasant, so I've started using that where I can.

One aspect of the game I'm really happy with is the dialogue and cutscene system. I really wanted some sort of coroutines³ so that I could sequence a cutscene using simple procedural code:

player.runLeft()
wait 120                        # give control back to the main thread
                                # then resume from here in 2 seconds.
player.stopRunning()
say chMaxwell, "Oh... Heck."    # show a speech box.

To achieve this initially I made my own hacked-together version of CPS - a macro that splits a block of code into a chain of functions. It was ok at first, but ended up being a buggy nightmare to maintain. Then, by chance a member of the GBAdev community went and implemented context switching for the GBA, which allowed me to adapt Zevv's nimcoro to get true Lua-style coroutines. After getting this working, I never looked back. it's perfect!

Oh yeah, I guess I should mention some pain points:

Nim's methods are too heavy for use on embedded platforms - RTTI eats up a ton of RAM and the performance degrades as more subclasses are added. So we had to roll our own VTables instead for things like the entity system.
Addressable contant data in Nim is still pretty limited. The improvements to let were nice but only work for arrays of ordinal types. So we've mostly resorted to generating all our data as C code to work around this, which is fine once you get used to it.
Lack of circular imports is super painful, as we need things to talk to each other and can't afford to use event busses and other high-level decoupling techniques that would usually solve this. We often have to resort to hacks involving {.exportc.} and {.importc.} to work around this problem.

That said, if you sent me back in time by 2 years I would absolutely choose Nim for this project again! It's a joy to work with and I can't think of any other language I'd rather be using today.

[1]	Later we switched to vanilla embedded ARM GCC (available on most package managers), with the help of gba-bootstrap by AntonioND. I'm so happy with this change, because it simplified installation and allowed us to distance ourselves from devkitPro, who are too gatekeepy for my taste nowadays.

[2]	This quickly changed after the demo, as we kept running out of RAM. So we started to allocate data for minigames, menus etc. on the heap so they'd take up zero memory when not in use. Newlib's malloc was too heavy so we used ACSL's instead.

[3]	Check my old post using Lua coroutines to create an RPG dialogue system to see why this is so awesome.

Things I've learned since 'Goodboy Advance'

2019-12-30T00:00:00+00:00

Goodboy Advance was the original jam version of Goodboy Galaxy, which Rik and I hacked together for Ludum Dare one weekend in December 2018.

It's not that good really... well it was kinda impressive at the time, but it's really missing enemies, characters, and story. If you're looking for a cool GBA homebrew game about a dog in space, you should definitely try Goodboy Galaxy: Chapter Zero instead.

However, if you'd like to know what we used to make the original jam game, and all the things we've learned since that allowed us to go on to make Goodboy Galaxy, then this is the page for you!

How we made it

The game was written in C using the devkitARM¹ toolchain, with libraries provided by this excellent free book called Tonc which can teach you almost everything you need to know about GBA programming.

We used Maxmod for music/sfx playback. Music was composed in MilkyTracker and MadTracker. i.e. we have different weapons of choice, but it doesn't matter because both support the XM format which Maxmod can use.

Aseprite was used for graphics/animations (having to be mindful of size and palette restrictions etc.). To convert the graphics into the raw formats which can be used by the hardware, we used Grit which is powerful but quite difficult to work with because there are so many options and sometimes it's hard to tell which ones do what you want².

And finally, we made the maps in Tiled, but it seemed like parsing XML or JSON in C on such limited hardware would be a terrible experience. So instead we made a Node.js script which goes over the Tiled data and generates C code for a given level. That may sound like a big hack but it was really a life saver!

Learnings

The source code for the jam game can be found on GitHub. This code was born from the ashes of a Super Crate Box clone that I was working on many years ago.

Here are some things it does poorly, which we've fixed in Goodboy Galaxy and/or you may want to do differently if you're aiming to make something bigger than a jam game:

All declarations are in 1 header file. This was convenient for the jam but wouldn't cut it for a larger project. (Actually for Galaxy we rewrote everything in Nim which has a decent module system instead of header files)
Misuse of VBlank. No separation between update & draw means that sometimes the game will perform visual changes (scrolling the background, fading the palette, modifying sprites) while the PPU is in the middle of updating the display, leading to tearing artifacts.
- Writing a decent GBA main loop is a topic that deserves its own article, but at the very least: "Game logic" -> "Wait for VBlank" -> "Visual updates" would be a much better structure than what I did here ("Wait for VBlank" -> "Do everything").
Tile/map/palette locations are hardcoded or allocated by simple counters. Instead, you might want to use allocators such as the ones presented in Gameboy Advance Resource Management
Statically allocated arrays for each type of entity. Consequently there's a maximum of 20 breakable blocks in a level, 8 bullets alive at a time, etc. This is fine for smaller games (keep it simple!) but doesn't scale well: if the current level doesn't have any breakables, that array of 20 breakables is still taking up RAM for no good reason.
- Consider putting all entities in 1 array (an object pool) and using some mechanism such as dispatch tables to give different behaviours to different entities.
- On modern hardware, dynamic dispatch can be considered a thing to avoid in the interest of cache-friendliness, but on the GBA it turns out that chasing pointers isn't particularly slow compared to the speed of the processor itself.
- More generally, if you're running out of memory you can try moving global variables from IWRAM into EWRAM which is slower to access but more plentiful.
  
  e.g. EWRAM_DATA u16 myarray[100];
- It's also OK to do dynamic allocation via malloc, but try to only use it for data that sticks around for a while but isn't needed permanently, e.g. the state of a boss fight on a particular level. The only trouble is, the default malloc implementation from newlib is pretty wasteful (>1KiB static IWRAM usage), so you might want to consider replacing it with a version that's tailored to the GBA, such as the one from ACSL.
The wrapping level mechanic introduces some nasty bugs. When the player goes beyond the right side of the level, they are teleported to the left side. This can cause objects to vanish or appear out of nowhere. It can also lead to getting stuck in walls or ceiling depending on placement.

For the jam, we designed the levels to minimise the problem. In Galaxy, we fixed it with more thorough checking and a proper spawn system (which ties into the '1 array of entities' mentioned above).
Streaming larger level maps (bigger than 2x2 screenblocks) - this code works but it's not that good. It uses 4 whole screenblocks which are copied every frame even if nothing changed. Probably need to be smarter about that...
- The way to do this properly is to take advantage of the fact that a single screenblock (tile map region) on the GBA is 2 tiles wider than the size of the GBA screen (and plenty of tiles higher). This means as the camera scrolls you can copy in new rows & columns of map data, to give you an infinitely large map from just a single screenblock. The Tonc bigmap example demonstrates this. There's also an annotated version of the same code by ColonelSalt which is easier to read.
- You may eventually run into the problem that there are too many unique tile graphics in your level. The maximum is 1024 (as tile IDs in the map are 10-bit). But you might run into problems before then, because 1024 tiles takes up a lot of VRAM! To solve this, you'll need a means of dynamically loading tiles as they scroll onto the screen, and unloading them as they scroll off. Once again, GBA Resource Management explains how to do this.
Too much DMA - the game occasionally crashes on screen transitions on real hardware. I suspect this might be due to me using DMA copies to load absolutely everything. As Tonc says, “don't wear it out”. Perhaps this would cause the game to miss interrupts or fire them too late (Maxmod in particular is picky about VBlank IRQ timing). I'd recommend using memcpy32 for most things instead. (If somebody knows more about this, I'd really like to know!)
Tooling: We have a script that converts Tiled level data into C code. Besides that, we used grit for all our image data, including the level maps themselves. In Galaxy we realised we need more control, so we ditched grit and ended up making a lot more scripts that generate all kinds of data from various config files. It takes time to get this stuff working, but it makes adding content to the game much quicker and less error-prone!

tl;dr Don't be afraid to write code that spits out more code.
Polish: The game has some niceties such as muzzle flash / impact fx / screenshake, but the position-locked camera and the static background let things down a little. In Galaxy we use HBlank DMA to get some gorgeous multi-layer parallax from just a single background.

[1]	devkitARM can be installed from here but nowadays I'd recommend something like sdk-seven, gba-toolchain or gba-bootstrap

[2]	SuperFamiconv is often recommended as a more user-friendly and less buggy alternative to grit. I'd recommend trying that first.

Flappy Delivery Co.

2018-01-02T00:00:00+00:00

A bird delivers a letter - what happens next will shock you!

A little thing I made for a job interview.

An Introduction to Metatables

2016-06-12T13:06:00+01:00

Note

Originally posted on the forums of PICO-8, a 'fantasy console' with limitations inspired by classic 8-bit computers, which uses a modified flavour of Lua 5.2.

Hi folks, this post aims to offer a clear introduction to the topic of metatables in Lua for those who are not yet familiar with them.

Without further ado, let's go!

A table is a mapping of keys to values. They're explained quite well in the PICO-8 manual and the Lua reference manual so I won't go into more detail. In particular you should know that t.foo is just a nicer way of writing t["foo"] and also that t:foo() is a nicer way of calling the function t.foo(t)

A metatable is a table with some specially named properties defined inside. You apply a metatable to any other table to change the way that table behaves. This can be used to:

define custom operations for your table (+, -, etc.)
define what should happen when somebody tries to look up a key that doesn't exist
specify how your table should be converted to a string (e.g. for printing)
change the way the garbage collector treats your table (e.g. tables with weak keys)

Point #2 is especially powerful because it allows you to set default values for missing properties, or specify a prototype object which contains methods shared by many tables.

You can attach a metatable to any other table using the setmetatable function.

All possible metatable events are explained on the lua-users wiki:

>>> list of metatable events <<<

which is, as far as I'm aware, the best reference for everything that metatables can be used for.

And that's really all you need to know!

Vectors Example

I'll now demonstrate how metatables could be used to make a "2D point/vector" type, with custom operators.

-- define a new metatable to be shared by all vectors
local mt = {}

-- function to create a new vector
function makevec2d(x, y)
    local t = {
        x = x,
        y = y
    }
    setmetatable(t, mt)
    return t
end

-- define some vector operations such as addition, subtraction:
function mt.__add(a, b)
    return makevec2d(
        a.x + b.x,
        a.y + b.y
    )
end

function mt.__sub(a, b)
    return makevec2d(
        a.x - b.x,
        a.y - b.y
    )
end

-- more fancy example, implement two different kinds of multiplication:
-- number*vector -> scalar product
-- vector*vector -> cross product
-- don't worry if you're not a maths person, this isn't important :)

function mt.__mul(a, b)
    if type(a) == "number" then
        return makevec2d(b.x * a, b.y * a)
    elseif type(b) == "number" then
        return makevec2d(a.x * b, a.y * b)
    end
    return a.x * b.x + a.y * b.y
end

-- check if two vectors with different addresses are equal to each other
function mt.__eq(a, b)
    return a.x == b.x and a.y == b.y
end

-- custom format when converting to a string:
function mt.__tostring(a)
    return "(" .. a.x .. ", " .. a.y .. ")"
end

Now we can use our newly defined 'vector' type like this:

local a = makevec2d(3, 4)
local b = 2 * a

print(a)      -- calls __tostring internally, so this prints "(3, 4)"
print(b)      -- (6, 8)
print(a + b)  -- (9, 12)

Pretty neat right?

Object Orientation

I mentioned that metatables can be used to define what should happen when a key lookup fails, and that this can be used to create custom methods shared by many tables. For example we might want to be able to do this:

a = makevec2d(3, 4)
a:magnitude()  -- calculate the length of the vector, returning 5

In Lua this is not always necessary, for example, we could define an ordinary function to do the job for us:

function magnitude(vec)
    return sqrt(vec.x^2 + vec.y^2)
end
magnitude(a)  -- returns 5

In fact, for PICO-8 I would recommend that approach, because it's as efficient as you can get, and it uses the least number of tokens (PICO-8 cartridges are limited in code size).

But I think it's educational to see how metatables can make it possible to use Lua in a more OOP style.

First off, we define all our methods in a table somewhere. Note, you can define them in the metatable itself (this is a common convention), but I'll put them in a different table to prevent confusion.

local methods = {}
function methods.magnitude(self)
    return sqrt(self.x^2 + self.y^2)
end

Now back to our metatable, mt:

The __index property of a metatable is referred to when you try to look up a key k which is not present in the original table t.

If __index is a function, it is called like mt.__index(t, k)
If __index is a table, a lookup is performed like mt.__index[k]

So we can add the magnitude function, along any other methods we may have defined, to all our existing vector objects by simply setting the __index property to our table of methods:

mt.__index = methods

And now, as we wanted, we can call a:magnitude()
Which is a shortcut for a.magnitude(a)
Which is a shortcut for a["magnitude"](a)

Hopefully given all this information, it's clear what's happening: We never defined a "magnitude" property in a, so when we try to lookup the string "magnitude", the lookup fails and Lua refers to the metatable's __index property instead.

Since __index is a table, it looks in there for any property called "magnitude" and finds the magnitude function that we defined. This function is then called with the parameter a which we implicitly passed when we used the : operator.

Well, that's it from me! I hope somebody finds this post useful, and please let me know if there is something you don't understand, or something that I left out or could have explained better. If you'd like to see more examples of metatable usage and OOP, I recommend chapters 13, 16 and 17 of Programming in Lua.

Using Lua coroutines to create an RPG dialogue system

2016-03-28T00:00:00+01:00

Recently I've been working on an RPG¹ with a friend, for whom coding is not their strong point. We're using the excellent LÖVE framework, so the whole game is written in Lua.

Scripting of dialogues, animations and in-game events is a hugely important aspect for any RPG, and I wanted to build a scripting system that's easy to use and doesn't require any knowledge about the rest of the game's engine, but is also powerful enough for me to extend with new functionality as needed. This post aims to show how a few simple Lua features can be combined to create a scripting environment that's pleasant to use.

First, let's take a look at the XSE language used in Pokémon modding, as this was probably my main point of inspiration. It has a very straightforward, imperative style, even though each instruction doesn't correspond to a single function in-game.

By this I mean, the whole game engine doesn't freeze just because you are talking to an NPC, however there are points at which the dialogue script cannot progress until the text animations have finished and the player has pressed the [A] button.

Another interesting tool is Yarn², a dialogue editor in which you connect nodes of text together to form complete conversations. It has variables, conditionals and custom commands which you can hook up to different parts of your engine to trigger animations and such. I'd say it's definitely worth checking out especially if you're using Unity or similar.

So how would we go about creating such a system in LÖVE without creating our own language or writing an interpreter for an existing language such as Yarn?

Part 1: Chaining Callbacks Together

The first thing we need is the ability to 'say' some text from inside a script, which boils down to setting a string and then waiting for the user to press a button before we resume execution of the script. The game should still be updating on every frame, even when text is being displayed.

In true JavaScript fashion³, we could create an asynchronous API that looks a bit like this:

text = nil
callback = nil

function say(str, cb)
    text = str
    callback = cb
end

Our game logic & rendering code could look something like this:

function love.update(dt)
    if not text then
        -- player movement code
    end
end

function love.draw()
    -- code to draw the world goes here

    if text then
        love.graphics.print(text, 10, 10)
    end
end

function love.keypressed(key, isRepeat)
    if text and key == "space" then
        text = nil
        if callback then
            -- execute the next part of the script
            callback()
        end
    end
end

Then we could write a dialogue script that looks like this, potentially fetching it at runtime with a call to dofile() or something:

say("Hello there!", function ()
    say("How's it going?", function ()
        say("Well, nice talking to you!")
    end)
end)

This kind of code grows unwieldy very quickly. It's confusing for non-coders and also error prone (many places to miss out a comma or a closing bracket). You could try some variations such as giving a name to each function, but it still turns out quite unpleasant to work with because managing all those functions gets in the way of what matters: writing good dialogue and scenes. At this point we'd surely be better off writing a Yarn interpreter or using some other existing solution.

But this is not JavaScript, and we can do better!

Part 2: Using Coroutines

For the uninitiated, coroutines are chunks of code that can be jumped to much like functions. A coroutine can suspend itself (yield) at will, returning to the point at which it was called. At a later stage, the program can jump back into the coroutine and resume where it left off.

I suppose this puts them in a sort of middle ground between functions and threads. They are more powerful than functions, but you still have to manage them explicitly - you can't just leave them running in the background to do their own thing. Typically they are used to break up an intensive task into small bursts, so that the program can still function as normal (receive user input, print to console, etc.)

Hang on a minute, doesn't this sound a lot like what we want from the dialogue scripting system? Executing a single line and then suspending the script while we give control back to the game loop?

Let's see how we could achieve the same result as Part 1, only using a coroutine instead of a chain of callbacks.

text = nil
routine = nil

function say(str)
    text = str
    coroutine.yield()
    text = nil
end

function run(script)
    -- load the script and wrap it in a coroutine
    local f = loadfile(script)
    routine = coroutine.create(f)

    -- begin execution of the script
    coroutine.resume(routine)
end

The important difference here is the implementation of the say function. Instead of setting a callback for later use, we tell the current coroutine to yield. This means we can't call say directly from the main program, only from inside a coroutine. Also there is now a loader function which creates a new coroutine and tells it to run the script.

Next we need to rewrite love.keypressed to make it resume the coroutine on the press of the space bar.

function love.keypressed(key, isRepeat)
    if text and key == "space" then
        if routine and coroutine.status(routine) ~= "dead" then
            -- execute the next part of the script
            coroutine.resume(routine)
        end
    end
end

And finally, we can write a script that looks like this:

say("Hello there!")                -- the script suspends once here
say("How's it going?")             -- it suspends again here
say("Well, nice talking to you!")  -- it suspends for the 3rd time here

Part 3: Sandboxing and Advanced Usage

If we declare a global variable, 'n', we can create an NPC that remembers how many times the player has spoken to it.

say("Hey kid, I'm Mr. Red!")

if n == 0 then
    say("I don't believe we've met before!")
else
    say("You have spoken to me "..n.." times!")
end

n = n + 1

It's great that this works, because it does exactly what you would expect and it's super easy to use. However, there are some problems.

If all the variables are stored in the global environment, we risk running into naming collisions which at best will cause scripts to behave incorrectly and at worst could replace key functionality and crash the game.

Additionally, having our game's state scattered across a ton of globals makes things very difficult when we want to think about serialising the gamestate to produce a save file.

Fortunately Lua makes it easy to swap out the environment of a function for any table, using setfenv in Lua 5.1 or _ENV in Lua 5.2 or greater. We don't need to change our scripts at all, we just need to make sure that they still have access to the say function, by placing it in their environment (the game table below).

game = {}

function game.say(str)
    text = str
    coroutine.yield()
    text = nil
end

function run(script)
    local f = loadfile(script)
    setfenv(f, game)
    routine = coroutine.create(f)

    -- begin execution of the script
    coroutine.resume(routine)
end

It also might be helpful to have a script that is called once at startup, to initialise all the game variables to default values, or load them from a save file.

As far as animation goes, we can drop in a tweening solution like flux, along with a few helper functions which will allow us to pause the script until the animation completes.

game.flux = require "flux"

game.pause = coroutine.yield

function game.resume()
    coroutine.resume(routine)
end

and then we could tween a character to x = 800 with a script like this:

flux.to(myNpc, 2.0, { x = 800 }):ease("linear"):oncomplete(resume)
pause()

which yes, is a mouthful for non-coders, and it introduces an asynchronous aspect back into the scripting API. We would probably benefit from a custom animation system that's more more tailored to our game, but this hopefully goes to show how easy it is to make scripts that can interact with any other part of the engine.

What Next?

I hope I was able to teach some interesting ideas here! I wanted to share this because coroutines are something I've known about for a while, but until now I've never had a good reason to use them. I would be interested to know which other languages can be used to create a system like this.

Here are some things you might want to do next, to create a more full-featured RPG engine:

Add lock() and release(), so it's possible to display text while the player is moving, or stop the player from moving even when there is no text.
Add an ask(str, ...) function whereby the player can choose from a list of options (e.g. yes/no)
Download a level editor such as Tiled, or create your own. Try attaching some scripts to game objects such as buttons and NPCs. Relevant tutorial on using Tiled with LÖVE
Create an easy-to-use animation system with commands such as 'face X direction' or 'move N steps'
Add character portraits so that the player knows who's speaking (this might require you to add an extra parameter to say() or some new functions)
Consider how you would go about handling save data. How to distinguish it from data which is part of the gamestate but does not need to be saved permanently?

[1]	We never finished the RPG, but I did make a little PICO-8 example to demonstrate the techniques from this article.

[2]	Now Yarn Spinner

[3]	JS async/await wasn't much of a thing back when this article was written.

Museum City Boat - Post Mortem

2015-09-11T00:00:00+01:00

Note

Recovered from ludumdare.com/compo/2015/09/11/museum-city-boat-post-mortem.

Hi! It's slightly late but I figured I'd finish up the post mortem for my entry, Museum City Boat.

It's a small, charming side-scroller where you get to go on a rampage as a monster, smash some lamps, flip some cars and generally do monster things.

The main tools used were Lua/LOVE, GraphicsGale, Fireworks, Renoise, and a Zoom H1 Handy Recorder.

Shout outs to the friendly participants on the #love channel (irc.oftc.net) who were really supportive and helpful as usual :)

What went well

Pre-compo planning

It was my 5th time entering, and I've noticed that the theme always catches me by surprise. This time, I wanted to be ready! So during the voting, I tried to make notes on possible game ideas for every single theme. Because thinking up game ideas is much easier when you are not dealing with jam stress.

This took up a lot of time and creative thinking, and I gave up on it half way through Round 3. It still paid off though: the theme 'You Are The Monster' did not give me any good ideas when it was announced, so I simply looked back at my notes and chose my favourite idea from there.

Style and Gameplay

This is possibly the first time I tried to make a game that evokes simple, classic arcade vibes rather than focusing on ambience and emotion. Sometimes I feel like there is a fine line between 'silly' and 'amateur'¹. I wanted to make something cute, fun and silly, but still high quality. It was only in the later stages of development that I realised what I was making might achieve those goals and not be garbage.

Friends and participants commented on the smooth camera movement, simple mouse controls, cute graphics and satisfying sound effects, so I feel like I succeeded here!

Another interesting thing I managed was to add replay value through score categories (number of structures destroyed, number of times seen, etc.) and just writing some challenges in the game's description. Like 'hey, can you beat the game without being seen by cameras or people?' - If the game was bigger or I had more time, this kind of thing would be put in an achievements system of some kind, but people will make their own fun if you tell them how!

Coding

The last time I made a game in Lua, I was using cmd and a general text editor, which meant I was missing out on some important workflow aspects such as quick-launch, error checking, rename variables etc. This time I used ZeroBrane Studio, which is a truly excellent Lua IDE that comes with love2d support built in. It made my life so much easier!

My code turned out clean, for a jam at least. I spent very little time tracking down bugs, even though I had plenty of globals that the other classes in the game depended on. I think this is because I stuck to some simple rules: initialise globals early, put them where they make sense (e.g. main or assets), be aware that their value might not be what you expect… and also because I was able to assume I didn't need to do any dangerous things like removing the player from the world (which could be disastrous because so many things access the player directly for AI or collision checking).

I had to throw in some rendering hacks to make sure things like water and game-over text displayed correctly (just stick them in the global drawing function), but this was OK because it was added quite late in development, so didn't get a chance to turn into spaghetti code.

Music and Audio

Electronic music is a passion of mine, so this part is always fun and usually turns out well! However, I spent the majority of my time drawing and coding, so audio was quite a rushed thing in the end.

I spent about 4 hours on the last day of the Jam to write a cheery 80s/90s track. I have a Korg M1 plugin which is perfect for this kind of stuff, combined with some great virtual analogue synths like FXPansion Strobe. The main challenge I had to overcome was my tendency to write really emotional chords and melodies which don't fit the vibe I was going for. It took a couple of attempts but eventually I came up with something that fit just right.

My two main inspirations here were Mitch Murder and Bacalao. I was listening to them almost all weekend, their music is so great!

The sound effects were pretty much done in the last 2 hours! Most of them came from the kitchen. I was literally standing there at 1AM with a mic, knocking glasses together and making growling noises. They were all trimmed, pitched and normalised in Renoise and Audacity.

Some sounds were more creative, for example the explosion was made by taking the muffled 'thud' of a cupboard closing, then pitching it down further, adding white noise and running it through a distortion plugin. The water hiss and camera beeps were generated with SunVox.

What could have gone better

Design Process, Confidence

The picture above was the closest thing I had to a 'design doc'. Not really a huge problem, because I never churn out pages for any of my small projects, I'm kinda used to improvising as I go along.

The main issue was settling on a graphical style. I never made a game with vector or high-res graphics before, so I figured given that I have Fireworks (hybrid vector/bitmap editing) and there are easy skeletal animation tools out there such as Spriter - how hard could it be to make a game using those? Or perhaps I could draw the monster with code, since the love2d splashes seem to have these delicious vector graphics? Though, how would I relate the vector graphics to the physics engine?

So I spent all afternoon contemplating and trying different ways to draw my monster and animate him, and the results were awful! At this point I just felt like giving up, or maybe switching to a different system altogether like PICO-8. It wasn't until Saturday night that I went back to GraphicsGale, drew some pixels and actually got the monster running around the screen. I eventually realised that if I wanted to make a game I was happy with, I'd have to enter the Jam to make up for all that lost time.

One good decision I made was to use Arne's 16-colour Palette. If I'd had more skill and time to put towards pixel-art, I could have chosen a more detailed style and really made the palette shine, but anyway it served me really well! In my previous entry I spent far too much time worrying about clashing colours, but this time I could forget all that and get on with pixelling. I settled on a clean flat style with 1px outlines and no shading.

Level Creation

When I was getting started, I drew the whole level as a huge image in Fireworks, and hard-coded the player and other entity spawns. I was planning on switching to a proper editor like Tiled, but I didn't feel like setting up and traversing all that exported data, so it never really happened.

I can't say whether or not I lost much time to this, but it was certainly inconvenient sometimes, and the fact that I chose to work this way makes my game much less scalable in its current state.

What next?

I'd love to take this game further and turn it into a deeper, longer and more interesting adventure (with boss battles!). Right now I'm experimenting with development for the Gameboy Advance, so maybe I'll ditch the rigid body physics and port the game to GBA? It will make it a far bigger technical challenge but it's a really rewarding platform to develop for.

At the same time I have some commitment to older projects that I want to get finished, but I'm worried that if I work on those then I will lose my motivation to work on this game? So in the long term I'm not quite sure what will happen.

As long as I'm doing GBA development I'd like to try blogging about it, because it's an interesting field but most of the reading material is from 2007 and earlier. Maybe it would help people to have some modern articles on the subject from someone who is still learning.

This has become quite a wall of text, so if you've made it this far, thanks for reading, and best of luck to all those awaiting LD33 results!

Until next time,

Gecko

Footnotes

[1]

in 2024 I'd describe this differently - it's like, there's a difference between confidently amateur (this is scrappy but there's intent, it works and I'm proud of it) and aimlessly amateur (having huge gaps in my vision and being unable to pull together a compelling work by the end). The latter doesn't make for a desirable end result, but can still be a valuable learning experience.

Tangentially, you should check out How To Make Good Small Games by John Thyer, it's really important!

Curiosity - Post Mortem

2013-05-10T00:00:00+01:00

About time I got around to writing a post mortem for my entry, here goes!

Curiosity is a little ambient exploration game written in the ooc programming language. You can play the game here (comments here) if you're interested.

The Idea

In the UK, Ludum Dare starts and ends at 3AM. I decided to stay up into the early hours of Saturday, and fell asleep with minimalism floating around in my head. I think I had a dream about a game idea, but unfortunately I couldn't remember it.

I thought about a game that starts of super minimalistic, and gets progressively more detailed and lush as the player progresses. Of course, this was silly and vague. In such a short space of time just having a finished project is a challenge, but I hope the game resembles my intentions a little.

I admit I didn't really like the theme at first - any game made in 48 hours is going to be minimal, so minimalism seemed to be a wildcard. I changed my mind once I got started.

Design

My graphics software hasn't changed since the last time I entered. Even though I'm 5 major versions behind now, and running it 2 operating systems ahead of what it was developed for, Fireworks is still my general purpose graphics editor of choice. Having .png as the native project format is really handy, along with the variety of non-destructive image processing options.

I'd heard good things about Ogmo Editor, and watched a tutorial on using it in FlashPunk. Considering this was my first time using it in a project, it worked amazingly! When designing the world, I tried to make sure there was more than one way to solve each challenge (though not everyone who played the game noticed this). Some people said the game reminds them of the Knytt series, which is very cool to hear! Nifflas was certainly a source of inspiration for me.

A few people found the game too difficult, but I don't think there were any major flaws in my level design this time. My old entry for LD21 had lots of blind jumps, no checkpoints, and you could fall off the world by going left. I've definitely improved in that respect! Personally I thought the difficulty level was fine, especially after playing some other awesome yet insanely hard entries.

Programming

My choice of language, ooc, served me incredibly well! It's a modern object-oriented language that compiles into C99, and therefore works on any platform with pthreads and a C compiler. I picked it up in the last few months, created quite a lot of bindings to existing C libraries, and have been working on a FlashPunk inspired game engine called Vamos using SDL 2.0's hardware accelerated rendering API, which I used to create this entry.

The majority of development issues were all tackled before the compo started, so I had a pretty smooth ride on my own framework. The day before, I bound a small XML library (MiniXML) to ooc, so I was able to parse Ogmo Editor's level data. On the first day I remembered I still hadn't implemented depth-sorted rendering, and that ate up a little bit of time, but was quite painless.

The main problem was that my game engine didn't have sound effects. I'd been trying to write my own audio mixer before the compo (without relying on SDL_mixer), but it had huge latency and I couldn't figure out how to avoid sounds being synchronized to the buffer size. The music playback (which uses stb-vorbis for decoding) was working fine, and I found a hacky solution last-minute to create smooth crossfades between tracks. That hopefully compensated for the lack of sfx.

Music

This has always been a strong point for me. I wanted to include just as much musical content as last time, which meant I had to make 4 tracks! In my last entry, my soundtrack was ruined for some people by streaming/stuttering issues. That wasn't a problem this time, because I was making a desktop game.

I'm primarily a Renoise user now (though SunVox is still awesome, and I highly recommend it if you're looking for a free music program). I've got a nice collection of free VSTs and samples and had fun creating some ambient songs and soundscapes. It gave me a nice break from the intense coding! :)

Overall

I'm really happy with how this turned out! I've since made some Linux binaries, and it also runs nicely on OSX (though I don't have a mac to test or package it). I'd love to develop Vamos further and make some more ooc games in the future.

I'd also like to thank everyone for their encouraging feedback so far. Thanks guys, and well done on all your finished projects!

Raspberry Pi Arrived

2012-10-21T23:55:00+01:00

Note

This is an ancient article from my short-lived Posterous blog, before they got bought out by Twitter and discontinued. Most of the information here is outdated, but I thought it'd be fun to publish for prosterity.

The Pi was super useful overall! At school I'd remote into it via PuTTY and do my computing classwork in the terminal. This spared me the pain of having to use the Turbo Pascal IDE in 2013 (yeah wtf). But probably the coolest thing I did was to run a small Pokémon Showdown server for my friends, modified to support random LC battles.

It was my 17th birthday recently and my grandma was kind enough to buy me a Raspberry Pi (256mb Model B), though she didn't know what the heck it was. Here's a little explanation on what I've done with it so far:

Initial Setup

I'm still relatively new to Linux/Unix, although I've had some experience with the terminal on my phone and iPod Touch, and running lightweight distros on VMs on my laptop, so I learned tons even in the first few steps. Having flashed Raspbian Wheezy onto my SD card with win32diskimager, I found a spare USB keyboard and mouse and connected the Pi to my TV with an RCA cable.

The startup guides had a lot of warnings about using at least 700mA power supplies - the specs on the side of my phone charger were confusing but it worked fine. I powered the Pi up and was welcomed by the raspi-config screen, where I set a password and resized the OS to fill the whole SD card. After that was done, I restarted the unit and was welcomed by the terminal. The startx command is used to initialize a desktop, although I haven't needed to use it much yet.

Remote Access

The latest Raspbian has SSH enabled by default, so this was pretty painless. I'm using PuTTY on my laptop, and my iPod Touch and Android phone both have SSH clients on them, so I can pretty much get onto the Pi from anywhere in my house. In order to remotely access the desktop, I installed tightvncserver with apt-get. Conveniently this starts up its own X desktop instance in the background, so I can start up tightvncserver over SSH, then connect with a VNC client. I've ordered a wireless dongle so hopefully I won't have this ethernet cable stretching across the house for much longer.

One of my main uses for the Pi is to run my Lua IRC bot on the bonuslevel chat, so I installed Lua and transferred the source via SFTP. The bot ran fine, but I had trouble launching it over SSH because it requires some initial input, but it must then run in the background even after the session has ended. The solution for this was to use a tool called dtach, which is perfectly suited for situations like this.

The command to create a new session and attach to it is

dtach -A <socket> <command...>

This confused me initially, as I thought that 'socket' was supposed to be a network socket, which was wrong. It is actually a Unix domain socket, which is a local means of communication between programs, bound to a temporary file which exists during the socket's lifetime. So, I can run

dtach -A bot_sock lua Main.lua

When I'm done responding to the bot's initial prompts, I can hit ctrl+\ to detach from the session. Now I have my Lua process running continuously in the background, and I can end the SSH session and go to France and have a McDonalds, while my IRC bot remains functional, running off a tiny board at home. Pretty cool.

The Great Unescape - Post Mortem

2011-08-27T00:00:00+01:00

Note

This was the first jam game I ever made, when I was 15 years old. Originally posted on the old Ludum Dare site, I'm putting it here for prosterity!

Looks like people are still writing post-mortems a week later, so here's mine!

Development

I woke up last Saturday and checked the theme on twitter. I didn't really expect the theme to be 'escape', but I had a think over breakfast and got a cool story idea, sort of inspired by an episode of an old TV show called Porridge. I started off with a dull blue wall tileset and made a prison cell in DAME.

Drawing tilesets in Graphics Gale.

Once the character graphics were done, I threw together a system which scans the DAME project file for game entities then places them on the map, since I didn't have time to get to grips with the complex export system in DAME. Eventually I had little Rick running and jumping around in his cell, and I spent the rest of the day composing in SunVox and using Tweener to arrange the introduction text and events.

I didn't actually start on the gameplay or levels until Sunday, when I decided to construct a small jungle full of spiders and spikes. It took most of the daytime to create the enemies, tiles, and music which left me with the evening to work out how to bring everything to a close. I stayed up right until the deadline designing the last area and finishing the game off, but I managed to squeeze in another tune, bringing me to a total of four songs!

Making the soundtrack in SunVox.

What Went Right

Considering this was my first time using DAME, creating the levels and making them work in Flixel was surprisingly painless.
I've practised a lot with SunVox, so I can churn out decent music fast!
I had a nice storyline idea and managed to keep it short without ruining it.
I've been practising with Flixel and FlashDevelop for quite a long time. Even though I hadn't released any Flixel games before this one, I was very comfortable with my choice of language and library.

What Could Have Gone Better

I missed a few details, for example there is no wall on the left side of the jungle, so you can fall off the screen and be stuck forever.
Quite a lot of people heard strange hiccups in the music playback. I have no idea what's causing this and I can't hear them myself, but I added a standalone download which should hopefully fix any audio problems.
I made a couple of bad design decisions, there are quite a lot of blind drops into enemies. I thought the levels were short enough not to need checkpoints, but it looks like I was wrong.

I'm really pleased with the amount I managed to get done in two days! If you're interested, check out the entry itself here.