libakgl/docs/tutorials/assets/README.md

# The tutorial asset contract

What `examples/sidescroller/` and `examples/jrpg/` are drawing, and the exact
numbers they have to use. Licensing is in `PROVENANCE.md`; refreshing the art
from upstream is `scripts/fetch_tutorial_assets.sh`.

Every claim below was checked against `src/`, not against header prose, and the
whole set was loaded through the real library -- `akgl_sprite_load_json`,
`akgl_character_load_json`, `akgl_tilemap_load` -- before being committed.

## Geometry

| Thing                   | Value  | Why it is that value                                                      |
|-------------------------|--------|---------------------------------------------------------------------------|
| Tile                    | 16x16  | Both tilesets ship on a 16x16 grid                                        |
| Tileset spacing, margin | 0, 0   | `akgl_tilemap_compute_tileset_offsets` gets nothing else right; see below |
| Character frame         | 32x32  | The fixed contract for these tutorials                                    |
| Art inside a frame      | 16x16  | Composited at (8, 16): centred, sitting on the cell's bottom edge         |
| Frames per sheet row    | all    | Every sheet is a single row, so `coords_for_frame` never has to wrap      |
| Frames per animation    | max 16 | `AKGL_SPRITE_MAX_FRAMES`; a 17th is `AKERR_OUTOFBOUNDS` at load           |
| Frame id                | 0..255 | `uint8_t`; a larger id is `AKERR_OUTOFBOUNDS` at load                     |

**The one alignment rule.** `akgl_actor_render` draws into a rectangle of
`sprite->width` by `sprite->height` with its top-left at the actor's `x`, `y`.
Because every frame's art is bottom-centred in its cell, an actor at `(x, y)`
has its feet at `y + 32` and its 16 px body spanning `x + 8` to `x + 23`. Ground
contact, pickup tests and hitboxes should use that inner rectangle, not the
32x32 cell.

## Sidescroller sheets

`sidescroller/player.png` -- 192x32, six frames.

| Frame | Facing | Pose                            | Used by                                       |
|-------|--------|---------------------------------|-----------------------------------------------|
| 0     | right  | contact                         | `ss_player_idle_right`, `ss_player_run_right` |
| 1     | right  | passing, airborne               | `ss_player_run_right`, `ss_player_jump_right` |
| 2     | right  | opposite contact                | `ss_player_run_right`                         |
| 3     | left   | contact (mirror of 0)           | `ss_player_idle_left`, `ss_player_run_left`   |
| 4     | left   | passing, airborne (mirror of 1) | `ss_player_run_left`, `ss_player_jump_left`   |
| 5     | left   | opposite contact (mirror of 2)  | `ss_player_run_left`                          |

The left-facing frames exist as their own art because `akgl_actor_render` passes
`SDL_FLIP_NONE` to `draw_texture` unconditionally (`src/actor.c`). There is no
way to ask the library for a mirrored blit.

`sidescroller/coin.png` -- 32x32, one frame. The pack ships no rotation frames.

`sidescroller/hazard.png` -- 128x32, four frames.

| Frame | What                     | Used by          |
|-------|--------------------------|------------------|
| 0     | red blob, ground, pose A | `ss_hazard_blob` |
| 1     | red blob, ground, pose B | `ss_hazard_blob` |
| 2     | moth, flying, wings up   | `ss_hazard_moth` |
| 3     | moth, flying, wings down | `ss_hazard_moth` |

## JRPG sheets

`jrpg/player.png`, `jrpg/npc_shopkeeper.png` and `jrpg/npc_elder.png` are
384x32, twelve frames, and share one layout.

| Frames | Facing | Poses                 | Idle sprite uses | Walk sprite uses |
|--------|--------|-----------------------|------------------|------------------|
| 0-2    | down   | stand, step A, step B | 0                | 1, 0, 2, 0       |
| 3-5    | left   | stand, step A, step B | 3                | 4, 3, 5, 3       |
| 6-8    | right  | stand, step A, step B | 6                | 7, 6, 8, 6       |
| 9-11   | up     | stand, step A, step B | 9                | 10, 9, 11, 9     |

The stand frame between the two steps is what makes it read as a walk rather
than a shuffle; it is the same three-frame cycle the source art was drawn for.

## States

A character's sprite map is keyed by `SDL_itoa(state)` and looked up with
`SDL_GetPointerProperty` (`akgl_character_sprite_get`), so **the match is on the
whole integer, not on a mask test**. A state the character has no exact entry
for makes the actor invisible for that frame -- `actor_visible` treats
`AKERR_KEY` as "nothing to draw", which is an answer, not an error.

These are the values the library's own input handlers produce.
`akgl_actor_cmhf_<dir>_on` clears every `FACE_*` and `MOVING_*` bit before
setting its own pair, and `_off` clears only its `MOVING_*` bit, so the facing
survives the key release and no two `MOVING_*` bits are ever set at once.

