docs/tutorials/assets/jrpg/npc_elder.png

<EFBFBD>PNG


IHDR<01> 邲<>-PLTE\bxzw<7A><77><EFBFBD><EFBFBD><EFBFBD>ə<EFBFBD><C999><EFBFBD>eA@<40>RC<52><43><EFBFBD>܆R<DC86><52><EFBFBD><EFBFBD>ȡ<EFBFBD>vR6<52>iB<69>y_J<5F><4A>tRNS@<40><>fZIDATX<54>퓻jA<14>Gն<47>C ^<5E><01>+<13><><1A>%<16> <20>z<EFBFBD>ILV<4C><56>A&<26>	<09>#<23>T[<5B>Za<5A><61>28<32>@<40>@<40>%E<>2[霳<>1<EFBFBD>R<EFBFBD><52>}s<><73><EFBFBD>M<13><>*y<1D><><EFBFBD><EFBFBD><EFBFBD>yrl<72><6C><EFBFBD><EFBFBD><EFBFBD>}XCn<43>v<EFBFBD><76>d3<17><><EFBFBD>N^<5E>)<29><><EFBFBD><EFBFBD><EFBFBD>8sǦ><3E><><EFBFBD>{<7B>➎<EFBFBD><E29E8E>]$<02><><EFBFBD>_v<5F>̄m<CC84>u4<75>ܯ6u̅7lG<6C>\<5C>v<EFBFBD><76><EFBFBD>̄]
<0A><05><>ZY<5A>LPtZ<1D>K<><4B><EFBFBD>0~<7E><06><><EFBFBD>hժx@<40>^<5E><><EFBFBD>i5<69>i8%<25><>Z<EFBFBD>{f<><66>:/<2F><><18>pa<70><61><EFBFBD>u<EFBFBD>a<EFBFBD><61><EFBFBD><EFBFBD>L<EFBFBD><4C>X<EFBFBD>"<22><><EFBFBD><EFBFBD><EFBFBD>򾆹<EFBFBD>թT<D5A9><54>b<EFBFBD>&(G<><47><EFBFBD>j<EFBFBD><6A>Y<EFBFBD>4F<13><><EFBFBD>O_<4F>2>G<>|~}<7D><>G<EFBFBD>b<EFBFBD><62><EFBFBD>d<EFBFBD><64>><3E><><EFBFBD><16>Jp<4A>z<>Ӄ<EFBFBD>ц<EFBFBD>	##%<25><0B><><EFBFBD><EFBFBD><0B>W<EFBFBD><57>q}<7D><>
<EFBFBD>.<2E><>q<EFBFBD><71><EFBFBD><1C>T<EFBFBD>+<2B>3<03>`<60><><EFBFBD>	<09><>O<0F><><03><>+<00><>h<EFBFBD>I<EFBFBD>,7<><06>_G<5F><47>_<16>#<23>H}<7D><05><><EFBFBD><1B><><EFBFBD><EFBFBD>to<00><><0E><><EFBFBD>/0<><30><EFBFBD>x<EFBFBD>4<>
H<><48>kd$<24>7 <20><>`<01><>]<5D>T<EFBFBD>')<29><>
<EFBFBD><EFBFBD>>R5<52><35><0E>Q@(&o<><6F><02><1F><><EFBFBD><EFBFBD><EFBFBD>B6<42><36>?s<16>Q<EFBFBD><51>)?<3F>>~(i<03> ea"I<>[<5B><18><>gQ<67><51><EFBFBD>fa<66>k<EFBFBD><6B><EFBFBD><EFBFBD>><3E><><EFBFBD>}<7D><1F><><EFBFBD>&-٤V\<5C>7,A<><41><EFBFBD><EFBFBD><EFBFBD><EFBFBD>L	<09><><03><>[<5B><><05><>.<2E><17><><EFBFBD>IEND<4E>B`<60>
-												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\bxzw<7A><77><EFBFBD><EFBFBD><EFBFBD>ə<EFBFBD><C999><EFBFBD>eA@<40>RC<52><43><EFBFBD>܆R<DC86><52><EFBFBD><EFBFBD>ȡ<EFBFBD>vR6<52>iB<69>y_J<5F><4A>tRNS@<40><>fZIDATX<54>퓻jA<14>Gն<47>C ^<5E><01>+<13><><1A>%<16> <20>z<EFBFBD>ILV<4C><56>A&<26>	<09>#<23>T[<5B>Za<5A><61>28<32>@<40>@<40>%E<>2[霳<>1<EFBFBD>R<EFBFBD><52>}s<><73><EFBFBD>M<13><>*y<1D><><EFBFBD><EFBFBD><EFBFBD>yrl<72><6C><EFBFBD><EFBFBD><EFBFBD>}XCn<43>v<EFBFBD><76>d3<17><><EFBFBD>N^<5E>)<29><><EFBFBD><EFBFBD><EFBFBD>8sǦ><3E><><EFBFBD>{<7B>➎<EFBFBD><E29E8E>]$<02><><EFBFBD>_v<5F>̄m<CC84>u4<75>ܯ6u̅7lG<6C>\<5C>v<EFBFBD><76><EFBFBD>̄]
<0A><05><>ZY<5A>LPtZ<1D>K<><4B><EFBFBD>0~<7E><06><><EFBFBD>hժx@<40>^<5E><><EFBFBD>i5<69>i8%<25><>Z<EFBFBD>{f<><66>:/<2F><><18>pa<70><61><EFBFBD>u<EFBFBD>a<EFBFBD><61><EFBFBD><EFBFBD>L<EFBFBD><4C>X<EFBFBD>"<22><><EFBFBD><EFBFBD><EFBFBD>򾆹<EFBFBD>թT<D5A9><54>b<EFBFBD>&(G<><47><EFBFBD>j<EFBFBD><6A>Y<EFBFBD>4F<13><><EFBFBD>O_<4F>2>G<>|~}<7D><>G<EFBFBD>b<EFBFBD><62><EFBFBD>d<EFBFBD><64>><3E><><EFBFBD><16>Jp<4A>z<>Ӄ<EFBFBD>ц<EFBFBD>	##%<25><0B><><EFBFBD><EFBFBD><0B>W<EFBFBD><57>q}<7D><>
 								<EFBFBD>.<2E><>q<EFBFBD><71><EFBFBD><1C>T<EFBFBD>+<2B>3<03>`<60><><EFBFBD>	<09><>O<0F><><03><>+<00><>h<EFBFBD>I<EFBFBD>,7<><06>_G<5F><47>_<16>#<23>H}<7D><05><><EFBFBD><1B><><EFBFBD><EFBFBD>to<00><><0E><><EFBFBD>/0<><30><EFBFBD>x<EFBFBD>4<>
H<><48>kd$<24>7 <20><>`<01><>]<5D>T<EFBFBD>')<29><>
 								<EFBFBD><EFBFBD>>R5<52><35><0E>Q@(&o<><6F><02><1F><><EFBFBD><EFBFBD><EFBFBD>B6<42><36>?s<16>Q<EFBFBD><51>)?<3F>>~(i<03> ea"I<>[<5B><18><>gQ<67><51><EFBFBD>fa<66>k<EFBFBD><6B><EFBFBD><EFBFBD>><3E><><EFBFBD>}<7D><1F><><EFBFBD>&-٤V\<5C>7,A<><41><EFBFBD><EFBFBD><EFBFBD><EFBFBD>L	<09><><03><>[<5B><><05><>.<2E><17><><EFBFBD>IEND<4E>B`<60>