When you fix a bug in a normal program, you fire up gdb or lldb, set a breakpoint, and step through the code. But what do you do when the “program” is a Macromedia Director game from 1995, written in a scripting language whose interpreter died two decades ago?

You build your own debugger. This post is a tour of DT (debugtools), the ImGui-based visual debugger built into ScummVM’s Director engine, which I have been working on since February.

DT was started by other ScummVM developers before I arrived; my work has been rebuilding the Score window, adding several new windows, and hardening the whole thing. Consider this the companion piece to my weekly posts, the missing chapter about where all the “DT:” commits actually go, with the parts I built called out along the way.

Why a game engine needs its own debugger

ScummVM’s Director engine is a reimplementation of the Macromedia Director runtime. Director games are “movies”: a timeline (the score) full of sprites, backed by a library of assets (the cast), all glued together with scripts written in Lingo.

When a game misbehaves, the bug is usually not in ScummVM’s C++ but in the interaction between the game’s Lingo scripts and our reimplementation of Director’s behavior i.e it’s a behavior difference which can be fixed in the C++ code.

But, a C++ debugger can’t help much there. What you actually want to see is: what frame is the movie on, which sprites are on which channels, what script is executing, what are the Lingo variables, and what did the original Director do differently.

DT answers those questions. It runs inside ScummVM itself, drawn with Dear ImGui, and you get it by launching any Director game with --debugflags=imgui. The game keeps running in its window while the debugger windows float around it, live.

This is the debugger layout I currently use. Layouts can be saved / loaded by clicking view > save state / load state.

The white outlines you see around the objects is enabled using the draw all command in the console debugger (see immediately below).

The older sibling: the console debugger

DT is not the engine’s first debugger. One directory up, in engines/director/debugger.cpp, lives the classic console debugger: a gdb-style text prompt (it literally greets you with lingo)) reachable through ScummVM’s debug console. It speaks the vocabulary you would expect, bpset, step, next, finish, bt for backtraces, disasm for bytecode, plus Director-specific commands like channels, cast, and markers, and even a small Lingo REPL for evaluating expressions against the running movie.

The two debuggers are complementary rather than competing. They share the same underlying machinery, breakpoints set in one are visible in the other, and the same interpreter hooks drive stepping in both. The console is precise and scriptable; DT is spatial.

The architecture in one diagram

The whole debugger lives in engines/director/debugger/, about 8,600 lines across a dozen files, and follows a simple shape. debugtools.cpp is the orchestrator: it owns the ImGui entry point, and every frame it calls a show*() function for each window. dt-internal.h holds the shared debugger state, one big struct that remembers which windows are open, what is selected, cached textures, script history, themes, and so on. Each dt-*.cpp file is one window, and each window reads directly from the live engine objects: the current movie, its score, its casts, the Lingo state.

Because ImGui is an immediate-mode UI, there is no retained widget tree. Every single frame, each window re-reads the engine data and redraws itself from scratch. That sounds wasteful but it is exactly what makes the debugger feel “live”: whatever the engine is doing right now is what you see, with no synchronization layer in between.

The Score window

This was my first big project, and it is still my favorite. The score is Director’s timeline: a grid where rows are channels and columns are frames, and each cell says which cast member is on that channel at that frame. The original Director authoring tool had a famous score window, and game logic constantly jumps around the timeline, so you really want to see it.

The first version of the window was a plain ImGui table. It worked, but it could not look like Director’s score, and it fought the framework on things like custom cell decorations. So I rewrote it using ImGui draw lists, which are essentially a canvas API: you get rectangles, lines, triangles and text, and you draw the entire grid yourself. That rewrite (my first merged PR of the project) opened the door for everything that came after.

What the score window does today:

• Sprite spans: consecutive frames where a channel holds the same sprite are drawn as one continuous bar with a start circle and an end square, exactly like Director drew them. Computing these spans means comparing every sprite against its neighbors across the whole score, so the result is cached per movie.
• Display modes: the cells can show the cast member name, the behavior script, ink type, blend, location, or an extended multi-row view that shows all of them at once.
• The main channels: tempo, palette, transition, and the two sound channels get their own rows above the sprite grid, again matching the original tool.
• Navigation: horizontal and vertical scrolling (including mouse wheel), frame labels above the ruler, a playhead that tracks the current frame, and a center button that snaps the view to the playhead.
• Interaction: clicking a cell selects the sprite and shows its details in an inspector strip (position, ink, blend, bounding box, flags), and double-clicking a frame jumps the movie there. That last one is dangerously fun.

The Cast windows

The cast is Director’s asset library: bitmaps, text, sounds, palettes, film loops, scripts, all numbered members. DT has a Cast browser with list and grid views, type filters, and thumbnails rendered from the actual cast member data, plus a Cast Details window that shows every property of a selected member, organized the same way Director’s own property dialogs were.

Some pieces of this I am particularly happy about:

• The film loop viewer. A film loop is an animation packaged as a cast member, and internally it has its own miniature score. So the details window renders a miniature score grid for it, with its own playhead and frame stepping, plus thumbnails of the sprites in the current frame.
• Sound playback. Sound cast members get play and stop buttons, sample rate and channel info, and a table of cue points. The preview plays through the engine’s own sound manager on a reserved channel, so what you hear is what the game would play.
• The image viewer. Clicking a bitmap or text member opens a dedicated viewer with zoom, pan, fit-to-window, and for text members, a tab showing the raw text with a copy button. Sounds trivial, but when you are comparing a rendered bitmap against a reference screenshot pixel by pixel, zoom and pan stop being luxuries.

Scripts: reading decompiled Lingo

Director movies do not ship with Lingo source code, they ship compiled bytecode. DT shows you readable Lingo anyway, courtesy of LingoDec, a decompiler that reconstructs an AST from the bytecode. The script windows walk that AST and render it with syntax highlighting: keywords, builtins, literals, comments, each in their own color, with a bytecode view one toggle away.

And the scripts are not just text. Handler calls are links, click one and you jump to its definition. Variables have an eye icon, click it and the variable is added to a watch list. Each line has a breakpoint gutter.

The navigation used to be one floating window per handler, which collapsed the moment two scripts from different cast libraries shared a member number, since the windows were keyed by that number. I replaced it with a single Scripts window that works like a browser: an ordered history, back and forward buttons, and a dropdown of everything you have visited. Go-to-definition pushes onto the history, back pops you out.

Breakpoints plug into the Lingo interpreter itself. When execution pauses, the Control Panel offers step over, step into, and step out, implemented as small predicate functions that the interpreter calls after each instruction to decide whether to keep running.

Here is the entire step-over logic, to show how small these predicates are:
The interpreter calls this after every instruction while running. Step into and step out are the same idea with the conditions changed: step into pauses on any line change or callstack change, step out only when the callstack gets shorter. The debugger does not drive the interpreter, it just answers “should we stop here” when asked.

The Execution Context window shows the call stack per engine window, and clicking a stack frame opens that handler at the paused line.

Finding things: Search and the Windows panel

A Director game can contain hundreds of scripts across multiple cast libraries and a shared cast. The Search window greps them all, with modes for handler names, variable names (properties, arguments and globals), and full script bodies, the last one by decoding the compiled bytecode instruction by instruction. Results open in the script browser, and the matched text gets highlighted in the rendered script.

The Windows panel came out of debugging multi-window games (Director movies can open other movies in windows, and yes, that is as messy as it sounds). It lists every loaded window with its movie, play state and frame position, and below that, every .DIR file found in the game directory, click one and the engine navigates to it. That turned out to be the fastest way to explore a game’s movies one by one.

Two more windows deserve a mention here. The Vars window shows every global, local and property variable live, with changed values highlighted, and any variable can be added to a watch list that logs every write along with the script that did it, which is how you catch the question “who keeps resetting this flag”. And the Archive window is a raw resource browser: every chunk in the movie file, viewable as a hex dump, for the days when the bug is below the level of sprites and scripts entirely.

A real session