| State | Bits                                | Sidescroller sprite | JRPG sprite      |
|-------|-------------------------------------|---------------------|------------------|
| 16    | ALIVE                               | (coin, hazards)     | --               |
| 17    | ALIVE, FACE_DOWN                    | `..._idle_right`    | `..._idle_down`  |
| 18    | ALIVE, FACE_LEFT                    | `..._idle_left`     | `..._idle_left`  |
| 20    | ALIVE, FACE_RIGHT                   | `..._idle_right`    | `..._idle_right` |
| 24    | ALIVE, FACE_UP                      | --                  | `..._idle_up`    |
| 146   | ALIVE, FACE_LEFT, MOVING_LEFT       | `..._run_left`      | `..._walk_left`  |
| 276   | ALIVE, FACE_RIGHT, MOVING_RIGHT     | `..._run_right`     | `..._walk_right` |
| 530   | ALIVE, FACE_LEFT, MOVING_UP         | `..._jump_left`     | --               |
| 532   | ALIVE, FACE_RIGHT, MOVING_UP        | `..._jump_right`    | --               |
| 536   | ALIVE, FACE_UP, MOVING_UP           | `..._jump_right`    | `..._walk_up`    |
| 658   | ALIVE, FACE_LEFT, MOVING_LEFT, UP   | `..._jump_left`     | --               |
| 788   | ALIVE, FACE_RIGHT, MOVING_RIGHT, UP | `..._jump_right`    | --               |
| 1041  | ALIVE, FACE_DOWN, MOVING_DOWN       | --                  | `..._walk_down`  |

The four jump states are there because a sidescroller that routes its jump
through `akgl_actor_cmhf_up_on` lands on 536 -- that handler clears `FACE_RIGHT`
and sets `FACE_UP`, which in a side view is not a facing at all. A game that
sets `ey` directly instead never reaches those states, and nothing breaks
either way.

State names in character JSON are the **prefixed** spellings from
`src/actor_state_string_names.c`: `AKGL_ACTOR_STATE_ALIVE`, not
`ACTOR_STATE_ALIVE`. `util/assets/littleguy.json` uses the old unprefixed names
and `velocity_x`, and does not load against the current library. Do not copy it.

## Maps

Both maps are Tiled 1.8 TMJ with the tileset **embedded**.

`akgl_tilemap_load` reads `columns`, `firstgid`, `tilecount`, `image`,
`imagewidth`, `imageheight`, `margin`, `spacing`, `tilewidth`, `tileheight` and
`name` straight out of each element of the map's `tilesets` array
(`akgl_tilemap_load_tilesets_each`). The string `source` appears nowhere in
`src/tilemap.c` and nothing in the library ever opens a `.tsj`, so an external
tileset reference fails with `AKERR_KEY` on the missing `columns`. `README.md`
in the repository root says the opposite; it is wrong.

| Map                       | Cells | Layers                                    | Objects |
|---------------------------|-------|-------------------------------------------|---------|
| `sidescroller/level1.tmj` | 40x15 | background (tile), terrain (tile), actors | 7       |
| `jrpg/town.tmj`           | 30x20 | ground (tile), decoration (tile), actors  | 3       |

Global tile ids are `(row * columns) + column + 1`; `0` means an empty cell and
is skipped. `sidescroller/tiles.png` has ten columns and 60 tiles;
`jrpg/tiles.png` has twenty-seven columns and 486 tiles, the last four columns
of which are the character art the sheets above were cut from. Those cells are
never referenced by `town.tmj`.

Other things the loader insists on, all of them checked:

- **Every object needs a `type` string**, including ones that are not actors. A
  missing `type` fails the whole load, not just that object.
- An actor object needs a non-empty `name`, a `character` **string** property
  and a `state` **int** property. The string-array form of `state` works in
  character JSON and is not accepted here.
- The `character` named must already be in `AKGL_REGISTRY_CHARACTER`, which
  means every sprite and character JSON has to be loaded before the map.
- A map's `properties` are optional; if present, `physics.model` must name a
  backend that exists (`null` or `arcade`) or the load fails. Gravity and drag
  keys are `float`.
- Tileset image paths resolve through `akgl_path_relative` against the map's own
  directory. Image-layer paths do not -- those go through a plain `"%s/%s"`
  join, so an absolute path there does not work. Keep every path relative.

## Physics

The sidescroller map asks for the `arcade` backend with `physics.gravity.y`
900.0 and `physics.drag.y` 1.5. There is no terminal velocity in the backend;
`ey` approaches `gravity_y / drag_y`, so those two numbers set it to 600 px/s.
The JRPG map asks for `arcade` with both gravity components at 0.0.

`ss_player` has `speed_y` and `acceleration_y` of 0.0 on purpose: a zero top
speed on an axis means `akgl_physics_simulate` zeroes that axis's thrust
outright, so holding a vertical direction cannot make the player fly. A jump
belongs in `ey`.