Recipes
Each recipe combines several options for a real need. The options mentioned are described one by one in the options.
1. Testing in a script
You want a program to show “READY” within 30 million cycles:
phosphoneo prog.neo --cycles 30000000 --screenshot-text out.txt
grep -q READY out.txt && echo OK || echo FAIL
The text console suits grep better than an image. For an exact image comparison, --screenshot produces a PPM whose fingerprint (sha256sum) you compare with a reference’s.
2. Filming a game
phosphoneo game.neo --cycles 75000000 \
--gamepad-at 5000000:04 --gamepad-at 12000000:0 \
--gamepad-at 13000000:20 --gamepad-at 15000000:0 \
--record play.avi
The gamepad walks forward (04) from 5 to 12 million cycles, then button B (20, “use”) opens a door. 75 million cycles make twelve seconds of video at 60 frames per second. To teleport the player, add --poke-ats.
3. Finding a failing call
phosphoneo prog.neo --cycles 60000000 --api-log j.log:3
grep -v 'err=0' j.log | head
Group 3 is files: any line whose err is not 0 is a call the firmware refused (for instance err=17, missing file). The pc= address says which instruction of the program issued it.
4. Stopping before a call and keeping memory
phosphoneo prog.neo --break-api 3,2 --break-dump ram.bin
Phosphoneo stops before the first 3,2 call (file load), prints the parameters as the program set them, writes the RAM to ram.bin and exits with code 3. You then examine the file: the requested file name is in RAM, at the address the parameters point to.
5. Skipping an intro
phosphoneo game.neo --headless --cycles 60000000 --save-state-at 40000000:after-intro.state
phosphoneo --load-state after-intro.state --headless --cycles 70000000 --screenshot-at 69900000:a.ppm
The first command plays the intro once and saves the state at cycle 40 million; the second restarts from there. Since time counts from the start, --cycles must exceed the saved cycle.
6. Waiting for an exact frame
If the program keeps a frame counter in a 16-bit word, for instance at address $0A10:
phosphoneo game.neo --screenshot-when 0A10:300:frame300.ppm --cycles 100000000
The capture is taken when that counter equals 300, whatever the cycle: the run stays correct if the program changes speed.