To make this concrete, here is roughly how the post office investigation from my last post went through DT (see https://blogs.scummvm.org/ramyak/category/week-6/).

The stamp snapped back on drop, so: open the Score window and find which channels the stamp and slot live on. Click the slot’s sprite, see it script in the inspector, click through to the Scripts window and read the decompiled mouseUp handler.

Set a breakpoint on it, drag a stamp in the game, and watch the breakpoint never fire.

That single observation, visible in seconds, is the whole bug. The rest was C++.

Everything breaks, including debuggers

A recurring theme this summer: the debugger observes a live engine, and live engines change under you. Movies get switched, casts get destroyed, windows get closed, and every raw pointer the debugger cached becomes a landmine. A good chunk of my June work was a sweep through the whole debugger fixing null dereferences, out-of-bounds accesses, stale pointers and memory leaks, several of which I found by reading the code, looking at crash backtraces etc. and asking about every stored pointer: who deletes this, and does the deleter know we kept a copy?

That exercise changed how I write the feature code too. It is one thing to be told “don’t cache raw pointers to engine objects”, it is another to watch your own cast details window explode because the movie you were inspecting no longer exists.

None of this happened in a vacuum. Every one of these PRs went through review, and the pattern of feedback shaped the debugger more than any single feature: sev pushing back on fixes that need rework, and me reflecting on the review to make the code better.

What is left

DT is genuinely useful today, I use it daily to debug the Gus games, but there is plenty on the wishlist like making it more bullet proof, finding edge cases, adding new features.

If you want to try it: build ScummVM with ImGui support, add --debugflags=imgui to any Director game, and press Ctrl+2 through Ctrl+4 to toggle the main windows.

Things worth knowing on day one: Ctrl+F1 toggles mouse capture, so your clicks stop reaching the game while you arrange windows (hold Shift to click through temporarily); debugger windows can be dragged entirely outside the main ScummVM window if multi-viewport is enabled in Settings; and there is a light theme in Settings for people who debug in daylight. Bug reports welcome, I have become quite good at reading the crashes.

The PRs behind this post

– New Score window GUI with draw lists
– Score scrolling and frame labels
– Score center button and QOL changes
– Variable watch logging and script search
– Film loop score viewer
– Sound cast member audio controls
– Cast viewer crash fix and film loop regression fix
– Image and text viewer window
– Bug and crash sweep through the visual debugger
– Search redesign and Windows panel
– Cast details improvements and browser-style script navigation
– Script viewer rendering fix

Appendix: what each file does

For anyone who wants to hack on DT, here is a map of engines/director/debugger/:

• • debugtools.cpp / debugtools.h: the orchestrator. Owns the ImGui lifecycle (onImGuiInit, onImGuiRender, onImGuiCleanup), the main menu bar, the keyboard shortcuts, and the theme definitions. Also home to the shared helpers everything else leans on: the texture cache for cast member thumbnails, toImGuiScript() for turning a handler into something renderable, and the script context lookups.
  • dt-internal.h: the shared state. One big ImGuiState struct that remembers which windows are open, current selections, script history, search results, cached vars, themes, everything that has to survive between frames. If two windows need to talk to each other, they do it through this struct.
  • dt-cast.cpp: the Cast browser window. List and grid views, type filters, name filter, thumbnails.
  • dt-castdetails.cpp: the Cast Details window with per-type property tabs (bitmap, text, rich text, shape, sound, film loop), the film loop mini-score viewer, and the image viewer with zoom and pan.
  • dt-controlpanel.cpp: playback controls (play, stop, rewind, frame stepping) and the Lingo stepping buttons. The step over/into/out predicates that the interpreter consults live here.
  • dt-lists.cpp: the grab bag of list windows: Vars (globals, locals, properties), Watched Vars with the write log, the Breakpoints list, the Archive resource browser with a hex view, and the Windows panel.
  • dt-score.cpp: the big one. The Score window (grid, spans, ruler, playhead, main channels, sprite inspector) and the Channels window showing the live state of every channel in the current frame.
  • dt-scripts.cpp: the Scripts window with its browser-style history, the Functions list, and the Execution Context window with per-window call stacks.
  • dt-script-d4.cpp: the renderer for decompiled Lingo. Walks the LingoDec AST and draws syntax-highlighted code with the breakpoint gutter, current-statement marker, and clickable handler calls. Used for Director 4+ bytecode.
  • dt-script-d2.cpp: the same job for older movies (D2/D3), which ScummVM compiles from source itself, so this walks ScummVM’s own AST instead of LingoDec’s.
  • dt-search.cpp: the Search window: handler names, variable names, and full body search by decoding bytecode.
  • dt-save-state.cpp: layout persistence. Serializes open windows, ImGui window positions, and settings to JSON so your debugging setup survives restarts.

Welcome back, happy to be writing back after so long. I’ve got myself on the work again and there’s 2-3 days of progress I want to brief about. But before that, I must inform that the initial PR for iBASS support has been merged(it was merged while I was away), which means that now you can play iBASS on the debug builds. All you need to arrange are the game files. Continuing the efforts of porting, I implemented the text chooser(the PR is currently opened). But first let’s understand what exactly is the text chooser.

Text Chooser

See the questions at the top. When we talk to the NPCs, a list of questions in this form appears. We have to select a dialogue from this list.

This is how it works.

The PR is currently opened. Once it gets merged, you’ll be able to use this feature.

The silent killer

Day before yesterday, while I was implementing the text chooser, the game crashed on starting. I was lucky that I had run that time with gdb so I recorded the backtrace-

Thread 1 “scummvm” received signal SIGSEGV, Segmentation fault.
0x000055555924128a in READ_UINT16 (ptr=0x55555ed36000) at ./common/endian.h:209
209 return ((const Unaligned16 *)ptr)->val;
(gdb) bt
#0 0x000055555924128a in READ_UINT16 (ptr=0x55555ed36000)
at ./common/endian.h:209
#1 Sky::Disk::getFileInfo (this=0x55555e4a7640, fileNr=60600)
at engines/sky/disk.cpp:310
#2 0x0000555559240c60 in Sky::Disk::fileExists
(this=0x55555e4a7640, fileNr=60600) at engines/sky/disk.cpp:169
#3 0x000055555922e5c6 in Sky::SkyEngine::init (this=0x55555e48dec0)
at engines/sky/sky.cpp:462
#4 0x000055555922f0f1 in Sky::SkyEngine::run (this=0x55555e48dec0)
at ./engines/sky/sky.h:130
#5 0x00005555560e808c in runGame
(enginePlugin=0x55555d3d2f60, system=…, game=…, meDescriptor=0x0)
at base/main.cpp:328
#6 0x00005555560ea70d in scummvm_main (argc=1, argv=0x7fffffffde28)
at base/main.cpp:840
#7 0x00005555560e4d84 in main (argc=1, argv=0x7fffffffde28)
at backends/platform/sdl/posix/posix-main.cpp:56

the getFileInfo function reads from a variable named _dinnerTableArea that is never written to in iBASS since iBASS doesn’t have a separate sky.dnr file.

So, the game starts successfully most of the time because it contains garbage. If it doesn’t, the game crashes. To fix this, I used the getEntry() method.

That’s all for this blog. See in the next post.

Thanks for reading 🙂

This week was about closing out a drag-and-drop bug that had been bothering me, building test movies in real Director 4, and finally facing the AddressSanitizer. Let me walk through what happened.

The Post Office Bug

The centerpiece of the week. In Gus Goes to Cyberopolis, the post office letter minigame was broken: dragging a stamp onto the letter’s slot made it snap back to its tray every time, making the minigame unwinnable.

Some quick background for this one. A Director movie is composed of sprites, visual objects placed on numbered channels, and each sprite can have a script attached that reacts to events like mouseDown and mouseUp. Lingo (Director’s scripting language) also has a property called the clickOn, which returns the channel number of the sprite the user last clicked.

The game’s logic is simple: the stamp’s script handles mouseDown and starts the drag, and the slot’s script handles mouseUp and places the stamp. On release, the slot’s script asks the clickOn which channel was involved and checks whether it holds an empty slot. So for a drop to work, two things must happen when the mouse is released: the mouseUp event must be delivered to the sprite under the mouse (the slot, not the stamp), and the clickOn must return the slot’s channel.

Neither was happening in ScummVM. For Director 4 movies, mouseUp was being delivered using the sprite remembered from the original mouseDown, so the stamp’s script received the mouseUp. The stamp has no mouseUp handler, so the event fell through to the frame script, whose fallback logic snaps the stamp back to the tray. And the clickOn still pointed at the stamp’s channel from the original click.

Understanding this took a detour through Director’s message hierarchy, events are offered to the sprite’s script first, then the cast script, the frame script, and finally the movie script, with each level able to stop or pass the event along. Reading the game’s four scripts against a debugger session made it click.

The fix: deliver mouseUp to the sprite currently under the mouse for Director 4 movies, and update the clickOn when mouseUp lands on a sprite, so drop-target scripts can identify the target channel. Stamps now stick to letters.

NOTE: the fix is not final yet. Further discussion with sev will decide its final shape.

Building the Regression Test

Sev’s condition for the fix was tests, so I made some test movies in Director 4. The test suite in the director-tests repo uses a plugin (an “XObject” in Director terms) that can inject input events, move the mouse, press and release the button, and assert on the order in which handlers run, using a global counter.

The new test places two sprites on stage, presses the mouse on sprite 1, moves to sprite 2, and releases. Sprite 1’s script asserts it received the mouseDown; sprite 2’s asserts it received the mouseUp. Without the fix, sprite 2’s handler never fires and the assert count comes up short; with the fix, everything passes.

My first version attached the handlers to the cast members instead of the sprites, and the test failed for the wrong reasons, the handlers need to be sprite scripts to exercise the exact dispatch path the fix touches. I also added a screenshot call to last week’s text wrapping test, so that fix now has visual regression coverage against a reference image captured from real Director 4.

Film Loop Position Shift

A film loop is a Director cast member that packages a small animation so it can be placed on a channel like any static image. In the Kooky Carnival’s shooting gallery, animal sprites jumped to the wrong position when clicked.

When a script swaps a sprite’s image for another cast member at runtime, the new member may use a different registration point, the anchor that decides how the image is positioned. Normal bitmaps anchor at the top-left; film loops anchor at their center. ScummVM wasn’t adjusting the sprite’s position for that difference, so the sprite visually shifted by half its size on swap.

The fix saves the sprite’s on-screen bounding box before the swap and adjusts its position afterward, so it stays put. I had pushed a similar solution a long while ago, but it was in the wrong place. This one works.

What not to do

I had some uncommitted changes sitting on the buildbot server, which broke the imagediff tooling.

A refactor by sev had moved code from imagediff.py into main.py, and two things were left broken. First, main.py imported its config before running the sys.path bootstrap, so the dashboard could not load from a fresh start at all (ModuleNotFoundError: config). Second, screenshot_diff.py still imported from the old imagediff/imagediff.py module that no longer existed, so every ScreenshotDiffStep failed.

The fix moved the bootstrap before the config import, pointed the diff step at the new module, and cleaned out leftover debug prints and dead code. Merged.

Fortunately the uncommitted changes on the server were trivial and I was able to revert them.

Lesson learnt: do not leave unfinished work on prod servers (-_-) (use git, github).

My First Use-After-Free

While testing one of the Cyberopolis movies, ScummVM crashed when switching movies, but only in my AddressSanitizer build. This was my first time actively reading an ASAN report. As I was looking into this, I asked sev and after looking at the backtrace he found 2 commits which were the likely cuplrits.

The older commit, related to some changes in movie cast members, was the culprit. As this is a difficult bug, this will be taken care of by sev.

The visual debugger

Some DT changes have been made locally, but will finalize them and push the commits soon. Mostly bugs and crashes, nothing very interesting. And the DT blog is almost ready. Wasn’t able to work on it for a few days. Will publish in a day or two.

Next up:
– work on an animation speed bug
– continue on gus bugs

PRs this week:
– Fix mouseUp dispatching to wrong sprite in D4 (not merged, in discussion)
– Add D4 test movies for mouseUp dispatch and text wrapping (director-tests)
– Fix filmloop position shift when swapping cast member via Lingo
– ImageDiff cleanup

Hello and welcome back! This is Week 6 of my GSoC journey, and I’m excited to share that I’ve finally completed the Dungeon Master engine!

Fixing the Endianness Problem

As I mentioned in the last blog, using READ_LE_UINT16 and WRITE_LE_UINT16 macros had a deeper issue — loadDungeonFile() reads Big-Endian file data and stores it into _thingData as native-endian uint16s, so on a Big-Endian machine the whole setup breaks regardless of the macro fix.

So I spent the first half of this week replacing those byte offset macros by parsing the file data directly into respective arrays of structs at load time. This involved removing all raw byte-to-struct pointer casting (e.g., (Door *)rawDat) from the codebase and updating the file loading and saving routines to read and write fields one at a time using stream operations like readUint16BE and writeUint16BE.

Uncovering Hidden Bugs

These changes also brought some new freezes and crashes to the surface — bugs that were silently hiding behind the old unsafe code. Raw pointer arithmetic was allowing silent reads and writes to out-of-bounds memory, which switching to Common::Array now catches immediately as crashes or assertions. Unsafe casting was hiding cases where one object type was being read as another, which strict C++ type assertions now catch instantly.

Debugging the Endgame

The endgame sequence had quite a few bugs hiding in it. When you capture the Lord of Chaos and fuse him with The Firestaff, the game unlinks the fluxcage — but in fuseSequence(), curThing was never being reset after that, causing the loop to run forever.

When the Lord of Chaos was turned back to normal, the message displayed was also corrupted — wrkString was declared outside the loop so it kept accumulating characters from previous words, and a stray \0 append was preventing it from reading past the first word. Moving wrkString inside the loop and removing \0 fixed the issue.

Another text bug had only the second row showing up in the message area — the first row was being cleared before it could scroll up. createNewRow() was clearing the line buffer before the scroll animation could finish, so the fix was to wait in a small delay loop until _isScrolling is false before proceeding.

Beyond that, I also added support for returning to the launcher after closing the game, along with other small fixes to get the engine to a solid, playable state.

Crash When Renaming Champion in the Hall of Champions

Clicking outside the character select table during champion renaming was calculating an invalid character index from out-of-bounds coordinates, causing a crash. The fix was straightforward — enabling a bounds check that was previously disabled, so clicks outside the table are now simply ignored.

Implementing Extended Saves

I also implemented extended saves for the DM engine, allowing the game to make use of ScummVM’s extended save functionality.

That was it for this week! It’s been a long road getting the DM engine to this point, but it’s rewarding to finally see the work of the previous contributor and Strangerke pay off after 10 years. You can find the previous contributor’s blog here.

Thanks to Sev for helping me throughout this.

I’ll see you in the next blog as I dive into a new engine. Until then, bye! 👋

Crossing the Atlantic: the US Amiga Release

Last week ended with the European Amiga version of Kult running almost perfectly, and a promise: next up, the US release. In America, the game shipped as Chamber of the Sci-Mutant Priestess, published by Draconian, and this week was all about making that version boot and play too.

Same game, different executable

My hope was that the US build would just be the EU one with translated text files. It wasn’t. The Draconian build lays out the KULT executable completely differently:

• Every static resource lives at a different offset. On the EU side, I had a table of file offsets for the resources embedded in the executable (palettes, icons, zone data…). The US executable shifts them around non-uniformly, so I couldn’t just add a constant — I had to reverse-engineer the US binary and rebuild the whole offset table entry by entry. The good news: once located, 8 of the 12 embedded resources turned out to be byte-identical to the EU ones; only ZONES, TEMPL, CARAC, and ICONE actually differ.

• The English text banks are jammed straight into the executable, completely abandoning the neat separate files the EU release used. This meant writing a different extraction path just for the US text.

• The filenames are lowercase.Normally, this would be an immediate problem on case-sensitive file systems like Linux. Thankfully, ScummVM’s Common::File API handles case-insensitivity out of the box, which saved me from having to write any extra fallback logic!

A different welcome screen

The US version also greets you differently: it shows an intro.pia title screen before the usual pres.bin presentation. It’s a small detail, but until the engine knew about it, the game wouldn’t even get past boot.

Zone Scan, the Amiga way

While testing, I also finished the Amiga version of the Zone Scan psi power. The Amiga renderer draws it differently from DOS: the effect applies a dedicated palette delta that tints the room green while the scan line sweeps across the screen. Getting the line itself right took one more fix — the sweep works on chunky pixels now, so the line width and the inversion effect had to be adapted from the original planar code.

Detection entries

With both variants playable, I added proper detection entries for the Amiga EU and US releases. ScummVM now recognizes all of them straight from the launcher.

Looking back at these past two weeks, I am incredibly happy to see the Amiga versions finally fully animated and playable. Building the Amiga support from absolute scratch was a massive, daunting challenge, and I honestly couldn’t have reached this milestone without the immense help and guidance from my mentor. Seeing these versions breathe and run flawlessly makes all the heavy lifting worth it!

Next week

While all this was happening, sev ran static analysis over the engine and sent me a nice stack of Coverity and PVS-Studio reports. While chasing those, I found a bug that wasn’t in my engine at all, but in ScummVM itself. More about that (and about a monster that refused to survive a save/load cycle) in the next post!).Stay tuned!

