Welcome to this adventure, where I write about the process of our latest game, Devils on the Moon pinball.

This is a story of how we lost almost two full weeks of work while chasing a crash that only happened on the Playdate device randomly after some time of playing.

It all started with a normal build to device that crashed; the weird part was that the game only crashed when putting the device to sleep.

I went to that part of the code and found nothing, literally nothing. I wasn't doing anything at all during that callback.

Ok, don't panic. Let's see what the crashlog.txt says. If you don't know what this file is, consider yourself lucky. But it's where the Playdate logs hard crash information, and it looks like this.

--- crash at 2025/12/10 20:35:08---
build:e44193e8-3.0.1-release.194549-gitlab-runner
   r0:00008001    r1:20009b90     r2:38800088    r3: 00000000
  r12:2000f8d1    lr:24021457     pc:24021456   psr: 410f0000
 cfsr:00010000  hfsr:40000000  mmfar:00000000  bfar: 00000000
rcccsr:00000000
heap allocated: 15233952
Lua totalbytes=0 GCdebt=0 GCestimate=0 stacksize=0

The first time I looked at this, I just closed the file and started putting logs everywhere. But this time I knew that wasn't going to work. So, understanding the crash report it is.

The Symbolizer

The first step to understand the crash is to run the firmware_symbolizer.py script provided by the SDK. This tool tries to tell you where the crash happened.

python $(PLAYDATE_SDK)/bin/firmware_symbolizer.py ./crashlog.txt build/playdate/pdex.elf

?? ??:0
?? ??:0

Well, that is not helpful, but this will happen a lot of times; the bad crashes tend to crash so badly that the symbolizer is unable to tell where the crash happened.

There are some things that have helped me, though. One is that I use a modified version of the symbolizer that prints the actual command used to get the line of code.

import re
import subprocess
import click

@click.command()
@click.argument("crashlog", type=click.Path(exists=True))
@click.argument("elf", type=click.Path(exists=True))
def symbolize(crashlog, elf):
    cl_contents = open(crashlog, "r").read()
    cl_blocks = re.split(r"\n\n", cl_contents)

    for block in cl_blocks:
        matches = re.search(r"lr:([0-9a-f]{8})\s+pc:([0-9a-f]{8})", block)

        if matches:
            lr = matches.group(1)
            pc = matches.group(2)
            lr_num = int(lr, 16)
            pc_num = int(pc, 16)
            lr_num = lr_num & 0x0FFFFFFF
            pc_num = pc_num & 0x0FFFFFFF
            print("lr: {} -> {}".format(hex(int(lr, 16)), lr_num))
            lr = hex(lr_num)
            pc = hex(pc_num)
            cmd = f"arm-none-eabi-addr2line -f -i -p -e {elf} {pc} {lr}"
            print(cmd)
            stack = subprocess.check_output(cmd, shell=True).decode("ASCII")
            print(stack)

if __name__ == "__main__":
    symbolize()

What the symbolizer is doing is calling the command arm-none-eabi-addr2line and passing the address that caused the crash. Your code lives in RAM memory, the same as your runtime allocations, and it's stored in a memory address. The PC and LR registers store the memory address where the function that caused the crash is stored. The only problem is that the address is not mapped one to one to your elf file because the Playdate stores it on a different offset depending on if it's a Rev A or Rev B Playdate. So the symbolizer also converts the memory you get from the crashlog.txt to the correct one on the elf file

lr: 0x24021457 -> 67245143
arm-none-eabi-addr2line -f -i -p -e ./build/playdate/pdex.elf 0x4021456 0x4021457
?? ??:0
?? ??:0

Still, not really helpful. Another tool I have used is the playdate-symbolize crate made in Rust that tends to give more human-readable errors, but sadly in this case it was the same result.

I have found that the really nasty bugs tend to crash on a random function that is not in a helpful region of memory. This can be because the function is a Playdate function and we don't have the map for that, or the address is completely wrong because the stack got corrupted. There are some people at the Playdate Discord that can tell what kind of function made the crash just by looking at the address (shout out to Scratchminer), but every time I see the ?? ??:0 I know I'm in trouble.

Memory suspects

One thing that may help right out of the bat is the heap allocated field; this might be relevant, especially for LUA-based projects, as if it's a high number, it probably means you have a memory leak and the device ran out of memory.

Out of memory

Well, here we have 15232096 that number represents the amount of memory your game has allocated in bytes. If we convert it to megabytes, we have 15.2MB. Well, the Playdate has 16MB of RAM, so that would be a pretty close call. In our case, though, what I'm doing is reserving as much memory as possible at the beginning of the game (15.2MB) and then using that memory through my own custom memory allocator. A simple memory arena. So I knew this was the cause of the crash here. If you are having memory leaks, though, a really useful tool is the device info window in the Playdate SDK.

As you can see here, the memory stays the same the whole time. Once you are using your own memory allocator, you can do a lot of cool stuff, like setting a custom limit and letting you know on a simulator build if you are getting past it. You can also use the malloc pool feature on the simulator and limit the 16MB memory your game has available.

Memory initialization

So it wasn't a memory leak. Another thing that may cause something to crash on a device and not in the simulator is that if you are using a low-level language like C, the memory can have trash values when you get it, causing a bunch of issues if you are not careful initializing things.

It happened to me a bunch of times that on the simulator build of the game, all the memory I got from the OS was zeroed out, but when I tried it on the device, it would crash because some trash value I assumed would be 0. I'm not sure, but I think the memory you get is actually just the memory from the previous process that was running, and if you just relaunched your game from a crash a lot of times, this is your own game. So what would happen to me is that the game would crash when starting from the launcher but wouldn't when starting using the pdc tool.

To fix this, there are a couple of things you can do. One is to make sure to clear out any memory that you get from the OS. This way at least you know that you are starting at the same state as in your desktop computer. For this, there are a couple of simple yet useful macros I like.

#define mclr(dst, size) memset((dst), (0), (size))
#define mclr_struct(s)  mclr((s), sizeof(*(s)))
#define mclr_array(a)   mclr((a), sizeof(a))

This is useful by itself, but combined with other macros, you can make sure to always have cleared memory.

#define alloc_struct(alloc, ptr)     (__typeof__(ptr))alloc_size(alloc, sizeof(*(ptr)), false)
#define alloc_struct_clr(alloc, ptr) (__typeof__(ptr))alloc_size(alloc, sizeof(*(ptr)), true)

void *
alloc_size(struct alloc alloc, ssize mem_size, b32 clr)
{
	void *mem = alloc.allocf(alloc.ctx, mem_size);
	if(clr) { mclr(mem, mem_size); };
	return mem;
}
...
struct game *game = alloc_struct_clr(alloc, game);

The problem is that clearing memory is fast but is not free; it takes some cycles to do it, so you don't want to do it everywhere. Well, another thing you can do is to poison your memory on the simulator.

#define MEM_POISON_PATTERN 0xCD
#if defined(DEBUG)
memset(mem->buffer, MEM_POISON_PATTERN, mem->size);
#endif

I think this is done by default on Visual Studio on debug builds.

This way you would lose performance on your debug build, but that's preferable to losing it on the release version. This pattern has helped me tremendously and removed one common cause of bugs in my code.

So I was sure it wasn't a memory uninitialized problem this time around.

Crash registers

Back to trying to understand the crashlog.txt

--- crash at 2025/12/10 20:35:08---
build:e44193e8-3.0.1-release.194549-gitlab-runner
 r0:00008001    r1:20009b90     r2:38800088    r3: 00000000
r12:2000f8d1    lr:24021457     pc:24021456   psr: 410f0000
cfsr:00010000  hfsr:40000000  mmfar:00000000  bfar: 00000000
rcccsr:00000000
heap allocated: 15233952
Lua totalbytes=0 GCdebt=0 GCestimate=0 stacksize=0

Thankfully there is excellent, albeit technical, documentation about this How to debug a HardFault on an ARM Cortex-M MCU.

One source of documentation that sometimes is useful is to search for FreeRTOS, like this article, as this is the operating system the Playdate is using.

The first thing I noticed is that the cfsr has a value set because it's not all zeros. So how it works is that the cfsr or Configurable Fault Status Registers stores information about the crash, turning on bits in a 32-bit register.

The numbers in the crashlog.txt are 32-bit hexadecimal numbers, so to know what register was turned on, we have to convert it to binary. Our value here of 00010000 converts to:

0000 0000 0000 0001 0000 0000 0000 0000

Thanks to this image, we know that the last 16 bits correspond to the UFSR as they are the only bits with a value. Let's focus on that.

UFSR stands for Usage Fault Status Register, so we know the crash was not caused by something related to memory access.

Now, thanks to this image, we know that the second bit means there was a UNDEFINSTR

0000 0000 0000 0001

From the article, this means that an undefined instruction was executed; this can happen if the stack got corrupted.

Reproduce

At this point I will be honest with you: I wasn't thinking completely straight and became paranoid. The fact that the game would only crash after some random time and then lock the screen made no sense to me.

Thankfully, JP is the best QA tester I have ever met and was able to find that the issue only happened after interacting with a specific entity in the game; we call him the Nalgón, which translates to Big butt guy in English.

He used to mockingly show his butt and is one of our favorite characters.

Even though we removed the version of him where he showed his butt. I started to feel like he was mocking me again… now with a bug.

Now that we had an easy way to reproduce the bug, go to the Nalgón bump it with the ball and lock the screen. I started commenting code to see if the crash kept happening. The process was painful:

1. Build the game
2. Launch the simulator
3. Press CTRL+U to send the game to the device
4. Wait for 3-5 minutes while the game get's copied
5. Enable the developer cursor
6. Bump the Nalgón

All in all, it took around 10 minutes to test each build, which quickly helped with my paranoia.

I wrote a small script to automate most of the tasks. I had built something similar years ago when working with Pullfrog when the Linux simulator didn't have the Send to Device command.

#!/bin/bash
set -euo pipefail

DESTDIR="build/"
GAME_NAME="devils-on-the-moon-pinball-dev"
PD_DEV="/dev/ttyACM0"
PD_MOUNT="/your/mount/folder"
SRC_DIR="${DESTDIR}playdate/${GAME_NAME}.pdx"
DST_DIR="${PD_MOUNT}/Games/${GAME_NAME}.pdx"


if [[ -e "$PD_DEV" ]]; then
  if [[ ! -d "$PD_MOUNT" ]]; then
    if ! pdutil "$PD_DEV" datadisk; then
      echo "Failed to enter Data Disk Mode." >&2
      exit 1
    fi

    for i in {1..20}; do
      if [[ -d "$PD_MOUNT" ]]; then
        break
      fi
      sleep 0.5
    done
  fi
elif [[ -d "$PD_MOUNT" ]]; then

else
  echo "Playdate not connected." >&2
  exit 1
fi

if [[ ! -d "$PD_MOUNT" ]]; then
  echo "Playdate mount did not appear." >&2
  exit 1
fi

rsync -azrt --update --modify-window=1 --prune-empty-dirs --delete \
  --info=name0 --info=progress2 \
  "${SRC_DIR}/" "${DST_DIR}/"

