Building a UEFI Boot-Layer Game with an AI Coding Assistant: Debugging Notes and Lessons

    This article documents the process of building a game in the UEFI boot environment with the help of an AI coding assistant, starting from third-party code that looked clean but would not run. It covers the constraints that make boot-layer development different (no OS, no system calls, no managed memory), the concrete debugging traps encountered — a dangling mode-information pointer after SetMode, and a protocol-locating error caused by the wrong GUID — and the fixes for each, followed by a round of optimization work. It closes with transferable practices for using AI coding tools in low-level or unfamiliar domains: review before editing, locate problems in layers with logging, respect memory and protocol lifecycles, and keep the key decisions in human hands.

    Why a Boot-Layer Game Is Worth Attempting

    When people discuss “what an AI coding tool is actually capable of,” they usually point it at web pages, shell scripts, or CRUD services. Those tasks are hard enough, but they all sit inside the shelter of a mature operating system: standard libraries, a runtime, ready-made graphics APIs. What really exposes a gap in capability are the “start from zero, close to the metal” scenarios.

    Writing a game in firmware / boot-layer code (UEFI) is exactly that kind of scenario. There is no operating system, no system call interface, and no library you can just call. To draw a single pixel you have to write directly into the frame buffer exposed by the graphics device; to read a key press you have to go through the firmware input protocol; you even have to manage the lifetime of your own memory. This build-every-wheel-yourself style of development places extremely high demands on code correctness — and it is a genuine litmus test for how well an AI coding assistant performs.

    The Constraints of Boot-Layer Development

    Before a program can run under UEFI at all, a few non-negotiable premises have to be understood:

    • The program is loaded and executed as a firmware module, scheduled by the boot phases rather than as an ordinary user-mode process.
    • Graphics capability depends on the Graphics Output Protocol (GOP) exposed by the firmware. Through it you query the supported display modes, set a mode, and obtain a frame buffer address that you write pixels into directly.
    • There is no managed memory in a high-level language. Any pointer misuse or dangling reference triggers a fault immediately — at best the program exits, at worst the whole environment goes down.
    • Debugging is hard. Screen output is unreliable, and for many phases you have to watch execution through serial logs.

    Precisely because the barrier is so high, this kind of task is a typical sample where AI coding tools can either prove their value or fail badly. The process recorded here started from a piece of code written by someone else: it looked well organized but did not run.

    Starting From a Mess That “Looked Fine”

    Suppose you are handed a boot-layer game codebase that is modularized fairly well: separate files for the entry point, the main loop, game logic, rendering, and input handling, with a clear directory structure and consistent naming. Read as source code, there is almost nothing to complain about — it looks the part. The moment you run it, though, the problems start arriving one after another.

    Throwing it away feels wasteful, and rewriting from scratch wastes time. The more pragmatic move is to hand it to an AI coding assistant and have it read, then modify, then debug. That in itself forms a reasonable collaboration flow: the AI takes care of fast comprehension and generation, while the human sets the goals, observes the results, and keeps the critical judgment calls.

    Round One: The Only Goal Was to Make It Boot

    Step One: Make the AI Understand the Code, Not Start Patching It

    My first instruction was not “fix this.” It was to ask the assistant to do an overall review of the code and lay out the potential problems. That order matters. Faults in low-level code tend to be interrelated; if you start editing without building a global understanding first, you end up pushing one problem down only to have another surface.

    The assistant worked through how the modules connect: how the entry point initializes, how the main loop drives execution, and how rendering and input interact. Within a few minutes it produced a list of issues. The value of that step was turning a vague feeling that “this probably does not run” into a handful of specific, verifiable suspects — giving the debugging that followed a concrete attack surface.

    Trap One: A Wild Pointer After Setting the Mode

    Once debug logging was added, the program booted, printed a message saying it had entered the main loop, and then exited immediately. A textbook case of getting through the door but not out of the room.

    By inserting logs at key points and watching them over the serial port, the fault could be traced to a point right after a call into the graphics protocol. The cause sat in a classic and easily missed spot. The typical code looks like this:

    1. // First, query mode information
    2. UINTN SizeOfInfo = 0;
    3. EFI_GRAPHICS_MODE_INFORMATION *Info = NULL;
    4. Status = gop->QueryMode(gop, Mode, &SizeOfInfo, &Info);
    5. // Then set that mode
    6. Status = gop->SetMode(gop, Mode);
    7. // Wrong: Info may already be invalid at this point
    8. UINT8 *framebuffer = (UINT8 *)Info->... // accessing a dangling pointer

    The core of the problem: setting the display mode invalidates the mode information buffer obtained by the earlier query. The memory that the mode information pointer referred to may have been reclaimed or overwritten by the firmware once the mode switch happened. Holding the old pointer and dereferencing it produces a wild pointer with unpredictable behavior, and the result is a crash.

    The fix is not complicated; recognizing the causal chain is what takes effort:

    1. // Query, then set the mode
    2. gop->QueryMode(gop, Mode, &SizeOfInfo, &Info);
    3. gop->SetMode(gop, Mode);
    4. // Key step: query again after the mode is set to get valid frame buffer info for the current mode
    5. gop->QueryMode(gop, Mode, &SizeOfInfo, &Info);
    6. // Only now is it safe to access the frame buffer
    7. UINTN FrameBufferBase = gop->Mode->FrameBufferBase;
    8. UINTN FrameBufferSize = gop->Mode->FrameBufferSize;

    After that change, the program stopped crashing on startup. The lesson worth keeping: any pattern of “query, switch, then use” deserves suspicion about whether the switch in the middle has invalidated the earlier data.

    Trap Two: A Misconfigured Protocol Identifier

    The program then ran stably, but the screen stayed blank for a long time. If the graphical interface never appears, the Graphics Output Protocol was never obtained correctly in the first place.

    In boot-layer code, protocols are located by a globally unique identifier (GUID), and in a firmware environment there is more than one identifier related to graphics, each corresponding to a different purpose (for example the protocol itself, the device path, or a device handle). Picking the wrong identifier during lookup makes protocol acquisition fail or return an incomplete handle, and every subsequent drawing call simply goes nowhere. The fix is to check which identifier is used for protocol location and make sure it is the one that corresponds to the Graphics Output Protocol itself:

    1. Status = gBS->LocateProtocol(
    2. &gEfiGraphicsOutputProtocolGuid, // must point to the Graphics Output Protocol
    3. NULL,
    4. (VOID **)&gop);
    5. if (EFI_ERROR(Status)) {
    6. return Status; // location failed; return here instead of continuing
    7. }

    The signature of this class of bug is “the program is alive, but the feature is empty.” It usually is not a crash but a silent failure, which is exactly why return-value checks and per-phase logging are needed to surface it.

    Round Two: Refinement and Optimization

    Round one was about “does it run”; round two is about “does it run well.” The goals at this stage included making frame refresh and input response more consistent, further decoupling rendering from logic, cleaning up redundant state checks, and covering edge cases such as the window not having focus and display resolution changes.

    During refinement, the AI coding assistant’s role shifted more toward being an “executor”: the human sets the direction and the standard for the optimization, and the AI carries out the concrete changes and generates the refactored code. The human judges whether a change introduces a regression; the AI figures out how to make it cleaner. This division of labor keeps human attention on design trade-offs and hands the mechanical tidying work to the tool.

    What This Practice Generalizes To

    Abstracting the process above, anyone using AI coding tools for low-level or unfamiliar work can borrow a few points:

    • Review first, edit later. Have the AI read the whole thing and list its suspects before touching anything. The more complete the context you give it, the more targeted the changes, and the less likely it is to fix one thing while breaking another.
    • Localize in layers, and let the logs talk. In an environment like the boot layer, serial and per-phase logs are practically the only pair of eyes you have. Give the AI enough runtime feedback and it can turn a “faint sense of something being wrong” into specific suspects. An effective human–machine loop depends on observable intermediate results.
    • Guard the boundaries of memory and protocols. Wild pointers, invalidated buffers, and mismatched identifiers are frequent killers in low-level development. Understand the lifetime of every pointer and handle, and do not trust “it compiles and it runs” as proof of correctness.
    • Keep the judgment for yourself and delegate the execution. AI is good at generating, refactoring, and tidying up, but on questions like “is this optimization worth it” or “will this design plant a landmine,” the human is still the decision maker. The point of collaboration is not full automation but each side contributing what it does best.

    Conclusion

    Writing a small game at the boot layer — something that can bounce a brick around or run a game of Tetris — looks like showing off. In practice it puts the AI coding assistant in an environment with no safety net. It will trip, it will crash, and it will paint a blank screen. But if you state the goal clearly, feed the feedback back at the right points, and keep the critical judgment in your own hands, it can turn a mess into working code step by step. The part actually worth paying attention to is never how impressive a single generation from a single model looked, but this collaboration pattern: the human sets the goals, the AI accelerates execution, and the human holds the key boundaries. That pattern is what makes AI genuinely usable — and trustworthy — in low-level development.