jonathanpeppers/dotnes/nes-emu-debug

dotnet build
dotnet build samples\hello\hello.csproj

# Find the Mesen executable (works on any OS / config)
$mesenExe = dotnet msbuild samples\hello\hello.csproj -getProperty:RunCommand
$mesen = (Resolve-Path $mesenExe).Path
$rom   = (Resolve-Path "path/to/rom.nes").Path
$script = (Resolve-Path "path/to/script.lua").Path
 
$proc = Start-Process -FilePath $mesen -ArgumentList `
  "--testRunner",            # Headless mode (no window)
  "--enableStdout",          # Show ROM loading info on stdout
  "--doNotSaveSettings",     # Don't persist config changes
  "--timeout=30",            # Kill after N seconds if script doesn't call emu.stop()
  "--debug.scriptWindow.allowIoOsAccess=true",  # Enable Lua file I/O
  $script, $rom `
  -PassThru -RedirectStandardOutput out.txt -RedirectStandardError err.txt -NoNewWindow
$proc.WaitForExit(35000)
# Exit code comes from emu.stop(N) in the Lua script, or -1 on timeout

local state = emu.getState()
-- CORRECT:
local pc = state["cpu.pc"]
local scanline = state["ppu.scanline"]
-- WRONG (nil!):
-- local pc = state.cpu.pc

local frameCount = 0
emu.addEventCallback(function()
  frameCount = frameCount + 1
  if frameCount == 120 then
    -- Do your inspection here
    emu.stop(0)  -- exit with code 0
  end
end, emu.eventType.endFrame)

local pixels = emu.getScreenBuffer()
-- Returns a Lua table of 61440 ARGB integer values (256 × 240 NES resolution)
-- Each pixel: (A << 24) | (R << 16) | (G << 8) | B

local sf = io.open("screen.raw", "wb")
for i = 1, #pixels do
  local p = pixels[i]
  sf:write(string.char((p >> 16) & 0xFF, (p >> 8) & 0xFF, p & 0xFF))
end
sf:close()
-- Result: 184320 bytes (256 × 240 × 3 RGB), convertible with ImageMagick/ffmpeg

# Using Python PIL/Pillow
python -c "
from PIL import Image
raw = open('screen.raw','rb').read()
img = Image.frombytes('RGB', (256,240), raw)
img.save('screenshot.png')
"
# Or using ffmpeg
ffmpeg -f rawvideo -pixel_format rgb24 -video_size 256x240 -i screen.raw screenshot.png

emu.stop(0)    -- exit test runner with code 0 (success)
emu.stop(1)    -- exit with code 1 (failure)
emu.stop(42)   -- any integer exit code

-- dump_state.lua — Dump CPU/PPU state after N frames
-- Usage: Mesen.exe --testRunner ... dump_state.lua rom.nes
local FRAMES = 120  -- wait 2 seconds (60 fps)
local OUT_FILE = "OUTPUT_PATH"  -- replace with absolute path using forward slashes
 
local frameCount = 0
emu.addEventCallback(function()
  frameCount = frameCount + 1
  if frameCount == FRAMES then
    local state = emu.getState()
    local f = io.open(OUT_FILE, "w")
 
    f:write("=== CPU State ===\n")
    f:write(string.format("PC=$%04X  A=$%02X  X=$%02X  Y=$%02X  SP=$%02X  PS=$%02X\n",
      state["cpu.pc"], state["cpu.a"], state["cpu.x"],
      state["cpu.y"], state["cpu.sp"], state["cpu.ps"]))
    f:write("Cycles: " .. state["cpu.cycleCount"] .. "\n")
 
    f:write("\n=== PPU State ===\n")
    f:write("Scanline: " .. state["ppu.scanline"] .. "  Cycle: " .. state["ppu.cycle"] .. "\n")
    f:write("Frame: " .. state["ppu.frameCount"] .. "\n")
    f:write("NMI enabled: " .. tostring(state["ppu.control.nmiOnVerticalBlank"]) .. "\n")
    f:write("BG enabled: " .. tostring(state["ppu.mask.backgroundEnabled"]) .. "\n")
    f:write("Sprites enabled: " .. tostring(state["ppu.mask.spritesEnabled"]) .. "\n")
 
    f:close()
    emu.stop(0)
  end
end, emu.eventType.endFrame)

