1 files changed, 27 insertions, 0 deletions
diff --git a/docs/guide.org b/docs/guide.org
index 380f04b..1c5a8f3 100644
--- a/docs/guide.org
+++ b/docs/guide.org
@@ -216,6 +216,32 @@ See =demo/platformer.scm= in the engine source for a complete working example.
 
 * Development Tips
 
+** Pixel Scaling
+
+Retro-style games often use a small logical resolution (e.g. 320×240) but need a larger window so players can actually see things. Use ~scale:~ to scale everything uniformly:
+
+#+begin_src scheme
+(make-game title: "Pixel Art" width: 320 height: 240 scale: 2)
+;; Creates a 640×480 window; all coordinates remain in 320×240 space
+#+end_src
+
+This is integer-only scaling. All rendering — tiles, sprites, text, debug overlays — is scaled automatically by SDL2. Game logic and coordinates are unaffected.
+
+See =demo/scaling.scm= for a complete example.
+
+** Fullscreen
+
+Use SDL2 window flags in the ~preload:~ hook to go fullscreen:
+
+#+begin_src scheme
+(make-game
+  title: "Fullscreen Game" width: 320 height: 240 scale: 2
+  preload: (lambda (game)
+    (sdl2:window-fullscreen-set! (game-window game) 'fullscreen-desktop)))
+#+end_src
+
+~'fullscreen-desktop~ fills the screen without changing display resolution; SDL2 handles letterboxing and scaling. ~'fullscreen~ uses exclusive fullscreen at the window size.
+
 ** 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:
@@ -252,6 +278,7 @@ Downstroke includes several demo games that showcase different features:
 | 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 |
 | Tweens | =demo/tweens.scm= | Easing curves, =tween-step=, =#:skip-pipelines= with tile collision |
+| Scaling | =demo/scaling.scm= | Integer pixel scaling with =scale: 2=, 2× upscaled rendering |
 
 Each demo is self-contained and serves as a working reference for a particular game mechanic.