I Blamed MvC's Graphics. The Bug Was One Missing '@'.

CPS-2 arcade boards have a built-in test menu (accessed via the F2 key / operator button). This menu provides hardware diagnostics, input testing, and color calibration. But what if you want to add your own diagnostic page? This post documents the complete process of injecting a "ULTRA SETTINGS" submenu into MvC1's test system -- displaying 24 lines of real-time ROM verification data with an interactive sound test, using pure 68000 assembly.

Engineering Outcomes:

• Added "9: ULTRA SETTINGS" as a new menu item in the F2 Test Menu
• Built a 24-line diagnostic screen verifying ROM expansion, character roster, palettes, secret functions, and audio injection
• Solved the CPS-2 sprite list terminator problem (the "11 11" artifact)
• Implemented robust input polling across hardware ports, VSync, and game state flags
• Entire system built via automated Python + vasm pipeline

The Problem

We expanded MvC1's ROMs to CPS-2 theoretical maximums (128MB GFX, 16MB Audio). But how do you prove the expansion is correct? How do you verify that character data, palette locations, and secret function entry points are intact?

The answer: build a verification screen directly into the game.

CPS-2 Test Menu Architecture

The F2 Test Menu is a state machine managed by the game's program ROM. It has a menu count, a cursor position, a jump table for dispatching to each menu item's handler, and text rendering via the CPS-2 tile system.

graph TD
  subgraph "Original F2 Test Menu"
    M1["1: DIP SW TEST"]
    M2["2:INGS TEST"]
    M3["3: COLOR BAR"]
    M4["4: SOUND TEST"]
    M5["5: CROSS HATCH"]
    M6["6: C.P.S.2 ADJUST"]
    M7["7: I/O CHECK"]
    M8["8: MEMORY CHECK"]
    M9["9: EXIT"]
  end

  subgraph "Modified Test Menu"
    N1["1: DIP SW TEST"]
    N2["2: INGS TEST"]
    N3["3: COLOR BAR"]
    N4["4: SOUND TEST"]
    N5["5: CROSS HATCH"]
    N6["6: C.P.S.2 ADJUST"]
    N7["7: I/O CHECK"]
    N8["8: MEMORY CHECK"]
    N9["9: ULTRA SETTINGS"]
    N10["10: EXIT"]
  end

  M9 -.->|"Shifted to 10"| N10
  N9 -.->|"NEW!"| PS["ULTRA SETTINGS Handler"]

  style N9 fill:#112d20,stroke:#419865,color:#eaf2ef,stroke-width:3px
  style PS fill:#12303a,stroke:#397b83,color:#eaf2ef,stroke-width:3px

Key ROM Locations

The Patches

Step 1: Increase Menu Count

The original menu has 9 items (1-8 + EXIT). We change the count byte from 0x09 to 0x0A:

CPU $0DFA01:  09 → 0A   (menu now has 10 items)

Step 2: Fix Cursor Limits

Three locations need updating so the cursor can reach position 9:

CPU $0DFA03:  08 → 09   (cursor limit 1)
CPU $0DFA0B:  08 → 09   (cursor limit 2)
CPU $0DFA1B:  08 → 09   (cursor limit 3)

Step 3: Fix Cursor Wrapping

The cursor wrap values use 2-byte immediate values (critical discovery -- using 4-byte values corrupted the adjacent BNE.S instruction):

CPU $0DD3AC:  09 → 0A   (wrap from bottom to top)
CPU $0DD3C6:  09 → 0A   (wrap from top to bottom)

Step 4: Extend the Jump Table

The original jump table at $0DD476 has entries for items 0-8. We redirect item 9 (previously EXIT) to our new handler, and item 10 becomes EXIT:

