Add two tutorial games that build, run in CI, and cannot drift
examples/sidescroller and examples/jrpg are complete programs, built with the
library and exercised headless by ctest. The chapters quote them with
`c excerpt=examples/...` blocks rather than restating the code, so a chapter
cannot drift from a program that compiles -- the excerpt check fails the moment
the source moves. 34 excerpts in one chapter, 21 in the other.
The two are complementary. The sidescroller is the physics tutorial: gravity, a
jump, coins, hazards. The JRPG is the content-pipeline tutorial: a town map,
NPCs spawned from map objects, four-way per-facing animation, a text box, a
follower.
Both smoke tests drive real SDL_Events through akgl_controller_handle_event and
step the physics clock at a fixed 1/60s rather than sleeping, so a scripted run
is deterministic and finishes in under five seconds.
Writing them is what turned up most of the defects recorded in the next commit,
because a game exercises paths a unit test does not. Each workaround says in the
chapter which library gap forced it:
- collision is written in a custom movementlogicfunc, because
akgl_physics_arcade_collide raises AKERR_API and akgl_physics_simulate never
calls collide at all;
- the sidescroller cancels the step's own gravity when it blocks downward,
because otherwise a quarter-pixel of penetration makes the *horizontal* sweep
report blocked and the character walks backwards a tile at a time;
- both clear movement_controls_face on every map-spawned actor, because the
default facefunc leaves a stopped actor with no facing bit, no sprite, and no
draw;
- the JRPG's follower gets a renderfunc that nulls obj->parent for the duration
of the draw, because a child's offset is counted twice.
Assets are CC0 from three Kenney packs, vendored with per-pack licence text,
per-file provenance, and the geometry contract in
docs/tutorials/assets/README.md. CC0 specifically rather than merely free: a
reader who copies a tutorial into their own game inherits no obligation.
scripts/fetch_tutorial_assets.sh refreshes them in the shape
mkcontrollermappings.sh was fixed into for 0.5.0 -- it checks curl's status,
refuses a pack page that does not say CC0, verifies the archive and the staged
dimensions, and leaves the tracked bytes untouched on any failure. Both failure
paths were tested, and a no-op refresh is byte-identical.
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-01 20:59:00 -04:00
|
|
|
|
<EFBFBD>PNG
|
|
|
|
|
|
|
|
|
|
|
|
IHDR <01> 邲<> 'PLTE <00>RC<52>vR܆R<DC86><52><EFBFBD><EFBFBD>əeA@<40><>y6<79>iB<69>y<EFBFBD>ȡŹ<C8A1><C5B9>Ԫ<EFBFBD>V<EFBFBD><56> tRNS @<40><>f IDATX<54>햱n<ED96B1>0<10><>7<EFBFBD>Y<12><>Z <0C> <20><><EFBFBD>%-4ޜJ<DE9C><13><11> <01>$<24>d<>u3<75>!M'#KQt:<3A>U:K<><4B><EFBFBD>Bѥ<42><D1A5>}<<3C><><EFBFBD>L'ILLLLLLLLLLL<4C> <00><>n<EFBFBD>?<3F>@ <0C>h*<2A><>]9<>X>a܂<0F><>fT׳4<D7B3>R<EFBFBD><52><17><>'s<><73><EFBFBD>}<7D> <09><>^h,<2C>]}<7D><>'8<><38>I <1E><>Ox<4F>6o4<6F><34>ESW
|
|
|
|
|
|
{<7B>Yݮ<14>|j<17>}<7D><><EFBFBD><EFBFBD><EFBFBD><EFBFBD>R<EFBFBD>ؼP<D8BC><13>X<EFBFBD><58>0{<7B>Ͼ)<29>l֭<6C>R<EFBFBD><14><>LaO8o!<21><><EFBFBD><EFBFBD><EFBFBD><EFBFBD>Xa_<61>x<EFBFBD>aE>r80<38> <0B><><EFBFBD>@aO<18><>U<EFBFBD>.<2E><><EFBFBD>8f
A<>jZ<6A><5A><EFBFBD> 6<> Y<>λ<>K<EFBFBD>=<3D><>mw<6D><77><11><><EFBFBD><M<>G<>B<EFBFBD>8?<3F><>&x<>7<EFBFBD>`Z<><5A>G<EFBFBD><47>O<0F>I&爷<>÷<EFBFBD><C3B7><EFBFBD><EFBFBD><EFBFBD>?n<>\<5C> .i<03>^<17>f<EFBFBD><66><EFBFBD><EFBFBD>g<EFBFBD>I<0E><><EFBFBD><11>i<EFBFBD>_<EFBFBD><5F><EFBFBD>
<0A><>~g =.<2E> <00><><0F>&<26><>n<EFBFBD><6E><EFBFBD> <09><07>D<EFBFBD>Zx<>%<<3C><07><><EFBFBD>v8<76>K<EFBFBD><4B>cv<63>?v<14><><EFBFBD><EFBFBD>4<EFBFBD> ,<>N<><4E><EFBFBD>0{>Y%}<7D>
|
|
|
|
|
|
<EFBFBD> <00> P<><50><EFBFBD>^<5E><><EFBFBD>Z*<2A><><EFBFBD><EFBFBD><EFBFBD>4̉<34>{<7B><><EFBFBD><EFBFBD><EFBFBD>
|
|
|
|
|
|
<EFBFBD>`<60>$<24>2v<32> F<><46><EFBFBD>C<EFBFBD><0E>vg<76><67><EFBFBD><EFBFBD>L<EFBFBD><4C>q<EFBFBD>WC<57><07><><06>5<EFBFBD><35>e<EFBFBD>j IEND<4E>B`<60>
|
