/step pauses at the end of the video frame, after the vsync IRQ has started the program's tick issue #5 open andymccall opened this 25 days ago · 0 comments

Measured on the x16emu fork (contract 0.5.0) driving a game whose loop ticks on the KERNAL jiffy, i.e. on the vsync IRQ.

/step?frames=N pauses when the emulator's frame counter reaches N — at the end of the video frame. The VERA vsync IRQ fires at the top of vblank, so the program's tick for that frame has already begun by the time the step returns, and a tick that runs longer than vblank (~10k cycles) is paused in flight: GET /regs shows the PC inside the game's code, half way through its per-frame work.

Consequences for a harness:

• a POST /mem made at the pause is seen by the next tick, not the one the harness thinks it just stepped to — a test wrote "gravity = 48 frames per row", stepped, and watched the piece fall one more row at the old rate;
• a GET /mem at the pause reads a tick half done.

Both are workable once known (the tetriblox harness now steps a frame after every write before reading, and asserts on state rather than on a frame), but "advance N frames deterministically" reads as if the machine stops at a well-defined point of the program's cycle, and it does not.

Two possible shapes for the contract, either would do:

1. /step pauses at the vsync boundary before the IRQ is delivered (the frame counter increments where the interrupt is raised, not where the last scanline ends), so a step lands between ticks for any program that ticks on vsync.
2. /step?frames=N&until=<addr> — after the frames, run on to a PC and stop there, so a harness can name its own safe point (the program's frame-wait loop).

Happy to prototype (1) on the x16 fork if the contract owners agree it is the right semantics.

Imported from GitHub #9, opened by andymccall on 2026-09-11.