graph LR
  subgraph "Jump Table"
    J0["[0] DIP SW handler"]
    J1["[1] INGS handler"]
    J8["[8] ULTRA SETTINGS → $0F1000"]
    J9["[9] EXIT handler"]
  end

  J8 -->|"JMP"| PS["Our Custom Code at $0F1000"]

  style J8 fill:#112d20,stroke:#419865,color:#eaf2ef
  style PS fill:#12303a,stroke:#397b83,color:#eaf2ef

The ULTRA SETTINGS Handler

The handler is written in 68000 assembly, compiled by vasm, and injected at $0F1000. It displays 24 lines of diagnostic information including an interactive sound test.

Screen Layout

  9.ULTRA SETTINGS
 
  PRG TOTAL: 4096KB
  PRG USED:   872KB
  PRG FREE:   152KB
  GFX TOTAL: 0128MB
  GFX USED:   032MB
  GFX FREE:  0096MB
  SND TOTAL:   16MB
  SND USED:    08MB
  SND FREE:    08MB
  CPS2 GFX: AT MAXIMUM
  CPS-2 MAX: 0128MB
  NORMAL IDS:  15
  SECRET IDS:  06
  STAGES:      12
  SPIDEY 2E:  OK
  P PALETTE:  OK
  K PALETTE:  OK
  FN RED VEN: OK
  FN ORG HLK: OK
  FN GLD WM:  OK
  FN SHD LDY: OK

How Each Value is Computed

Function Verification Logic

The 4 secret character load functions were independently decompiled to C, one translation per function, confirming their structure:

The ULTRA SETTINGS screen verifies these functions are intact by reading the first word at each entry point. If it's $0000 (NOP) or $FFFF (empty ROM), the function is considered missing:

verify_function:
    move.w  (A0),D0        ; Read first word at function address
    cmpi.w  #$0000,D0      ; Is it NOP?
    beq.s   .fail
    cmpi.w  #$FFFF,D0      ; Is it empty ROM?
    beq.s   .fail
    ; ... write "OK" ...
.fail:
    ; ... write "NO" ...

The Display Artifact Saga

Building the ULTRA SETTINGS screen required solving three interrelated display bugs. Each fix revealed deeper understanding of CPS-2 hardware.

Bug 1: "11 11" Text Artifacts

When the diagnostic screen first displayed, garbled "11 11" text appeared across the screen background. The root cause had two layers:

Layer 1: Tile 0 in GFX ROM has "11" graphics. CPS-2 scroll layers use tile map entries (16-bit tile number + 16-bit attributes). Clearing VRAM to $00000000 sets every tile position to tile index 0. In MvC1's graphics ROM, tile 0 contains "11" debug graphics from Capcom's development -- NOT a blank tile.

Fix: Fill scroll VRAM with tile $0020 (space character) instead of $0000:

; Clear scroll VRAM ($660000-$66BFFF) with tile $0020 (space)
; NOT tile $0000! Tile 0 in MvC1 GFX ROM contains "11" graphics.
lea     $660000,a0
move.l  #$00200020,d1           ; tile $0020 for both words
move.w  #$2FFF,d0
.cv:    move.l  d1,(a0)+
        dbra    d0,.cv

Layer 2: CPS-2 extended GFXRAM at $900000. Besides the standard scroll VRAM at $660000, CPS-2 has 192KB of additional video memory at $900000-$92FFFF. The game's display system may source tile data from this region. Clearing it eliminates any residual graphics:

; Clear GFXRAM ($900000-$92FFFF, 192KB)
lea     $900000,a0
move.w  #$BFFF,d0               ; 48K longwords = 192KB
.cg:    clr.l   (a0)+
        dbra    d0,.cg

Bug 2: Persistent Sprite Artifacts (Brown Character Blobs)

Character sprites from the game's last state appeared on the diagnostic screen despite clearing sprite RAM. This required understanding CPS-2's double-buffered OBJ RAM:

