Andrew Kesterson
88aaa184e4
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>
73 lines
3.4 KiB
CMake
73 lines
3.4 KiB
CMake
# The top-down JRPG tutorial game, quoted by docs/20-tutorial-jrpg.md.
|
|
#
|
|
# It is a real target built by `all`, not a snippet: a tutorial whose program
|
|
# does not compile is the failure this whole documentation effort exists to
|
|
# stop, and the chapter's `c excerpt=` blocks fail the moment this source moves
|
|
# under them.
|
|
|
|
add_executable(jrpg
|
|
jrpg.c
|
|
world.c
|
|
textbox.c
|
|
)
|
|
|
|
target_link_libraries(jrpg
|
|
PRIVATE akstdlib::akstdlib akerror::akerror akgl
|
|
SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image SDL3_mixer::SDL3_mixer
|
|
jansson::jansson -lm)
|
|
target_include_directories(jrpg PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}")
|
|
target_compile_options(jrpg PRIVATE ${AKGL_WARNING_FLAGS})
|
|
|
|
# The game finds its data through two absolute paths baked in here. A game that
|
|
# ships would install its assets and resolve them against SDL_GetBasePath(); a
|
|
# tutorial has to run from the build tree, from the source tree, and from
|
|
# whatever working directory CTest hands it, so the paths are compiled in.
|
|
get_filename_component(JRPG_REPO_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../.." ABSOLUTE)
|
|
target_compile_definitions(jrpg PRIVATE
|
|
JRPG_ASSET_DIR="${JRPG_REPO_ROOT}/docs/tutorials/assets/jrpg"
|
|
# tests/assets/akgl_test_mono.ttf, which ships beside its licence file.
|
|
JRPG_FONT_FILE="${JRPG_REPO_ROOT}/tests/assets/akgl_test_mono.ttf"
|
|
)
|
|
|
|
# The vendored SDL satellite libraries land in per-project subdirectories that
|
|
# are not on the loader's default search path, exactly as they do for the test
|
|
# suites. AKGL_VENDORED_RPATH is set by the top-level CMakeLists.txt and is only
|
|
# defined when something was actually vendored.
|
|
if(AKGL_VENDORED_DEPENDENCIES)
|
|
set_target_properties(jrpg PROPERTIES BUILD_RPATH "${AKGL_VENDORED_RPATH}")
|
|
endif()
|
|
|
|
# The headless smoke run. `--demo` drives the arrow keys from a script and steps
|
|
# the physics clock by a fixed 1/60 s, so the run is deterministic and finishes
|
|
# in well under a second; `--frames` bounds it. Between them the run walks the
|
|
# player into a wall, opens the text box, and exercises the follower's render
|
|
# hook -- rather than just proving that main() returns.
|
|
#
|
|
# add_test() reaches the real command here: the top-level CMakeLists.txt shadows
|
|
# it to suppress the vendored projects' registrations and lifts the suppression
|
|
# again long before examples/ is added.
|
|
add_test(NAME example_jrpg COMMAND jrpg --frames 320 --demo)
|
|
set_tests_properties(example_jrpg PROPERTIES
|
|
TIMEOUT 120
|
|
ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_RENDER_DRIVER=software;SDL_AUDIODRIVER=dummy"
|
|
)
|
|
|
|
# ENVIRONMENT above replaces the environment wholesale, so LD_LIBRARY_PATH has
|
|
# to go in the same property rather than a second one. Only needed when the
|
|
# dependencies were vendored; an installed build resolves them normally.
|
|
if(AKGL_VENDORED_DEPENDENCIES)
|
|
if(CMAKE_VERSION VERSION_GREATER_EQUAL "3.22")
|
|
set(JRPG_TEST_ENV_MOD "")
|
|
foreach(dir IN LISTS AKGL_TEST_LIBPATH)
|
|
list(APPEND JRPG_TEST_ENV_MOD "LD_LIBRARY_PATH=path_list_prepend:${dir}")
|
|
endforeach()
|
|
set_tests_properties(example_jrpg
|
|
PROPERTIES ENVIRONMENT_MODIFICATION "${JRPG_TEST_ENV_MOD}")
|
|
else()
|
|
string(REPLACE ";" ":" JRPG_TEST_LIBPATH_JOINED "${AKGL_TEST_LIBPATH}")
|
|
set_tests_properties(example_jrpg PROPERTIES
|
|
ENVIRONMENT "SDL_VIDEODRIVER=dummy;SDL_RENDER_DRIVER=software;SDL_AUDIODRIVER=dummy;LD_LIBRARY_PATH=${JRPG_TEST_LIBPATH_JOINED}:$ENV{LD_LIBRARY_PATH}"
|
|
)
|
|
endif()
|
|
endif()
|