udiskie-umount --eject /dev/sde1
sleep 2.0
pdutil "$PD_DEV" run "Games/${GAME_NAME}.pdx";

This reduces the effort of testing the build on the device by a lot. It only works on Linux, and you will need to change variables to make it work in your setup. If you want a similar script for Mac, Nino has this great script.

Well, one thing that this particular interaction does is to trigger the gate open/close mechanic on the ramp. For the close to work as we wanted, we needed to split the gate into 3 different entities, each with their own collision, events, and actions. I removed some event system code, and the game stopped crashing when I locked the Playdate but kept crashing after bumping a lot of times with the Nalgón.

At this point I made the mistake of stopping checking the crashlog.txt and assuming I knew what was happening; again, I was paranoid. So my theory was that I probably did something bad and used a bad pointer somewhere that was pointing to a random memory address and slowly corrupting the stack.

Sanitize

If you are programming in C, there are a couple of tools that can help you catch a footgun at compile and runtime.

First, I had already turned on a bunch of warnings. These are my normal compiler flags.

WARN_FLAGS += -Werror -Wall -Wextra -pedantic-errors
WARN_FLAGS += -Wstrict-prototypes
WARN_FLAGS += -Wshadow
WARN_FLAGS += -Wundef
WARN_FLAGS += -Wdouble-promotion
WARN_FLAGS += -Wno-unused-function
WARN_FLAGS += -Wno-unused-but-set-variable
WARN_FLAGS += -Wno-unused-variable
WARN_FLAGS += -Wno-unused-parameter

Some of them come from this great post. I like this because I was quite inexperienced with C, at least when I started working on this game 2 years ago. But this helps you catch bugs at compile time. The worst bugs, though, are at runtime: use after free, double free, etc. For that, sanitizers are great! Since almost the beginning, I have been using the following:

DEBUG_CFLAGS += -fsanitize-trap -fsanitize=address

fsanitize-trap Make it so when I'm asserting something with this macro, the debugger stops right at the line where the assert failed.

#define dbg_assert(c) if(!(c)) __builtin_trap()

And the address sanitizer inserts some poison memory to detect memory leaks and out-of-bounds access.

I use them all the time and have caught a lot of bugs using them. I highly recommend enabling them if you can.

Another common sanitizer is the -fsanitize=undefined I didn't have it enabled because I didn't really understand what was undefined behavior and what wasn't, and in some code that worked perfectly fine on both platforms, it triggered the sanitizer. But now, full of paranoia, I thought, surely I'm doing a scary, undefined behavior that is corrupting my memory.

So I enabled the sanitizer and slowly read about the undefined behaviors I was doing fixed all of them. Ran my script to build the game, and… It was still crashing.

Out of options

I will save you the next couple of days, but I did refactor everywhere I suspected something could have gone wrong. Five days later I was still getting the crash. At this point I had stopped paying attention to the crash message, as I had marked it as useless long ago. But JP told me after another test, “Still getting the same message, Stack Overflow, on the game task.” I froze. How could I miss this?

The Playdate has a small stack of 10Kb, my struct event_context struct is 88 bytes, and my struct action is 168 bytes. This means that I can pass around on the stack around 110 actions on my event process function, and this is without counting all the local variables, etc. So looking back at what the Nalgón does, it fires up like 10+ events and actions every time the ball bumps it.

This shouldn't be a big issue, especially if you are processing the events one by one in a queue. Our problem was that any event could trigger a new event, and instead of adding it to a queue, I kept running the actions and triggering more events until eventually I blew the stack.

Once I knew this, the solution was easy: make sure every time there is an event, instead of running the side effects right away, add it to a queue, and at the end of the frame process, enter a while loop where I'm processing the events until there are no more events to process.

while(q->count > 0) {
	struct event *event = &q->items[q->head];
	event_process(event_ctx, event);
	q->head = (q->head + 1) % q->cap;
	q->count--;
}

After implementing this new system, the issue was completely fixed!.

Well, I hope this story will help someone.

Extra notes

One common crash that I didn't cover here is the 10-second watchdog crash. This is a common thing to happen, and it's triggered if one of your frames took more than 10 seconds to give back control to the OS. The most common way it happens is while booting the game and loading all the assets, as this gets progressively slower the more full the Playdate hard drive is. So a good rule of thumb is that if your game is taking more than 5 seconds to load, you should start implementing some kind of loading screen. Squid God has an excellent video on the subject.

Welcome to this adventure, where I write about the process of our latest game, Devils on the Moon pinball.

We are ramping up to the final stages of the game, so I had to cross off one of our long standing pending features: The Pinball spinner

From the beginning of development, when the idea to make a pinball game started, we were excited about the spinner. Jp had to figure out a way to use Blender to generate rotated sprites that looked good (hopefully one day he will have enough time to talk about it here). And we played the physical table of Pulp Fiction, and we fell in love with its spinner.

So Jp started working and soon enough had a good spinner sprite for me to implement in to the game.

Now we just needed a way to make it spin. The first step I needed was to detect if the ball was colliding with the spinner in some way. This was the first time we needed to know if the ball was inside a collision shape but didn't affect it as a physics body. So I implemented the sensor system.

The Sensors

Each sensor component has two buffers with a list of entity handles. Each frame it queries entities inside its collision shape using the spacial hashing and then compares the new list with the previous list of entities.

If there is an entity that is not on the previous frame list, it sends the event body_entered. If an entity is missing from the previous frame, it sends the event body_exited.

As we only have one ball, at least for the main table, we are probably not going to have multi-ball. The check is really simple; I just go through both arrays and compare them one to one.

Another problem was, how do we decide which sensors should update each frame? We have over 70 sensors in the main table, some of them with complex polygon collision shapes. So I decided to use the ball to tell which one to update. I query a circle at the position of each of the balls that's 4 times the radius of the ball and mark all the overlapping sensors as dirty. Then we go through all the dirty sensors and update them.

Back to the spinner

Having the sensors set up, the spinner logic became easy. If there is a ball inside the spinner sensor, the spinner angular velocity is equal to the ball velocity. And when it exits, I just apply a damping factor so the spinner would eventually stop.

Each 0.5f turn we count it as a spin, so we compared the previous angle to the new one, and if it changed enough, we notified a spin.

b32 did_spin = false;

if(spinner->handle.id != 0) {
	entity *ball = pinball_get(pinball, spinner->handle);
	spinner->vel = v2_len_sq(ball->body.vel);
}

f32 vel = spinner->vel;
f32 t   = spinner->t + (vel * dt);
i32 t_a = floor_f32(spinner->t * 2.0);
i32 t_b = floor_f32(t * 2.0);

if(t_a != t_b) {
	did_spin = true;
	spinner->spins++;
}

spinner->vel = vel * spinner->damp;
spinner->t   = t;

return did_spin;

The only problem with this is that the spinner would stop at some awkward rotation and stay like that until the ball entered again. That's not how pinball spinners work! They have a weight at the tips to make sure it always ends up perpendicular to the table. It worked but didn't feel as good.

This is how the spinner in Catchadiablos works, by the way.

Springs

The first time I was reading about using springs for animation was from this great article by Josh W. Comeau. The article is full of interactive examples that helped the concept click. Since then I have used it sparingly for some little animations on our games. Another great resource is this video on a small script for Godot that helps you animate almost anything using springs.

When I started thinking about our spinner problem, I thought I would need to simulate some kind of pendulum using physics and that my cheap trick of just using the ball velocity was going away. And that's why I put if off for a long time, until I got this article on my RSS feed on springs and all their utilities. It's great! I greatly recommend it.

So I started thinking these springs surely look like the motion a pinball spinner.

I didn't have to change that much; just make sure to record the starting direction of the spinner as it will bounce back and forth until it gets to its resting angle.

Calculate the target turn and apply a spring force to get there.

And stop registering spins after the spinner changes direction for the first time.

b32 spinned    = false;
f32 angle_prev = spinner->angle_turns;

if(spinner->entity_handle.id != 0) {
	entity *ball     = pinball_get(pinball, spinner->entity_handle);
	spinner->direction      = sgn_f32(ball->body.vel.y);
	spinner->angular_vel    = v2_len_sq(ball->body.vel);
	spinner->register_spins = true;
}

f32 angle            = spinner->angle_turns;
f32 angular_vel      = spinner->angular_vel;
spinner->angle_turns = angle + (angular_vel * dt);

f32 k                = spinner->stiffness;
f32 c                = spinner->damping;
f32 target           = round_f32(spinner->angle_turns * 2.0f) * 0.5f;
f32 accel            = -k * (spinner->angle_turns - target) - c * spinner->angular_vel;
spinner->angular_vel = spinner->angular_vel + accel * dt;

f32 prev_half = floor_f32(angle_prev * 2.0f);
f32 curr_half = floor_f32(spinner->angle_turns * 2.0f);

if(curr_half != prev_half && spinner->register_spins) {
	f32 delta = spinner->angle_turns - angle_prev;
	if(sgn_f32(delta) == spinner->direction) {
		spinned = true;
		spinner->spins++;
	} else {
		spinner->register_spins = false;
	}
}

return spinned;

And now it looks great! So yeah, springs, I just think they are neat.

Welcome to this adventure, where I write about the process of our latest game, Devils on the Moon pinball.

The main way we handle logic in our game is using a system of events and actions. Some stats that probably will change a little by the end of development.

• 48 types of events.
• 78 types of actions.
• 575 registered entity actions using the Tiled editor.

How it works

Whenever something happens to an entity we call the function event_sys_notity, for example if we want to play an animation:

void
animation_sys_play(struct event_ctx event_ctx, struct entity_handle entity_handle, i32 ani_index)
{
	f32 timestamp           = event_ctx.frame.timestamp;
	struct entity_sys *entity_sys = event_ctx.entity_sys;
	struct entity *entity   = entity_get(entity_sys, entity_handle);
	struct props args = {
		.props = {
			{
				.type = PROP_I32,
				.i32  = ani_index
			}
		}
	};
	event_sys_notify(
		event_ctx,
		entity_handle,
		EVENT_ANIMATION_STARTED,
		args);
	animator_animation_play(&entity->animator, ani_index, timestamp);
}

The event context is a struct that allows us to pass around instances of other systems that are not part of the main game entity system.

For example, if an entity needs to do it's action later in the game, it starts a timer, to do so, it needs a reference to the timer system. But timers are smaller than our general game entities and have different logic for spawning/updating etc. So the event context has a reference to the timers system.

This allows us to keep the signature of the function small and if we need to add more data that the event system needs we don't need to update each call to the event_sys_notify, but just were we start passing around the context object.

Notify

The event_sys_notify functions is called with the entity_handle that triggered the event, you could say that each entity is an observer of it's own events.

Queue the event

We also save the event in an event queue that it's used at the end of the frame to handle events at a game level instead of a entity level. For example if the multiplier changed, we update the GUI, or spawn a special VFX.

Run components actions

After that, we check the components that the entity that triggered the event has, and depending on that we do some pre-defined actions.

For example if the entity that triggered the event body collided has one of the reactive components we can play an animation or offset the sprite for a few seconds or apply an impulse to the entity that collided with it.

