Playable by Claude

Sandbox note (Claude Code on the web)

A shell call that starts Xvfb and leaves it running gets SIGKILLed when the call returns — and the kill swallows the output, so it looks like an unexplained "exit 1" with nothing printed. Fix: drive every visual test through a single, self-terminating process that boots Xvfb + the engine, waits, screenshots, and tears everything down before it exits. Launch with setsid … < /dev/null & so neither is tied to the controlling terminal.

Boot sequence (exact order)

Critical: use SDL_VIDEODRIVER=x11, NOT dummy. The dummy driver skips rendering entirely — you get a black screen. Teardown is the same two pkill lines.

Input simulation

DR's origin is bottom-left, xdotool's is top-left: for a DR button at y: 300, the xdotool y is 720 - 300 = 420. Every xdotool call needs DISPLAY=:99.

Verification strategies

1. Read the screenshot — scene titles, HUD text, UI presence, red text = DR exception.
2. Log check: grep -i EXCEPTION /tmp/dr.log | grep -v "~gtk.reset~" (filter normal reset warnings).
3. File size: stat -c%s shot.png — >5KB good, <2KB blank.
4. Regression: compare -metric RMSE baseline.png current.png diff.png.

Debug-mode teleports (preferred for deep scenes)

The most reliable way to reach a specific scene is built-in debug hotkeys, gated so they only fire when $gtk.production? is false. No code injection at test time, no cleanup, deterministic, and CI can drive the same keys.

Then a visual test is just: xdotool key F3; sleep 3; scrot scene.png.

Adapting to any DR game

Find the scene dispatch (case args.state.scene), each scene's init_* guard and the state it reads on first tick, then the input bindings (keyboard.key_down). Write a teleport per scene, or just boot and screenshot whatever loads first and check the log for exceptions.

DragonRuby has a built-in dev HTTP server with a remote eval endpoint that executes arbitrary Ruby in a running game and returns the result — full read/write access to live state without touching source files.

Prerequisites

The server starts on the second tick after boot — wait ~3–5s after launch before requesting.

Eval endpoint (primary tool)

Common queries: current tick Kernel.tick_count; all state keys $gtk.args.state.as_hash.keys.to_s; inspect a key $gtk.args.state.some_key.to_s; serialize an entity $gtk.args.state.some_entity.serialize.to_s; framerate $gtk.current_framerate.to_sf.

You can also mutate state and call methods: $gtk.args.state.some_flag = true, MyModule.some_method($gtk.args), $gtk.write_file("dump.txt", …), $gtk.reset.

Input can't be injected via eval

The C engine controls input state and overwrites Ruby-level changes before the tick reads them — setting keyboard.key_down.space = true does nothing. Instead, call the function the key would trigger: MyModule.handle_action($gtk.args.state). For real input-driven testing, use replay files (--replay), which inject at the engine level.

Other endpoints

• GET /dragon/log/ — full game log since boot
• POST /dragon/reset/ — reset game state
• POST /dragon/record/ · /record_stop/ · /replay/ — record & replay gameplay
• GET /dragon/code/ — list loaded source files
• GET /dragon/control_panel/ — HTML reset/record/replay buttons

Tips & common mistakes

Multiline code works (separate with \n or ;); the return value is the last expression; an empty response means it returned nil (add .to_s). Connection refused = the game hasn't finished booting, or the cvars weren't picked up (restart after changing them). Use single quotes around the --data JSON and escape inner quotes.

A debugging specialist for DragonRuby GTK. Combines runtime knowledge — 60fps loop, args.state persistence, hot-reload, the bottom-left 1280×720 coordinate system, the render layer order (solids → sprites → primitives → labels → lines → borders → debug) — with inventive techniques.

Where to look first

• logs/exceptions/current.txt — most recent exception + backtrace
• logs/exceptions/game_state_NNNN.txt — state snapshot at the exception tick
• Live REPL: press ` / ~ in the running game — $gtk.args.state.inspect, GTK.reset
• HTTP introspection via dragonruby-httpd (port 9001) — see the live-inspection skill

Exception workflow

1. Read current.txt for the exception and backtrace.
2. Read the matching game_state_NNNN.txt for exact state.
3. Open the failing file at the backtrace line.
4. Check the usual suspects: Hash/Array primitive mismatch, nil refs (missing ||=), audio props as int instead of float, top-left vs bottom-left coordinate confusion, render-target invalidation.
5. Propose a specific fix with reasoning.

Debug rendering & watches

Remember: y = 0 is the BOTTOM. y > 720 is off the top, y < 0 off the bottom. A sprite needs a: 255 — alpha 0 is invisible.

Creative strategies

• Time-travel: push args.state.serialize into a history ring, dump the last 60 frames when the bug fires.
• Conditional breakpoint: on a bad condition, write state to a file, GTK.notify, $gtk.show_console, and gate the tick.
• Differential state: serialize before/after a suspect function and diff the changed keys.
• Assertions: assert(args.state.player.hp >= 0, "HP below zero") that dumps state and raises.

Avoid generic Ruby advice without DR context, "just add logging" without locations, or fixes proposed before reading the actual error.

DragonRuby's loop assumes exactly 60 ticks/sec — a 16.67ms frame budget. Drop below and animation drifts, audio desyncs, input feels laggy. Profile first, then optimize.

Profiling workflow

Boot headlessly (see dragonruby-visual-test), navigate to the heavy scene, and instrument the tick to split logic vs render cost:

Logic high → O(n) scans, allocations, Math calls. Render high → too many primitives or hash-form solids. Both low but FPS still drops → it's engine/audio overhead, or Xvfb's software renderer (test a known-simple scene to rule the environment out).

Top optimizations (in priority order)

1. Array-form primitives — usually the single biggest win. mruby Hash allocation is expensive; a flat array skips it.
   # SLOW: a new Hash every frame args.outputs.solids << { x: 100, y: 200, w: 50, h: 10, r: 255, g: 120, b: 0, a: 200 } # FAST: flat array — [x, y, w, h, r, g, b, a] args.outputs.solids << [100, 200, 50, 10, 255, 120, 0, 200]
   Solids/borders [x,y,w,h,r,g,b,a], lines [x,y,x2,y2,r,g,b,a]. Labels are hash-only (and usually few).
2. Kill Math.sin in hot paths — replace shimmer/pulse with a triangle wave or tick.even? ? 1 : -1. Keep it only for large, slow, visible oscillations.
3. No per-frame O(n) scans — replace timeline.count { … } and .find { … } with incremental counters and forward-only cursors.
4. Cache expensive lookups — don't File.exist? every frame; memoize in a global hash.
5. Reduce density — a 60-solid FPS sparkline can cost more than the scene; show one label instead.
6. Avoid args.audio.keys iteration — track active channels with a counter + expiry queue.

Verify, then clean up

Screenshot the FPS counter during the heaviest moment, check min FPS (not just average) across multiple phases, then remove the timing instrumentation — array-form primitives stay (they're the correct production form, not debug code).