Move the engine-update to the scene

1 files changed, 18 insertions, 32 deletions

diff --git a/docs/guide.org b/docs/guide.org
index 96663ea..d98b00e 100644
--- a/docs/guide.org
+++ b/docs/guide.org
@@ -5,7 +5,7 @@
 
 Downstroke is a 2D tile-driven game engine for Chicken Scheme, built on SDL2. It is inspired by Phaser 2: a minimal game is about 20 lines of Scheme.
 
-The engine handles SDL2 initialization, the event loop, input, rendering, and physics. You provide lifecycle hooks to customize behavior. This guide walks you through building your first game with Downstroke.
+The engine handles SDL2 initialization, the event loop, input, rendering, and — by default — a full physics pipeline each frame (~default-engine-update~). You provide lifecycle hooks to customize behavior; ~update:~ is where you usually set movement *intent* (~#:vx~, ~#:vy~, ~#:ay~) and game rules. This guide walks you through building your first game with Downstroke.
 
 * Installation
 
@@ -89,18 +89,13 @@ Now let's add an entity you can move with the keyboard. Create =square.scm=:
       (let* ((input  (game-input game))
              (scene  (game-scene game))
              (box    (car (scene-entities scene)))
-             ;; Read input and update velocity
+             ;; Intent only: default engine-update integrates #:vx / #:vy each frame
              (box    (entity-set box #:vx (cond ((input-held? input 'left)  -3)
                                                  ((input-held? input 'right)  3)
                                                  (else 0))))
              (box    (entity-set box #:vy (cond ((input-held? input 'up)   -3)
                                                  ((input-held? input 'down)   3)
-                                                 (else 0))))
-             ;; Apply velocity to position
-             (box    (entity-set box #:x (+ (entity-ref box #:x 0)
-                                             (entity-ref box #:vx 0))))
-             (box    (entity-set box #:y (+ (entity-ref box #:y 0)
-                                             (entity-ref box #:vy 0)))))
+                                                 (else 0)))))
         (game-scene-set! game
           (update-scene scene entities: (list box)))))
 
@@ -129,7 +124,7 @@ Press arrow keys to move the yellow square around. Here are the key ideas:
 - **Scenes**: =make-scene= creates a container for entities, tilemaps, and the camera. It holds the game state each frame. Optional =background:= ~(r g b)~ or ~(r g b a)~ sets the color used to clear the window each frame (default is black).
 - **Entities**: Entities are plists (property lists). They have no class; they're pure data. Access properties with =entity-ref=, and update with =entity-set= (which returns a *new* plist — always bind the result).
 - **Input**: =input-held?= returns =#t= if an action is currently pressed. Actions are symbols like ='left=, ='right=, ='up=, ='down= (from the default input config).
-- **Update & Render**: The =update:= hook runs first and updates entities. The =render:= hook runs after the default rendering pipeline and is used for custom drawing like this colored rectangle.
+- **Update & Render**: Each frame, after input, the built-in =engine-update= integrates =#:vx= / =#:vy= into position (gravity and tile steps no-op without =#:gravity?= or a tilemap). Your =update:= hook runs *after* that and sets velocities for the following frame. The =render:= hook runs after the default scene render and is used for custom drawing like this colored rectangle.
 - **Rendering**: Since our tilemap is =#f=, the default renderer draws nothing; all drawing happens in the =render:= hook using SDL2 functions.
 
 * Adding a Tilemap and Physics
@@ -171,32 +166,23 @@ For a real game, you probably want tilemaps, gravity, and collision detection. D
         (scene-add-entity scene player)))
 
     update: (lambda (game dt)
-      ;; Typical pattern for platformer physics
+      ;; Game logic only — gravity, collisions, and #:on-ground? run in default-engine-update
       (let* ((input  (game-input game))
              (scene  (game-scene game))
-             (tm     (scene-tilemap scene))
              (player (car (scene-entities scene)))
-             ;; Set horizontal velocity from input
+             (jump?  (and (input-pressed? input 'a)
+                          (entity-ref player #:on-ground? #f)))
              (player (entity-set player #:vx
                        (cond
                          ((input-held? input 'left)  -3)
                          ((input-held? input 'right)  3)
-                         (else 0))))
-             ;; Jump on button press if on ground
-             (_ (when (and (input-pressed? input 'a)
-                           (entity-ref player #:on-ground? #f))
-                  (play-sound 'jump)))
-             (player (apply-jump        player (input-pressed? input 'a)))
-             ;; Run physics pipeline
-             (player (apply-acceleration player))
-             (player (apply-gravity      player))
-             (player (apply-velocity-x   player))
-             (player (resolve-tile-collisions-x player tm))
-             (player (apply-velocity-y   player))
-             (player (resolve-tile-collisions-y player tm))
-             (player (detect-on-solid   player tm)))
-        (game-scene-set! game
-          (update-scene scene entities: (list player)))))))
+                         (else 0)))))
+        (when jump? (play-sound 'jump))
+        (let ((player (if jump?
+                          (entity-set player #:ay (- *jump-force*))
+                          player)))
+          (game-scene-set! game
+            (update-scene scene entities: (list player)))))))
 
 (game-run! *game*)
 #+end_src
@@ -206,9 +192,9 @@ Key points:
 - **=game-load-scene!=** loads a TMX tilemap file (created with the Tiled editor), creates the tileset texture, and builds the scene. It returns the scene so you can add more entities.
 - **=init-audio!=** and **=load-sounds!=** initialize the audio subsystem and load sound files. Call these in the =preload:= hook.
 - **=play-sound=** plays a loaded sound effect.
-- **Physics pipeline**: Functions like =apply-gravity=, =apply-velocity-x=, =resolve-tile-collisions-x= form the physics pipeline. Apply them in order each frame to get correct platformer behavior.
-- **Tile collisions**: =resolve-tile-collisions-x= and =resolve-tile-collisions-y= snap entities to tile edges, preventing clipping.
-- **On-solid check**: =detect-on-solid= sets the =#:on-ground?= flag from tiles below the feet and, if you pass other scene entities, from standing on solids (moving platforms, crates). Call it after collisions; use the flag next frame to gate jumps. (Despite the =?=-suffix, it returns an updated entity, not a boolean.)
+- **Automatic physics**: By default, =make-game= uses =default-engine-update=, which runs the full pipeline (tweens, acceleration, gravity, velocity, tile and entity collisions, ground detection, group sync) *before* your =update:= hook. Your =update:= sets =#:vx= and a one-frame =#:ay= for jumps; =*jump-force*= (from =downstroke-physics=, default 15) is a conventional jump impulse.
+- **=engine-update: #f=** disables that pipeline — use this for games that move entities entirely in =update:= (see =demo/shmup.scm=, =demo/scaling.scm=) or supply your own =engine-update:= procedure to replace =default-engine-update=.
+- **=detect-on-solid=** (inside the default pipeline) sets =#:on-ground?= from tiles below the feet and from other solids in the scene entity list. When your =update:= runs, that flag already reflects the current frame.
 
 See =demo/platformer.scm= in the engine source for a complete working example.
 
@@ -300,7 +286,7 @@ You now know how to:
 - Create a game with =make-game= and =game-run!=
 - Add entities to scenes
 - Read input with =input-held?= and =input-pressed?=
-- Apply physics to entities
+- Rely on the default physics pipeline (or turn it off with =engine-update: #f=)
 - Load tilemaps with =game-load-scene!=
 - Play sounds with =load-sounds!= and =play-sound=