This is how the slingshots and bumpers work!

Validate on event actions

Each entity can have a list of event actions.

Sadly Tiled always organizes properties alphabetically.

After doing all the component pre-defined actions we go through the list of entity actions and check if the action-event matches. If it does, some events pass as props information about that event itself, so if the event condition type is set we check the condition and if it passes, we run the action.

Events can pass 3 props to give context on what happened, but we only use the first one to check for action conditions.

So for example the a animation_finished event would pass the animation index that finished on the first prop.

And the body_entered event would pass the angle at which the body entered as it's first prop, and in the second prop the entity handle that entered.

switch(b.type) {
	case PROP_I32: {
		switch(condition.type) {
		case CONDITION_EQ: {
			return a.i32 == b.i32;
		} break;
		case CONDITION_NEQ: {
			return a.i32 != b.i32;
		} break;
		case CONDITION_GT: {
			return a.i32 > b.i32;
		} break;
		case CONDITION_LT: {
			return a.i32 < b.i32;
		} break;
		case CONDITION_GTE: {
			return a.i32 >= b.i32;
		} break;
		case CONDITION_LTE: {
			return a.i32 <= b.i32;
		} break;
		default: {
			dbg_sentinel("Invalid prop type");
		};
		}
	} break;
	...
}

Each action can have a single argument. The most basic example and probably the most used one is the play_animation action, the argument is used as the index of the animation that should be played.

I thought eventually we would need to add more conditions or arguments to the editor but we are almost done and it hasn't been necessary.

The action cool-down functions as a throttle, each time the action is called we save the timestamp of when it was called and if it's called again we ignore it if the cool-down hasn't passed.

This really helps for collision actions, as we use a sequential impulses physics engine so the same colliding pair can happen along multiple frames. So if we want to play an SFX when a collision happens we can make sure it doesn't play again until the SFX finishes by setting a cool-down of the duration of the SFX.

The action delay was something that took me a while to figure out but we use it all over the place once we had it. Whenever a function is triggered if it has an action delay it starts a new timer that copies all the data from the action and the event, then the timer's systems checks if the timer has finished and triggers the action. Each action has a timer handle so that if it's triggered again before the timer fires up, it cancels the previous timer and starts a new one.

We might need to add some way to change the behavior to not always restart the timer but we haven't had the need yet.

The action ref tells which entity should do the action, if the ref is empty, we do the action on the entity that triggered the event. This let's us copy/paste actions between entities really easily.

The action type I guess it's self-explanatory.

The debug checkbox has been super useful, when on it logs the event and entity that caused the action, and the action data. I want to change this field to a generic flags field so that I can add another boolean disable to comment out actions quickly from the editor.

Custom handler

Finally any entity can have a custom on_event function pointer that it's not null it gets called and passed all the information. We use this for entities with custom logic that would be to hard to do in the editor.

void (*on_event)(struct event_ctx event_ctx, struct entity_handle entity_handle, enum pinball_event_type type, struct pinball_props args);

Lessons learned

I really like this system, I'm surprised how much we have managed to do with it! For example the pinball game in Catchadiablos has no custom logic and works with only events and actions. I do think sometimes we have abused it and it can get really hard to debug issues when there are a lot of chaining events.

The best part about this system is that it allows JP to prototype ideas really quickly. I would say 90% of the game logic is handled this way and every time we would add a new event or action to do one specific idea, it made it easier to do other parts of the game. It also makes it easier to build re-usable blocks of logic and apply them to multiple entities.

The bad part is that Tiled was not mean to be used like this. If we ever need to do another game with this amount of logic in the editor I think it makes sense to invest some time on doing a custom editor that allow us to tailor it more to our needs.

The biggest benefit of a good editor is being able to iterate fast, but if you are to afraid to change something because it may break something else you kill the creative process.

At the end of the day event if it's not textual coding, having logic in a visual way is still coding and you need a way to debug/validate/inspect that logic at edit/run time. And if you are doing it in a custom way eventually you will need to build the tools to help you do that.

In our frustration dealing with big lists of events defined in Tiled with no way to change the way it's displayed, we spent a week doing a small prototype of a platforming game using our own engine as the level editor.

It turned out great! and definitely will try to build the editor inside the game for our next project.

Welcome to this adventure, where I write about the process of our latest game, Devils on the Moon pinball.

Kind of a silly thing that made me really happy yesterday

Before we continue this post has spoilers for our game Catchadiablos.

A long time ago I remember there was a thread on twitter talking about lives UI in games and how it tends to be ambiguous.

When you have some sort of HUD that has a filled and unfilled icon for how many tries you have left and you lose, do you expect to have another chance?

The problem is, how do you set the right expectation? And if it's ambiguous, should you resolve the tension at the resolution with an upward beat or a downward beat?

When we started building the HUD for Devils on the Moon pinball, we talked about this. We knew we wanted to give the players 3 balls to play with. How do we show that in the UI?

Option A

We show the three balls filled in the UI, and then when you lose one, we remove it? But wouldn't that give you the expectation that you had 3 more balls apart from the one that you had at the beginning?

Later on, when the ambiguity is resolved and you lose the last game, the game ends. If you had the expectation that you still had an extra ball, that's a big downward beat.

Option B

We show only two balls, as that's the chance you have left? But then we never show the UI with three balls; the UI has the space to show you three balls filled, but we never do! It felt wrong somehow.

Again, kind of silly.

After like a day of debate, we ended up with option B, it's better to not risk disappointing the player. That's how we show it in the Catchadiablos pinball

Yesterday, though, we were working on the ball spawning polish, adding animations, making sure timings were right, etc. It sounds simple, but we had to change a lot of things, as before we weren't destroying the entity and spawning it again; we just used the same ball entity and just reset its position.

At the end, when we were tweaking the timings, we had an idea: what if we show the 3 balls filled in the UI, and with the spawning animation, we remove the ball from the HUD, signaling that you just spent one ball of the 3 balls that you have available? Best of both worlds!

Kind of silly, but really happy with how it turned out.

I don't know what awaits us in our next adventure, but see you there when it happens.

Welcome to this adventure, where I write about the process of our latest game, Devils on the Moon pinball.

I know I said the next post was going to be about the physics debugger, but I'm getting closer to finishing up a big refactor that had been on my TODO list for a long time. And I wanted to talk about it.

We are moving from an entity type/archetype to component-based behaviors.

Before

I had this structure for the game objects/entities of the game:

struct entity {
	enum entity_type type;
	u32 components;
	struct transform transform;
	struct rigid_body body;
	struct sensor sensor;
	struct sprite sprite;
	struct animator animator;
	...
};

This was mirrored in the Level editor (Tiled), where I would build custom types that had the components needed for that entity type.

Then I would iterate over the entities, check which type they were, and perform some logic depending on the type.

Inside the function, I would assert that the entity had the components needed for that type to work, so something like:

// game.h
void game_upd(struct entity *entities, size count, f32 dt){
	for(size i = 0; i < count; ++i){
		struct entity *entity = entities[i];
		switch(entity->type):
			case ENTITY_FLIPPER:
				flipper_upd(entity, dt);
	}
}

// flipper.h

void flipper_init(struct entity *entity);

void flipper_upd(struct entity *entity, f32 dt) {
	assert(entity->components & COMPONENT_SPRITE);
	assert(entity->components & COMPONENT_RIGID_BODY);
	assert(entity->components & COMPONENT_TRANSFORM);
	struct sprite *sprite = &entity->sprite;
	// Update sprite
}

void flipper_drw(struct entity *entity);

This worked well for a while, but quickly I stopped updating every entity every frame, because some things didn’t need to be updated unless they were on the screen or near a ball.

So I started caching the types of entities in the world and updating entities more based on their type, instead of going through the whole list every frame.

void flipper_sys_upd(struct world *world, f32 dt){
	struct entity *entities = world_query_entity_type(world, ENTITY_FLIPPER);
	for(size i = 0; i < arr_len(entities); ++i){
		flipper_upd(entities[i], dt);
	}
}

The more I did this, the more I realized a lot of the logic was at the component level, not really at the entity type level. So I started moving all the common logic for updating components to their own systems.

I used the same idea of making a DB of all the entities that had a specific component and using that for caching.

void sprite_sys_upd(struct world *world, f32 dt){
	struct entity *entities = world_query_component_type(world, COMPONENT_SPRITE);
	for(size i = 0; i < arr_len(entities); ++i){
		sprite_upd(&entities[i]->sprite, dt);
	}
}

The more I migrated the entity logic to the components, the more flexible the game code and level editor became.

I even created a new entity type called Generic Entity that we started using more and more. It would be a blank entity in Tiled by default, and then we could add components to it one by one.

At some point, I realized we could just get rid of the entity_type variable altogether. I was a little hesitant to change things, because we had a lot of entities already placed in the map, and migrating and checking them one by one seemed like a lot of work.

But then we stopped working on the game for 6 months to work on Catchadiablos (You can Pre-order it now!). When we came back, we had both forgotten 60% of the game’s systems and functionalities. So it seemed like a good time to refactor this architectural design, and re-visit all the game functionality.

Now

It worked! It forced us to go through each entity, check what it was supposed to do, and ensure that after the refactor, it still behaved as intended.

If an entity needed a new behavior, I could create a new component and add it as a property to the Tiled entity without having to modify every entity of the same type.

This also allowed us to have optional components that wouldn’t clutter the Tiled inspector, if an entity didn’t need them, we simply wouldn’t add them.

And if I need to implement logic for a specific type of entity archetype that requires a group of components to work properly, I can just create a new component and add it to any entity. Even if it's just a bool, its main purpose is to allow me to query for that component specifically and update the entity accordingly.

void flipper_upd(struct entity *entity, f32 dt) {
	assert(entity->components & COMPONENT_SPRITE);
	assert(entity->components & COMPONENT_RIGID_BODY);
	assert(entity->components & COMPONENT_TRANSFORM);
	assert(entity->components & COMPONENT_FLIPPER);
	struct flipper *flipper = &entity->flipper;

	// Do specific flipper logic
}

void flipper_sys_upd(struct world *world, f32 dt){
	struct entity *entities = world_query_component_type(world, COMPONENT_FLIPPER);
	for(size i = 0; i < arr_len(entities); ++i){
		flipper_upd(entities[i], dt);
	}
}

This way I keep the ability to have specific archetypes of entities but with the added flexibility for the more generic ones.

And this is how it currently looks in Tiled: we can reorder, rename, or remove any of the components and the game will keep working.

It doesn't look like much, but it helped us clean up the Tiled properties a lot. To convert from one type of entity to another, you just need to add or remove a component, instead of changing the entity type. Before, we needed to create a new entity type for each combination of components. Whereas now, we can remove and add components freely.

Another benefit is that now I can store the entity data in a more Data-Oriented way. So instead of having everything stored in the entity struct, we can have an array of components.

struct entity {
	u32 id;
	u32 components;
};

...

struct world {
	struct entity entities[100];
	struct sprite sprites[100];
};

void sprite_sys_upd(struct world, f32 dt){
	for(size i = 0; i < arr_len(world->sprites); ++i){
		sprite_upd(&sprites[i], dt);
	}
}