sequenceDiagram
    participant HW as CPS-2 hardware
    participant B1 as OBJ bank 1 at $700000
    participant B2 as OBJ bank 2 at $708000
    participant Us as Our clear routine
    HW->>B1: reading this bank right now
    Us->>B2: clear the bank we can see
    Note over B2: looks clean in the debugger
    HW->>HW: VBlank -- banks swap
    HW->>B2: now reading the cleared bank
    Note over B1: the bank we never touched<br/>still holds the last fight's sprites
    B1-->>HW: brown character blobs return
    Us->>B1: fix: write FF terminators to BOTH banks
    Us->>B2: every one of 1024 entries, each bank

The hardware reads from one bank while the game writes to the other. At VBlank, they swap. Writing $FF000000 (Y-position terminator) to ALL entries in BOTH banks eliminates sprites regardless of which bank the hardware is currently reading:

clear_sprites:
    move.l  #$FF000000,d1       ; $FF in Y high byte = STOP RENDERING
 
    ; Clear OBJ Bank 1 ($700000)
    lea     $700000,a0
    move.w  #$03FF,d0           ; 1024 entries
.cb1:   move.l  d1,(a0)+        ; Y=$FF00 (terminator), tile=0
        clr.l   (a0)+           ; X=0, flags=0
        dbra    d0,.cb1
 
    ; Clear OBJ Bank 2 ($708000)
    lea     $708000,a0
    move.w  #$03FF,d0
.cb2:   move.l  d1,(a0)+
        clr.l   (a0)+
        dbra    d0,.cb2
    rts

Bug 3: Game's VBlank Handler Repopulates Sprites

Even after clearing both OBJ banks, calling JSR $0004FC (VSync) triggered the game's VBlank interrupt handler, which immediately wrote sprite data back to OBJ RAM. Every frame: we clear, VBlank writes sprites, hardware displays sprites.

Fix: Mask all CPU interrupts after rendering:

move.w  sr,-(sp)                ; Save status register
ori.w   #$0700,sr               ; Set interrupt priority level to 7 (mask ALL)
bsr.w   clear_sprites           ; Final clear -- stays clean now

With interrupts masked, no VBlank handler runs, no sprite DMA occurs, and our OBJ RAM clear persists indefinitely. The hardware still renders from its current state -- it just displays our clean data.

graph TD
  subgraph "Before Fix (3 bugs combined)"
    B1["Tile 0 = '11' graphics everywhere"]
    B2["Only clearing 1 of 2 OBJ banks"]
    B3["VBlank handler rewrites sprites each frame"]
    B4["Result: garbled screen with artifacts"]
  end

  subgraph "After Fix"
    A1["VRAM filled with tile $0020 (space)"]
    A2["GFXRAM at $900000 cleared"]
    A3["Both OBJ banks cleared with $FF terminators"]
    A4["Interrupts masked -- no VBlank repopulation"]
    A5["Result: clean diagnostic display"]
  end

  style B4 fill:#351b1b,stroke:#b56565,color:#f6dada
  style A5 fill:#112d20,stroke:#419865,color:#eaf2ef

Exit Mechanism

With interrupts masked, the game's normal input system (which relies on VBlank processing) doesn't work. Instead, we read the hardware input ports directly:

; Direct hardware I/O -- works regardless of interrupt state
; $800000 bits 0-7: P1 joystick + buttons (active LOW)
; All bits high ($FF) = no buttons pressed
.wp:    bsr.w   frame_delay
        move.w  ($800000).l,d0
        andi.w  #$00FF,d0
        cmpi.w  #$00FF,d0       ; All released?
        bne.s   .ex             ; No → button pressed → exit
        bra.s   .wp
 
.ex:    move.w  (sp)+,sr        ; Restore SR (unmask interrupts)
        movem.l (sp)+,d0-d7/a0-a6
        jmp     $0DD2B0         ; Test menu draw entry point

Key design decisions:

1. Direct port reads ($800000) work with interrupts masked since they're memory-mapped I/O
2. Frame delay via NOP loop provides timing without needing VBlank
3. Exit restores interrupts before jumping back to the test menu's draw loop at $0DD2B0
4. Debounce phase waits for all buttons released before accepting new presses

