- Easier setup: clearer dependency checks and a guided setup command for the compiler, emulator and ROM profiles.
- PyPI installation: package the CLI, templates and runtime so installation
works without a Git checkout. Move tool downloads and writable caches outside
the installed package, then test a clean wheel install before publishing.
pipx install amiga-game-kitis the target, not a supported command yet. - Real hardware testing: boot the demo disks on physical A500 and A1200 machines and record the exact configurations, controls, timing and audio results. AGA support remains experimental until this is checked.
These are planned improvements, with no release dates promised. For now, use the source setup or download a demo.
Each item came from real friction while making examples/voidrunner (a
50 fps shmup) and fitting Retro Diffusion art into it. Status is kept here as
the work lands; the commit that finishes an item names it.
| # | item | why | status |
|---|---|---|---|
| 1 | agk lint: per-frame code that calls libgcc maths (__divsi3, __modsi3, __mulsi3, ...) |
On a 68000 these are slow library calls. VOIDRUNNER hand-replaced them; nothing caught a stray %. |
done: agk lint, a summary after agk build, agk_lint over MCP. It found a 32-bit multiply in VOIDRUNNER's boss sweep. |
| 2 | agk art: declared colours keep their slot even when unused; pin with @slot |
An unused colour shifted the ship's last three out of the starfield's slots 29-31, silently. | done: pins (W 0xFFF @31, or slots = {31 = "0xFFF"} for PNGs) and a warning when an unused listed colour moves the ones after it. Kept backward compatible: every example's art converts byte-identically. |
| 3 | Scenario motion checks: expect-scroll |
The backdrop jumped 16 px every 64 frames and every test passed: screenshots can't see motion. | done: expect-scroll X0 Y0 X1 Y1 FRAMES DX [DY]. Put back in VOIDRUNNER, the old bug fails it with "frame 13: -17, frame 17: +15"; the game now has tests/scroll.agk. |
| 4 | agk profile: where the frame goes (CPU functions, blitter, DMA) |
Finding the 105% frame took awk over the serial log. | done: the emulator samples the PC and the bus every raster line and knows each frame's working time; agk profile SCENARIO reports load, bus use, functions and the heaviest frames, --disasm FUNC per instruction, agk_profile over MCP. First finding: VOIDRUNNER's heaviest frames are CPU-bound (blitter ~8% of the bus), not blitter-bound as assumed. |
| 5 | agk art-fit: fit any PNG (Retro Diffusion --free-colors) to the game's palette |
Every game needs it; VOIDRUNNER wrote art/tools/from_rd.py. |
done, in agk art-export (it already made text art from PNGs): --palette, --pin 0xRGB@REG, --dither, --trim; reductions leave room for pins. It reproduces VOIDRUNNER's hand-made Retro Diffusion conversions; animation frames (the Warden's flash) stay game code. art-gen --free-colors points to it. |
| 6 | agk record for READMEs: --gif-start, --gif-size, --gif-colors |
The docs GIF was made by hand with ffmpeg. | done: those, --size, and --readme (640x512 MP4 + 6 s 480x384 GIF). The GIF now comes from the clean frames in the same ffmpeg pass: VOIDRUNNER's 6 s GIF is 0.9 MB instead of 2.5 MB. |
| 7 | runtime/: blit queue, double-buffered copper lists, HUD split, sprite starfield |
Each game rebuilt them from scratch. | done: agk/blitq.h, copw.h, text.h (with the kit font) and stars.h; VOIDRUNNER and the sidescroller use them with every golden unchanged. See #14. |
| 8 | Perf chart per test run (load over time, with the game's state) | Seeing where the peak is, at a glance. | done with #4: load.png, one column per game frame (blue CPU-bound, orange blitter-bound, red over budget). |
| 9 | Scenarios that start from a checkpoint (a saved state mid-level) | perf plays the whole level to reach the boss. |
done: checkpoint NAME and start-at NAME, cached per build and per the lines leading there, made again automatically. VOIDRUNNER's boss test runs the Warden fight in 3 s instead of replaying 70 s of level. |
| 10 | Warn when two sprite channels need the same colour registers with different colours | Sprites share colour registers in pairs. | done: a 3-colour sprite inside an attached sprite's registers 17-31 with other colours, and palette.txt setting those registers to others (black placeholders aside), both warn with the fix (pin). Same-pair sprites were already an error. |
| 11 | Chip-RAM report: AGK mem lines and an expect-min-chip-free check |
Games die mysteriously when the 512 K runs out. | done: AGK mem chip= chipmax= fast= with every perf line (AvailMem under Forbid, no OS switch), expect-min-chip-free KB, the lowest values in every run's report. VOIDRUNNER has 134 KB of chip left on Kickstart 1.3. |
| 12 | agk release: ADF + README + screenshot zipped for Aminet / itch.io |
The step that turns a build into a download. | done: agk release → build/release/NAME-VERSION.zip (ADF, executable, README.txt, a 640x512 screenshot from a scenario) and an Aminet-format .readme, from agk.toml [release]. |
| 13 | agk map: Tiled .tmj → ACE tilemaps |
Levels bigger than one need a real format and editor. | done: agk map reads Tiled JSON (external or embedded tilesets, csv/base64/zlib) into plain-C tables: tile layers column-major for ACE, a bounds-checked mapNameAt, tile property bits, objects with classes and number properties, a drawn preview. The sidescroller's level and enemy spawns moved into maps/level1.tmj with every golden unchanged. |
| 14 | Roadmap #7, the rest: copper lists, HUD split, sprite starfield in runtime/ |
So the next shooter starts where VOIDRUNNER ended. | done: copw.h (used by VOIDRUNNER and the sidescroller), text.h + g_pAgkFont8 (tools/font8.py), stars.h (its hot loop in asm). Lint now checks the runtime too, and the profiler caught two regressions on the way: a 32-bit multiply per text row, and a compare loop spilled to the stack. |
| 15 | Techniques: sprite multiplexing, an asm hot path checked against C, a trackloader with packed data | Planned in techniques/README.md since phase 1. |
done: techniques/hotpath (asm checked against C by the blitter, timed), techniques/multiplex (24 bullets from 6 channels), techniques/loading (disk/ packed by the build, agkLoadFile; a trackloader isn't worth losing AmigaDOS for). |
| 16 | Reading foreign games: agk inspect (any ADF, scripted, sampled, snapshots, dumps, --disasm), agk rip (copper lists, the screen, bitmaps, tile sheets), agk regs in the emulator |
The user wants to port Ocean's RoboCop; others will bring their own disks. | done: docs/reading-games.md is the RoboCop walkthrough; the self-test inspects and rips the kit's own hello disk. Not followed yet: copper jumps (COPJMP2 lists), sprites in rips, hires fetch. |