This seems obvious in hindsight, especially if you're familiar with Unity, where this is the norm. But when starting the project, it was easier to think about all the pieces separately and not try to generalize too much.

I don't know what awaits us in our next adventure, but see you there, when it happens.

Welcome to this not-December adventure, where I write about the process of our latest game, Devils on the Moon pinball.

So I have good and bad news. The good news is that we are releasing a game on the Playdate's second season!

I present to you: Catchadiablos!

You can learn more about Season 2 and the other great games that will release on May 29 at the Playdate Update #7.

The bad news is that we paused the development of Devils on the Moon Pinball for the past 6 months while we finished CatchaDiablos. That’s why there haven’t been any updates on it.

The good news is that both games share the same underlying engine (we call it Luna). When we left off Devils on the Moon Pinball, we didn’t have a sound engine, a save system, or text rendering. It's the first time I needed to code that from scratch. So there was a big question mark about how long it would take — or even if I could pull it off.

Well finishing a game requires all of that so we did it for CatchaDiablos.

So even if we haven't worked on Devils on the moon pinball, we’ve made a lot of progress on the systems that will help us finish the game.

The bad news is that it's not a pinball game. You’d think that after spending months developing our own custom physics and pinball systems we would do something remotely related to a pinball game, but we didn't.

The good news is that it's a really cool game and we’re super proud of how it turned out. I'm not going to spoil anything, but it has some mechanics we have always wanted to play with and now we got the chance to make them.

We learned a lot in the process and will write more once it's released.

The other good news is we are still planing to release Devils on the Moon Pinball before the year ends, you can wish list it now on Catalog. We even made a ridiculous video that showed up in the Playdate Update #6 to announce the game’s catalog page launch.

Now for real, see you in the next adventure: The physics debugger.

Welcome to this December adventure, where I write about the process of our latest game, Devils on the Moon pinball.

One of the few good programming classes I had at university was deceptively called C++. I say deceptively because we learned little about the language features, and instead the class focused heavily on the control flow of a program.

The teacher showed us how to use the Visual Studio debugger and go step by step through the code. Each class, he would teach us a new concept and walk us through it. We would go step by step in the program and showed us how to inspect the state of the program.

After that class, I practically stopped using a debugger even though I learned a lot using them. I eventually ended up doing print statements and got used to this way of working.

I used a debugger a couple of times but only for really specific issues and the majority of the time it seemed like too much hassle that wasn't worth the effort.

When I started learning C watching the Hand Made Hero video series, Casey always ran his program through the debugger. It didn't matter if he was searching for a bug or not. He dedicates a couple of hours at the beginning to setting everything up, but by the time he is actually working on his code, running the game through a debugger was as easy as running the game without it.

I also watched his video talking about Remedy BG. It certainly looked useful, and as I considered myself a novice in C I needed all the help I could get. This is how my search for a debugger that worked on Linux started.

GDB

GDB Is the de facto debugger people use on Linux. Not only that, but by the end of this adventure, I realized almost all the other options were just GDB in disguise, or a GDB front end, as they would say in their description.

I’m not a person who shy away from the terminal and rely on tools like nvim, tmux, bat, ripgrep, lazy git, and others almost daily. However, for some reason, just like with the profiler, I was having a hard time making sense of the debugger on the CLI.

I saw a couple of tutorials, read the manual a little and learned enough to be able to use it. But by the end of the day, it never felt faster or easier than just printing stuff to the terminal.

It was really valuable though, in the future I already knew for example how to print a variable in hex or binary format, and that knowledge carried over to the other tools I tried.

So even if you don't like CLI, I would say it's valuable to learn how to use GDB. At the end of the day, a lot of tools are based on it, so you probably would end up learning how to use it even if you don't want to.

GDB TUI

The GDB TUI seems to be recommended a lot when people complain about using the CLI. It does improve things a little bit but, but not by that much. The UI somehow would always end up somewhat broken after a couple of minutes poking around at a program, and still a lot of functionality was behind the CLI interface, so I needed to learn all the syntax and small tricks that the GDB CLI interface used.

And as with all the other GDB front ends, I eventually would find something I wanted to do that GDB supported, but the TUI didn't, GDB has an enormous set of features, and it seems really hard that a GUI has support for everything that GDB can do.

Seer

Seer was one of my first tries at a GUI debugger on Linux; it sounded promising, but after using it for a day, it lacked a bunch of features, and the workflow was just too slow for me. It didn't fulfil the requirement of being more convenient than a print statement.

GF

This is one of the best if not the best GDB front end, it supports a bunch of features from GDB, it works well while launching from a terminal.

One problem is that it doesn't support Wayland natively, so my code looks all blurry. Also, it has a layout system that you have to define from a config file, and having to make a change, to restart GF and then wanted to change something else quickly became tedious.

When I started using it, there was a Memory Viewer module behind a Patreon, so I subscribed to the Patreon and compiled the app with the Memory Viewer enabled. This was nice, but I would have preferred to install it directly from my package manager. After a couple of weeks, the Patreon was closed and the memory viewer plugin realized. I haven't checked in a while, but it wasn't updated in Arch yet.

VS Code C/C++ Tools

This is the option that I'm currently using. Watching Casey video on Remedy BG made me realize that a debugger could be a lot nicer than what there is right now in the Linux ecosystem, but at least with VS Code it runs fast enough, I'm already familiar with the UI, and it does most of what I need.

I have a long list of things I would like in the VS Code debugger, like being able to launch from the CLI the project attached to the debugger or a way to show my custom strings as text in the watch window. But it doesn't seem like it's going to be possible any time soon.

So that's it! I'm really excited to try out the Raddebugger once it's available on Linux. Who knows, maybe next year is actually going to be the year of the Linux desktop!

Any way, It was time to polish the physics of the game and after using this tools I had an idea.

See you in the next adventure: The physics debugger.

Welcome to this December adventure, where I write about the process of our latest game, Devils on the Moon pinball.

One thing I was afraid of when I started working on this game was profiling code. By the end of Pullfrog Deluxe development, I tried using the SDK profiler, but I had a really hard time.

The call stack in general was big, and it wasn't clear for me which things were the ones I had control over.

So when we started working on the pinball, I prioritized an easy way to measure performance.

Reading the Playdate dev forum, I learned that if you were doing things in C, you couldn't use the simulator profiler on desktop, just on device. Even the device profiling wasn't that great. But you could use any of the profilers for desktop apps.

I remembered there was a profiler project from the Hand Made community that sounded interesting, so I started looking into it.

The project name is Spall and to my delight, integrating the tracing library was super simple. The library is a single header file; you include it in your project and add a couple of macros to the functions you want to trace.

This was different from my previous approach in Pullfrog where I started with the full code being profiled and got lost quickly because it was hard to tell what was happening. You can profile specific functions using the Lua SDK, but you would still get all the other functions in the data.

But the thing that made the biggest difference was the overall UI/UX of Spall. You can zoom in and out, and pan the graph smoothly, whereas in the Playdate SDK you have to first select a section of the timeline and then view that profiling info.

Another big benefit from Spall is that they have a free web version, so you can try it out and see if it works for you.

I even managed to generate the Spall profiling data on the device! It was not perfect; the device would stall after the ring buffer was full and needed to write to disk, but it was enough for me to test small code paths.

At the end, my setup wasn't perfect, but just learning how to interpret the data was enough for me. I learned that a good UI takes you a long way into understanding something complex and scary.

I'm thinking of dropping Spall, at least for device profiling. Now that I actually understand what's happening, I feel more confident to use any profiler.

I also wanted to try Tracy, but after reading the documentation, it seemed that I needed to get a C++ build system, and my build system is super simple. So it didn't seem worth it for this project.

One thing that got me excited is that Superluminal is coming to Linux. Sounds like the next year could be the year of the Linux desktop!

Well, it seems that all the people who talked about profiling were right, it's really useful! And after years of using print statements to debug, I started to wonder... Is this the time to learn how to actually use a debugger?.

See you in the next adventure, The Debugger.

Welcome to this December adventure, where I will write about the process of our latest game, Devils on the Moon pinball.

If I could only choose one book to recommend from this adventure, that would be Real-Time Collision Detection by Christer Ericson. Collision detection is a subject that has come up a bunch of times in my career, and it's something that once you learn can apply to a bunch of things in game dev.

Narrow collision detection

We already had all the primitive checks (minus one that I will cover in a later post) that we needed to make our game, the most complex one being the polygon collision test. The Pikuma 2D physics course covered the Separating axis theorem, and I had already understood and implemented that. But I had heard about the GJK algorithm for a while and wanted to try it out.

After watching a couple of videos and reading some articles, I understood some of it, but wasn't that confident in being able to implement it in a language I wasn't comfortable with yet. Not only that, but this was a basic piece we needed for our game. I remembered reading about the cute headers single header libraries and specifically knew there was a header for collision detection.

After reading the documentation, I got excited; not only did it supported polygons using GJK, but it also had a way to do swept collision detection, which at the time sounded useful.

Turns out we didn't need the swept functions, as running our physics step 4 times every frame and doing sequential impulses was enough to avoid any tunneling issues, at least with the speed the ball was moving in our game. But I'm getting out of topic.

I quickly added the header library to my project and started to testing it out. It worked great.

But as I mentioned before, after we added a bunch of polygons, the game started to slow down. I knew it was due to the lack of any spatial partitioning. I was checking every ball with every polygon every frame.

Broad collision detection

There are various ways to solve this, and Real-Time Collision Detection talks about a bunch of them, not only that but compares them and explains in which case you would use each one of the different techniques.

The main goal is to split the checks you have to do by some kind of spatial characteristic.

For example, Quad trees which I knew thanks to The Coding Train (Jp & I are fans). Quad trees are a technique where you subdivide the space into 4 parts. You put each element inside of one of these 4 parts, and if any part has more than a certain number of elements, you split that part into smaller 4 parts and repeat.

By David Eppstein

I always wanted to try to implement them; it didn't sound terrible complicated, and what better moment. But I decided to keep reading and see what the difference was with the other techniques.

"A very effective space subdivision scheme is to overlay space with a regular grid. This grid divides spaces in to a number of regions, or grid cells of equal size. Each object is then associated with the cells it overlaps. Thanks to the uniformity of the grid, accessing a cell corresponding to a particular coordinate is both simple and fast." Real-Time Collision Detection by Christer Ericson

Well, I know grids. It's one of the most basic things you start doing while programming, and they are everywhere. Quad trees may sound more interesting, but nothing beats simple.

Not only that, but reading more, I realized our pinball table was mostly static, so storing all the static bodies in the grid could be done in a cache-friendly way.

"When a grid data is static, the need for a linked list can be removed all together. Rather than storing the data in a linked list, the idea is to store all cell data in a single contiguous array." Real-Time Collision Detection by Christer Ericson

So I load all the polygon data from our Level Editor, order them by their top left corner, calculate the bounding box of each polygon, and store them in a contiguous array. I know the number of polygons beforehand thanks to the level editor, so I only need to allocate memory once.

