{"id":45,"date":"2026-06-15T18:53:37","date_gmt":"2026-06-15T18:53:37","guid":{"rendered":"https:\/\/blogs.scummvm.org\/andy\/?p=45"},"modified":"2026-06-15T19:13:08","modified_gmt":"2026-06-15T19:13:08","slug":"week-3","status":"publish","type":"post","link":"https:\/\/blogs.scummvm.org\/andy\/2026\/06\/15\/week-3\/","title":{"rendered":"WEEK 3"},"content":{"rendered":"
\n
\n

The Endgame That Ate Itself<\/h2>\n

Welcome back! After last week’s rampage through tunnels, ghosts, and greedy opcodes, the EGA port was finally playable. So this week, I did what any reasonable person does with a newly playable game: I tried to actually beat it.<\/p>\n

That\u2019s when the final boss fought back\u2014not in the story, but in the engine.<\/p>\n

Story 1: The Confrontation That Wouldn’t End<\/h3>\n

The endgame features a tense confrontation sequence. You whittle the enemy down, and at the climax, you use the “PSI POWERS” menu to win the game. In my playthrough, I successfully gave the enemy the winning item… but nothing ended.<\/p>\n

Instead, the confrontation menu re-prompted me as if nothing had happened. Because the win state had already been consumed, the engine immediately threw me into a forced game-over. Worse, the longer this loop dragged on, the more the screen fell apart: sprites glitched, the rendering corrupted, and the game’s global variables seemingly rewrote themselves at random.<\/p>\n

Two symptoms\u2014a looping menu and creeping visual corruption\u2014almost always point to one thing: a stack overrunning its bounds.<\/p>\n

I dug into the engine and found the culprit: script_stack<\/code>, a tiny 5-frame array used to track nested script calls. The original DOS game had a “priority command” mechanism. When a priority command fired, the original assembly engine would yank the script stack pointer all the way back to a known baseline, effectively throwing away whatever nested call chain was in progress.<\/p>\n

Our C++ port never restored that pointer. So, every time a priority command fired from inside a subroutine, it quietly leaked one script_stack<\/code> frame. In the endgame, every single use of “PSI POWERS” fires a priority command. If you use it five times, the 5-frame array overflows, scribbling over the globals that live right next to it in memory. That explained the sprite garbage and the corrupted script state!<\/p>\n

Furthermore, each C++ call nested the menu one level deeper. When I finally won, the stack unwound only one<\/i> level, landing me back in a stale, “zombie” confrontation menu.<\/p>\n

The fix was an architectural shift to make our port honor the original DOS stack discipline. I restored the script stack pointer to its baseline when a priority command runs:<\/p>\n

\n
\n
\n
\n

C++<\/span><\/p>\n

<\/div>\n<\/div>\n
case<\/span> 0xF000<\/span>:\r\n    script_stack_ptr = script_stack;\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
Then, instead of re-entering the priority handler at whatever deep nesting level we happened to be at, I propagated the pending flag straight up to the main gameLoop<\/code>, draining all pending commands from a safe baseline:<\/p>\n
\n
\n
\n
\n
C++<\/span><\/p>\n
<\/div>\n<\/div>\n
do<\/span> {\r\n    g_vm->_prioritycommand_1 = false<\/span>;\r\n    g_vm->_prioritycommand_2 = false<\/span>;\r\n    res = runCommand();\r\n} while<\/span> (g_vm->_prioritycommand_1);\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
No more accumulating menu frames, no more overflow, and no more haunted endgame. The final puzzle actually triggers the victory sequence now!<\/p>\n<\/div>\n
Story 2: The Bugged Wall<\/h3>\n
Deep in the game, there’s a room called The Wall<\/i> \u2014 a massive gate you open and close by stepping toward it. Press the arrow once, and the gate slides halfway shut; press again, and it should slam closed, sealing the room in front of you. That’s the drama the designers intended.<\/p>\n
In my EGA build, the drama fell completely flat. The gate would slide in from the sides… and then just stop, leaving a big black void in the middle where solid stone was supposed to be. Half-closed left a small black gap; fully closed left a massive black hole. The wall looked less like an ancient sci-fi gate and more like someone forgot to finish painting it.<\/p>\n
The Wrong Suspects<\/h4>\n
My first instinct was that the closed wall was being drawn correctly, but then immediately erased. The engine keeps two copies of the screen\u2014a visible “front” buffer and a persistent “back” buffer used to redraw things. I figured the freshly closed gate was living only in the front buffer and getting reverted by the back buffer a frame later. So, I wrote code to explicitly copy the gate into the back buffer after the animation.<\/p>\n
No change.<\/p>\n
So, I went bigger: I forced the game to re-run its full room-entry redraw routine after the gate moved. That immediately earned me a segmentation fault. Those routines simply aren’t safe to call in the middle of a script command. Two dead ends.<\/p>\n
The thing that finally turned the investigation around was a more precise look at the symptom itself: the center wasn’t reverting<\/i> to black, it was never drawn in the first place. And the more the gate “closed,” the more black space appeared. That didn’t sound like a state bug anymore. That sounded like a broken sprite.<\/p>\n
Reading the Bytes<\/h4>\n
The wall sprite isn’t one solid image\u2014it’s a little mosaic. The game stores it as a list of small tiles, each with an offset instructing the engine: “place me at this position in the door.”<\/i><\/p>\n
The original CGA code lays those tiles into a buffer that’s 20 bytes wide (80 pixels). Therefore, a tile’s offset maps to a grid spot like this: row = offset \/ 20<\/code>, column = offset % 20<\/code>.<\/p>\n
The EGA port I inherited was doing the math differently. It divided by 40 and halved the column. Rather than argue with myself about which formula was right, I opened the data file and printed the actual tile positions using both methods:<\/p>\n
    \n
  • \n
    Correct (CGA layout):<\/b> columns 0, 16, 32, 48 | rows 0, 30 \u2192 a full 4\u00d72 grid.<\/p>\n<\/li>\n
  • \n
    The EGA code’s version:<\/b> columns 0, 8, 16, 24 | rows 0, 15 \u2192 everything crushed into one corner.<\/p>\n<\/li>\n<\/ul>\n
    There it was. The EGA formula squashed every tile to half spacing on both axes, piling the entire door into the top-left quarter of its own frame. The rest of the gate\u2014most of it\u2014stayed completely empty. Black.<\/p>\n
    The animation and the draw code had been perfectly innocent the entire time; they were faithfully rendering a sprite that had been assembled wrong from the start!<\/p>\n
    The Fix<\/h4>\n
    The fix took just two lines. I made the EGA assembler agree with the original CGA math:<\/p>\n
    \n
    \n
    \n
    C++<\/span><\/p>\n
    <\/div>\n<\/div>\n
    \/\/ Before \u2014 squashed into a corner<\/span>\r\nuint16 row    = cgaOfs \/ 40<\/span>;\r\nuint16 colCga = (cgaOfs % 40<\/span>) \/ 2<\/span>;\r\n\r\n\/\/ After \u2014 full 20-byte-wide layout, like CGA<\/span>\r\nuint16 row    = cgaOfs \/ 20<\/span>;\r\nuint16 colCga = cgaOfs % 20<\/span>;\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
    Because that single function builds every wall sprite, the fix lit up everything at once. The half-closed gate, the fully closed gate, and the sliding animation in between all snapped into solid, properly-textured stone. The wall finally closes the way it was meant to.<\/p>\n
    \n
    Honorable Mention: A Faithful Roll of the Dice<\/h3>\n
    Last week, I seeded the RNG from the host’s millisecond timer to make encounters properly random again. However, my mentor Sev rightly pointed out that ScummVM has a native, deterministic way to handle randomness: Common::RandomSource<\/code>. If a tester wants to provide a fixed seed via the GUI to reproduce a bug, my timer hack would break that.<\/p>\n
    But here was the catch: the original game didn’t actually generate math-based random numbers on the fly. It used a hardcoded lookup table (aleat_data[]<\/code>) to guarantee a specific probability distribution. If I replaced the game’s dice rolls entirely with ScummVM’s modern RNG, I would lose the authentic feel of the original game.<\/p>\n
    I found a perfect middle ground. I kept the original DOS lookup table, but I used ScummVM’s Common::RandomSource<\/code> to pick the starting offset<\/i> of that table:<\/p>\n
    \n
    \n
    \n
    \n
    C++<\/span><\/p>\n
    <\/div>\n<\/div>\n
    void<\/span> randomize<\/span>(void<\/span>)<\/span><\/span>{\r\n    rand_seed = (byte)g_vm->_rnd->getRandomNumber(255<\/span>);\r\n    getRand();\r\n}\r\n<\/code><\/pre>\n<\/div>\n<\/div>\n<\/div>\n
    This honors ScummVM’s architecture (we get GUI configuration support for free) while keeping the original game’s exact probability sequence completely intact.<\/p>\n
    What’s Next<\/h3>\n
    The endgame actually ends! This feels like a massive milestone\u2014you can now play the Kult<\/i> EGA port from start to finish. Next week, I’ll focus on polishing, chasing down the remaining EGA-specific rendering quirks, and ensuring the whole experience is as stable as possible.<\/p>\n
    Thanks for reading \u2014 see you next week!<\/p>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
    The Endgame That Ate Itself Welcome back! After last week’s rampage through tunnels, ghosts, and greedy opcodes, the EGA port was finally playable. So this week, I did what any reasonable person does with a newly playable game: I tried to actually beat it. That\u2019s when the final boss fought back\u2014not in the story, but […]<\/p>\n","protected":false},"author":31,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-45","post","type-post","status-publish","format-standard","hentry","category-gsoc-2026"],"_links":{"self":[{"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/posts\/45","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/comments?post=45"}],"version-history":[{"count":3,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/posts\/45\/revisions"}],"predecessor-version":[{"id":49,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/posts\/45\/revisions\/49"}],"wp:attachment":[{"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/media?parent=45"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/categories?post=45"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.scummvm.org\/andy\/wp-json\/wp\/v2\/tags?post=45"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}