path: root/docs/scenes.org

#+TITLE: Scenes, Cameras, and Game States
#+AUTHOR: Downstroke Project

* Overview

A /scene/ in Downstroke is the immutable record that answers the question "what should the engine simulate and draw right now?". It bundles the entity list, an optional tilemap (for TMX-backed levels), an optional tileset (for sprite-only games that still want tile-sheet rendering), a camera, a background clear color, and a choice of which physics pipeline to run. Each frame the engine reads the current scene from the ~game~ struct, runs an engine-update pass on its entities, lets your ~update:~ hook produce a /new/ scene, snaps the camera to a tagged target if asked, and then hands the new scene to the renderer.

Everything about scenes is built around swapping one immutable value for another: constructors like ~make-scene~ and ~make-sprite-scene~ build them; accessors like ~scene-entities~ and ~scene-camera~ read them; functional transformers like ~scene-map-entities~ and ~scene-add-entity~ return new scenes; and ~game-scene-set!~ is the single point where the engine sees the new state. If you also want more than one "mode" — a title screen and a play screen, say, or a paused state and a gameplay state — Downstroke layers a lightweight /game state/ system on top, so each state gets its own update and render hooks while sharing the same scene or building its own on demand.

* The minimum you need

The smallest scene is a sprite-only one with a single entity, built inside the ~create:~ hook:

#+begin_src scheme
(import scheme
        (chicken base)
        (only (list-utils alist) plist->alist)
        downstroke-engine
        downstroke-world
        downstroke-entity
        downstroke-scene-loader)