Then I calculate how many polygons each cell has, and store the polygons index on each cell they occupy, instead of storing them in a single cell and then having to check multiple ones when doing the broad face collision detection.

I have to run this logic twice, the first time to know how many elements each cell has, allocate the memory needed, and then run again to actually store the indices.

Not gonna lie, this process takes some time. I'm sure I'm doing it in the slowest way possible, but this only happens once when the game launches, I have it on my list of TODO to optimize it at some point, but if the game launches and the loading time is long, well you will know it was in exchange for really fast collision detection! (I mostly kid, I really want to fix it).

We filled the bottom part of the level with all the polygons we planned for the game and smooth 50fps, not a single frame drop.

Well, intuition and good practice can only take you so far. I wanted to be sure that if there were any performance issues, I had tools to diagnose them and fix them!

Will see you in the next adventure: The Profiler.

Welcome to today’s December adventure, where I will write about the process of our latest game, Devils on the Moon pinball.

One day, as we were scrolling through the Playdate Squad Discord server, Lukas Wolski the dev behind the excellent game Owlet’s Embrace posted the following picture.

Some time ago I wrote my own sprite and primitive blitting routines without using the SDK. I went for the same bitmap format like the SDK: First half of the bitmap buffer black/white pixel data, second half of the buffer transparent/opaque pixel data.

I wondered what would happen if I rewrote my code and texture format to use an interlaced layout, where 32 bits of black/white and 32 bits of transparent/opaque are alternating. You need to read and write both of them for basically all graphics routines anyway. The performance difference depends probably on the size of the bitmaps used (-> distance between b/w and transparent regions in a bitmap).

The very same game scene in my own game went from 35 FPS to 50 FPS. And it all came down to cache misses, stalling the CPU. I use some very big textures here and there btw.

This sounded promising! When we were working on Pullfrog I didn't know a lot about how to measure performance bottlenecks, but even I knew that drawing things on the screen was expensive. If we could get a speed bump by doing our own custom drawing routines, that sounded like a big win!

I can't say I fully understood what Lukas was talking about or why it mattered, but I have heard before that cache misses were important for performance.

From Game Engine Architecture by Jason Gregory

Ok good. What is interlacing again? You probably have experienced this on the web.

Sometimes a website image will show row by row of pixels while loading. But other times it would wait until the whole image is loaded. When the image is not interlaced, the browser needs the whole image information to be able to render it. This is because the information about the colors of the pixels and, the transparency is separated. So to show a single pixel, the browser needs to load all the color information and then load all the transparency information.

When the image is interlaced, meaning all the information to render a row of pixels is close together, the browser can render the pixel as soon as it loads that single pixel information.

Ok now that I got that. First I needed to figure out how to convert our .png images to something interlaced that I could then read on the Playdate and blit it to the screen. My first attempt was to convert them to the CHR format I knew my friend Devine was using it for his Nasu sprite sheet editor

I wrote a custom Aseprite exporter for ICN and CHR and BOOM; we have textures in the screen. This was my first time reading/writing a binary format, so it felt like a massive win.

Now this didn't assure me that it would be faster to draw than the Playdate's PDI format; not only that, but the restriction of having everything in tiles was something that made sense for the Famicom but not for our game.

With this new knowledge, I started reading Lukas’ code. He shared it on the Playdate Squad Discord server and had his game code on GitHub. I didn't understand the blipping code yet, but thanks to his previous messages in the Discord, I was able to replicate the image format. Once again, I wrote another small Aseprite script and tried it with this code; it worked!

Kind of...

A couple of tries later, and it worked!

We now had physics and a way to draw textures on the screen; we felt over the devil’s on the moon pinball.

At this point, Jp had plenty of time to plan the pinball table design and had a bunch of art ready to implement.

We added a bunch of polygons and tried the game, but when we started to see the frame rate drop, I knew what I needed to do.

See you in the next adventure, Part 04: The spatial partitioning.

Welcome back to this December adventure, where I will write about the process of making our latest game, Devils on the Moon pinball.

When following the Pikuma 2D Physics course, one thing I did quite fast was making a simple polygon editor. I quickly got tired of inputting every vertex by hand.

This presented a problem: how are we going to author the pinball table for our game? Not only that, but good pinball games have a lot of curves. Am I going to need a way to create Bézier curves? How do I convert Bézier curves to something useful? In my case, to polygon colliders? Should I start working on a custom level editor?

I briefly tried writing an Aseprite extension to generate the collision masks but failed. It was fun though.

The main thing we wanted to know was if we could use the same approach from the physics engine for the Playdate game. First I had to translate from C++ to plain C and from SDL to the Playdate. Second, I wanted to put a lot of polygons on the screen, a couple of balls, and see how the frame rate behaved.

As you will see in future posts, I don’t need a lot of reasons to start making a new tool, but everything was still up in the air; if performance wasn’t good enough, I would need to go back to the drawing board and find a different way to define the level.

So I started searching for a UI to make polygons. I wanted something simple that would let me define some polygons and ideally set different stats on the polygons to test the physics.

In my search, I found the Code & Web Physics Editor. It ran on macOS and Linux; it had a simple UI and allowed me to write a plugin to change the export file to something that fitted my needs. I didn’t have a good way of defining custom entities that weren’t physics-related, but it was good enough to start.

One intermediately obvious benefit of the Code & Web editor was that it took care of subdividing the polygons to make them concave automatically.

I hacked around a custom exporter that would generate a .h file with an array of polygons and started working from there.

// map.h

