Debug a bot

Run spimbot or spimbot gui with up to two bot files, bot 0 first, and any match options:

spimbot gui bot0.s bot1.s --seed 7 --mode part1

The debugger opens paused at cycle 0, or running with --run. Its title shows the bot files and the seed, such as bot0.s vs bot1.s (seed 7) - Spimbot. Without --seed, the match gets a random seed.

• Choose File > Load bot 0… or File > Load bot 1….
• Drop a .s or .asm file on the window to add it as the next bot.
• Choose File > Reload to read the files again. Each breakpoint stays on its source line.

Loading and reloading restart the match from cycle 0. When a file doesn't assemble or load, a dialog shows the errors:

Fix the file, then choose Reload in the dialog or press Ctrl+R.

The View menu turns each panel on and off, and View > Reset layout puts them back.

The selector at the right end of the menu bar picks the bot that Registers, Text segment, Data segment and Devices show. The current cycle appears beside it.

Run > Speed caps the cycles run each second, and Run > Loop restarts the match when it ends. The Timeline has the same commands as buttons, with the Step by count in the box beside them:

The status line says why the match paused, such as Paused at breakpoint 0x004002b4 (bot 0). When the match ends, it gives the result, such as bot0 wins after 10,000,000 cycles (12-7).

Run > Match settings… changes the seed, the mode, the cycle limit and tournament rules:

• Random draws a new seed.
• No limit removes the cycle limit.
• Apply restarts the match from cycle 0 with the new settings and keeps the bots, breakpoints and watchpoints.

Reset, Reload and video exports use the new settings until you close the window.

Select an instruction in the Text segment and press F9, or click the gutter on its row. When a bot reaches a breakpoint, the match pauses. Running or stepping from a breakpoint passes over it.

A red dot in the gutter marks a breakpoint, and the amber arrow and row mark the instruction the bot runs next. The comment on the first instruction from each source line gives the file, the line number and the source.

The Breakpoints panel lists every breakpoint and watchpoint with its bot, kind, address, location and contents. The entry the match is paused at is amber:

• Each entry's checkbox turns it on and off, and × removes it.
• Enable all, Disable all and Remove all act on every entry.
• Double-clicking an entry shows it in its segment.

A watchpoint pauses the match when a bot reads or writes a word, through an instruction or a syscall's buffer. Right-click the word in the Data segment and choose a watch item:

Choose a checked item again, or Remove watchpoints, to remove it. When a watchpoint pauses the match, the status line gives the address and the instruction, such as Paused on a watched write to 0x100105d0 at 0x00400300 (bot 0).

Run > Pause on exceptions, on by default, pauses the match when a bot raises an exception other than an interrupt, and the status line names the exception. The Breakpoints panel has the same checkbox. Turn it off to let the bot's exception handler run. Under tournament rules, an exception crashes the bot and ends the match.

A bot that reads its console with no input waiting pauses the match, and its Console tab takes the keyboard. Type a line and press Enter to send it. A match that was running resumes. Rewinding, looping and video exports replay console input at the cycle you sent it.

• Go > Go to… takes a hex address, a symbol, a register such as $sp, or pc.
• Go > Follow target, or double-clicking a branch or jump target, goes to the target.
• Go > Back and Go > Forward retrace these jumps.
• Edit > Copy copies the focused panel's selection as plain text. Context menus have more copy commands, such as Copy address and Copy value.

Drag the seek bar in the Timeline. Dragging back rewinds the match at once. Dragging past the furthest cycle reached runs the match forward to that cycle. After a rewind, running, stepping or sending console input replaces the rest of the match.

File > Export PNG… saves the map as it stands, the same picture that spimbot run --png saves. File > Export video… asks for the cycles per frame and a .mp4, .webm or .gif file, then plays the match again from cycle 0 to encode it. Video export needs ffmpeg on your PATH, as Videos describes.

View > Theme picks the color theme, and the zoom commands scale the window from 50% to 300%. Debugger settings describes where the debugger saves its layout and settings.

View > Show grid draws a line on every tile edge and a brighter one every 5 tiles, labeled with its pixel coordinate along the top and left edges. Divide a coordinate by 10 for its tile: the line labeled 150 is the left edge of tile 15. Exported PNGs and videos show the grid while it is on.

Shortcuts don't work while you type in a field or while a menu or dialog is open. Keys marked "held" repeat while you hold them.