diff options
Diffstat (limited to 'docs/api.org')
| -rw-r--r-- | docs/api.org | 28 |
1 files changed, 20 insertions, 8 deletions
diff --git a/docs/api.org b/docs/api.org index f6cfe50..1f15945 100644 --- a/docs/api.org +++ b/docs/api.org @@ -55,7 +55,7 @@ Lifecycle order within each frame: 1. Collect SDL2 events 2. Update input state 3. Call ~update:~ hook (or active state's ~update~) -4. Clear renderer +4. Set the renderer clear color from the current scene's ~background:~ (see ~make-scene~), then clear the framebuffer (~#f~ or invalid value uses opaque black) 5. Call ~render-scene!~ (if scene is set) 6. Call ~render:~ hook (or active state's ~render~) 7. Present renderer @@ -153,9 +153,11 @@ Auto-generated by defstruct. Use keyword arguments: (make-scene #!key (entities '()) (tilemap #f) + (tileset #f) (camera #f) (tileset-texture #f) - (camera-target #f)) + (camera-target #f) + (background #f)) #+end_src Creates a scene record representing the current level state. @@ -164,9 +166,11 @@ Creates a scene record representing the current level state. |-----------+------+---------+-------------| | ~entities~ | list | ~'()~ | List of entity plists | | ~tilemap~ | tilemap/false | #f | Tile grid and collisions | +| ~tileset~ | tileset/false | #f | Tileset metadata (from ~load-tileset~) when there is no tilemap; required with ~tileset-texture~ to draw ~#:tile-id~ sprites without a TMX map | | ~camera~ | camera/false | #f | Viewport position | | ~tileset-texture~ | SDL2 texture/false | #f | Rendered tileset image | | ~camera-target~ | symbol/false | #f | Tag symbol of the entity to follow (see ~scene-camera-target-set!~) | +| ~background~ | list/false | #f | Framebuffer clear color: ~(r g b)~ or ~(r g b a)~ (0–255). ~#f~ means opaque black. Set each frame in ~game-run!~ before ~SDL_RenderClear~. | ** ~make-camera~ @@ -358,7 +362,7 @@ Returns true if ~step-symbol~ appears in the entity’s ~#:skip-pipelines~ list (define-pipeline (procedure-name skip-symbol) (entity-formal extra-formal ...) body ...) #+end_src -Syntax for authors of per-entity pipeline steps: expands to a ~define~ that returns the **first** formal (the entity) unchanged when ~skip-symbol~ is listed in ~#:skip-pipelines~; otherwise runs ~body ...~ inside ~(let () ...)~. Used throughout ~downstroke-physics~; other modules can use it for consistent skip behavior. The procedure name and skip symbol differ when needed (e.g. ~detect-ground~ vs ~ground-detection~). +Syntax for authors of per-entity pipeline steps: expands to a ~define~ that returns the **first** formal (the entity) unchanged when ~skip-symbol~ is listed in ~#:skip-pipelines~; otherwise runs ~body ...~ inside ~(let () ...)~. Used throughout ~downstroke-physics~; other modules can use it for consistent skip behavior. The procedure name and skip symbol differ when needed (e.g. ~detect-on-solid~ vs ~on-solid~). ** Shared Entity Keys @@ -403,7 +407,7 @@ The built-in physics functions are normally run in this order each frame (after 5. ~resolve-tile-collisions-x~ — snap against horizontal tile collisions 6. ~apply-velocity-y~ — move by ~#:vy~ 7. ~resolve-tile-collisions-y~ — snap against vertical tile collisions -8. ~detect-ground~ — set ~#:on-ground?~ if standing on a tile +8. ~detect-on-solid~ — set ~#:on-ground?~ if standing on a tile and/or another solid entity (optional third argument) 9. ~resolve-entity-collisions~ — push apart solid entities (whole list) Entities may list ~#:skip-pipelines~ to omit specific steps; see ~entity-skips-pipeline?~ under ~downstroke-entity~ and ~docs/physics.org~. @@ -466,13 +470,13 @@ Detects and resolves collisions between the entity's bounding box and solid tile Detects and resolves collisions between the entity's bounding box and solid tiles along the Y axis. Snaps the entity's ~#:y~ to the near/far tile edge and sets ~#:vy~ to 0. Returns a new entity. -** ~detect-ground~ +** ~detect-on-solid~ #+begin_src scheme -(detect-ground entity tilemap) +(detect-on-solid entity tilemap #!optional other-entities) #+end_src -Probes one pixel below the entity's feet to detect if it is standing on a solid tile. Sets ~#:on-ground?~ to true or false. Only applies if ~#:gravity?~ is true. Returns a new entity. +Sets ~#:on-ground?~ to true if the entity is supported by a solid tile (probe below the feet) and/or, when ~other-entities~ is a list, by another solid's top surface (e.g. moving platforms). Omit the third argument for tile-only detection. Only applies if ~#:gravity?~ is true. Returns a new entity (the ~?~-suffix denotes call-site readability, not a boolean return value). Prefer calling after all collision resolution when using the entity list. ** ~apply-jump~ @@ -629,7 +633,7 @@ The renderer module provides SDL2 drawing abstractions. (render-scene! renderer scene) #+end_src -Draws the entire scene: first the tilemap layers, then all entities. Called automatically by ~game-run!~ before the user's ~render:~ hook. Does nothing if the scene is ~#f~. +Draws the entire scene: tilemap layers (if any), then every entity. Sprites use ~#:tile-id~ and the scene's tileset texture when both are available; otherwise an entity with ~#:color~ ~(r g b)~ or ~(r g b a)~ is drawn as a filled rectangle. Called automatically by ~game-run!~ before the user's ~render:~ hook. Does nothing if the scene is ~#f~. ** ~entity-screen-coords~ @@ -1207,6 +1211,14 @@ Loads a TSX tileset file, stores it in the game asset registry under ~key~, and Opens a TTF font at ~size~ points, stores it in the game asset registry under ~key~, and returns the font. Wraps ~ttf:open-font~. +** ~create-texture-from-tileset~ + +#+begin_src scheme +(create-texture-from-tileset renderer tileset) +#+end_src + +Creates an SDL2 texture from a tileset struct's image surface (after ~load-tileset~ / ~game-load-tileset!~). Use with ~make-scene~ when ~tilemap~ is ~#f~ but entities use ~#:tile-id~. + ** ~create-tileset-texture~ #+begin_src scheme |