Andrew Kesterson
6553da812c
They read as design commentary: why a choice was made, what the previous state of the project was, which library defect a line works around. That is useful to somebody who already knows the library and useless to somebody trying to build a game, which is who a tutorial is for. Both chapters now open with a screenshot of what the reader is building and a numbered list of the steps to get there, and each step is its own section: what you are trying to achieve, the code that achieves it, and the two or three things about that code that are easy to get wrong. Chapter 20 starts from first principles -- what a sprite, a character, an actor and a tilemap are, and the four error macros -- and chapter 21 assumes it and covers what a top-down game adds. Where a line exists because of a defect, the line comes first and the defect comes after it, with a pointer to the TODO entry that will remove the need. A reader who is copying code should not have to read an apology before they can use it. The library's own history is gone from both. That belongs in the design chapters and in git. Two new docs_examples setups stage the tutorials' own art, so the sprite and character files a reader is shown are loaded exactly as printed rather than through a generic fixture. `json excerpt=` is new for the same reason: a Tiled object is now quoted out of the real map instead of being retyped. Excerpts across docs/ go from 91 to 137. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KzBDV2fqgnUAcqCKqKvc71
37 lines
1.3 KiB
Bash
Executable File
37 lines
1.3 KiB
Bash
Executable File
#!/bin/bash
|
|
#
|
|
# Stage the sidescroller tutorial's own assets in the sandbox.
|
|
#
|
|
# docs/20-tutorial-sidescroller.md shows the reader a real sprite file and a real
|
|
# character file out of docs/tutorials/assets/sidescroller. Those are worth
|
|
# running through the loader exactly as printed rather than through a generic
|
|
# fixture, because a beginner following the chapter types what is on the page --
|
|
# so what is on the page has to be a file that loads.
|
|
#
|
|
# Two directories are staged, because the checker looks in two places:
|
|
#
|
|
# ./ a `json kind=sprite` block's spritesheet path is resolved
|
|
# relative to the sprite file, which lives in the sandbox root
|
|
# ./sprites tools/docs_checkjson.c loads everything here through
|
|
# akgl_sprite_load_json before it touches a `kind=character`
|
|
# block, since a character resolves its sprites by name
|
|
#
|
|
# $1 is the repository root. The caller runs this with the sandbox as the
|
|
# working directory.
|
|
|
|
set -u
|
|
|
|
ROOT="${1:-}"
|
|
if [ -z "${ROOT}" ]; then
|
|
echo "usage: sidescroller.sh <repository-root>" >&2
|
|
exit 2
|
|
fi
|
|
|
|
ASSETS="${ROOT}/docs/tutorials/assets/sidescroller"
|
|
|
|
cp "${ASSETS}"/*.png . || exit 1
|
|
|
|
mkdir -p sprites || exit 1
|
|
cp "${ASSETS}"/*.png sprites/ || exit 1
|
|
cp "${ASSETS}"/sprite_*.json sprites/ || exit 1
|