flowchart TD
  A["Enter ULTRA SETTINGS"] --> B["Clear VRAM + GFXRAM + both OBJ banks"]
  B --> C["Draw all 22 diagnostic lines"]
  C --> D["Mask interrupts (IPL=7)"]
  D --> E["Final sprite clear (stays clean)"]
  E --> F["Wait loop"]
  F --> G["Read $800000 directly"]
  G --> H{"Any button pressed?"}
  H -->|No| F
  H -->|Yes| I["Restore SR (unmask interrupts)"]
  I --> J["JMP $0DD2B0 (test menu redraw)"]

  style A fill:#12303a,stroke:#397b83,color:#eaf2ef
  style J fill:#112d20,stroke:#419865,color:#eaf2ef

Text Rendering

CPS-2 doesn't have a traditional framebuffer for text. Instead, text is rendered by writing tile indices to a RAM buffer, which the hardware's scroll layers display.

Word-Swapped Text

A critical discovery: CPS-2 ROMs store bytes swapped within 16-bit words. When the CPU reads from ROM, the hardware un-swaps them. But when writing to RAM, no un-swap occurs. This means text data in ROM must be pre-swapped:

String "OK" in ASCII:   4F 4B
Stored in ROM (swapped): 4B 4F
CPU reads from ROM:      4F 4B (hardware un-swaps)
Written to RAM:          4F 4B (no swap, correct)

Decimal Number Display

The diagnostic screen displays numbers in decimal (e.g., "1024KB"). The 68000 doesn't have a decimal division instruction, so we use DIVU (unsigned divide):

; Convert D0 to 4-digit decimal string at (A1)
    divu    #1000,d0       ; D0.w = thousands, D0 high = remainder
    addi.b  #$30,d0        ; Convert to ASCII
    move.b  d0,(a1)+       ; Store thousands digit
    swap    d0             ; Get remainder
    andi.l  #$FFFF,d0
    divu    #100,d0        ; Hundreds
    ; ... continue for tens and ones ...

Build Pipeline

The entire system is built by a single Python script:

flowchart TD
  A["Build pipeline (one command)"] --> B["Load base ROMs from ZIP"]
  B --> C["Expand GFX: 8x 4MB → 16MB"]
  C --> D["Expand Audio: 2x 4MB → 8MB"]
  D --> E["Apply menu byte patches"]
  E --> F["Generate 68000 assembly"]
  F --> G["Compile with vasm"]
  G --> H["Word-swap binary output"]
  H --> I["Inject at $0F1000 in ROM"]
  I --> J["Save 148MB mvscud.zip"]

  style A fill:#33290f,stroke:#b28c36,color:#f4e9c8
  style J fill:#112d20,stroke:#419865,color:#eaf2ef

What the Script Does

1. ROM Expansion -- All GFX chips to 16MB (128MB total), all audio chips to 8MB (16MB total)
2. GOLD Marker -- Plants GOLD\x01 at mvc.13m:0x3FFFFB for verification
3. Menu Patches -- 9 byte-level patches to extend the test menu
4. Assembly Generation -- Produces ~3600 bytes of 68000 code with embedded text data
5. Compilation -- Calls vasmm68k_mot to assemble the code
6. Injection -- Word-swaps the binary and writes it to ROM offset $071000
7. Packaging -- Creates a single mvscud.zip with all 20+ ROM files

Postscript: Re-Verifying Against the Running Machine

Months later the handler had drifted. A build regression had replaced the interrupt-masked render loop with a "minimal" busy-wait, and three defects had crept in: the screen hung (no button would exit), the diagnostic text overlapped stale menu text, and background garbage tiles ("11 11", brown blocks, a ghost "H") bled through. Rather than eyeball it, I drove the whole thing headlessly under MAME and let the running machine settle the arguments — several of which contradicted the assumptions written above.