struct body TABLE_BODIES[43] = {
    {
        /* ID=poly0-0 */
        .p = {0.0, 0.0},
        .restitution = 0.60f,
        .friction = 1.00f,
        .mass = 0.0f,
        .inertia = 0.0f,
        .mass_inv = 0.0f,
        .inertia_inv = 0.0f,
        .shape.shape_type = COL_TYPE_POLY,
        .shape.poly = {
            .count=6,
            .verts={{44, 105},{39, 109},{39, 162},{45, 171},{50, 160},{50, 109}}
        }
},
...

Then came the porting process to the Playdate, we were super excited the first time we saw the ball moving around the screen and colliding with the polygons. We knew at that point that we were actually going to be able to make it. Suddenly making a janky pinball game similar to early game boy pinball games wasn’t enough; we knew we could do better.

While I was playing around with the physics system, Jp finally had some tools to start designing; he already had some ideas for the design of the table. The Code & Web editor got us really far. It allowed us to focus on the overall design of the table and making sure the physics were right before moving on to the next steps of the game.

I wrote a really basic camera system, that followed the main ball, and as Jp added more and more polygons, the game kept running at steady 50FPS.

There were a lot of things left to do, but the scariest part was done, or at least done enough. In retrospect, I really like that we went with the Code & Web editor first; eventually we migrated to Tiled, but only after we took the Code & Web editor to its very limits.

Now we just needed to find a way to draw textures on the screen, and there was a message on the Playdate Squad discord server that excited us a ton.

See you in the next adventure, Part 04: The image format.

Welcome to this December adventure, where I will try to write about the process of our latest game, Devils on the Moon pinball.

When we decided to make a pinball game, the main challenge I saw was the physics system. I don't consider myself to be someone good at math, and physics simulations sound like a scary big math mountain to climb.

But there was always a small sliver of hope; old Game Boy pinball games didn't look like they had a really sophisticated physics simulation, so If we at least managed something like that, we would be fine.

I started looking more into how these games worked. I found a couple of good answers online.

The main gist of it seemed to be to generate a collision mask where every pixel had encoded the value of the angle the ball had to bounce off in a value between 0-255. You then read the value of each pixel around the radius of the ball, get the x and y components of the force vector from the average of the angle, and apply the force to the ball. This sounds... simple!

One thing that you need to understand is that here at Amano, after 10 years working together, Jp and I try to always work in parallel. Gone are the days were JP would send me the file through Dropbox, I would put them in the correct folder with the correct naming convention, show him my build of the game, tweak a couple of values and then recompile.

My main priority while making a system for a game we will do together is to give JP the tools to be able to work on design while I'm working on the next system.

So going back to the collision mask, I just didn't know a good way of generating these masks. Today, a year later, I have some ideas, but at the time I felt there was not enough information around on how this was supposed to work.

JP who has become steadily better at 3D over the years, saw it as an opportunity to use Blender and came up with a pipeline on how to generate a mask like that.

I tried it for a day but quickly became frustrated; for one, as I said, there was little information on how to do this. I didn't understand the math behind it, as simple as it was, and I depended on JP to generate a new image if I wanted to try a new mask.

I researched a little on the state of physics libraries for Playdate, but the results weren't encouraging. There were a couple of bindings for Box2D and Chipmunk physics, but the libraries seemed too complicated for what I needed they didn't seemed to have the results I wanted.

I was kind of lost; on one hand, I could try to figure out the collision mask method and have the simple janky physics of some early Game Boy pinball games. And in the other, I could just try to do a rigid body simulation myself and see how that goes.

My first rule when I started this project was, "I prefer something simpler and done by myself, rather than doing something more complicated and just grabing someone else's code." So going for the collision mask seemed like the best option if I was going for simplicity, but the lack of resources made it harder on the ‘me understanding it’ part of the rule.

For a long time I had been wanting to do one of the courses on Pikuma.com. They seemed to share a similar spirit to Hand Made Hero, and they had a course on a 2D physics engine, just what I needed, neat!

I skimmed the contents, and it seemed like just the thing I needed.

It took me around a week to finish the course and it was good! I don't understand all the underlying math and wouldn't be able to derivate the formulas by myself, but I understood enough to feel confident to reimplement the physics engine in C for our pinball game.

It was a dangerous decision because while I took a full week learning new things, I left JP with the hype of a new project and not a lot of tools to work with, but after showing my progress, we were both excited.

The main benefit of doing things ourselves meant that we could cut corners where it made sense for our specific project.

Now I had to port my new physics engine to C and make it work on the Playdate so we could validate how many things we could have on the screen at the same time.

But first I started to worry. Remember how I said that my main priority was having tools ready so that JP could work in parallel while I worked on the next thing? Authoring the collisions for the game started to look like a task more difficult than what I was expecting.

See you in the next adventure, Part 03: The first level editor.

Resources

Before I go go. I want to share a couple of links to resources that helped me tremendously with this. And on that note, I also want to tell you that doing a basic rigid body simulator is not that hard! If you are even a bit interested, you should try it! I don't regret it one bit, and you can have something fun happen quite fast.

How to create a custom physics engine by Randy Gaul

By far the easiest of the bunch, you can follow along and have something working in a day, also Randy Gaul so if you haven't checked their libraries of CuteHeaders I highly recommend them.

Game physics series by Allen Chou

A little bit more in depth and touch on more intermediate subjects, whenever I got stuck with a specific concept, I would try to read this article series, a lot of times it went over my head! But the little knowledge that I was able to absorb was super valuable.

Rigid Body Dynamics by Chris Hecker

Chris Hecker was mentioned quite a lot in the Hand Made Hero video series, so it was a nice surprise to find his name all over the place whenever I was searching for rigid body Dynamics.

Physac a 2D physics header-only library in C by Victor Fisac

Whenever I'm doing something new, I always feel more confident when I have the code of someone else I can read along with and digest. While doing anything in a new language and one that was so different from what I was used to, Physac helped me to double-check everything I was doing and make sure it made sense.

Everything by Erin Catto

I don't really know where to start when linking things from Erin Catto. If you have worked for a while in games, probably you already know about Box2D and even maybe heard about Erin. What you may not know is that Box 2D is not at all as complicated as I thought it was! By the end of my work with the physics engine, my main source of reference was the Box2D and the Box2D Lite source code. I didn't even realize that the intention behind Box2D Lite was to teach people on how to do physics simulations. Anyway, all the GDC presentations and all the code that Erin has written is excellent, and you should check it out.

Solving Rigid Body Contacts by Richard Tonge

At some point I got stuck with a weird behaviour we were having with multiple collisions in a single frame, I may talk a little more about it in a later post, but this presentation saved my ass. And now I'm forever a fan of Antonio Signorini

It’s been a long time since we talked about Pullfrog. The main reason being that we paused the development to work on another game called Don Salmon, you can read more about it on the previous devlog.

But now we are back working on Pullfrog, with our main goal of finishing it, we haven’t yet, but we are close! It’s at the stage where we are comfortable with what the game is and what it isn’t.

So buckle up because this is going to be a long one.

What happened?

When we started working on Pullfrog for Playdate, the plan was to work on it for a month, three months tops. The plan was to port the PICO-8 version and improve some things on the way. It took us a year to have the basic version of the game we wanted to do. By the end we were a little tired, so when we heard Panic! was looking for games to publish, we saw it as an opportunity to spend some time on a proper pitch and take a break from developing the game.

While we waited to hear from Panic! we started working on Don Salmon. We wanted to apply everything we had learned making Pullfrog, on a game where the limitations were different. We wanted to experiment with new platforming mechanics, like wall-jumping, air jumping, dashing etc.

One day we got a tweet from @Guv_Bubbs and @TYMplaydateshow asking us on the status of the project. At that point we were deep on the development of Don Salmon, and we hadn’t heard anything from Panic! So we replied that the project was on indefinite hiatus while we finished Don Salmon. Panic! saw this and emailed us asking us if we were still interested in publishing the game but cutting the scope of it.

Who would have thought that lowering the scope saved the game.

Before Panic! approached us, we looked at the amount of work we had yet to finish, and it was frankly a lot! In trying to make a different enough game from the PICO-8 version, we put a lot of pressure on changes. So when Panic! contacted us after not working on the game for a year and asked us if we were interested in reducing the scope and finishing the game, we got excited, Ideas started coming through.

The first thing was to stop trying to make a different game. We scrapped all the ideas to make it more like a dungeon crawler with enemies and a final boss and focused on closing the loop of the game, to make it play more like the PICO-8 version which we knew worked, but with the learnings from the past year applied towards making it better.

Make everything bigger

One of the first things Jp did was to completely re-do all the game assets to make all the sprites larger. After playing other Playdate games, we came to the conclusion that the game would read better by changing the size of the character and the pieces, though at the slight cost of losing some vertical space for the game screen.

The shop

The second part was removing the shop logic of the game. The initial plan was to have a shop like the one in Downwell, and allow you to step out of the game and use the eyes as currency to get new power ups.

As you can see, we had everything working already, but we decided it was something that the game didn’t need and added a lot of complexity to the project. The way we did it in the PICO-8 version was that every time you cleared 3 lines, the shop would pop-up in a little window and pause the gameplay while you browsed, and you could choose an item for free. So we decided to go with this as well.

The thought of deleting all that code and focusing on the important parts of the game felt good. After that it took us about two weeks to get back up to speed, but once we did, we where closing tickets left to right.

The eyes

One consequence of changing the shop was that we had all these systems based on getting eyes, but now they didn’t hold any value anymore.

In the PICO-8 version you could also collect eyes, by choosing five of them on the shop instead of a useful upgrade, a secret door would appear. Something we like from the new version, is that to collect an eye, it needs to be inside of a cleared line. If you use your tongue to destroy a block piece that contains an eye piece, you loose the eye. This makes the game a little more like a puzzle and forces you to think more about which pieces you destroy.

Now that you don’t collect the eyes in the shop, we had more space left for power-ups.

1UP

One thing we discovered while working on this new version is that having an extra life can be nice, but too many and the game is less fun. Getting squished by a piece but being able to get a second chance and go back to the game felt great.

So we came up with the power up of a 1UP, there will only be one each run, so it is precious but gives you that second chance.

So yeah! We are almost done, we are excited to see what people think of the game, and happy with the progress we have made in the last couple of months. As of writing this we’ve finished the first beta build, there are still a couple of months left of work, but we are getting close!

Some things have been happening that triggered me to write this blog post. One of them is that a good friend of the studio showed me a couple of neat muck-ups for a pixel art point-and-click adventure game, which took me down a rabbit hole of research, and I ended up reading 50 entries of the Thimbleweed Park blog in a day.

I also went to GDC for the fifth time! The first time I went to GDC I didn't have a good time, mostly because I didn't know anyone, my English wasn't great, and the projects I was working on at the moment were hard to talk about with a bunch of cool people at the Yerbabuena park.

Last year, I had a great time, mainly because I had two big things going on for me. The first one was that I gave a talk!. This was the first time I went to GDC with a ticket, which was great! The second thing is that I was working on Pullfrog and had one of the few PlayDates, (maybe the only one?) in San Francisco at the time, so everyone I met wanted to try out the game!

What happened with Pullfrog?

A lot! But it was on hold for about a year. We just took a break from it, mainly because Panic announced that thanks to the big success of the Playdate pre-orders, they were looking for games to publish.

We sent an email and a pitch deck but didn't hear back, so we assumed Panic wasn't interested. At the time we were working on Pullfrog's unlockable abilities, we had a bunch of ideas we wanted to try but to finish the game we had to focus on performance for a bit. We had already optimized the game a lot, but the game would drop to 20FPS regularly on advanced levels, so after sending the pitch deck, we decided to take a little break while we waited to see the future of the project.

We planned to publish this post in April! And a lot has happened since then, mainly that Panic! Got in contact with us, and we have been working on Pullfrog since the end of May. That’s the main reason why this post is published now: so that we can start writing about Pullfrog.

As I said in the previous log, we have been dabbling with 3D, and personally, I was really deep in to learning the Godot Game engine, so I wanted to make a small game with it to get it out of my system. So after we send the email, I started working on a small prototype.

The main idea of the game was to make a 2D platforming game with all the platforming mechanics: corner correction, dashing, wall jumping, double jumping, triple jumping, QUADRUPLE JUMPING, you get the idea. And we needed a way to limit the abilities, and one thing we hadn't done in a game before, was combat.

After I saw this GIF on my timeline, I came up with the idea of a game with a waterfall where you can climb to the top while punching things that are coming down. Depending on your combo, you get more platform mechanics.

After a day of working on it, I showed it to Jp, and he got excited and started working on the art. We made a couple of level prototypes to nail down the resolution and general workflow, and we had a nice demo!

Perfect, I said; in a month we will finish this little game and come back to work on Pullfrog.

It's been 10 months 1 year, and we haven't finished, but here is how the game looks right now. We are pretty happy with it; we are still figuring out something on the main mechanics, but that's a topic for another log.

Last year we made the decision to take a break and focus on a spooky game around the spooky season.

This year we wanted to try and do a 3D game. We already have a 3D spooky game, Gossip Ghost but we never finished it, and it left us with an urge to try it again later.

One thing that I wanted to try is Godot, as a Linux with a bad internet user Unity tended to be a little hostile.

We spent around a month and a half on a small 3D demo of a game, with the idea to maybe make it something bigger. Turns out doing a 3D game can get tricky, more so when you are learning a new programming language, game engine and asset pipeline. In general, the experience was positive, and we are excited to try and do more 3D games next year, but our time was up, and we decided to go back and finish Pullfrog.

Possibly in another post we will talk about our experience with Godot and 3D games in general, but I'm trying to finish an entry here.

Eyes and levels

The last thing we were working on before taking a break was our eye system. The idea is to have some sort of hard currency that you need, to advance to the next level. This is the mayor difference between this new version of the game, compared to the PICO-8 version. The concept of levels. We started the development with the idea to do something more similar to a dungeon crawler than an arcade game.

The idea is that every piece has a probability to spawn an eye in one of their blocks, and if you clear a line of pieces containing an eye, you get it. After you fill the level quota, the door unlocks, and you can go and talk to a pondering frog merchant, who will eventually give you a nice perk before advancing to the next level.

I loved implementing all these things, after months of tracking performance and trying to keep things under a CPU budget, being able to put as much polish as possible in little details was a joy to work on.

Level editor

One of the things we love about PICO-8 is the integrated level editor. It may not be much, but just having something ready to use for any game adds a lot of possibility to your workflow. For a hard core use of the PICO-8 tile map editor check out @calixjumio who always takes the level editor to an extreme in a interesting way.

For the original Pullfrog you may not know this, but we used the tile map editor extensively. The main reason was for testing. Pullfrog this is a complex arcade game with a custom physics engine and complicated rules. We had to test a lot of weird situations and the easiest way to do so was starting the game on a specific situation using the tile map editor.

From the start of the PlayDate version, we made the decision to find a level editor for our internal testing, or in the worst case build one ourselves by hand. We don't need much, just paint some tiles and have at least a flag per tile telling what kind of tile it is.

The PlayDate SDK comes with an example on how to use Tiled. We have used it in the past and the experience wasn't great, granted, it was our first time doing a tile map game and we were using a hacky plugin to transform the map in to unity game objects, but in general Tiled seemed like a complicated solution for a really simple problem.

I have been following Deep Night from some time now, I'm a fan of the game dev articles and saw the release of LDTK which seemed promising. I tried using it while working on The lost night but we were already too deep into the game and would need to rewrite a lot of stuff to make it work, and probably more tokens, but it left a great impression on me. Making a parsing system for our PlayDate game sounded more fun than trying to use Tiled.

Workflow

One of the things I love about LDTK is that the map file is a JSON file, so there is no need for an export → engine pipeline. We can just read the map JSON file which is the same that it's used by the editor. Another thing I like, is the file structure, it's well-thought-out to make the parsing job easier, and the documentation is really good.

So I started writing our LDTK parsing module, currently it consists of 160 lines. We are not using the full list of features LDTK has, just a small subset of things that we require for the game, and every time we require something else I go in and add a couple of lines to the parse. If we start building a lot of levels, I may need to split the levels in files and load them depending on where the player is, but that's future Mario's problem.

We have a couple of LDTK's entities to quickly iterate over the game, one that controls in which level the player is going to spawn and one that controls where in the level the player is going to spawn and with which properties.

We also have one entity per shape of piece, this allows is to specify what kind of piece it is (more on this in the next post) and if the piece should spawn with an eye. So if we have a specific bug we want to try, we just need to set it up on the map and run the game.

The world

We currently don't have a specific plan on how we are going to handle the level progression. Currently, when you open the door and fall to the next level, the level that it's directly below the one you were before gets loaded, and if there is no other level below we just restart the previous level. This works fine for prototyping, but we need to figure out a good way to present the different mechanics that we have planned, we have a couple of ideas, but I don't want to spoil them until we have a basic implementation.

The future

The game will be out when it's finished, this means we have no idea when that would be, but we would like to at least have an early access version when the PlayDates start arriving to people, so we can have user feedback and add the finishing touches to the game.

Meanwhile I leave you with a Gif showing how we tend to debug UI elements.

Remember when I said that making a hole inside a big collider was a good idea? It was not. After rewriting the physics system for the third time, it was time to start working on more fun stuff. The frog death system™.

Something we wanted to improve from the PICO-8 version of the game, was to make it harder for the player to die. The game can be hard, as you need to mix platforming with puzzle solving abilities.

On top of that, dying while pulling the pieces towards you was no fun, so we came up with a system to try to save you, moving you out of danger.

First we figured we only are going to try to save the frog if you are getting squished by a piece that is moving vertically.

The most important part is to figure out which direction we should move you. Our first approach was to compare the piece center with the player center, and move the player to the closest side to freedom.

