Rendering

render-scene! is the one function game-run! calls each frame to draw the current scene. It does three things, in order:

1. Clear the framebuffer using scene-background (via renderer-set-clear-color!). A missing or non-list background falls back to opaque black.
2. Draw the tilemap, if both a tilemap and a tileset-texture are present on the scene. A missing tilemap or missing texture simply skips this step — no error.
3. Draw each entity in scene-entities via draw-entity.

draw-entity applies a strict priority when deciding how to draw one entity:

1. If #:skip-render is truthy, the entity is skipped entirely.
2. Otherwise, if the entity has a #:tile-id and the scene provides both a tileset and a tileset texture, it is drawn as a tileset sprite.
3. Otherwise, if the entity has a #:color list of three or four integers (r g b) / (r g b a), it is drawn as a filled rect.
4. Otherwise, nothing is drawn for that entity.

The #:facing key controls horizontal flip on sprite-drawn entities: #:facing -1 renders the tile mirrored, any other value renders it unflipped. #:color entities ignore #:facing.

A sprite font is a bitmap font encoded as glyphs inside a tileset. Downstroke's sprite-font record captures the tile size, spacing, and a hash table mapping characters to tile-id values. Construct one with make-sprite-font*:

(make-sprite-font*
  #:tile-size 16
  #:spacing   1
  #:ranges    '((#\A #\M 918)        ;; A-M start at tile 918
                (#\N #\Z 967)
                (#\0 #\9 869)))

Arguments:

• tile-size (keyword, required): pixel width and height of each glyph tile.
• spacing (keyword, default 1): horizontal pixels between glyphs.
• ranges (keyword, required): list of triples (start-char end-char first-tile-id). The first character in the range maps to first-tile-id, and each subsequent character maps to the next tile id.

Ranges are always stored uppercase; lookups also uppercase, so a font defined with #\A…#\Z will also render lowercase input correctly. Overlapping ranges raise an error at construction time.

To draw text, call draw-sprite-text:

(draw-sprite-text renderer tileset-texture tileset font text x y)

• renderer, tileset-texture, tileset come from the scene (typically (game-renderer game), (scene-tileset-texture scene), and (tilemap-tileset (scene-tilemap scene))).
• font is the sprite-font returned by make-sprite-font*.
• text is a string — characters not in the font's char map are silently skipped (the cursor still advances).
• x, y are pixel coordinates on the screen (not camera-local).

Two helpers are useful for layout:

• sprite-font-char->tile-id font ch returns the tile id for one character, or #f if it isn't mapped. Upcases ch first.
• sprite-text-width font text returns the total pixel width of text drawn with this font, accounting for spacing.

Sprite fonts and tile frames share the same tileset in the example demo, so the same texture that draws the level tiles also draws the HUD text. See the spritefont demo — run with bin/demo-spritefont, source in demo/spritefont.scm.

The render: keyword on make-game is an optional hook called every frame after render-scene! (and after the debug overlay, if enabled) but before render-present!. Its signature is (lambda (game) …) — no delta-time, since rendering should be a pure read of game state.

This is the right place for:

• HUDs (score, health bars, timers).
• Menu text and button overlays.
• Debug visualizations beyond the built-in overlay.
• Any SDL2 drawing that needs to go on top of the scene.

(make-game
  title: "..." width: 600 height: 400

  render: (lambda (game)
            (let ((renderer (game-renderer game)))
              ;; draw a HUD bar across the top
              (set! (sdl2:render-draw-color renderer)
                    (sdl2:make-color 0 0 0 200))
              (sdl2:render-fill-rect! renderer
                (sdl2:make-rect 0 0 600 24))
              (draw-ui-text renderer *hud-font* "SCORE 00" color 8 4))))

draw-ui-text is a thin convenience that wraps ttf:render-text-solid and create-texture-from-surface. Pass it a renderer, a TTF font (from ttf:open-font), a string, an SDL color, and the top-left pixel coordinates. For menus, draw-menu-items takes a list of items and a cursor index and stacks them vertically with a selected prefix " > " in front of the current one.

Full example: the menu demo — run with bin/demo-menu, source in demo/menu.scm. The menu demo uses draw-ui-text and draw-menu-items from a render: hook that is resolved via make-game-state (per-state render hooks override the top-level render: hook)./

Any entity with #:color '(r g b) draws as a filled rect, even when the scene has no tileset or tilemap at all. This is the fastest way to get something on screen.

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

See the getting-started demo — run with bin/demo-getting-started, source in demo/getting-started.scm.

Define your game in its logical resolution and pass scale::

(make-game
  title: "Demo: Scaling (2×)"
  width: 320 height: 240     ;; logical pixels
  scale: 2                   ;; window is 640×480
  ...)

All subsequent drawing — entities, camera, render: hook — uses the logical 320×240 coordinate space. See the scaling demo — run with bin/demo-scaling, source in demo/scaling.scm.

Build the font once in preload: or create:, then call draw-sprite-text from the render: hook:

(render: (lambda (game)
           (let* ((scene    (game-scene game))
                  (renderer (game-renderer game))
                  (tileset  (tilemap-tileset (scene-tilemap scene)))
                  (texture  (scene-tileset-texture scene)))
             (draw-sprite-text renderer texture tileset *sprite-font*
                               "HELLO WORLD" 50 50))))

See the spritefont demo — run with bin/demo-spritefont, source in demo/spritefont.scm.

Use draw-ui-text (TTF) or draw-sprite-text (bitmap) from a render: hook. The hook runs every frame, after scene rendering, so anything drawn here sits on top of the game world:

(render: (lambda (game)
           (let ((renderer (game-renderer game)))
             (draw-ui-text renderer *hud-font*
               (format #f "SCORE ~a" *score*)
               (sdl2:make-color 255 255 255) 8 4))))

See the menu demo — run with bin/demo-menu, source in demo/menu.scm — which uses draw-ui-text and draw-menu-items from per-state render hooks attached via make-game-state.

Flip on colored AABBs for players, enemies, attacks, and tile cells:

(make-game
  title: "..." width: 600 height: 400
  debug?: #t                      ;; or (command-line-arguments)-driven
  ...)

The platformer demo wires this to a --debug command-line flag — run with bin/demo-platformer --debug, source in demo/platformer.scm.

When you want sprite drawing but have no Tiled map, build the scene with make-sprite-scene and pass the tileset, tileset-texture, and any background:

(create: (lambda (game)
           (let* ((ts  (game-load-tileset! game 'tiles "assets/tiles.tsx"))
                  (tex (create-texture-from-tileset
                         (game-renderer game) ts)))
             (game-scene-set! game
               (make-sprite-scene
                 entities:        (list (make-player))
                 tileset:         ts
                 tileset-texture: tex
                 background:      '(20 22 30))))))

Because there is no tilemap, render-scene! skips the tilemap draw and goes straight to draw-entities. The sprite tileset resolves from scene-tileset as documented above.