From 78a924defabc862a7cfa5476091152c1ef5333ee Mon Sep 17 00:00:00 2001
From: Gene Pasquet <dev@etenil.net>
Date: Mon, 6 Apr 2026 03:41:09 +0100
Subject: Fixes, updated license

---
 docs/guide.org | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

(limited to 'docs/guide.org')

diff --git a/docs/guide.org b/docs/guide.org
index af6319e..ca9cfbf 100644
--- a/docs/guide.org
+++ b/docs/guide.org
@@ -214,9 +214,33 @@ Key points:
 
 See =demo/platformer.scm= in the engine source for a complete working example.
 
+* Development Tips
+
+** Debug Mode
+
+During development, enable ~debug?: #t~ on ~make-game~ to visualize collision boxes and the tile grid. This helps you understand what the physics engine "sees" and debug collision problems:
+
+#+begin_src scheme
+(define my-game
+  (make-game
+    title: "My Game" width: 600 height: 400
+    debug?: #t))  ;; Enable collision visualization
+
+(game-run! my-game)
+#+end_src
+
+With debug mode enabled, you'll see:
+
+- **Purple outlines** around all non-zero tiles
+- **Blue boxes** around player entities
+- **Red boxes** around enemy entities
+- **Green boxes** around active attack hitboxes
+
+This is invaluable for tuning collision geometry and understanding why entities are clipping or not colliding as expected.
+
 * Demo Overview
 
-Downstroke includes five complete demo games that showcase different features:
+Downstroke includes seven complete demo games that showcase different features:
 
 | Demo | File | What it shows |
 |------|------|--------------|
@@ -225,6 +249,8 @@ Downstroke includes five complete demo games that showcase different features:
 | Physics Sandbox | =demo/sandbox.scm= | Entity-entity collision, multi-entity physics, auto-respawn |
 | Shoot-em-up | =demo/shmup.scm= | No tilemap, entity spawning/removal, manual AABB collision |
 | Audio | =demo/audio.scm= | Sound effects, music toggle, text rendering |
+| Sprite Font | =demo/spritefont.scm= | Bitmap text rendering using non-contiguous tileset ranges |
+| Menu | =demo/menu.scm= | State machine menus, keyboard navigation, TTF text rendering |
 
 Each demo is self-contained and serves as a working reference for a particular game mechanic.
 
@@ -235,7 +261,7 @@ If you cloned the downstroke source, you can build everything:
 #+begin_src bash
 cd /path/to/downstroke
 make          # Compile all engine modules
-make demos    # Build all 5 demo executables
+make demos    # Build all demo executables
 ./bin/demo-platformer
 ./bin/demo-topdown
 # etc.
-- 
cgit v1.2.3