    -- Fake code
    local pieceCenter = piece:getCenter()
    local playerCenter = player:getCenter()

    if playerCenter < pieceCenter then
        player:moveLeft()
    else
        player:moveRight()
    end

This simple solution had a small problem, our pieces have different shapes and the center is not always, well, in the center.

So we created a small system to place the center of the pieces by hand

Now we have to figure out how many pixels we want the system to move the player each frame. If we move it too much, it would look like we are teleporting the player. If we move it too little, then it can get stuck for many frames and look like the game broke.

We decided we didn't want the player to die until the very last moment. When the piece is squishing it so much that there is no room to escape.

We can get this information based on the overlapping rect between the piece and the player. If the height of the rect is less than 10 pixels (the frog collider is 11 pixels tall), we keep trying to break you free.

We figured that 1 pixel at a time would look the best most of the time. There are some times when you are on top of a piece that's falling and if you pull it towards you, you get stuck sliding between a piece sandwich. So in that specific case, we move you 2 pixels at a time to get you out faster.

Another thing we realized was that it didn't feel good when you died while you were moving in one direction, and our system forced you to move in the opposite direction.

You would still be dead if we moved the direction you were trying to move. But it felt unfair because we were forcing you to move in to a direction you didn't intend.

So now if you press any of the D-PAD arrows while being squished, we force the direction you are pressing to try to get you out. You die more times than before, but it always feels like it's your fault, not the game's fault.

After implementing this, we found another issue. If you stopped pressing the D-PAD after we started moving you, then our system would try to move you in the opposite direction if you hadn't cleared the piece center.

This looked bad as the character was moving without you controlling it in random looking directions.

We decided to save the D-PAD direction if you were pressing it while being squished and try to save you on that direction even if you stopped pressing it.

Sometimes you would only get squished by a small amount on one of the player corners. If you were moving in to the piece and get caught, then our system would pull you in and kill you without anything you could do about it.

We added another rule. If the piece is crushing you by only a small amount, then we try to move you in the closest direction to freedom, regardless of what you are pressing.

Finally, if we fail to save you and the intersection rect between the piece and the frog is taller than 10pixels. This kills the frog.

Here is the code we ended up having, there is a lot of context missing, but helps to understand the system a little better.

---

function Player:SquishY(other, x, y, w, h, dy)
    local px = self.x
    local ox, oy = table.unpack(other.overrideCenter)
    ox, oy = other.x + ox, other.y + oy
    local dirX = self.flip and 1 or -1
    local correctingDir = self.correctingDir
    local velX = self.velocity.x

    local sideDist = 8
    local maxSquish = 10
    local speed = 1
    local cornerThreshold = 4
    local speedThreshold = 0.4

    if other.targetPosition then speed = 2 end
    -- When you get squish from a piece that it's moving upwards,
    -- check if there is a solid on top of you and if there is
    -- this kills the frog
    if dy < 0 then if self:checkSolid(0, -1) then return self:die() end end

    -- The player always overrides the direction where you are going
    -- to be tried to be saved.
    -- If the player stops pressing a button we use the last direction
    -- the user pressed.
    if (input.btn("left") or velX < -speedThreshold) and w >
        cornerThreshold then
        dirX = -1
        self.correctingDir = dirX
    elseif (input.btn("right") or velX > speedThreshold) and w >
        cornerThreshold then
        dirX = 1
        self.correctingDir = dirX
    else
        if correctingDir == nil then
            if (px < ox) then
                dirX = -1
            elseif (px > ox) then
                dirX = 1
            end
        else
            dirX = correctingDir
        end
    end

