Scenes, Cameras, and Game States

• 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.

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:

(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)

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 lives in (downstroke scene-loader) and wraps make-scene with sensible defaults for sprite-only games:

(make-sprite-scene
  entities:        (list (make-player))
  background:      '(20 22 30))

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

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

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

(game-load-scene! game "demo/assets/level-0.tmx")

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):

(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))

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

(tilemap-objects->entities tilemap registry)

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.

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:

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

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.

(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:

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

(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:

(scene-map-entities scene
  (lambda (scene_ e)
    (if (eq? (entity-type e) 'demo-bot)
        (update-demo-bot e dt)
        e)))

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

(scene-filter-entities scene
  (lambda (e) (or (eq? (entity-type e) 'player) (in-bounds? e))))

(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:

(scene-transform-entities scene resolve-entity-collisions)
(scene-transform-entities scene sync-groups)

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

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.

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

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)))))

or a chain of them, when multiple pipelines compose:

(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?)))

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.

(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.

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:

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

(update-scene scene camera-target: 'player)

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.