kleemans.ch

Creating a GameBoy TAS

Mon, 05 Feb 2024 12:00:58 +0100

This post is part of the Game Boy series (#7).

In the world of speedrunning, a TAS is a Tool-assisted speedrun, meaning that it was not (only) done by human hand, but using some sort of tool.

This leads to a quite different challenge than speedrunning itself: Find the most optimal sequence of inputs for a game and then record a video of how those inputs are being executed. As the sequence of inputs can be written down and saved, they can be then fine-tuned, improved and optimized far beyond what a human player could be capable of.

BizHawk

Now for the GameBoy, one emulator that has great TAS support is BizHawk. It is very accurate per-frame (unfortunately not always in real-time, see emulator tests here) and allows for "programming" a sequence of inputs directly in the UI.

Let's look at a first example:

The game used here is Wordle for GameBoy. To the right, a sequence of inputs (Up, Down, Left, Right, A, B) are being scrolled down, and on the left the emulator executes those inputs on the emulator.

Starting a new TAS project

So let's get started with our TAS! We'll use the newest version of BizHawk for Windows, as it works best there. You can download it from the Github link above or from tasvideos.org, which, by the way, have a lot of TAS resources available.

After downloading and installing, we are greeted with an empty, black window. Next we need some kind of GameBoy ROM, a game. We'll use the freely available game "Gunman Clive" for GameBoy, you can download the ROM here.

After dragging the file into the BizHawk window, the game should load. Now we can open the TAStudio:

We now have a side-by-side view like in the first video above. We can now let the game start using the "Pause" button, and pause it again when the "Press Start" is visible.

That's the point we can add our first input: Click in the "S" column to simulate a "Start" press, and the game should start!

Tip: Sometimes you need more than a single-frame input, as manual inputs usually also last for at least 2-3 frames.

Learning to walk

Now that we're in the actual level, let's try and move forwards. To move on an actual GameBoy you'd press and hold Right, so we're going to add a lot of "R" inputs:

Tip: You can just click & hold and then drag down the column to add many inputs at once. The same works for undoing them.

Next up is an obstacle - let's jump over it! Jump is mapped with an "A" input and we'll have to time it somewhat to actually land on the crate and not before it.

Tip: If you click and hold in the leftmost, white column and then drag up or down, the emulator will follow and you can watch the game run in slow motion or go back and forth framewise, which is really helpful for "debugging" or optimizing a certain section of the game.

After putting some effort working on our TAS project, be sure to save it, which you can do via "File > Save As", and save it as a new .tasproj-File. This file contains all the inputs and other configuration and will let you continue were you left.

Tip: I would recommend to backup the .tasproj-File now and then (with creating a simple copy), to make sure you don't lose your progress. It happens now and then that BizHawk crashes or that you mess up with the project (for example with branches, which are a way to explore variants).

Advanced: Using RAM watch / RAM search

One technique which can be very helpful is digging into the GameBoy's internals, and observe certain values to better understand what is going on.

For example, in Gunman Clive, you can fire at most 3 bullets at once (using "B"). After that, nothing will happen if you press "B":

Now let's find out where this limit is stored. Let's close TAStudio for now (don't need it for this step) and open RAM search:

Now we see a list of all in-memory values, which the game will update, for example position of te player, movement speed, position of enemies etc.

Let's try to pin down the exact location of where the limit of 3 bullets is saved. Now this works as follows:

You start out with the full memory bank (here 8192 addresses), which you can observe at runtime. One or some of those addresses are related to what you're searching, so you'll have to search for the right ones.
You can either search for specific values (which is often very tricky, as we don't know how it is stored), or, which is often more successful, filter by how the value changes. For example, if we shoot bullets, we expect the value to decrease. If we do nothing, we expect the value to stay the same. This way, we can filter out all the RAM addresses which are not related to what we're searching.

If we have found an address which seems to match, we can observe it by adding it to the RAM Watch. It seems that address 1240 is related to what we're searching:

We can then for example set a value ourselves, or freeze it to see what happens:

Infinite bullets! It also seems to introduce a bug where bullets will reappear on the left side of the screen if they move out on the right.

Tip: Sometimes it's worth switching the word size to 2 or 4 byte, as we don't know how the game stores its values. If some addresses are found it's best play around and see what happens.

With 2-byte words, we can see what happens now when we freeze the address in RAM:

We now have the ability to stop time! :-)

The goal was to show here that it can be handy to know more about the internals of the game. We obviously can't manipulate the game RAM while making our TAS, but it can be really helpful to know exactly how much speed we have, what items give us the best power-up etc.

Result

You can see the finished (for now - maybe you'll find a more efficient way!) TAS here:

You can also download the .tasproj-File here: gunmanclive.zip

Bonus: Discovering glitches

Using TASes can also be very helpful in figuring out how a game works internally. For example, in Home Alone 2, there is a glitch which lets you change where the elevator goes, depending on when the Up button is pressed:

Thanks for reading and happy TASing!

Random pizza chooser

Mon, 01 Jan 2024 12:00:22 +0100

At our team day at work when everybody is around, we often go out for Pizza. Everybody has their few favourites, but recently I got somewhat bored and wanted to try a random pizza - but how to choose?

I decided to come up with a quick mobile page: Just tap the pizza and it will select a random pizza for you!

Direct link

The pizza menu data is from Restaurant Bahnhof.

Source: https://github.com/akleemans/random-pizza

Thanks for reading and Bon appétit!

Practice Terraform using Christmas trees

Mon, 18 Dec 2023 12:00:55 +0100

Terraform is a great tool to manage your infrastructure via plain text. It helps detecting what changed and how to bring the infrastructure to the state you want it to be in.

Now Terraform has all the important Cloud services like Azure, AWS etc. as "providers" (adapters) available, but there are also some more obscure ones, like Spotify or Dominos.

To fiddle around a bit with the concepts of Terraform, we'll use the Christmas tree provider!

Getting started with Terraform

At first we'll need a working Terraform installation. Hashicorp has a good installation guide for all the major platforms, I'm going to use Ubuntu here.

After installing the needed dependencies (like gnupg etc.), adding the HashiCorp GPG key and their Debian package repository, we're able to install terraform using

sudo apt install terraform

After this, we'll see that it was installed:

adrianus@adrianus-ThinkPad:~$ terraform -v
Terraform v1.5.7 on linux_amd64

Setting up the provider

With Terraform installed, we can get going and create a new file main.tf, where we can add the provider with its version. We could also configure options for our provider, but christmas-tree doesn't need any ({}).

terraform {
  required_providers {
    christmas-tree = {
      source = "cappyzawa/christmas-tree"
      version = "0.6.1"
    }
  }
}

provider "christmas-tree" {}

Now we can initialize Terraform:

$ terraform init

This will setup Terraform for our project, create a .terraform-folder and download the provider for us.

Creating a resource

Now let's create our first Christmas Tree. According to the Documentation, we can define a new "Christmas tree"-resource as follows:

resource "christmas-tree" "my-tree" {
  path        = "/tmp/tree"
  ball_color  = "red"
  star_color  = "yellow"
  light_color = "white"
}

We can now check what Terraform wants to do, based on this resource:

$ terraform plan
Terraform will perform the following actions:

  # christmas-tree.my-tree will be created
  + resource "christmas-tree" "my-tree" {
      + ball_color  = "red"
      + id          = (known after apply)
      + light_color = "white"
      + path        = "/tmp/tree"
      + star_color  = "yellow"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Nice! It recognizes a new resource and indicates that it wants to create it.

How Terraform works

When working with Terraform, 3 things are important:

The current reality - your actual (infrastructure) resources
Terraform's internal state - this is what Terraform thinks the current status of your resources is. It is maintained in the file terraform.tfstate.
The definition of what your resources should be, kept in main.tf. This is the file we created and which we're going to change.

Now when running terraform plan, Terraform will first check against what is actually there (1.), so it can then update its internal state (2.). After that, it will check what should be the new state (3.) against the current state (2.) and map out the differences (add, update, replace, delete). It will show these differences then as an output of plan.

After making a literal "plan" of what to do, we can accept if with terraform apply. This will apply all the recognized differences and the planned state (3.) will match both the internal state of Terraform (2.) and your actual resource state (1.)

If we run terraform plan again, but this time with -out tfplan, we can run apply after that to be sure that exactly the changes from before will be applied. This will look like follows:

$ terraform apply "tfplan"
christmas-tree.my-tree: Creating...
christmas-tree.my-tree: Creation complete after 0s [id=/tmp/tree]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Detecting & applying changes

What if we change something small, for example the ball_color? Running a terraform plan will result in an update:

christmas-tree.my-tree: Refreshing state... [id=/tmp/tree]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # christmas-tree.my-tree will be updated in-place
  ~ resource "christmas-tree" "my-tree" {
      ~ ball_color  = "red" -> "blue"
        id          = "/tmp/tree"
        # (3 unchanged attributes hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Breaking changes

If we want our Christmas tree at a different location, say /tmp/new-tree instead of /tmp/tree, this will be such a big change that Terraform will not be able to update our existing ressource - instead, it will do a replacement. This will be marked with +/- and will look like this:

$ terraform plan -out tfplan
christmas-tree.my-tree: Refreshing state... [id=/tmp/tree]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
-/+ destroy and then create replacement

Terraform will perform the following actions:

  # christmas-tree.my-tree must be replaced
-/+ resource "christmas-tree" "my-tree" {
      ~ id          = "/tmp/tree" -> (known after apply)
      ~ path        = "/tmp/tree" -> "/tmp/new-tree" # forces replacement
        # (3 unchanged attributes hidden)
    }

Plan: 1 to add, 0 to change, 1 to destroy.

Thanks for reading, happy terraforming and merry Christmas!

How to host an Angular App for free on Github

Mon, 04 Dec 2023 12:00:09 +0100

I work a lot with Angular - at work and also at home, for private projects. Often I find myself in the situation where I want to share a simple Angular app, and have it available publicly.

Github offers an amazing free service, Github pages, which lets you serve static content. As a compiled Angular App is also just a bunch of static JavaScript and CSS files, here's how to set up a project to As an example, I'll use the [gb-manual-search](TODO link) which [I've written last time about](TODO blogpost link).

Setting up angular.json

In the angular.json build options, we'll have to update two things:

Github pages has a fixed folder it relies on, the docs folder, so we can set that here as our build output.
The page will be available under a subpath of github.io, for example https://akleemans.github.io/gb-manual-search/. To make Angular work with that (and not being in the root path), you'll have to add the /<name-of-your-repository>/ as baseHref.

After changing that, the angular.json should look like this:

Building the App

With the angular.json properly configured, we can trigger npm build to get our application built. After that, our docs-folder should look like this:

Make sure add it to the tracked git files and commit them to the repository.

Activate Github pages

Now, for activating Github Pages, go to the Settings of your repository and enable it here:

You could also choose another branch besides main, if you want to keep the published site on a specific branch (so you can push to that branch specifically if you want more control when to "release"). For simplicity's sake I mostly just use main.

When activated, it will auto-deploy everything that is in docs to a web page.

Accessing the page

After configuring everything, you should see a Github Pages "deployment" (under "Actions") with a green checkmark:

You can now access your page, for example https://akleemans.github.io/gb-manual-search/! 🎉

Thanks for reading and happy publishing!

Making GameBoy manuals searchable via OCR

Mon, 06 Nov 2023 12:00:06 +0100

This post is part of the Game Boy series (#6).

TLDR: I created a searchable index of scanned PDF Game Boy manuals: akleemans.github.io/gb-manual-search.

There has been an ongoing effort to preserve and collect GameBoy manuals, and many (although not all) are available today, mostly as PDF.

What I was missing though was to do a text search in them - search for a term across all manuals and then find manual and the passages where they occur.

Using OCR on a collection of manual PDFs

From multiple source like Kirkland's, archive.org dumps or gamesdatabase.org, I found the most complete to be sprintinglegs' GameBoy manual list, so that's the one I used.

Once having all the manuals as PDFs, I decided to use Python to extract the text content. In a first step, the images are extracted page by page using pdf2image, and then subsequently scanned with OCR using pytesseract.

The content is then saved as JSON (for easy processing in a web app). Here is the code:

import glob
import json
import pdf2image
import pytesseract

def get_text(pdf_file):
    text = ''
    images = pdf2image.convert_from_path(pdf_file)
    for pg, img in enumerate(images):
        print(f'Working on page {pg}')
        text += pytesseract.image_to_string(img)
    return text

ocr_text = {}
files = glob.glob("manuals/*.pdf")
print(f'Found {len(files)} files.')
for file_name in files:
    print(f'Scanning {file_name}...')
    text = get_text(file_name)
    ocr_text[file_name] = text

with open('text-output.json', 'w') as write_file:
    write_file.write(json.dumps(ocr_text, indent=4))

Creating a simple Angular App

After having all the text content ready, I created a small Angular app to search through the text and show a list of occurences, grouped by the manual. The search term is "highlighted" with brackets ([ ]) and some context around the occurence (50 characters before and after) is also shown.

The list is sorted by the amount of occurences, so manuals with more occurences will appear higher:

You can try it here yourself!

Source code: https://github.com/akleemans/gb-manual-search

Thanks for reading and happy searching!