This week had a mix of bug fixes, debugger improvements, and game detection work. Let me walk through what happened.

Before I get into bugs, a quick note: I will be posting a separate blog on the visual debugger soon. Here is a snippet from a data flow diagram for the dt:

An Unresolved Bug

While testing Gus Goes to Cybertown’s Science Dome, I found a bug in the Sink or Float minigame: dropping the golf ball or spoon shows Prof. Gus’ face instead of the drop animation.

I traced it to cast member 525 (s_fqt, a digital video) on channel 14, which spans frames 7350 – 7359 during the drop animation.

In the original Director 4, this sprite is effectively invisible, its bounding box appears as three vertical dots on stage, not selectable or resizable. For the spoon case, no bounding box appears at all. ScummVM renders it at full size (240×180) instead.

The score stores the correct dimensions, setCast is called correctly, and the bbox passed to createWidget is right. So ScummVM is reading the data correctly – the original Director is doing something to suppress this sprite that we aren’t replicating yet. The likely culprits are the ink mode or a puppet flag, but I haven’t confirmed which yet.

Sev’s advice was to study the score at the exact frame where the original renders correctly; check ink, dimensions, and puppet flag,  and look for any Lingo touching that channel. If the cause still isn’t clear, the plan is to strip the movie down to just the affected frames and cast members as a minimal test case, which can then live in the test suite to prevent future regressions.