A headless reproduction harness. MAME's Lua interface (-autoboot_script) can assert input ports, read the 68000's state, tap memory, and dump the emulated framebuffer — no window required. The tricky part was entering the service menu: holding the "Service Mode" line does nothing (it is a toggle, needing a press→release edge), and the test menu only appears after ~1,200 frames of boot intro. The harness toggles the switch, detects the menu by its screen signature (~94% black with sparse text), navigates to item 9, selects it, and screenshots each state to PPM:

-- detect the menu, then drive P1 Down x8 -> Button 1
if bf() > 0.80 and bf() < 0.995 and stable then menuUp = n end
-- capture the emulated screen straight to disk
local px, w, h = screen:pixels()   -- 32-bit ARGB, no display needed

Instrumentation beats guessing. Frame-boundary PC sampling only ever caught the idle wait-loop ($000328) — the menu logic runs inside the VBlank IRQ. So I switched to execution and exception taps: a read-tap on the handler region to prove it ran, and a tap on the 68000 exception-vector table ($000008-$00002F) that reads the pushed stack frame to recover the faulting PC and address the instant any bus/address/illegal fault fires. That turned "it crashes somewhere" into an exact instruction.

What the running machine corrected. Several claims earlier in this post were reverse-engineered from the disassembly and MAME docs but not re-checked against the game actually running. Driving live inputs and tapping writes disproved three of them:

The QSound trap. The interactive sound test never played, independent of the input bug: CPS-2's Z80 shared RAM is wired umask16($00FF) — only the odd 68000 byte reaches the Z80, and Z80 byte $C000+N lives at $618001 + 2N. The play routine had been writing sequential (even) addresses, which the hardware silently drops. Mirroring the working sound-test hook ($618001/$618003/$618009/$61801F) fixed it.

With $804000 input, per-layer blank tiles, the VSync loop, and the odd-byte QSound protocol, the screen entered cleanly, responded to Up/Down/LP/HP, played injected tracks, and exited to a clean menu. One family of artifacts survived — a row of "11 11" tiles along the bottom, tan blocks on the flanks, a faint "H" — which I initially blamed on CPS-2's protection-obfuscated CPS-A scroll registers. That theory was wrong, and the real answer is the best bug of the whole project. Keep reading.

Postscript II: The Artifacts Were Never Where We Looked

