Coming back to a large codebase after a break is disorienting.
I returned this week after a 3-week gap and barely recognized the code I’d been working on. So I planned the week around small, finishable tasks. Nothing ambitious. Just things I could complete and feel good about, to rebuild momentum.
Start small
Sev assigned me my Planka board (the task tracker we use) and pointed me toward a set of Gus games: Gus Goes to Kooky Carnival, Cybertown, and a few others. I went through the tickets, broke each issue into its own card, and we had a Zoom call where he helped me set up the environment properly.
This call is worth describing because it’s a good example of what mentorship looks like here. We talked about Dumper Companion (a tool for inspecting Director movie internals), useful ScummVM debug flags, debugging workflows. The non-technical conversation ended up being just as helpful for reorientation as the technical one. If you’re new and a maintainer makes space for this kind of call, take it.
cast viewer in the visual debugger
It wasn’t loading shared cast members. I fixed that and removed some duplicate code while I was there. Small, satisfying, done. That’s the point of starting small.
Bug 1: Crashing on empty cast slots
The hard part of a fix is often defining the boundary correctly, not writing the code
In original Director, if you set a property on a cast member slot that exists but is empty, it fails silently. ScummVM was throwing an error, which crashed games that relied on that behavior.
Imagine cast slots are numbered 1 through “b”, where “b” is the last populated member. Accessing slot “a” (within bounds but empty) should fail silently. Accessing slot “c” should throw an error. The bounds are defined by the last populated cast member, not the total allocated size.
The fix seemed obvious: skip the error if the cast member isn’t found. But that would also swallow errors for genuinely out-of-bounds IDs, real bugs you’d want to catch. The problem wasn’t the error. It was defining “in-bounds” correctly.
test movies
This is also where Sev introduced me to test movies, minimal Director movies that reproduce a single buggy behavior in isolation. Instead of loading an entire game to verify a fix, you create the smallest possible movie that triggers the issue. Much faster, much cleaner.
The solution: teach ScummVM to distinguish between an empty cast slot within a valid range and a genuinely invalid cast member ID (error).
Bug 2: Sprite dragging not working
The symptom and the cause can live in completely different systems
In one of the Gus games, clicking a puzzle piece should let you drag it around the screen. In ScummVM, clicking did nothing. The piece stayed frozen.
I assumed the drag logic was broken. It wasn’t. The drag code was fine. The real issue was buried in the event pipeline, and finding it meant tracing the entire event flow from click to handler.
ground truth testing
I needed to confirm how Director 4 actually behaves, so I ran the original Director inside Basilisk II (a classic Mac emulator) to observe the real immediate sprite property. You can’t rely on documentation alone (shocker for me), some features are marked obsolete but still functional, and behavior varies between versions.
Here’s what immediate does in Director 4 (5 & 6 too):
normally, mouseDown fires on press and mouseUp fires on release. When immediate is set on a sprite, both mouseDown and mouseUp fire on the press.
The drag handler works by running a repeat while the stillDown loop inside on mouseUp. If mouseUp only fires after the physical release, stillDown is already false and the loop exits instantly. Nothing moves.
The fix was in queueEvent(): when a press arrives on an immediate sprite in D4, queue both mouseDown and mouseUp events immediately, then suppress the physical mouseUp later to prevent double-firing.
version boundaries
sev pointed out something: does immediate behave the same in D3? Does it stop working in D5?
Turns out immediate works in D4, D5, D6. Not tested D3 yet. Will update this after.
the director-tests repo
Instead of loading full games to test a behavior, we use the director-tests repo, a collection of minimal test movies that verify specific Director engine behaviors. You create the smallest possible movie that reproduces just the thing you care about, and it lives in the repo as a permanent regression test.
What I’m aiming for next week
-
Work through more Gus bugs.
-
Look at build-bot issues.
-
Go deep on one subsystem end-to-end.
-
Improve tests and stress the visual debugger.