(define (make-player)
  (plist->alist
   (list #:type 'player #:x 100 #:y 100
         #:width 32 #:height 32
         #:color '(100 160 255))))

(game-run!
 (make-game
  title:  "Minimal Scene"
  width:  320 height: 240
  create: (lambda (game)
            (game-scene-set! game
              (make-sprite-scene
                entities:   (list (make-player))
                background: '(20 22 30))))))
#+end_src

That is all that is required to put a blue square on a dark background. ~make-sprite-scene~ fills in sensible defaults for everything you have not specified — no tilemap, a camera at ~(0, 0)~, no camera target, the default (physics) engine update — and ~game-scene-set!~ installs the result on the game. From here on, every section in this document describes a field you can fill in or a function you can compose to reshape what is on screen.

* Core concepts

** The scene record

~scene~ is a record type defined with ~defstruct~ in ~downstroke-world~. Its fields map one-to-one onto the things the engine needs to know about the current frame:

| Field             | Type                           | Purpose                                                                                          |
|-------------------+--------------------------------+--------------------------------------------------------------------------------------------------|
| ~entities~        | list of entity alists          | Every entity the engine simulates and draws this frame.                                          |
| ~tilemap~         | ~tilemap~ struct or ~#f~       | Optional TMX-loaded tilemap (layers + embedded tileset). ~#f~ for sprite-only scenes.            |
| ~tileset~         | ~tileset~ struct or ~#f~       | Optional tileset used for sprite rect math when ~tilemap~ is ~#f~.                               |
| ~camera~          | ~camera~ struct                | The viewport offset (see /Cameras/ below).                                                       |
| ~tileset-texture~ | SDL2 texture or ~#f~           | GPU texture used to draw tiles and any entity with a ~#:tile-id~. ~#f~ is allowed (see note).    |
| ~camera-target~   | symbol or ~#f~                 | A tag the engine will auto-follow with the camera. ~#f~ disables auto-follow.                    |
| ~background~      | ~#f~ or ~(r g b)~ / ~(r g b a)~ | Framebuffer clear color. ~#f~ means plain black.                                                 |
| ~engine-update~   | ~#f~, procedure, or ~'none~    | Per-scene physics pipeline choice (see below).                                                   |

The raw ~make-scene~ constructor is auto-generated by ~defstruct~ and accepts every field as a keyword argument. It does /not/ provide defaults — if you call ~make-scene~ directly you must pass every field, or wrap it with ~make-sprite-scene~ (below) which does the defaulting for you. The paired functional copier ~update-scene~ takes an existing scene and returns a new one with only the named fields replaced:

#+begin_src scheme
(update-scene scene
  entities:      (list new-player)
  camera-target: 'player)
#+end_src

*** What each "optional" field actually means

- ~tilemap: #f~ — sprite-only scenes. No tilemap rendering, no tile collisions (the physics pipeline tile-collision steps no-op when there is no tilemap). Used by all the shmup, topdown, tween, scaling, and sandbox demos when they want full control over layout.
- ~tileset: #f~ — fine when the scene has a ~tilemap~ (the renderer falls back to ~(tilemap-tileset tilemap)~ for rect math) /or/ when no entity has a ~#:tile-id~. Set it explicitly only when you have sprites but no tilemap and still want tile-sheet rendering (the ~animation~ and ~sandbox~ demos do this).
- ~tileset-texture: #f~ — allowed. The renderer's ~draw-entity~ guards on the texture being present and falls back to ~#:color~ rendering when it is missing, so sprite entities are /not/ silently dropped on ~#f~ — they draw as solid colored rectangles. Tilemap layers are simply skipped if either ~tilemap~ or ~tileset-texture~ is ~#f~.
- ~background: #f~ — the renderer clears the framebuffer with opaque black every frame. Any non-~#f~ value must be a list of at least three 0–255 integers; a four-element list includes alpha.
- ~engine-update:~ — three forms are accepted:
  - ~#f~ (the default) means "inherit": the engine runs ~default-engine-update~, which is the built-in physics pipeline (tweens → acceleration → gravity → velocity → tile collisions → ground detection → entity collisions → group sync → animation).
  - A procedure ~(lambda (game dt) ...)~ replaces the pipeline entirely for this scene. You are fully responsible for whatever transformations of ~(game-scene game)~ should happen each frame.
  - The symbol ~'none~ disables engine-update altogether — nothing runs before your ~update:~ hook. Used by the shmup and scaling demos which hand-roll all motion.
- ~camera-target:~ — a symbol that will be looked up via ~scene-find-tagged~ in each entity's ~#:tags~ list. When set, the engine centers the camera on that entity on every frame and clamps the result to ~x ≥ 0~ and ~y ≥ 0~. ~#f~ disables auto-follow (you can still move ~scene-camera~ yourself).

All eight fields are plain slots: read them with ~scene-entities~, ~scene-tilemap~, ~scene-camera~, ~scene-camera-target~, ~scene-background~, ~scene-engine-update~, and so on.

** Constructing a scene

Downstroke offers three escalating ways to build a scene, from full manual control to "load a whole level off disk in one call".

*** ~make-scene~ — full control

The auto-generated constructor accepts every slot as a keyword and does no defaulting. You will use it when you want to build a scene by hand with some exotic combination of fields, most often because you are bypassing the physics pipeline or embedding a procedurally built tilemap:

#+begin_src scheme
(make-scene
  entities:        (list (make-player))
  tilemap:         #f
  tileset:         #f
  camera:          (make-camera x: 0 y: 0)
  tileset-texture: #f
  camera-target:   #f
  engine-update:   'none)
#+end_src

This is the form the ~shmup~ and ~scaling~ demos use to turn off the physics pipeline and drive everything from their own ~update:~ hook. If you omit a field it will be unbound on the struct; prefer ~make-sprite-scene~ below unless you actually need that degree of control.

*** ~make-sprite-scene~ — convenient sprite-only scenes

~make-sprite-scene~ lives in ~downstroke-scene-loader~ and wraps ~make-scene~ with sensible defaults for sprite-only games:

#+begin_src scheme
(make-sprite-scene
  entities:        (list (make-player))
  background:      '(20 22 30))
#+end_src

It always passes ~tilemap: #f~, and supplies these defaults for anything you leave out:

| Keyword            | Default                     |
|--------------------+-----------------------------|
| ~entities:~        | ~'()~                       |
| ~tileset:~         | ~#f~                        |
| ~tileset-texture:~ | ~#f~                        |
| ~camera:~          | ~(make-camera x: 0 y: 0)~   |
| ~camera-target:~   | ~#f~                        |
| ~background:~      | ~#f~                        |
| ~engine-update:~   | ~#f~ (inherit = run physics) |

Use this whenever your game has no TMX map — see ~demo/getting-started.scm~ for the canonical example.

*** ~game-load-scene!~ — load a TMX level

When you have a Tiled (TMX) map on disk, ~game-load-scene!~ wires up the entire pipeline in one call:

#+begin_src scheme
(game-load-scene! game "demo/assets/level-0.tmx")
#+end_src

Internally it performs four steps:

1. Calls ~game-load-tilemap!~ which invokes ~load-tilemap~ to parse the TMX (via expat) and the linked TSX tileset, also loading the tileset's PNG image. The resulting ~tilemap~ struct is stored in the game's asset registry under the key ~'tilemap~.
2. Calls ~create-tileset-texture~ (a thin wrapper around ~create-texture-from-tileset~) to upload the tileset image as an SDL2 texture via the game's renderer.
3. Builds a ~scene~ with ~entities: '()~, the parsed ~tilemap~, the fresh tileset texture, a camera at the origin, and no camera target.
4. Installs the scene on the game with ~game-scene-set!~ and returns it.

Because it returns the new scene, you can chain additional transformations before the frame begins (see the ~topdown~ and ~platformer~ demos):

#+begin_src scheme
(let* ((s0 (game-load-scene! game "demo/assets/level-0.tmx"))
       (s1 (scene-add-entity s0 (make-player)))
       (s2 (update-scene s1 camera-target: 'player)))
  (game-scene-set! game s2))
#+end_src

Note that ~game-load-scene!~ does /not/ automatically populate ~entities~ from the TMX object layer. That conversion is available as a separate function:

#+begin_src scheme
(tilemap-objects->entities tilemap registry)
#+end_src

~tilemap-objects->entities~ walks the parsed ~tilemap-objects~ and, for each TMX ~<object>~ whose ~type~ string matches a prefab in your registry, calls ~instantiate-prefab~ with the object's ~(x, y, width, height)~. Objects with no matching prefab are filtered out. You can call it yourself to build the initial entity list from the TMX objects and then feed the result to ~scene-add-entity~ or a fresh ~update-scene~.

*** Related asset loaders

Three smaller helpers register assets into ~(game-assets game)~ keyed by a symbol, so other code can fetch them with ~game-asset~:

- ~(game-load-tilemap! game key filename)~ — parse a ~.tmx~ and store the ~tilemap~ struct.
- ~(game-load-tileset! game key filename)~ — parse a ~.tsx~ and store the ~tileset~ struct.
- ~(game-load-font! game key filename size)~ — open a TTF font at a given point size and store it.

Each returns the loaded value so you can bind it directly:

#+begin_src scheme
(let* ((ts  (game-load-tileset! game 'tileset "demo/assets/monochrome_transparent.tsx"))
       (tex (create-texture-from-tileset (game-renderer game) ts)))
  ...)
#+end_src

This pattern — load once in ~preload:~ (or early in ~create:~), retrieve many times via ~game-asset~ — is how the ~animation~ and ~sandbox~ demos share one tileset across multiple prefabs and scenes.

** Manipulating scene entities

All scene transformers in ~downstroke-world~ are /functional/: they take a scene and return a new one. Nothing is mutated; the idiomatic pattern inside an ~update:~ hook is always

#+begin_src scheme
(game-scene-set! game (<transformer> (game-scene game) ...))
#+end_src

or, when composing multiple transformations, a ~chain~ form from ~srfi-197~.

*** ~scene-add-entity~

~(scene-add-entity scene entity)~ appends one entity to the entity list. Use it after ~game-load-scene!~ to drop the player into a freshly loaded TMX level:

#+begin_src scheme
(chain (game-load-scene! game "demo/assets/level-0.tmx")
  (scene-add-entity _ (make-player))
  (update-scene _ camera-target: 'player))
#+end_src

*** ~scene-map-entities~

~(scene-map-entities scene proc ...)~ applies each ~proc~ in sequence to every entity in the scene. Each ~proc~ has the signature ~(lambda (scene entity) ...) → entity~ — it receives the /current/ scene (read-only, snapshot at the start of the call) and one entity, and must return a replacement entity. Multiple procs are applied like successive ~map~ passes, in argument order.

This is the workhorse of the physics pipeline; see ~default-engine-update~ in ~downstroke-engine~ for how it is chained to apply acceleration, gravity, velocity, and so on. In game code you use it for per-entity updates that do not need to see each other:

#+begin_src scheme
(scene-map-entities scene
  (lambda (scene_ e)
    (if (eq? (entity-type e) 'demo-bot)
        (update-demo-bot e dt)
        e)))
#+end_src

*** ~scene-filter-entities~

~(scene-filter-entities scene pred)~ keeps only entities for which ~pred~ returns truthy. Use it to remove dead/expired/off-screen entities each frame:

#+begin_src scheme
(scene-filter-entities scene
  (lambda (e) (or (eq? (entity-type e) 'player) (in-bounds? e))))
#+end_src

*** ~scene-transform-entities~

~(scene-transform-entities scene proc)~ hands /the whole entity list/ to ~proc~ and expects a replacement list back. Use this when an operation needs to see all entities at once — resolving pairwise entity collisions, for instance, or synchronising grouped entities to their origin:

#+begin_src scheme
(scene-transform-entities scene resolve-entity-collisions)
(scene-transform-entities scene sync-groups)
#+end_src

The engine's default pipeline uses ~scene-transform-entities~ for exactly these two steps, because they are inherently N-to-N.

*** Tagged lookups

Two helpers let you find entities by tag without iterating yourself:

- ~(scene-find-tagged scene tag)~ returns the /first/ entity whose ~#:tags~ list contains ~tag~, or ~#f~.
- ~(scene-find-all-tagged scene tag)~ returns every such entity as a list.

Both are O(n) scans and intended for coarse queries — finding the player, all enemies of a type, the camera target — not for every-frame loops over hundreds of entities. The engine itself uses ~scene-find-tagged~ internally to resolve ~camera-target~.

*** The update idiom

Putting it together, the typical shape of an ~update:~ hook is either a single transformer:

#+begin_src scheme
update: (lambda (game dt)
          (let* ((input  (game-input game))
                 (scene  (game-scene game))
                 (player (update-player (car (scene-entities scene)) input)))
            (game-scene-set! game
              (update-scene scene entities: (list player)))))
#+end_src

or a chain of them, when multiple pipelines compose:

#+begin_src scheme
(game-scene-set! game
  (chain (update-scene scene entities: all)
    (scene-map-entities _
      (lambda (scene_ e) (if (eq? (entity-type e) 'player) e (move-projectile e))))
    (scene-remove-dead _)
    (scene-filter-entities _ in-bounds?)))
#+end_src

In both shapes, ~game-scene-set!~ is called exactly once per frame with the final scene. That single write is what the next frame's engine-update and renderer read from.

** Cameras

A /camera/ is a tiny record with two integer slots, ~x~ and ~y~, holding the top-left pixel coordinate of the viewport in world space. ~make-camera~ is the constructor:

#+begin_src scheme
(make-camera x: 0 y: 0)
#+end_src

The renderer subtracts ~camera-x~ and ~camera-y~ from every sprite and tile's world position before drawing, so moving the camera east visually scrolls everything west.

*** ~camera-follow~

~(camera-follow camera entity viewport-w viewport-h)~ returns a /new/ camera struct centered on the entity, clamped so neither ~x~ nor ~y~ goes below zero. It floors both results to integers (SDL2 wants integer rects). You can call it directly from an ~update:~ hook — for example to manually follow an entity without tagging it — but the engine provides an auto-follow mechanism built on top of it.

*** Auto-follow via ~camera-target:~

If a scene has ~camera-target:~ set to a symbol, the engine runs ~update-camera-follow~ /after/ your ~update:~ hook and /before/ rendering. That function looks up the first entity whose ~#:tags~ list contains the target symbol via ~scene-find-tagged~. If found, it replaces the scene's camera with one centered on that entity (using the game's ~width~ and ~height~ as the viewport size); if no tagged entity is found, the camera is left alone. The clamp to ~x ≥ 0~ and ~y ≥ 0~ is inherited from ~camera-follow~, so the camera never reveals negative world coordinates.

To opt in, just tag the entity you want followed and set ~camera-target:~ to that tag:

#+begin_src scheme
(define (make-player)
  (plist->alist
   (list #:type 'player
         #:x 100 #:y 50
         #:tags '(player)
         ...)))

(update-scene scene camera-target: 'player)
#+end_src

Subsequent frames will keep the camera locked to the player. To stop following, set ~camera-target:~ back to ~#f~ (you keep whatever camera position was most recent).

If you need to animate the camera yourself (shake, parallax, cutscenes), leave ~camera-target:~ at ~#f~ and edit ~scene-camera~ via ~update-scene~ from inside your own update. The engine will not override what you write so long as no target is set.

** Named game states

Many games have more than one "mode": a title menu, a playing state, a game-over screen, maybe a pause overlay. Downstroke's game-state system is a lightweight way to switch update and render hooks between modes without having to build a single mega-update.

A game state is just an alist of lifecycle hooks, built with ~make-game-state~:

#+begin_src scheme
(make-game-state #:create main-menu-create
                 #:update main-menu-update
                 #:render main-menu-render)
#+end_src

Each of ~#:create~, ~#:update~, and ~#:render~ is optional (~#f~ by default). The engine uses them as follows:

- ~#:create~ is called by ~game-start-state!~ when the state becomes active. Use it to lazily build the scene for that state (e.g. build the level the first time the player picks "Play").
- ~#:update~, if present, /replaces/ the game's top-level ~update-hook~ while this state is active. The engine's ~resolve-hooks~ prefers the state hook and falls back to the game-level hook when the state has no ~#:update~.
- ~#:render~ is handled the same way: state-level wins when present, otherwise the game-level ~render-hook~ runs.

Registration is done by name with ~game-add-state!~:

#+begin_src scheme
(game-add-state! game 'main-menu
  (make-game-state #:update main-menu-update
                   #:render main-menu-render))
(game-add-state! game 'playing
  (make-game-state #:update playing-update
                   #:render playing-render))
#+end_src

And transitions happen through ~game-start-state!~, which sets the active state and runs the new state's ~#:create~ hook if present:

#+begin_src scheme
(game-start-state! game 'main-menu)
...
(when (input-pressed? input 'a)
  (game-start-state! game 'playing))
#+end_src

Only ~update~ and ~render~ are state-scoped; ~preload~ and ~create~ at the ~make-game~ level still fire once each at boot. The engine's built-in engine-update (the physics pipeline) still runs whenever a scene exists, regardless of which state is active — states only swap which user hook drives the frame.

* Common patterns

** Sprite-only scene with no tilemap

The default choice for small demos and menus: one ~make-sprite-scene~ call, no tilemap, a plain background color.

*Getting started demo* — run with ~bin/demo-getting-started~, source in ~demo/getting-started.scm~. A blue square you push around the screen with the arrow keys; canonical minimal sprite scene.

*Tweens demo* — run with ~bin/demo-tweens~, source in ~demo/tweens.scm~. A grid of easing curves applied to moving boxes; also sprite-only.

** TMX-loaded scene with a player prefab

Load the level off disk, append the player, set up camera follow. One chain per create hook.

*Platformer demo* — run with ~bin/demo-platformer~, source in ~demo/platformer.scm~. Uses ~game-load-scene!~ for the TMX map and then ~scene-add-entity~ and ~update-scene~ to attach the player and enable camera follow.

*Topdown demo* — run with ~bin/demo-topdown~, source in ~demo/topdown.scm~. Same pattern, with ~#:gravity? #f~ on the player so the default engine-update gives four-direction motion.

** Camera following a tagged entity

Tag the entity you want the viewport to track, set ~camera-target:~ to the tag, let the engine take care of the rest:

#+begin_src scheme
(define (make-player)
  (plist->alist
   (list #:type 'player
         #:x 100 #:y 50
         #:width 16 #:height 16
         #:tags '(player)
         ...)))

;; In create:
(chain (game-load-scene! game "demo/assets/level-0.tmx")
  (scene-add-entity _ (make-player))
  (update-scene _ camera-target: 'player)
  (game-scene-set! game _))
#+end_src

Any entity carrying the right tag will be followed, and the camera clamps to non-negative world coordinates every frame. The ~platformer~ and ~topdown~ demos both use ~camera-target: 'player~ exactly this way.

** Switching between a title screen and a play state

Register two named states in ~create:~, each with its own update and render hooks, and kick off the first one. Transitions happen anywhere you have a ~game~ handle, including from inside another state's update.

*Menu demo* — run with ~bin/demo-menu~, source in ~demo/menu.scm~. Registers ~main-menu~ and ~playing~ states, switches to ~playing~ when the player selects the menu entry, and switches back on ~Escape~.

#+begin_src scheme
create: (lambda (game)
          (game-add-state! game 'main-menu
            (make-game-state #:update main-menu-update
                             #:render main-menu-render))
          (game-add-state! game 'playing
            (make-game-state #:update playing-update
                             #:render playing-render))
          (game-start-state! game 'main-menu))
#+end_src

Each state owns its render surface — in the menu demo both states clear the screen themselves, since there is no scene installed on the game — but nothing stops a state from sharing a scene: the menu state's ~#:create~ could build it, and the play state's ~#:update~ could simply read and transform ~(game-scene game)~.

** Loading multiple assets up front

The ~preload:~ hook is the one place guaranteed to run before the first scene is built, after SDL2 has opened a renderer. Use it to warm up the asset registry so ~create:~ and ~update:~ never block on I/O:

#+begin_src scheme
preload: (lambda (game)
           (game-load-tileset! game 'tiles "demo/assets/monochrome_transparent.tsx")
           (game-load-font!    game 'title "demo/assets/DejaVuSans.ttf" 24)
           (game-load-font!    game 'body  "demo/assets/DejaVuSans.ttf" 14)
           (init-audio!)
           (load-sounds! '((jump  . "demo/assets/jump.wav")
                           (coin  . "demo/assets/coin.wav"))))
#+end_src

Inside ~create:~ or ~update:~ you read them back with ~game-asset~:

#+begin_src scheme
(let ((ts  (game-asset game 'tiles))
      (fnt (game-asset game 'title)))
  ...)
#+end_src

Because the registry is a plain hash table, you can store anything — parsed JSON, precomputed tables, your own structs — under any symbol key you like. The three ~game-load-*!~ helpers are there for the file formats the engine itself understands; everything else is ~game-asset-set!~ + ~game-asset~.

* See also

- [[file:guide.org][guide.org]] — step-by-step construction of the getting-started demo, including the first ~make-sprite-scene~ call.
- [[file:entities.org][entities.org]] — the entity alist, conventional keys like ~#:tags~ and ~#:type~, and how prefabs build entities that the scene-loader instantiates.
- [[file:physics.org][physics.org]] — what the default engine-update actually does, and how to skip or replace individual pipeline steps per entity.
- [[file:rendering.org][rendering.org]] — how ~render-scene!~ walks the scene to draw tiles, sprites, and fallback colored rects.
- [[file:animation.org][animation.org]] — the animation pipeline step, run by ~default-engine-update~ on every entity.
- [[file:tweens.org][tweens.org]] — per-entity declarative tweens, stepped as the first stage of the default pipeline.
- [[file:input.org][input.org]] — action mapping and polling, used inside ~update:~ hooks to drive entity changes.
- [[file:audio.org][audio.org]] — loading and playing sound effects alongside your scene-loading hooks.