The stubborn leftovers survived everything: clearing every tilemap window, clearing both OBJ banks every frame, even an isolate-and-restore sweep that zeroed each 16KB window of Video RAM one at a time (saving and restoring content so a palette wipe couldn't mask later windows). The sweep did teach us the real display map — $908000 = text layer, $90C000 = a higher-priority layer whose blank tile $6820 is transparent (zero it and the whole screen floods with opaque tile-0 "1" glyphs), $914000 = the palette (never write it), $918000 = blank pairs $0020,$0015 — but the artifacts shrugged all of it off. Write-taps then showed something damning: during the ULTRA screen, nobody writes OBJ RAM but our own clear loop, and nobody writes the tilemaps but our own fill and the game's text renderer.

Which left exactly one suspect: our own render call. Disassembling the game's text renderer at $00156C settled it. Its stream format is not the fixed 28-byte records the patch had assumed for months. It is:

[X][Y][attr] chars... '/' [X][Y][attr] chars... '@'

'/' ($2F) starts a new positioned line. '@' ($40) — and only '@' — terminates the stream. Two consequences:

1. Our template began with raw text, so the renderer ate the title's first three characters as a position header. "9.ULTRA SETTINGS" had never displayed — a bug previously misdiagnosed as "row 0x02 is overscan."
2. Our template ended with $00,$00 instead of '@'. The renderer marched straight past the end of the template, interpreting copy-slack and junk as characters and headers — painting tile-0 "11" glyphs and garbage cells at junk-controlled positions. The "artifacts" were the renderer's own brush, every single frame, which is precisely why no amount of VRAM clearing could remove them.

flowchart TD
    tpl["Our text template"] --> rend["Game's text renderer at $00156C"]
    rend --> fmt["Real stream format:<br/>X, Y, attr, then chars,<br/>slash starts a new positioned line,<br/>at-sign and ONLY at-sign ends the stream"]
    fmt --> c1["Template began with raw text<br/>-- renderer ate the title's<br/>first three characters as a header"]
    c1 --> miss["9.ULTRA SETTINGS never displayed<br/>-- misdiagnosed for months<br/>as 'row 0x02 is overscan'"]
    fmt --> c2["Template ended with 00 00,<br/>not an at-sign"]
    c2 --> past["Renderer marched past the end,<br/>reading copy-slack as characters<br/>and headers"]
    past --> art["Tile-0 '11' glyphs and garbage cells<br/>repainted at junk positions<br/>EVERY FRAME"]
    art --> why["Which is why no amount of<br/>VRAM or OBJ clearing removed them:<br/>the brush was ours"]

One four-byte stream header, one '@' terminator, and every artifact vanished in the same build — plus the title displayed for the first time. The same discovery explained the main menu's misaligned "SELECT/START" footer: each entry's metadata positions the next line (successor chaining), so splicing new items in with hardcoded metadata had displaced the stock instruction rows. Preserving the original entry's final 4 metadata bytes restored the factory alignment.

The rebuilt screen also gained what a diagnostic menu should have had all along: a live input row (INPUT: FFFF FFFF — raw port words for stick/punches and kicks, refreshed every 8 frames, so you can watch bits drop as you press), edge-detected input (press-and-hold no longer machine-guns the sound code), the real injected-track count (it had been reading a dead variable and showing 00 forever), and a build-date stamp so every screenshot self-documents which ROM produced it.

Bug Chronicle

Lessons Learned

1. CPS-2 has TWO OBJ RAM banks at $700000 and $708000 -- hardware reads one while game writes the other, swapping at VBlank. You must clear BOTH.
2. Tile 0 is NOT blank -- In MvC1, it contains "11" debug graphics. Always fill cleared VRAM with a known blank tile index.
3. You run in user mode -- Masking interrupts (ori #$0700,sr) privilege-faults because the test menu executes unprivileged. Don't fight the VBlank handler; use it — jsr $0004FC each loop lets the game maintain the scroll layers for you (see the postscript).
4. Verify port addresses against the running machine -- The real P1 stick+punches port is $804000 (active-low), not $800000 or the kicks port $804010. A single wrong I/O address is the difference between a working menu and a dead hang; press a button and watch the bits.
5. Every scroll layer has its own blank tile -- text layer $908000 = $0020,$0006, the high-priority layer $90C000 = $6820,$0000 (transparent — tile 0 there is an opaque "1" glyph), $910000 = $0900,$0000, $918000 = $0020,$0015. And $914000 is the palette: never blanket-clear Video RAM. 5b. Know your renderer's stream format before feeding it -- $00156C wants [X][Y][attr] chars '/' ... '@'. A missing '@' terminator meant the renderer painted junk beyond the template every frame — artifacts no amount of VRAM clearing could remove, because the brush was ours. When artifacts survive every clear, stop asking "what didn't I clear?" and start asking "what keeps drawing?" (write-taps answer that in minutes).
6. 2-byte vs 4-byte immediate sizes matter -- 68000 instruction encoding is precise; overwriting adjacent instructions causes silent corruption.
7. Test menu cursor limits are stored in multiple locations -- Missing even one causes wrap bugs.
8. Know your exit path -- JMP-based dispatchers require explicit return addresses. The test menu's draw entry at $0DD2B0 is the safe re-entry point.

References

• CPS-2 hardware documentation (MAME cps2.cpp driver source)
• CPS-2 sprite format analysis (MAME cps_draw.cpp)
• MvC1 test menu disassembly via Ghidra + MAME debugger
• 68000 Programmer's Reference Manual (Motorola)