This one is staying open for now. Sev also pointed out that since this bug is complicated, it’s worth finishing a sweep of all the Gus games first to find something simpler to close out, which is the plan for the coming week.

Text Wrapping 

The next bug I tackled was text wrapping in D4 text cast members. Some labels like “Hamburger” were incorrectly wrapping as “Hamburge\nr”, one character too early.

The root cause turned out to be two separate issues. MacText treats maxWidth as the outer width and subtracts border, gutter, and shadow internally, so I was passing the wrong value and the effective inner wrap width was narrower than the cast member’s designed text area.

On top of that, wordWrapTextImpl was using > instead of >=, meaning text that exactly fills the available width was being wrapped onto a new line when it shouldn’t be.

Both are easy fixes in isolation, but finding them required understanding how the text layout pipeline chains together across three layers. The fix ships with a regression test in director-tests.

Debugger (DT): Script Viewer

While testing Gus Goes to Cybertown, clicking on some cast members in the Cast window showed the script tooltip on hover but opened nothing on click. The script viewer window stayed empty.

The issue has two parts. First, scripts using internal generic event handlers (scummvm_generic) were failing because getHandler() matched by handler.name == handlerId exactly, but generic event handlers store an empty name and are only identified by the isGenericEvent flag.

Matching on that flag when handlerId is “scummvm_generic” fixes it.

Second, some cast members return null from getScriptContext(), the root cause is still under investigation, but the scripts do exist and their source text is available in CastMemberInfo::script.

As a workaround, addToOpenHandlers() now falls back to displaying the raw Lingo source text when no compiled AST is available.

Sev shared a different D8 movie that had the same issue, which confirmed it’s not game-specific. The workaround covers that case too.

Gus Goes to Cybertown: Detection Entries

Gus Goes to Cybertown has three distinct Windows versions: Retail (Director 3), Retail Revised (Director 4), and Golden Master (Director 4). Each has different file sizes and hashes, so three separate detection entries were needed.

That was a summary of most of the things I did this week.

My next immediate goal is to fix the remaining gustown errors, and add it to release.

PRs this week:
Fix text wrapping in D4 text cast members
D4-win director-tests repo changes for the above PR
Fix script not rendering in script viewer
Add detection entries for Gus Goes to Cybertown

Hi everyone, this is week 5 of my GSoC project. Work on the Dungeon Master engine is almost at an end — except for one last hurdle, which I’ll discuss later.

The Unresponsive Wall

At level 13, casting Zo Kath Ra spell to open the wall should free the power gem — but the wall stayed completely unresponsive.

Cause:

