<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
<title>nebulo.computer · projects</title>
<link>https://nebulo.computer/projects/</link>
<description>Things Nebulo has built, from a 2D game engine written in x86-64 assembly to tools for family and friends.</description>
<language>en</language>
<lastBuildDate>Wed, 21 Oct 2026 00:00:00 GMT</lastBuildDate>
<atom:link href="https://nebulo.computer/projects/feed.xml" rel="self" type="application/rss+xml"/>
<item>
<title>asm-engine</title>
<link>https://nebulo.computer/projects/asm-engine/</link>
<guid isPermaLink="true">https://nebulo.computer/projects/asm-engine/</guid>
<pubDate>Wed, 21 Oct 2026 00:00:00 GMT</pubDate>
<dc:creator>Nebulo</dc:creator>
<category>projects</category>
<category>x86-64</category>
<category>opengl</category>
<category>glfw</category>
<category>ci</category>
<description>A 2D engine written from scratch in assembly, with a UI and post-process layer, and a self-built docs pipeline. All of it to make Last Stop, a Balatro-style bus ride card game.</description>
<content:encoded><![CDATA[<p>A 2D game engine written from scratch in x86-64 assembly, and <em>Last Stop</em>, a card game built on top of it. Both started as a university assignment: make a game in assembly. I wrote nearly all of the engine and some parts of the game, in a team of four.</p>
<figure><img src="https://nebulo.computer/content/projects/img/asm-engine-gameplay.png" alt="Last Stop gameplay" loading="lazy"><figcaption class="n-caption">Last Stop mid-stop: cards, answer buttons, HUD and the CRT shader</figcaption></figure>
<h2 id="source-0-3">Source 0.3?</h2>
<p>The engine is a static library. A game fills in one config struct (somewhat inspired by Valve's Source engine gameinfo.gi), registers its scenes and calls a single run routine. From there the engine owns the window, the frame loop, input, 2D drawing, text, sound and post-processing. The game only owns the rules and what the screens look like. The engine is about 4,800 lines of GNU <code>as</code> in AT&amp;T syntax, a good share of which is comments, only using GLFW, legacy OpenGL, stb_image, stb_truetype and miniaudio as dependencies. All of these are C libraries, and assembly calls them like any other C function.</p>
<p>What a game provides:</p>
<ul><li><strong>Scenes.</strong> A scene is a description of update, draw, enter and exit routines, and a layout. Switching is only <em>requested</em> during a frame and happens at the start of the next one, so a scene is never torn down while one of its own routines is still running.</li><li><strong>Virtual screen size.</strong> The game draws in fixed units of its choice (for example, 1280 by 720). The engine scales that to the window, keeps its shape with letterbox bars, and maps the mouse back the other way. Window size and framebuffer size are kept apart so HiDPI screens work.</li><li><strong>UI layer.</strong> A scene's layout is an array of rects, and a slot is an index into it. The game asks whether a slot is hovered, clicked, or was <em>just</em> entered, and decides for itself how it looks.</li><li><strong>Everything is a quad.</strong> Rects, outlines, sprites and text all go through one routine that draws a textured quad. A plain rect uses a one-pixel white texture, and OpenGL multiplies it by a given colour. Text bakes a font into an atlas and draws glyphs as sub-rectangles of it. The atlas is larger than necessary and sub-rects are drawn smaller so text stays sharp as the window grows.</li><li><strong>Post-processing.</strong> If the engine is given two GLSL shader paths, then every frame is drawn off-screen and through the provided shader. Our game uses it for a CRT look: curvature, scanlines, a soft bloom and a vignette.</li><li><strong>Sound.</strong> Effects are decoded into memory once and can overlap themselves; music streams one looping track. With no audio device the game just runs silently.</li><li><strong>Seedable random numbers.</strong> xorshift64 with a state the caller owns, so a game can keep separate streams.</li></ul>
<figure><img src="https://nebulo.computer/content/projects/img/asm-engine-ui.png" alt="Engine UI layer" loading="lazy"><figcaption class="n-caption">The UI layer: slots that lift and grow on hover</figcaption></figure>
<h3 id="design-choices-i-m-happy-with">Design choices I'm happy with</h3>
<p><strong>Zero means none.</strong> Textures, fonts and sounds are small integer IDs, and 0 is always &quot;nothing&quot;. Every routine accepts 0 or an unknown id and quietly does nothing. A missing asset makes the game look or sound wrong, but it never crashes it, and the reason is printed to stderr. This was crucial during development when assets weren't always available.</p>
<p><strong>State stays in its file.</strong> Each file owns its own data and no data label is ever global. If another file wants it, it calls a routine. So when you open a file, everything that can change its variables is in the file itself.</p>
<p><strong>Only two files are shipped.</strong> The game sees <code>engine.inc</code> (keys, config offsets, scene layouts) and nothing else. Everything else is hidden behind the library.</p>
<p><strong>C only where it has to be.</strong> There are a few things that I can't do in assembly. For example, there is no way to know how big a miniaudio struct is, so a tiny C file exports those sizes and the assembly code allocates exactly that many bytes.</p>
<h2 id="assembly-is-a-system-neo">Assembly is a system, Neo</h2>
<p>The course came with a set of rules, but I expanded upon them to improve readability across the codebase. Every routine has a stack frame, even the ones that call nothing. The stack is 16-byte aligned at every call. Callee-saved registers are saved and restored the same way every time. Labels, prefixes and comment blocks follow one scheme. No clever tricks, always prefer plain loops and instructions over optimisation, the goal of this project is to write readable, maintainable assembly.</p>
<p>Small rules can easily be missed, so I set up a Python tool that <strong>lints</strong> the conventions (names, doc blocks, stack frames, operand-size suffixes, no position-relative addressing) and <strong>generates documentation</strong> from the comments in the source. It runs in a pre-commit hook, so a commit that breaks a rule doesn't land, and the docs are always regenerated from the final state of the code. Comments are written as small doc blocks with a C signature above every routine, which meant the assembly could be read like an API.</p>
<h2 id="dhl-express-shipping">DHL Express Shipping</h2>
<p>The engine lives in its own repository on a Forgejo instance. When the version file changes on the main branch, CI builds the library and publishes a release tarball with the archive and the headers. The game pins an engine version in its Makefile, downloads that release on the first build, and caches it. Upgrading the engine is changing one number. It also kept us honest: the game only ever sees the library and its headers, the same as anyone using a library off the internet.</p>
<h2 id="last-stop">Last Stop</h2>
<p><em>Last Stop</em> is the game we built on this engine, a roguelike card game about a bus ride. A run is nine stops. At each stop you draw cards and answer four questions about the next card: red or black, higher or lower, between or outside, and whether its suit is already in your hand. Right answers add the card's chips and the question's mult, and the pot is chips times mult (a system VERY lightly inspired by Balatro). Reach the stop's threshold and you can get off, take your pay and visit the shop. Fall short and you spend a retry.</p>
<p>In the shop you buy passengers, with 29 of them across rarities. They bend the scoring in different ways. One gives hearts +3 mult, another doubles your mult on suit questions, and another grows stronger with every stop you clear. Every run plays from a seed, and the card order and the shop use separate random streams, so what you buy never changes the cards you draw. Using the same seed twice replays a run exactly.</p>
<figure><img src="https://nebulo.computer/content/projects/img/asm-engine-shop.png" alt="Last Stop shop" loading="lazy"><figcaption class="n-caption">The shop: passengers on offer, reroll, drive on</figcaption></figure>
<p>The game is split in three: a <strong>model</strong> that holds the rules and never draws, a <strong>view</strong> that draws from a state struct and never changes the run, and a <strong>controller</strong> that reads input and calls the model. Input is table-driven: rows of key, slot, handler and argument, so adding a control is simply adding a row.</p>
<h3 id="my-part">My part</h3>
<p>We were four on the game, and without my teammates none of this would've been remotely as good as it is, let alone possible. They made the assets, audio system, gameplay rules and logic, passenger system and the restructure into the model, view and controller folders. I did work on the following:</p>
<ul><li><strong>UI system</strong>: Slot drawing, hover effects, and a large rework of the HUD and theming in late development</li><li><strong>Post Processing</strong>: Wrote a GLSL CRT style shader and plugged it into the engine</li><li><strong>Gameplay Design</strong>: Balanacing the game mechanics and rules, and tuning the economics of the game to make it fair and rewarding.</li><li><strong>System Redesigns</strong>: Reworked passengers to have an upgrade system and overhauled the retry flow and win conditions.</li><li><strong>CI/CD</strong>: the build setup and the game/engine release pipeline</li></ul>
<figure><img src="https://nebulo.computer/content/projects/img/asm-engine-run.png" alt="Last Stop pay preview" loading="lazy"><figcaption class="n-caption">The pay preview before choosing retry or get off</figcaption></figure>
<h2 id="what-the-pain-taught-me">What the pain taught me</h2>
<p>Assembly isn't hard because the instructions are hard, it's hard because nothing tells you when you messed up. A missing register save shows up three calls later as a wrong colour. What made the project work was not cleverness but rules, tooling and small files. Our best decision was to have thin modules, one idea each, written so a teammate who has never seen them can read them.</p>
<p>It also changed how I read and approach higher-level code. A lot of game engine and graphics API concepts have become a lot more understandable now. I've also started to get into the habit of writing far more modular code and systems (no matter how high or low level the language is), not because it's more performant, but because it's more maintainable and easier to reason about.</p>
<hr class="n-rule">
<p><em>The source isn't public, because the work belongs to the university, though that may change. If it does, I'll link it here.</em></p>]]></content:encoded>
</item>
</channel>
</rss>
