Move outstanding work from TODO.md into the issue tracker

TODO.md carried two records in one file: what had been done, with the
measurements behind it, and what was left. The second half is what a tracker
is for, and keeping it here has already cost something -- AGENTS.md records a
round where eleven entries described code that had already changed, and this
file admitted to three more.

Every open item is now an issue on source.starfort.tech/andrew/libakgl,
labelled by kind and blast radius and milestoned by what it can land in: 0.9.x
for anything that breaks no ABI, 0.10.0 for new or changed public symbols,
1.0.0 for the design work. Four are epics: the performance plan (#60),
coverage (#61), actor rotation (#62), and the false header comments (#63).

Verified against the tree before filing rather than transcribed. Three entries
were already fixed and were not filed: the akgl_path_relative context leak, the
akgl_draw_background test extension, and the SDL enumeration audit -- keyboards,
gamepads and mappings are all freed in CLEANUP today. Two were reworded because
the code had moved: the fonts item is a missing teardown entry point rather than
a missing API, since akgl_text_unloadallfonts exists, and draw_world's tilemap
call is already bounded by numlayers, so only the per-layer actor rescan remains.

TODO.md keeps the part a tracker has no place for: why a decision went the way
it did, what the measurement was, and which arguments turned out to be wrong.

TODO.txt is deleted. Four of its eight entries had shipped -- actor-to-actor
collision, actor-to-world collision, automatic facing, image layers -- and the
four that had not are #74 through #77, with the GPU renderer's research links
kept because that is the part that took the time.

Every reference that named an item number or a moved section is repointed, in
the manual, the headers, the tests and the examples.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
This commit is contained in:
2026-08-02 18:47:34 -04:00
parent c399ef75d3
commit ff4af80693
43 changed files with 850 additions and 2520 deletions

View File

@@ -412,7 +412,7 @@ window:
```
Without this line the first frame calls through a null function pointer. Making the library
pick a default is tracked in `TODO.md` under "Known and still open"; until it does, this call
pick a default is issue #36; until it does, this call
belongs in every libakgl program.
### The frame loop
@@ -524,7 +524,7 @@ Assign it right after `akgl_game_init()`:
```
The hook exists so a game can shed work when it is running slowly. This one has nothing to
shed. The first-second false positive is recorded in `TODO.md`.
shed. The first-second false positive is recorded in `TODO.md`, "Performance".
---
@@ -763,8 +763,7 @@ Add three custom properties to the **map itself** (Map → Map Properties):
| `physics.drag.y` | float | `1.5` | Air resistance on the vertical axis |
Gravity of 900 px/s² with a drag of 1.5 gives a terminal fall speed of 600 px/s. Drag is what
bounds a fall, so do not set it to zero. (A `terminal_velocity` setting is in `TODO.md` under
"Arcade physics feel".)
bounds a fall, so do not set it to zero. (A `terminal_velocity` setting is issue #29.)
Putting physics in the map rather than in code is what lets a swimming level and a walking
level differ by data.
@@ -816,7 +815,7 @@ Then the map:
**Load into `akgl_gamemap`, which already points at storage the library owns.** Do not
declare an `akgl_Tilemap` on the stack: it is about 26 MB, several times a default thread
stack, and you get a segfault before the loader writes a byte. Shrinking it is `TODO.md`
stack, and you get a segfault before the loader writes a byte. Shrinking it is issue #28
targets 14 and 15.
That one call creates an actor for every `actor` object in the object layer, binds each to
@@ -1200,7 +1199,7 @@ Snap to zero below a pixel per second, because an exponential decay never actual
The library's own `akgl_actor_cmhf_left_off` zeroes `tx` outright, which stops the actor dead
in one frame — right for a top-down game, wrong for a sidescroller. Friction and deceleration
in the backend are tracked in `TODO.md` under "Arcade physics feel"; when they land, this
in the backend are issues #29 through #32; when they land, this
whole section becomes a setting.
### The whole movement function, in order
@@ -1569,7 +1568,7 @@ else.
underneath the registry that still points at them.
Do not call `akgl_tilemap_release` unless you are loading a second level — it has a
double-free, recorded in `TODO.md` under "Known and still open" item 2. A process that is
double-free, recorded in `TODO.md` under "Defects". A process that is
exiting can leave the textures to `SDL_Quit`.
### Reporting a failure from `main`