-- read_zeropage.lua
local f = io.open("OUTPUT_PATH", "w")
 
local frameCount = 0
emu.addEventCallback(function()
  frameCount = frameCount + 1
  if frameCount == 120 then
    f:write("=== NES Library Zero Page ===\n")
    -- Names from src/dotnes.tasks/Utilities/NESConstants.cs
    local names = {
      [0x01]="STARTUP", [0x02]="NES_PRG_BANKS", [0x03]="VRAM_UPDATE",
      [0x04]="NAME_UPD_ADR", [0x06]="NAME_UPD_ENABLE", [0x07]="PAL_UPDATE",
      [0x08]="PAL_BG_PTR", [0x0A]="PAL_SPR_PTR",
      [0x0C]="SCROLL_X", [0x0D]="SCROLL_Y", [0x0E]="SCROLL_X1",
      [0x0F]="PPU_CTRL_VAR1", [0x10]="PRG_FILEOFFS", [0x12]="PPU_MASK_VAR",
      [0x14]="NMI_CALLBACK", [0x17]="TEMP", [0x18]="TEMP_HI",
      [0x19]="TEMP2", [0x1A]="TEMP3", [0x1B]="OAM_OFF", [0x1C]="UPDPTR",
      [0x22]="sp", [0x3C]="RAND_SEED"
    }
 
    for addr = 0, 31 do
      local val = emu.read(addr, emu.memType.nesInternalRam)
      local name = names[addr] or ""
      f:write(string.format("  $%02X = $%02X  %s\n", addr, val, name))
    end
 
    f:close()
    emu.stop(0)
  end
end, emu.eventType.endFrame)

-- dump_palette.lua
local f = io.open("OUTPUT_PATH", "w")
 
local frameCount = 0
emu.addEventCallback(function()
  frameCount = frameCount + 1
  if frameCount == 120 then
    f:write("=== Palette RAM ===\n")
    f:write("Background palettes:\n")
    for pal = 0, 3 do
      f:write(string.format("  Palette %d: ", pal))
      for i = 0, 3 do
        local val = emu.read(pal * 4 + i, emu.memType.nesPaletteRam)
        f:write(string.format("$%02X ", val))
      end
      f:write("\n")
    end
 
    f:write("Sprite palettes:\n")
    for pal = 0, 3 do
      f:write(string.format("  Palette %d: ", pal + 4))
      for i = 0, 3 do
        local val = emu.read(16 + pal * 4 + i, emu.memType.nesPaletteRam)
        f:write(string.format("$%02X ", val))
      end
      f:write("\n")
    end
 
    f:close()
    emu.stop(0)
  end
end, emu.eventType.endFrame)

-- dump_nametable.lua — Read a rectangular region of the nametable
local NT_BASE = 0       -- 0 for nametable 0, 0x400 for nametable 1
local START_ROW = 0
local END_ROW = 29      -- 30 rows total
local START_COL = 0
local END_COL = 31      -- 32 columns total
 
local f = io.open("OUTPUT_PATH", "w")
 
local frameCount = 0
emu.addEventCallback(function()
  frameCount = frameCount + 1
  if frameCount == 120 then
    f:write("=== Nametable ===\n")
    for row = START_ROW, END_ROW do
      f:write(string.format("Row %2d: ", row))
      for col = START_COL, END_COL do
        local addr = NT_BASE + row * 32 + col
        local tile = emu.read(addr, emu.memType.nesNametableRam)
        if tile == 0 then
          f:write(".. ")
        else
          f:write(string.format("%02X ", tile))
        end
      end
      f:write("\n")
    end
 
    f:close()
    emu.stop(0)
  end
end, emu.eventType.endFrame)

-- capture_screen.lua
local FRAMES = 120
local RAW_FILE = "OUTPUT_PATH.raw"