    if h <= maxSquish then
        actorCornerCorrect(self, dirX * speed, 0, sideDist, {0})
        self.squishedY = true
    else
        self:die()
    end
end

This is a more polished version of a long message that I wrote in the official Playdate Discord server. A couple of things I would recommend when starting your first game on the Playdate.

Lazy Devs

Lazy Devs is one of the best teachers for game development out there. I love his tutorials because it shows you the process of doing a game from start to finish with a lot of polish and focus on gameplay. The tutorials are for PICO-8, but it also uses LUA, so a lot of things translate well to Playdate.

a327ex

If you want a big LUA codebase to look at as a reference, BYTEPATH and SNKRX are good examples of finished games made in LOVE2D. They are open source so you can check how they handles everything in the games.

Basic example:

Coming from PICO-8 I wasn't used to importing external files so I was importing CoreLibs in every single file. At some point I started to wonder if that's how everyone was doing it. I looked at a327ex code and ended up having an single init.lua file where I do all my imports and set up the game.

Using a framework

The most valuable thing from a framework in my opinion is to look at their code. So you can check the general structure of the project and figure out if it works for you, or grab the things that do. In general, I would recommend against starting with a framework on top of the Playdate SDK for your first Playdate project. You will end up with another layer of things you have to learn.

Scene Management

This is a common mistake, I know that I have fallen in to this trap a couple of times before. Scene management is not especially hard to do, but it's something that can impose a lot of friction between iterations of your game.

I like to start my games with the main interaction of the gameplay and make that feel as nice as possible.

In our game that would be movement and platforming. In other games it could be moving the cursor for a point and click adventure or grid movement for a puzzle game.

Making it feel good takes a lot of iteration. If you have to go through: Title screen animation -> Main menu -> testing your small change, it will end up as a painful process. You might even start working on tools to make that process faster. And end up spending more time doing the scene management and the tools around it than actually doing the main mechanic of your game.

In a more code-centric problem the first version of your scene system probably is not going to be the best. And you probably don't know all the things that you will need for it to work the best it can for your game. If you introduce it too early you may find yourself coding in a way to accommodate to your first attempt at your scene management system. So my advice would be start with movement first. Try to finish a game loop and if you need some scenes to make that happen do them in the simplest way possible.

LUA and OOP

This is personal preference but a lot of the times it is better to start without OOP. It can make your LUA tables bloated in exchange for a small convenience that you may regret later on. I use the basic sprite for everything and do helper functions that accept a reference to the sprite. After a while it becomes clear if I need to abstract it in a class, but a lot of the times it doesn't.

function spriteGetMapCoords(sprite)
    local x,y = sprite.x, sprite.y
    x = math.floor(x/16)
    y = math.floor(y/16)
    return x,y
end

-- VS

local gfx <const> = playdate.graphics

class('MySprite').extends(gfx.sprite)
function MySprite:init(x,y,img)
    MySprite.super.init(self)
    assert(img)
    self:add()
    self:setImage(img)
end

function MySprite:getMapCoords()
    local x,y = self.x, self.y
    x = math.floor(x/16)
    y = math.floor(y/16)
    return x,y
end

Playdate has a lot of limitations on the amount of objects that you can update/have in every frame. So hiding them away on abstractions class can end up being a bad idea.

It's been a while since we post anything new about Pullfrog 2Bit and it's mainly because all the new stuff is hard to share as it is has been a lot of refactor to try to have the game running at a better frame rate in the Playdate. I leave you with a GIF on the latest bug.

There are many techniques that you can apply so that a platformer game feels good. One of those is corner correction.

As with most of these techniques, the goal is to assist the player in getting to the position where they want to be. Even if there is something in the way that wouldn't let them. In this case we are moving the player a few pixels to the sides so that they clear the platform above them.

In the PICO-8 version of Pullfrog, we solved this using multiple colliders. We would check which one of them triggered the collision, based on that, we would apply some logic to move them where we wanted. This worked fine but the problem is that we where checking all the colliders every frame. It was hard to maintain, and an expensive operation, dropping frames when there were a lot of pieces in the screen.

When starting the Playdate version I imposed myself a challenge, to have the same behavior using only one collider. The first thing we tried was to compare the position of the player with the object they collided with. Check if the distance between them is less than a certain amount, and if it is, move the player in the opposite direction.

This worked fine, but it was a little more complicated than what we needed, and caused a couple of undesired consequences. For example the jump distance would get altered and you would miss platforms that you would otherwise land on.

On top of that our physics logic for moving platforms was getting too complicated. Then someone on the Playdate Discord shared an old post by Maddy Thorson about the physics system on Towerfall and Celeste. After reading it a lot of things clicked, and I got excited to change my broken physics mess for a more elegant solution.

For the corner correction Maddy doesn't go in to detail, but you can see and implementation on the Celeste 2 PICO-8 game repo. It took me a while to understand it, because PICO-8 code tends to be a little bit hard to read.

The main takeaway I got from Maddy's post and the Celeste 2 code, was to split the movement into two functions. One for X and one for Y. This made everything easier to think about and easier to resolve the collisions. In the case of corner correction, once we detect a collision, we try to move you out of it depending on the direction that you where moving. If while correcting you in one axis you collide again then we just don't move you, after that it's time for the other axis to try and correct you.

I'm thinking of doing a more in-depth explanation with some code. But haven't had the time to add code snippets support to the Devlog and this post is already getting big!.

A nice thing about doing this from scratch, is that now the code is less coupled with the player. This allow us to apply the same logic on different stages of the game an player movement. For example: If you are going to get squished by a moving piece, now we try to move you to safety.

Another example would be when you pull a piece and it collides with another one, we try to move the piece so that it ends up where you intended it to be.

Did you noticed how the piece pushed you? this was an added benefit form the new physics system and a big difference from the PICO-8 version of Pullfrog, but we will talk about this is a different post.

On some occasions people have commented on the character animations of the original Pullfrog. Saying how they look very bouncy, and asking how many frames we were using to get them to look so smooth. This used to throw me off-guard because the answer is one frame, or more like, as few as I can possibly draw.

This is probably something that’s been talked about a million times, but here’s my take on the subject. To me, character animation is not about how smooth the movement is, or about trying to get in as many frames as possible to really make the character feel alive. It’s quite the opposite actually. I want to convey the action in the least amount of frames possible because I’m lazy, animation is a lot of work, and most people don’t really care or notice. Let the player’s mind fill-in the blanks. Well, those aren't the only reasons. See, I’ve worked in animation before, so while economizing is important to get work done, I like the challenge of getting an action to come across with very few frames. It feels elegant. It feels like I solved a problem.

So why DO these animations feel “Smooth” or “Bouncy”?

The most important thing to keep in mind are the key poses of an action.

A key pose is THE most essential frame of an action that the viewer needs to see. That single pose should be clear enough, that even without in-between frames the viewer knows exactly what action the character is performing.

Another Equally important decision, is choosing which poses you want to emphasize in order to get that reactive feeling when a character interacts with the world. So in the case of Pullfrog, I wanted to really emphasize the jumping part because, well… frog.

So I determined that each step pf the jump needed to have an impactful pose. These steps being:

1- Going UP  (Exaggerated stretch pose)

2- Coming Down (Frog curls into a ball)

3- Landing (Super Squash)

A simpler version of this goes into the walk an idle actions. Since I’m working with a n 8x8 grid there’s not a lot of room for detailed poses so the walking cycle is just a body squash and the legs opening and closing in alternation more like a “shimmy” than a walk, but it works!

So it’s not about how many frames I’m using rather, what actions I’m deciding to pose.

All this talk about economizing on frames does not mean that I don’t embellish my animations with extra frames for smoothness. I might if I can afford the sprites and have the extra time. Which is exactly what I chose to do in Pullfrog 2.

Since the Playdate doesn’t really have any limitations to the amount of sprites, I decided to get a little fancy and add some extra frames to every action. These are just simple in-betweens where I’m using some animation principles like smears and anticipation to convey fluidity in movement. I also don’t want to over animate because this is still a game and reaction times are still more important than animations.

Another advantage I now have is that I'm making the character on a 16x16 grind instead of 8x8 so that gives me a lot more room to really explore the strectchiness of the character.

Anyways. Once we start adding new mechanics and movements I’ll post about them too. And maybe talk about some cheating techniques to convey anticipation without hindering reaction times.

That’s all for now. Thanks For reading!

It all started with this little boy right here. A bug that had been annoying us for a couple of days, and this week was the time to fix it!

As stated on the previous post, updating all the pieces all the time was a bad idea. We needed to figure out a way to update only the ones that needed to be updated after another block got destroyed. The quick and dirty solution was to check all the pieces inside a bounding box on top of the piece that got destroyed.

We found an issue with the solution because If you have a structure like the one below, you could affect pieces in a column far away to the destroyed block and the algorithm would miss them.

The easiest solution was to check all the blocks above the one destroyed. We tried it, but came across a couple of issues. We updated way more pieces than the ones that were needed, not only that, but we some pieces kept freezing in the air.

At this point I realized that the basic idea was flawed. The pieces need to get updated not only if the block below them gets destroyed, but also when one piece below them starts moving.

So the new solution is: after we grab one piece, we search for all pieces that are in contact with it. Then we search for pieces in contact with those pieces, and then again and again. This is fast because we save the dry pieces inside a grid, so we only search nearby cells.

And it works!, we only update the pieces that need to be updated, and the code is way simpler to maintain.

A couple of tools helped us chase down this bug. We use LDTK to generate the game screen, it's very helpful, as we can generate any specific layout in seconds and start testing from there. Making the parser took us a couple of hours and has saved us a huge amount of time already.

We also added a grid overlay to the game through the Playdate men, to position things or figure out their coordinates.

About Amano

JP: So, a couple of months back, Mario and I were happily working away on The game, finding out the workflow and working out the kinks of developing for the PlayDate. We laid down the main mechanic, block were falling and colliding correctly the character was moving alright but we were doing everything on the simulator, NOT testing on the actual device. so when we decided to take it for a spin…  it crashed.

Turns out, the way we were handling collisions wasn’t the best. So we got kinda bummed out and stopped working on the game for a bit.

During that off-time decided to address another issue. Mario wasn’t very thrilled about our games coming out under his personal itch.io, Newgrounds, and Lexaloffle accounts because he’d constantly get solely credited for the games on social media and stuff. So in order to unify things in one place and give our games more of an identity, we designed a brand a website: Amano.

^This was gonna be the logo for a while. but IDK, one morning I kinda' hated it so I changed it on a whim.

We went through a ton of iterations for the text; but the hand and the eye came out pretty much on the first sketch.

Hand-made tortillas are better than their machine-made cousins, and far superior to their ( born out of the necessity to cover demand and convenience) factory mass-produced alternatives. So sometimes I go on rants about how much I love hand-made tortillas. Especially to Mario. Hence his idea to name out little project Amano. “A mano”, which translates to “hand made” from Spanish.

The Collision conundrum

Mario: The PlayDate SDK has pretty much everything we needed to start making Pullfrog, One of those things is a collision system. After spending the majority of the development time making a collision system for the original Pullfrog, this came as a welcome surprise. With a reassuring feeling that if everything went bad, we could always recreate the same system as the one in the PICO-8 version.

We started working on the main character and its behavior, we wanted to recreate the same feeling and polish we had on PICO-8 so the basic collision handling that we had on the PlayDate wasn't enough. Fortunately it wasn't to hard to customize and we ended up with even a better version of what we had in PICO-8. After a couple of days we already had the character moving in the screen! we already kind of had a game, so I built the game and send it to my device and started moving the little frog around.

After solving the collisions for the player, we though the next step would be as easy. Add falling pieces, and then we had the base game ready. We tried to keep things simple, so we had each the pieces with a list of blocks, and each one of blocks had their collider. We need this because when the player starts pulling and destroying the pieces with it's tongue we need to know which block was stroked.

After a couple of weeks, I decided it was time to try the game again on the device, we where so excited that we added a hacky system for playing SFX's. I build the game, send it to the device, boot it up and then ... the game crashed.

Ok ok nothing serious, maybe I did something dumb with my hacky SFX manager and I could fix it later. I disabled the SFX's and tried again, after a few seconds of moving the little frog, the game crashed again!. After a couple of hours trying to figure out what was causing the issue, we realized it was the amount of blocks on the screen. Turns out that having one collider per block and checking collisions every frame was expensive and not a good idea, we needed a break.

Our previous game, The Lost Night, is a small spooky themed RPG made in PICO-8 where we hit all the platform limits at the very end of the development process and we had to scratch about 60% of the content we had planned for the game. By the end of the development we were bummed out. We didn't want the same thing to happen with Pullfrog2. Saddened, we started discussing our options, but nothing seemed to work better than what we had. We shifted our focus on something more exciting, Amano. We spent one month building the website, and it was a nice break, so by the end we were eager again go back and fix the game. You can check out the source code of the website if you want.

After we knew the issue was having too many colliders in the game, I went back and started planing on how to reduce that number. The first thing that came to my mind was to have one collider for the bigger part of the piece and in some cases an extra one. This meant we would need to check twice each frame for half of the types of pieces. On top of that we still needed to know which block was struck by the tongue and would need an extra step.

After a couple of hours I realized that if the pieces weren't moving, it didn't matter if we had all the colliders in the screen. Then we could keep a single collider per block and use them for the interaction with the frog's tongue. Now we needed to figure out how to handle when the pieces were falling as they only care about other pieces below them.

Next thing I tried was to query other sprites inside the bounds of the piece and check if there was something that should stop them. We made a quick test on the PlayDate and it Worked!. We could have the screen full of pieces falling and the game kept running. The frame rate drops a bit but that also happens on the PICO-8 version and no one has complained yet. I realized we didn't need to update the pieces when they are "dry", which is how we call them when they change their pattern to a state where they can be destroyed. We only needed to update the pieces that are above one that got destroyed the last frame. We can even have the screen full of dry pieces without any issue with the frame rate, which is how you play 99% of the time.

There was only one thing else to fix. Some pieces have an empty block space in them, which makes them always a source of tricky bug. I figured to first check the big bounding box of the piece and then, if it collides, check if it overlaps with the empty space in the piece and ignore it. It's similar to the many colliders in the piece approach but with the advantage that we only check the empty space once, instead of twice for each piece.

It worked!. But then I kept thinking there must be a better way of doing it. JP kept telling me that we could check the collisions based on a tile map like we do in PICO-8 version. It's tricky because the pieces can move around while you are pulling them, so when they are falling, we need more sophisticated collisions. And when they are in the floor we don't. We had a way of checking if the cell in the grid is occupied by a block for the line clearing, so we could use that while the piece where in the floor and use our new system when they are falling.

I'm sure there is still room for improvement but the game is playable in the device and we are happy with it for now. At the end it's similar to how we handle things in PICO-8, but it was hard to know how to translate that in the PlayDate without trying it first.

We where so happy about the game running in the PlayDate that JP did the launcher cards for the game, they look SO GOOD.

Next up is dealing on how the pieces and the frog behave when you pull them and they collide with the frog. We have some ideas on how to improve this based on what we learned from the PICO-8 version.

Back in 2020 during the month of may Mario and myself started working on a game for PICO-8 as part of a monthly game development club. I've always loved playing Tetris and other falling block puzzle games, although Tetris is more of a skill game than a puzzle game such as Panel De Pon. I've also always loved playing platformers. Moving around a character that has well-polished controls makes it feel like controlling an extension of your body. So I'd kinda wanted to mash-up these two things for a while.

I started by trying to lay down the feel of the character movement. I am not a programmer but attempting this really helped me understand how games and code really behave. and so after a while at work I managed to produce this janky-ass thing.

And then I tried again. Getting the basic movement allowed me to focus on important platforming details like "Coyote Jumping", collision corner corrections and input buffers. and so the second version was a little better.

This is where I hit my programming ability wall and Mario took over. He refactored the code, made pertinent changes, and continued to develop, what was initially just an exercise in learning good platforming feel, into a complete game. We came up with the look and core loop for the game, which is to move around and pull the falling blocks in to place with your tongue in order to clear lines and obtain power-ups, and keys in order to open a door at the end of the game. This Unlocks a new characters that play slightly different to the frog. Ideas were sketched, mechanics were polished, pixel art was pixeled. PICO-8's token limit was reached over and over again, but after 30 days we finished Pullfrog.

We learned a ton from the experience. Collisions, movement, performance, pacing, polish, math. Even though we were working remotely, most of the time we were talking on discord each doing our part. Finishing this game really made us feel that with enough time and resources we could make any kind of game we liked. So we put it out on Itch.io, Lexaloffle, and Newgrounds. People responded great to it, we were content and moved on to the next thing. We worked on a couple more pico ideas. But the itch remained. The "what if?". What kind of a game could we have made without the limitations of PICO-8?

So towards the end of the year, Mario managed to get his hands on a Development console for the handheld "Playdate" and we decided to attempt do make a second version of Pullfrog, this time featuring a playful little crank and seemingly less restrictions except for the apparent ones like the black and white color of the screen. Oh the naivety.

So this is the plan:

We want to make a version of Pullfrog that features more polish and variations in gameplay like:

• Different kinds of blocks.
• Some enemies and or bosses.
• Level progression.
• Replayability mechanics.
• Make use of the crank controller.
• Smoother animations and controls.

Slowly making progress as we get to know the Playdate console more and more. Developing tools and better ways to work. We're gonna try to keep this devlog going as we work and hope that whoever reads it can get something out of it. Thanks for reading.

You can follow us on twitter and stay updated on the development of our games.