for (thingBeingProcessed = squareFirstThing; thingBeingProcessed != _vm->_thingEndOfList; thingBeingProcessed = dungeon.getNextThing(thingBeingProcessed)) {
		Thing lastProcessedThing = thingBeingProcessed;

The lastProcessedThing pointer was being updated to thingBeingProcessed at the start of each iteration. Before unlinking this particular sensor, the code checks if (lastProcessedThing == thingBeingProcessed). Since both pointed to the same thing, this check always failed and the sensor was never unlinked, failing to trigger the next sensor.

Fix:  updating lastProcessedThing to thingBeingProcessed before updating thingBeingProcessed resolved the issue.

Shade Screen Box

Next I implemented DisplayMan::shadeScreenBox. It draws a checkerboard pattern over a given box by coloring every other pixel based on alternating coordinates, creating a semi-transparent shading overlay on top of whatever was already drawn there, graying out menus or buttons.

Before:

After:

Before:

After:

Before:

After:

Fix blitToBitmapShrinkWithPalChange()

Enabled palette translation in blitToBitmapShrinkWithPalChange by mapping each source pixel through the translation table and dividing by 10 to account for the original game’s 10-multiplier scale.

A spell stone kept on ground:

When viewed from a distance of 2 tiles, it looks:
Before (without Palette translation):

After (with Palette translation):

Segfault on restart

Restarting after your party is dead would result in a crash with buffer overflow.

Cause:  On restart, loadDungeonFile() was skipping reallocation to reuse existing buffers — but if the new dungeon needed more space than what was previously allocated, writes would go out of bounds.

Fix:  Track each thing type’s allocated capacity in _allocatedThingCounts. On restart, if the new dungeon’s count exceeds what was previously allocated, reallocate and update the tracked limit

Runtime errors

Some places in the code used << on signed integers, which is undefined behavior in C++ when the value is negative.

Fix: Replaced those with * to get the same result safely.

Another instance,

int16 attribMask = 1;
for (uint16 stringIndex = 0; stringIndex < 16; stringIndex++, attribMask <<= 1) {

On the 16th iteration the value overflowed the int type, causing signed integer overflow.

Fix: changed attribMask to uint16

Fixing blitBoxFilledWithMaskedBitmap()

*nextDestPixel = *mask & nextSrcPixel;

Cause:  Doing a bitwise-AND directly on ScummVM’s 1 byte per pixel format corrupts the resulting color palette index. The combined indexes produced garbage color index numbers, leading to severely corrupted/incorrect pixel colors on the screen

Fix:  Rewrote the logic to pick the mask color directly if it isn’t white, or fall back to the source pixel if it isn’t transparent.

Spellcasting Tabs Display

Cause: The highlight screen box was using an XOR mask of 0x0F, but only the 3rd bit needed to be flipped, producing the wrong highlight color on the spellcasting tabs.

Fix:  Changed the mask to 0x04.

Before:

After:

The one last hurdle

Issue:  loadDungeonFile() reads Big-Endian file data and stores it into _thingData as native-endian uint16s. But the gameplay macros like DOOR_nextThing access this memory using READ_LE_UINT16 and WRITE_LE_UINT16, which always expect Little-Endian memory layout. On Big-Endian machines this setup won’t work.

Proper Fix:  As Sev suggested, I would parse the file data on load directly into arrays of structs, so the engine can just address those structs directly instead of re-parsing every time. This time it won’t take much time as I’m already familiar with the places these macros are used.

The Amiga Comes to Life!

This week was a massive milestone. The European Amiga version of Kult now runs almost perfectly under ScummVM — it boots, plays through, and looks exactly the way it did on real hardware. Getting there took twelve intensive commits(for now) that dragged the port all the way from “the engine knows the Amiga platform exists” to “you can actually sit down, click around, and play it.”

The absolute best news from the start: the Amiga build didn’t require a completely separate engine. It runs on the same chunky, one-byte-per-pixel, 16-colour pipeline as EGA — the Amiga’s planar source data just gets converted into it. Almost everything that differs comes down to the palette, the way static data is stored, and a handful of filenames. That single insight shaped my entire week.

Sharing the EGA Path

The first major step was to stop the graphics code from asking “is this strictly EGA?” and start asking “is this an EGA-like renderer?”

I added an isEgaLikeRenderer() helper and routed the sprite, portrait, and transition code through it instead of comparing directly against the EGA render mode. With that simple seam in place, the upcoming Amiga renderer could reuse all of those paths completely unchanged! There was zero behavioural change for EGA or CGA, but we now had a clean foundation to hang the new platform on.

On top of that, I implemented the AmigaRenderer itself: a custom 12-bit palette over the same planar graphics, selected purely by platform. It came with its own cursor decoder for the SOURI.BIN hardware sprites, plus the title screen and its fade-in ramp wired directly into the boot path.

Finding the Data

The Amiga release doesn’t lay its files out like the DOS versions. Instead of a compressed PXI module, it keeps the static resources uncompressed inside the KULT executable itself. Furthermore, it ships per-language text files  rather than the generic ...I.BIN names.

I added a dedicated loadAmigaStaticData() function and routed the resource loading accordingly, ensuring the engine pulls text and data from the exact right offsets for each language.

Colour, At Last

Early on, the rooms were wearing the wrong palette entirely. The fix was to compose the room palette from the zone’s palette_index and apply it as soon as the zone loads. This means intro and special screens (which can bypass the usual zone refresh) are no longer left stuck on the previous title palette.

The title screen also had its own bizarre palette bug. It was reading a table at one offset in the KULT executable that turned out to be a brightness fade-lookup ramp, not actual RGB data — which is exactly why the whole title initially rendered in spooky shades of red! Pointing it at the title’s actual 16-colour palette brought the gorgeous artwork fully back to life.

 Before:

After:

Decoding the Sprites

The sprite banks were the trickiest reverse-engineering puzzle of the week. They share the EGA record layout, but with two fun twists:

• The record size is stored big-endian.

• The width/height byte pair is swapped.

The pixels themselves are word-planar — one big-endian word per four-pixel column. I added appendFromStreamAmiga() to decode them, a shared placeholder for any missing sprites, and successfully loaded the merged Amiga banks (SPRIT/PUZZL/A/B).

Scripts and Threads

Two subtler bugs came next:

• The Padding Bug: The Amiga script blob inserts 0x00/0xAA padding for word alignment right in the middle of instructions. The engine didn’t expect this and was aborting scripts early (for instance, the Twins’ serpent-jaw redraw would just randomly stop). Instructing the engine to skip that padding fixed it instantly.

• The Racing Thread: I also had to explicitly skip animateGauss on Amiga, because it runs on the timer thread and blitting from there directly races the main render thread.

The Ending and Final Polish

The endgame sequence needed several specific fixes to shine:

• Saucer Animation: The vblank flush originally only pushed the chunky screen buffer for EGA, meaning the in-place saucer take-off animation never reached the Amiga screen. Now, it correctly flushes for any EGA-like renderer.

• End Screen Noise: The engine was trying to decode the planar Amiga PRES.BIN with the CGA splash loader, turning the ending into a band of static noise. Loading it properly and restoring the title palette fixed the climax.

• Infinite Loops: The non-US end path used to loop forever on an empty busy-loop, causing the host OS to report a frozen, “not responding” application. Now it cleanly pumps the event loop, holds the end screen until the player clicks or presses a key, and then returns gracefully to the launcher.

• Portrait Pacing: Portrait animations were pacing off a busy-wait loop that collapses to nearly zero on fast modern CPUs, making them run at lightspeed. They are now properly paced by wall-clock time.

• UI Borders: The rectangular UI boxes finally had their borders corrected and the right color as well.

Next Week

With the European Amiga version playing through cleanly, next week I’ll turn my full attention to the US variant. I’ll be checking exactly how its assets and text differ to bring it up to the exact same standard. The hardest groundwork is done; now it’s all about making the second variant just as rock-solid as the first!

These are some versions from before I find the right palette:

Tuesday

Not a lot happened this week because I was travelling.

the hfs file system

The file system used by old mac computers was the Hierarchical File System (HFS). And for director engine that meant a bunch of issues, like allowing the weird file names (solved by punycode) and resource forks.

Mac files have two parts: a data fork and a resource fork. For Director games, the projector executable lives in the data fork, but the startup movie (the first thing the game loads) is in the resource fork.

When ScummVM detects a Mac Director game, it hashes the resource fork specifically (using the r: prefix in detection entries) rather than the data fork, because the data fork is just the generic Director player and would be identical across many games.

This week I added detection entries for Gus Goes to Cyberopolis, both Windows and Mac versions. The process was interesting: you add a placeholder entry with a garbage hash, compile, point ScummVM at the game folder, and it reports back the real hash and file size for you to fill in.

I also learned why two-file detection entries (MACGAME2, WINGAME2) matter: with a single file, ScummVM just picks whichever game has the most files matching, which can cause false matches when multiple games share a disc. Two files makes the match unambiguous.

For Windows, it’s a bit different. The .exe file is actually three things concatenated together: the generic Director projector code, the startup movie, and a small header at the end that stores the offset to the movie. The executable would read its own tail to find the header, then seek back to load the startup movie. This is why ScummVM can’t hash the first 5000 bytes of a Windows Director executable, they’re always identical across every game built with the same Director version. Instead it hashes the last 5000 bytes (t: prefix), which come from the embedded startup movie and are unique to each game.

ImageDiff Integration (final)

I also worked on integrating ImageDiff into the ScummVM buildbot.

I have mentioned about the imagediff tool in my past blogs in detail. It was currently running on a detached tmux session, which is kind of a hack, so sev gave me some resources to read and integrate the tool into actual buildbot.

This process unfortuntely took a lot of time for me, because this was my first time in a long time dealing with a different kind of code.

The integration used a buildbot plugin called buildbot-wsgi-dashboards, which lets you embed a Flask web app directly into the buildbot UI. Getting it to work involved fixing a few issues. Most of the issues were trivial but there was this one issue which was causing a lot of problem and I wasnt able to figure out the root cause for, for the longest time.

The issue was, whenever I loaded the imagediff page on the buildbot, it would load unreliably i.e every time I would refresh the page, I couldn’t predict whether I would get a “Resource not found” error or the page would actually load. On top of that the table wasn’t loading properly.

The fix was actually two separate issues. First, the environment variables weren’t being loaded early enough, the SCREENSHOTS_DIR variable was being read at import time before the .env file had been loaded, so it defaulted to ./screenshots/ which didn’t exist on the server. Adding load_dotenv() at the top of config.py fixed that.

The second issue was the JavaScript on the frontend constructing API URLs without the correct path prefix. Since ImageDiff is served under /plugins/wsgi_dashboards/imagediff/, a hardcoded /api/target_data/... URL would 404 every time. The fix was deriving the base path dynamically from window.location.pathname at runtime. That’s why the page was loading unreliably, depending on timing and caching, sometimes the old URL worked by accident and sometimes it didn’t.

After sorting all of that out, ImageDiff is now properly integrated into the ScummVM buildbot at john.scummvm.org. But it’s still rough around the edges, and the remaining issues will be handled by sev.

PRs:

Imagediff

Detection Entry

Hey everyone! This week I finally got back to the task given by Sev in my first week — converting all the raw struct casts in the Dungeon Master engine to portable byte-offset macros. This was responsible for undefined behavior that could cause crashes or wrong results on platforms with different endianness or alignment requirements.

Earlier it used to be like this:

// Struct definition
class TextString {
    Thing _nextThing;
    uint16 _textDataRef;
public:
    explicit TextString(uint16 *rawDat) : _nextThing(rawDat[0]), _textDataRef(rawDat[1]) {}
    bool isVisible() { return _textDataRef & 1; }
    void setVisible(bool visible) { _textDataRef = (_textDataRef & ~1) | (visible ? 1 : 0); }
};

Now it looks like this:

#define TEXTSTRING_nextThing(address)   (Thing(READ_LE_UINT16((address) + 0)))
#define TEXTSTRING_textDataRef(address)  READ_LE_UINT16((address) + 2)
#define TEXTSTRING_isVisible(address)    (READ_LE_UINT16((address) + 2) & 1)
#define TEXTSTRING_setVisible(address, visible) WRITE_LE_UINT16((address) + 2, (READ_LE_UINT16((address) + 2) & ~1) | ((visible) ? 1 : 0))

And the call site changed from:

TextString textString(_thingData[kDMstringTypeText] + thing.getIndex() * _thingDataWordCount[kDMstringTypeText]);
if (textString.isVisible()) { ... }

To:

byte *textString = getThingData(thing);
if (TEXTSTRING_isVisible(textString)) { ... }

Why this refactor was necessary

This refactor was necessary because the original code relied on casting raw game data directly to C++ structs, which assumes specific object layouts, alignment, and byte ordering. These assumptions are not guaranteed across different architectures, especially on big-endian machines. By switching to explicit byte offsets and endian-aware accessors, the engine now accesses game data in a portable and predictable way.

Lesson 1:

It was a massive refactor across 13 structs in the engine and required multiple attempts. My first approach was still broken — I wrote:

uint16 getTextDataRef() const { return READ_LE_UINT16((const uint16 *)this + 1); }

I thought using READ_LE_UINT16 alone would fix the portability issue, but I missed the real problem: the C++ standard does not guarantee that a struct’s members are packed without padding. A compiler is free to insert padding between members, so the second field is not guaranteed to be located exactly one uint16 after the start of the object. As a result, (const uint16 *)this + 1 may not point to the second field at all. READ_LE_UINT16 handles endianness correctly, but it can’t save you if you’re reading from the wrong offset in the first place.

Lesson 2:

After converting all the struct methods to macros operating on byte *, I still had an issue at the call sites. I was passing non-byte * pointers directly to the macros, relying on the cast inside the macro definition to handle it. While this compiled and ran, Sev pointed out that casts hide problems — you are forcing the compiler to interpret memory as a different type, relying on assumptions about object layout that may not hold on all platforms. By switching the call sites to use byte * explicitly, the macros now operate directly on raw data using fixed byte offsets rather than through potentially misleading type casts.

Result

In total, this refactor touched 13 classes throughout the Dungeon Master engine. After several iterations, the final result is a portable implementation that accesses serialized game data explicitly through byte offsets.

Another Freeze

Towards the end of the week I continued my playthrough of the game and reached level 9 out of the 13 dungeon levels. During testing I encountered another freeze when interacting with a Wizard Eye monster. After some debugging, I found that the issue originated from projectile allocation. Wizard Eyes attack by spawning projectile objects, which are allocated through getUnusedThing(). However, the size of projectile data was being incorrectly divided by two using >> 1, causing the engine to allocate only 2 words instead of the required 5. In ScummVM, _thingDataWordCount already stores sizes in words, making the division unnecessary.
Before:

int16 thingDataByteCount = _thingDataWordCount[thingType] >> 1;

After:

int16 thingDataWordCount = _thingDataWordCount[thingType];

As a result, newly spawned projectiles overlapped existing objects in memory and corrupted their linked-list pointers. In the failing case, a projectile’s next pointer was overwritten and linked back to Door 0 instead of terminating at _thingEndOfList, creating a cyclic linked list on that map square. The rendering function drawObjectsCreaturesProjectilesExplosions() then looped infinitely while traversing this list, freezing the game. Removing the obsolete >> 1 division restored the correct allocation size and resolved the issue.

That was it for this week. Next week I plan to finish my gameplay testing of Dungeon Master, continue hunting for any remaining issues, and start implementing the remaining unimplemented methods in the engine. See you in the next one. Until then, goodbye! 🙂

Hey, now you can run bigger games on PS3 with our new multi-engine modules version package.

This package reduces ScummVM's memory usage by approximately 90 MB by loading engines as separate modules, leaving more memory available for games.

For more information, see the PS3 platform documentation page.

Week 4: Phantom Pixels, a Lying Clock, and the Effects That Never Played

Welcome back! Last week ended on a high note: the endgame finally ended, and the Kult EGA port was playable start to finish. This week was all about the ultimate QA test: a full, end-to-end playthrough to hunt down the final remaining gremlins. Quick heads-up: I have more stories than usual to tell you this time! 🙂

And spoiler alert: we did it. The game is now incredibly stable and essentially bug-free! The final polish came down to fixing subtle rendering gremlins that survive a normal playthrough, and finally implementing the EGA visual effects the port had quietly left as empty stubs.

A theme ran through almost everything: EGA stores four bytes where CGA stored one, and a lot of inherited code never got the memo—either by doing CGA math in an EGA world, or by not doing the work at all. Here are the final stories that stood between the EGA port and perfection.

Story 1: The Garbage at the Top of the World

Some rooms—like Placating the Powers, where you face the High Priestess—have animated objects scattered around: flickering torches, glowing runes, things that breathe. And in those rooms, a band of garbage pixels kept getting stamped across the very top rows of the screen. Not flickering. Not reverting. Just… smeared there, like the engine wiped its hands on the ceiling.

The mechanism behind animated spots is clever and frugal. Before the engine draws a moving object, it backs up the background underneath it so it can restore it cleanly next frame. Those backups live in a scratch buffer, and right after them—at a fixed +1500 byte offset—the engine loads the animation sprites themselves (lutin sprites).

scratch_mem1  ──► spot backups
scratch_mem2  ──► scratch_mem1 + 1500  ──► lutin sprites

That 1500-byte gap is the original CGA budget. And there’s the trap: in CGA, each backed-up pixel is packed 4-to-a-byte. In our EGA port, every pixel is stored as a full CLUT8 byte—four times the size. A backup that needed 1500 bytes on CGA needs up to 6000 on EGA.

So, the backups overran their 1500-byte fence and spilled straight into the lutin region. The next sprite load then clobbered the backup headers—and a corrupted header means a corrupted offset, with an X coordinate no longer aligned to 4. When the engine dutifully restored those backups, it pasted them at a bogus, top-of-screen position. The garbage band was the engine faithfully restoring backups it could no longer find.

The fix was to teach the memory layout about EGA’s appetite. I sized the gap for the EGA worst case, and grew the scratch buffer so neither a fat backup nor a fat sprite can overrun its neighbor:

// Spot-backup gap: EGA worst case is 4x the CGA budget
gap = 6000;                 // was 1500
scratch_mem1 = gap + 12800; // gap + EGA lutin worst case

No more overrun, no more clobbered headers, no more graffiti on the ceiling.

Story 2: The Clock That Lied

Vorts and turkeys (yes, turkeys) are timed encounters. They’re supposed to wander into a room, hang around, and leave on a schedule. In my build, they were teleporting in and out at the wrong moments, blinking on for a frame, vanishing, and leaving little visual scars behind. The room felt haunted.

The encounter logic is a simple comparison: has enough time passed yet? It checks an encounter deadline (next_vorts_ticks, next_turkey_ticks) against the global timer (timer_ticks2). Straightforward—except the two numbers weren’t speaking the same dialect.

The deadlines are stored as plain numeric values (host endianness). The global timer is stored big-endian. Comparing them directly is like comparing 0x0100 against 1 and wondering why the alarm keeps going off early. The clock wasn’t broken—it was just lying about what time it was.

The fix is a one-sided byteswap so both operands are honest numbers before the comparison:

if (next_vorts_ticks <= Swap16(script_word_vars.timer_ticks2)) { ... }

With both sides numeric, the vorts and turkeys finally keep their appointments instead of strobing through the walls.

Story 3: The Scan That Gave Up a Quarter of the Way

This one I caught live, mid-playthrough. The Zone Scan PSI power sweeps a horizontal line down the room to reveal hidden objects. The line is supposed to travel cheek to cheek across the whole play area.

In EGA, it covered exactly a quarter of the width and stopped dead.

You can probably guess the villain by now—it’s Story 1’s twin. Room coordinates in this engine are measured in 4-pixel blocks. The scan’s starting offset is computed by calcXY_p, which correctly scales the block coordinate by 4 for EGA’s one-byte-per-pixel buffer. But the width of the line being inverted and blitted was the raw block count, used directly as a byte count:

• CGA: one byte = 4 pixels, so w bytes cover the full width.

• EGA: one byte = 1 pixel, so w bytes cover… one quarter.

Same root cause as the backup overflow—a CGA-era width used unscaled in a 4x wider EGA world. The fix is to scale the width by 4 in EGA (and widen the loop counter, since w * 4 no longer fits in a byte):

// Room coords are 4-pixel blocks; EGA is 1 byte/pixel
uint16 pw = (videoMode == kRenderEGA) ? (uint16)w * 4 : w;
for (px = 0; px < pw; px++)
    frontbuffer[offs + px] = ~frontbuffer[offs + px];

The scan now sweeps the full width, the way the designers intended—and the hidden flask reveals itself like it’s supposed to.

Story 4: The Ending That Almost Wasn’t

Fixing last week’s confrontation loop got me to the victory sequence—which had its own pile of problems. You win, the screen pans up to a flying saucer receding into the sky, and THE END drops in. Instead, my EGA build crashed with a divide-by-zero, and on the runs that somehow survived, the saucer shot off-screen and the logo was clipped or missing. One ending, five bugs:

1. The crash: The end-logo frame descriptor was missing from the table, so the portrait builder read a frame width of zero and divided by it. Restoring pers_frames[9] (plus a defensive guard) killed the SIGFPE.

2. The runaway saucer: Our recurring villain again—the saucer’s path X, read from SOUCO.BIN, was treated as a 4-pixel-byte column and multiplied by 4. In EGA it’s a raw pixel column. Dropping the *4 put it back on its flight path.

3. The saucer that wouldn’t shrink: The EGA zoomImage and zoomInplaceXY functions were non-scaling stubs that ignored the target size and redrew at native size every frame. I wrote a real nearest-neighbour scaler so the saucer actually recedes properly.

4. The clipped ‘D’: The scaler sampled with (srcW-1)/dstW, which drops the final source column—shearing the right stroke off the D in THE END. Switching to srcW/dstW makes a 1:1 draw the identity map.

5. The rising red dot: The cutscene cleared its buffer with sizeof - 2, leaving the bottom-right two pixels uncleared. CGA never noticed; EGA’s scroll-reveal lifted them up the screen as a tiny red balloon riding the saucer. Clearing the whole buffer sent it home.

Now, the saucer rises, shrinks, and slips away; THE END lands cleanly; and nothing divides by zero on the way to the credits.

Story 5: The Effects That Never Played

The last piece of polish wasn’t a bug—it was a blank. Walk between rooms in CGA and the world animates: when you stride The Ring or the passages, the background spirals in over the old room before the new one appears; elsewhere there are lift wipes, a dot dissolve, and zoom-in reveals. In EGA, all of these were stubbed out—rooms just snapped. Functional, but lifeless, and not what the designers built.

So, I implemented the EGA renderer’s transition effects to match the original CGA:

• The spiral reveal for The Ring and passages (finally wiring up a flag, skip_zone_transition, that had been sitting unused, which decides when the spiral should play).

• The lift wipes (the room block slides up / down / left / right one line per step).

• The dot dissolve.

• The zoom-in reveals.

It’s the kind of work that’s invisible when it’s done right—and that’s exactly the point. Room changes in EGA now have the same texture and rhythm as the original, instead of cutting like a cheap slideshow.

What’s Next: Expanding the Scope

With these final quirks down, a clear pattern emerged: the deepest EGA bugs weren’t logic errors, they were unit mismatches and missing pieces. Fixing them was the final piece of the puzzle.

After applying these patches, I completed a full start-to-finish playthrough of the main EGA port without encountering a single glitch, crash, or graphical artifact. But Kult isn’t just one version. Now that this primary EGA build is rock-solid, my focus for next week shifts to full regression testing. I will be diving into the other EGA releases and the original CGA versions, playing through them to ensure my engine fixes didn’t break anything else, and making sure the entire Kult family runs perfectly in ScummVM.

Thanks for reading, and see you next week!

So far, we are able to keep the release cadence. This quarter, the team is bringing you a set of new and old, all exciting features!

Newly Supported Games:

• Nancy Drew: The Haunted Carousel
• Nancy Drew: Danger on Deception Island
• Noctropolis
• Cartoon Carnival
• Alfred Pelrock: En Busca de un Sueño
• Pilot Brothers: On the Track of Striped Elephant
• Pilot Brothers: The Case of Serial Maniac and 5 more games on the same engine

General enhancements

This was the period of the Google Summer of Code start, so we had an influx of new contributors, who were busy with improving our GUI, adding small and big quality-of-life features, such as improved search, kinetic scrolling, and revamped About dialog.

Engine bugfixes and improvements

Ten supported engines got their tweaks and improvements. Martian Memorandum got script bug fixes, Simon 2 multilanguage support became better, there is a new whole control panel for the GLK engine, allowing to adjust text rendering, Last Express had some corner case bugs squashed, which also happened to the Rex Nebular. Might and Magic 1 had major rewiring of its keymapper, and the enhanced patch support plays better than ever.

There was active work on the Nancy engine, and besides the two newly added games (number 8 and 9), most of the already supported games in the series received their bug fixes (thank you very much for submitting bug reports).

Two new games landed to the SLUDGE engine, and we made them downloadable from our website. And last but not least, the TwinE engine, used for the Little Big Adventure series, got its own measure of bugs fixed.

On the ports side, the Atari port is an ongoing constant series of big and small optimizations, and the PlayStation 3 port is easier on the memory consumption, allowing heavier games to be played.

For more detailed itemization of the improvements, you may refer to the release notes.

And as per our new release procedure, the port builds will be arriving within the next few weeks.

ScummVM has officially wrapped up on Gamos’s Windows proprietary game engine. The engine originally powered Pilot Brothers 1 & 2, launching the iconic adventure series before it later transitioned to qdEngine and NGI tech. The engine was also widely used to build a wave of office time-killer games.

This engine adds support for 7 games:

• Patience
• Flip-Flop
• NetWalk
• Pilot Brothers: On the Track of Striped Elephant
• Pilot Brothers: The Case of Serial Maniac
• Vitamin
• WildSnake

So, if you would like to remember the past and spend some time with two eccentric detectives, Chief and Colleague, or kill some time with Solitaire-style games, you need the latest daily development build and the game’s required data files. As always, if you encounter any irregularities or oddities, please submit those to our bug tracker.

Wednesday

This is the follow-up to the previous post.

The Blunder

The first task was integrating ImageDiff into the buildbot repo.

The first PR was wrong immediately. I added the files directly without bringing in the git history from the original ImageDiff repo. Sev had asked for history. The PR wasn’t mergeable, and sev fixed the git situation himself rather than have me fight with it. First mistake.

Then the actual blunder. When wiring ImageDiff into the buildbot’s Python pipeline, I hit an import error imagediff.py does from config import SCREENSHOTS_DIR at module level, which breaks when imported from a different directory. Instead of reading the error and fixing it, I asked an AI, got an importlib workaround, and pushed it.

Sev said in the chat, “please don’t do that anymore, asking AI and pushing the slop I mean.”

The correct fix was a one-line sys.path insert, something I’d have found in two minutes if I’d just read what the error was saying.

Deployment

After the ImageDiff PR merged, I was hesitant to deploy directly on the buildbot server as I didn’t want to break anything.

In response I was given the green light to break it, because we already have a VM snapshot saved.

Deployed, it worked, buildbot was up with ImageDiff integrated.

The Misunderstanding That Cost the Most Time

Once it was running, sev noticed the tool was timing out on target: theapartment-mac, he found it and pointed toward the cache logic.

That was a part of it. The cache logic was kind of flawed. But we had a bigger elephant in the room.

The real problem was something I hadn’t understood about how the tool was supposed to work at all.

The movie_diff() function was opening every PNG frame from both builds with PIL, running ImageChops.difference() on each pair, and checking to detect any pixel difference.

But it was completely wrong. The Director engine already does the pixel comparison during playback, in score.cpp. It compares each new frame against the stored reference using a pixel difference threshold, and only saves the file to disk if the difference exceeds that threshold.

So, file presence is the diff signal.

The fix was replacing all the PIL logic with: does any file matching {movie}-*.png exist in the comparison build’s directory?

I didn’t know the engine had this mechanism. PIL was redundant work the engine had already done.

The Punycode Crash

After the performance fix, a new crash appeared:

ValueError: chr() arg not in range(0x110000)

The movie name causing it was xn--xn--File IO-oa82b-. Sev explained why this exists.

Mac HFS allowed file names with characters that would be illegal on any normal filesystem  /, *, newlines, etc. “The Apartment” has movies named things like File I/O and •Main Menu.

To store these on a normal filesystem, sev designed an encoding scheme based on Punycode: files with special characters get an xn-- prefix, the special characters are removed from the name, and their positions are encoded in the tail.

xn--xn--File IO-oa82b- is doubly encoded, it went through the encoder twice, which is valid, it just needs two decode passes to get back to File I/O.

The bug was in decode_string(). There was a loop that stripped trailing dashes from the string before handing it to the punycode decoder:

i = len(orig) - 1
while i >= 0 and orig[i] == "-":
i -= 1
orig = orig[:i+1]

For xn--xn--File IO-oa82b-, this strips the trailing - and corrupts the input before the decoder even runs. Removing it was the entire fix. Without the loop, Python’s punycode decoder handles the string correctly.

Director Debugger

Three things on the dt-new branch:

Cast Details Panel: was showing ... for almost everything. Now shows : script text previews on hover with click-through. The old showScriptCasts pipeline was removed entirely everything now goes through renderScript.

Scripts Window: decoupled from the execution context, which previously shared state with it. The scripts window now has its own handler list and browser-style back/forward navigation.

Also fixed a bug where the Lingo/Bytecode toggle was a single global flag shared across all open handlers.

Keyboard Shortcuts: Cmd+2/3/4 toggle Control Panel, Cast, Score. On Mac, cmd instead of ctrl must be used.

PRs

scummvm-sites #39 · #40 · #41 · scummvm #7577

Hi, this is week 3 of my GSoC journey. After spending the last two weeks chasing crashes across the DM engine, this week turned into something more like detective work — digging into array indices, stale pointers, and byte alignment bugs that were quietly corrupting things under the hood.
This week, I faced freezes along with crashes. Some of these bugs only revealed themselves when stress-testing specific actions, like throwing explosives at a creature group, which would lock up the game entirely instead of just throwing an error.

Stride and Seek

Flying items rendering with garbled pixels when shrunk on screen. The cause was in blitToBitmapShrinkWithPalChange, which computed the destination row stride from destPixelWidth, the raw pixel width. But allocated bitmap rows are actually 8-byte aligned via getNormalizedByteWidth, so the real stride is wider than that. Using the raw width meant every row started at the wrong offset, bleeding into the next and corrupting pixel data.

Fix: compute destStride = getNormalizedByteWidth(destPixelWidth / 2) * 2 and use it instead of destPixelWidth when indexing destLine = &destBitmap[destY * destStride]

Before:

After:

The Defense Drift

Next was a crash in processEventEnableChampionAction, but the more dangerous part of this bug wasn’t the crash. _actionDefense is a lookup table indexed by action type, via _actionIndex, but the code was indexing it with curChampion->_actionDefense instead, the champion’s current defense value. That’s an arbitrary runtime number, not a valid index, so when it grew large enough to exceed the table size, the read went out of bounds and crashed outright. That part was at least loud and easy to notice.

The real problem showed up when the stat stayed within bounds. The lookup would quietly succeed, but against the wrong table entry, subtracting an incorrect defense bonus every time a combat action ended. There was no crash, no error, nothing to flag it. Just a small wrong number applied again and again, every fight, every action. Over enough time, that drift compounded into a champion whose defense stat had wandered far from what it should be, sometimes ending up nearly immortal, sometimes alarmingly fragile, with nothing in the logs to explain why.

Fix: a one-character typo fix, replacing _actionDefense[curChampion->_actionDefense] with _actionDefense[curChampion->_actionIndex].

The Gimme Slot Bug

Next one came from the gimme debug command. Cmd_gimme loops over every slot for a given thing type, but unused slots have their first word set to thingNone and the loop wasn’t checking for that before passing them to getIconIndex, which calls into getWeaponInfo or getObjectType. Those ended up reading garbage from empty slots, sometimes crashing.

Fix: read the raw first word of each slot, and skip it with continue if it equals thingNone.

The Duplicate Item Bug

Another gimme bug. When it allocated a new item slot by copying thing data and bumping _thingCounts, it forgot to update dummyThing’s index to point at the new slot, still handing over the original thingIndex instead of thingCount. Two references ended up pointing at the same thing slot, causing duplicate item corruption and crashes whenever one reference was modified or deleted.

Fix: one line, dummyThing.setIndex(thingCount), after the allocation.

The Object Aspect Crash

Next one was inside drawObjectsCreaturesProjectilesExplosions, the function responsible for rendering objects, creatures, and projectiles in the dungeon view. It chained getObjectInfoIndex straight into _objectInfos[...]._objectAspectIndex and then into _objectAspects209[...], all in one expression, with no validation along the way. But getObjectInfoIndex can return an out-of-range value for invalid or corrupt things, and _objectAspectIndex itself can exceed k85_ObjAspectCount, causing crashes.

Fix: guard both indices before use, skipping the object with continue if either is out of range.

An Enum That Wasn’t One

Next one was about ActiveGroup::_directions, typed as Direction, an enum. But the field doesn’t actually store a single direction, it stores packed 2-bit direction values for up to 4 creatures combined together, built via getGroupValueUpdatedWithCreatureValue. That’s a bit-packed integer, not a valid enum value, and casting a packed integer to an enum type is undefined behavior in C++.

Fix: change the field type from Direction to uint16, and remove the (Direction) casts at every assignment site, letting the packed value be stored and manipulated as a plain integer like it should’ve been.

The Freeze That Wouldn’t Crash

This one ate up most of my week, and it didn’t go down easy. The game would freeze, not crash, whenever explosives were thrown at certain creature groups. No ASan output to point at anything, since nothing was actually invalid memory. GDB’s backtrace wasn’t any more helpful either, it didn’t even surface the method actually responsible.
So it came down to reasoning it out manually. The freeze only ever happened when throwing explosives at a group with loot to drop, which meant something to do with damaging groups and handing out their possessions. That pointed toward GroupMan, so I started going through its methods one by one, comparing them against the original reversed code to spot where our implementation had drifted.
That led to dropCreatureFixedPossessions, which iterates a fixedPossessions pointer array to hand out loot. Two early-exit continue paths, one for skipping a random drop, one for when no unused thing slot was available, both forgot to advance the pointer before looping back. Without that advance, the loop kept re-reading the exact same array entry forever, spinning in place instead of crashing.

Fix: advance currFixedPossession = *fixedPossessions++ in both continue branches before skipping, so the loop always makes forward progress.

The Projectile Crash

Next one started simple, throw a sword or any projectile, and the game crashed. No obvious cause at first. Going through the methods from the GDB backtrace one by one eventually led to initializeGraphicData, where the loop over 6 projectile scale levels was writing all 6 byte-counts to the same fixed offsets, derivedBitmapIndex, derivedBitmapIndex+6, derivedBitmapIndex+12, every iteration, missing + projectileScaleIndex. Only the last iteration’s values stuck, leaving every earlier entry sized incorrectly.

Fix: add + projectileScaleIndex to all three cache offsets, so each scale level writes to its own correct slot.

New Addition

Added a nuke debugger command. Killing monsters manually just to clear a path for testing wasted time, so nuke finds the group directly in front of the party via mapCoordsAfterRelMovement and groupGetThing, then removes it instantly with groupDelete. No gameplay impact.

Tuesday

No, this is not my last post. I am just rushing because today is the last day to post for the previous week and I am not sure how long will I have a stable internet connection.

I will not be online (probably) for the next 2 days, because I am in a very remote location (mountains) so internet access might be a problem. So, this post will get straight to the point.

I made a very big blunder this week, and a lot of code was rushed. But the week ending was good. Got to learn a lot. And very interesting story to tell.

I will make a detailed post for this week after I get a stable internet connection.

See you soon.

Good news for adventure game fans: Alfred Pelrock is now supported in ScummVM!

Originally released in 1996, Alfred Pelrock is a humorous point-and-click adventure featuring cartoon-style graphics, quirky puzzles, and an irreverent sense of humor. After dreaming of an Egyptian princess imprisoned in the distant past, Alfred embarks on a time-travelling adventure to Ancient Egypt to rescue her, encountering bizarre situations and eccentric characters along the way.

While the game is packed with comedy and satire, players should be aware that it also includes mildly suggestive themes and occasional adult-oriented humor typical of its era. It is also worth noting that the game was released exclusively in Spanish and has no official translations.

As always, if you own an original copy of the game and speak Spanish, grab the latest daily development build, add the game’s required data files and enjoy. We also welcome bug reports. and feedback from players to help improve compatibility and preserve this quirky piece of adventure gaming history.

Come one, come all! Hanna-Barbera's Cartoon Carnival is now ready for public testing in ScummVM.

Originally developed and released for Philips CD-i in 1993 by Funhouse Design and then ported to Windows and Macintosh in 1995, Cartoon Carnival brings together a cast of familiar Hanna-Barbera characters in a collection of short arcade-style minigames. Scooby-Doo, Fred Flintstone, George Jetson, Top Cat and friends each get their turn in different challenges, ranging from mazes and pattern matching games to balloon catching and trivia quizzes.

Rather than a traditional adventure game, this is a colorful piece of mid-90’s multimedia entertainment, full of animation, voices and music. It is also one of those licensed titles that can easily slip through the cracks, so we are especially happy to help keep it playable on modern systems.

At this time, only the Windows and Macintosh versions are supported. The original CD-i version is not supported.

To test the game, you will need the latest daily development build and either an original copy of the Windows or Macintosh release, or its demo (which we were only able to source in Italian). Please check the wiki page for the required data files.

As usual, please report any issues to our bug tracker, including the version you tested, your platform, and any useful screenshots or save files.

Step right up, pick a game, and help us make sure this carnival runs properly!

Hey there, welcome back to the blog. The inventory is fully implemented and hence, we’re now able to drag the rung and open the fire exit, hurray.

Other than this, there’s no way to get out of this scene(except if you use the debugger console 😉 ).

Also if you notice, I have revived the original cursor of Beneath a Steel Sky here too.

Ever since I started the development on iBASS, I had turned the engine to 32 bits for both BASS and iBASS. Since the original beneath a steel sky featured an 8 bit colour depth, sev suggested to revert it back to make BASS run in 8 bpp mode which I successfully did. Now, BASS is running in 8 bpp and iBASS in 32 bpp.

There was one more crash I encountered at this phase of the game-See the cursor at the right edge of the window? That is the exit. But when I clicked on it, it hit this assert. To fix this, I guarded this call to never draw out of the boundary of _screen32.

I also performed some refining in the LINC terminal.

Major tasks that are still left to be done include implementing the text chooser. Here’s a snippet from the original Beneath a Steel Sky regarding the text chooser-

Currently, we cannot do this in iBASS. Some other tasks yet to be done include fixing the transparency issue in the inventory icon, render the cog icon for the control panel on the top left, etc. All this while we have no audio yet along with the intro and the outro.

Also, I had an important announcement to make. I’ll be away for the next few weeks due to some personal reasons. As agreed with my mentor, I will be unavailable from 13 June to 3 July. I’ll be catching once I return. Thanks, and talk to you all in a few weeks.

Thanks for reading 🙂

Tired of running a mundane bookstore and ready to dive into the gritty, neon-drenched pages of a comic book? Get your trench coat ready, because Flashpoint Productions’ 1994 dark adventure, Noctropolis is now ready for public testing!

In this interactive comic brought to life you play as Peter Grey, a lonely bookstore owner pulled into a dystopian superhero world where the sun never shines. With the legendary hero Darksheer retired, it is up to you to take on his role, solve the puzzles, and save the city from a cast of villains doing the bidding of a mysterious force.

To help us test, you will need your copy of the game data files and a recent daily development build of ScummVM.

Support has been added for both the original DOS release (including demos) and the Nightdive Studios digital re-release, which is available from GOG or Steam.

As you patrol the dangerous streets, please report any issues you find on our bug tracker.

The city needs a hero – will you answer the call? Happy crime-fighting!