Add SCROLL viewport + tutorial_gfx examples and cheat-sheet page

- GfxVideoState scroll_x/scroll_y; SCROLL dx,dy; SCROLLX()/SCROLLY()
- Apply offset in canvas + raylib text/bitmap renderers and sprite composite
- examples: tutorial_gfx_scroll/memory/tilemap/gamepad/index + tile PNG
- web/tutorial-gfx-features.html; README, CHANGELOG, embedding doc, to-do

Co-authored-by: Chris Garrett <chris@chrisg.com>

Author: cursoragent

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Unreleased
 
+- **Viewport scroll (basic-gfx + canvas WASM):** **`SCROLL dx, dy`** sets pixel pan for the text/bitmap layer and sprites; **`SCROLLX()`** / **`SCROLLY()`** read offsets. `GfxVideoState.scroll_x` / `scroll_y`; Raylib and canvas compositors apply the same shift. Examples: **`examples/tutorial_gfx_scroll.bas`**, overview **`web/tutorial-gfx-features.html`**.
+
 - **Gamepad (basic-gfx + canvas WASM):** **`JOY(port, button)`**, alias **`JOYSTICK`**, and **`JOYAXIS(port, axis)`** (`gfx_gamepad.c`). **Native:** Raylib **1–15** button codes; axes **0–5** scaled **-1000..1000**. **Canvas WASM:** `canvas.html` polls **`navigator.getGamepads()`** each frame into exported buffers; Raylib codes map to **Standard Gamepad** indices. **Terminal WASM** (no `GFX_VIDEO`) still returns **0**. **`HEAP16`** + **`_wasm_gamepad_buttons_ptr`** / **`_wasm_gamepad_axes_ptr`** exports. Example **`examples/gfx_joy_demo.bas`**.
 
 - **Tilemap sprite sheets:** **`LOADSPRITE slot, "path.png", tw, th`** defines a **tw×th** tile grid; **`SPRITETILES(slot)`**, **`DRAWSPRITETILE slot, x, y, tile_index [, z]`** (1-based tile index), **`SPRITEFRAME slot, frame`** / **`SPRITEFRAME(slot)`** (default tile for **`DRAWSPRITE`** when crop omitted), **`gfx_sprite_effective_source_rect`**, **`SPRITEW`/`SPRITEH`** return one tile size when tilemap is active. **`SPRITECOLLIDE`** uses tile size when no explicit crop.

README.md

@@ -377,6 +377,10 @@ Releases include **basic-gfx** — a full graphical version of the interpreter b
 - Use `SCREENCODES OFF` to restore the default (ASCII strings like `PRINT "HELLO"` map naturally).
 - The window closes automatically when the program reaches `END`.
 
+**Viewport scroll (basic-gfx + canvas WASM)**:
+
+- **`SCROLL dx, dy`** sets a **pixel** offset for the **text/bitmap layer and sprites** (positive **dx** pans the world to the left; positive **dy** pans up). Use **`SCROLL 0, 0`** to reset. **`SCROLLX()`** / **`SCROLLY()`** return the current offset (roughly **-32768..32767**). Tutorial: `examples/tutorial_gfx_scroll.bas`.
+
 **PNG sprites / HUD overlay (basic-gfx)**:
 
 - `LOADSPRITE slot, "file.png"` queues loading a PNG from disk. Paths are relative to the **`.bas` file’s directory** (or absolute). Only `.png` is supported here; use `LOAD "bin" INTO …` for raw bytes.
@@ -405,6 +409,7 @@ Releases include **basic-gfx** — a full graphical version of the interpreter b
 
 The `examples` folder (included in release archives) contains:
 
+- **Graphics / WASM feature tours** (run with **`./basic-gfx`** or load into **`web/canvas.html`**): `tutorial_gfx_index.bas` lists short demos — **`tutorial_gfx_scroll.bas`** (**`SCROLL`**), **`tutorial_gfx_memory.bas`** (**`POKE`/`PEEK`** bases), **`tutorial_gfx_tilemap.bas`** (**tile** **`LOADSPRITE`** + **`tutorial_tile_sheet_demo.png`**), **`tutorial_gfx_gamepad.bas`** (**`JOY`**/**`JOYAXIS`**). See also **`web/tutorial-gfx-features.html`** for a static overview (serve the `web/` directory over HTTP).
 - `dartmouth.bas`: classic Dartmouth BASIC tutorial; exercises `PRINT`, `INPUT`, `IF`, `FOR/NEXT`, `DEF FN`, `READ`/`DATA`, and more.
 - `trek.bas`: Star Trek–style game; exercises `GET`, `ON GOTO`/`GOSUB`, multi-dimensional arrays, and PETSCII-style output.
 - `chr.bas`: PETSCII/ANSI color and control-code test (run with `-petscii`).

basic.c

@@ -2173,7 +2173,9 @@ enum func_code {
     FN_JOY = 47,
     FN_JOYAXIS = 48,
     FN_SPRITETILES = 49,
-    FN_SPRITEFRAME = 50
+    FN_SPRITEFRAME = 50,
+    FN_SCROLLX = 51,
+    FN_SCROLLY = 52
 };
 
 /* Report an error and halt further execution.
@@ -2409,10 +2411,10 @@ static const char *const reserved_words[] = {
     "INKEY", "INPUT", "INSTR", "INT", "INDEXOF", "JSON", "LEFT", "LEN", "LET", "LINE", "LOAD", "LOADSPRITE", "LOCATE", "LOG",
     "LASTINDEXOF", "LCASE", "FIELD", "LTRIM", "MEMCPY", "MEMSET", "MID", "MOD", "NEXT", "OFF", "ON", "OPEN", "OR", "PEEK", "POKE", "PLATFORM", "PRESET", "PSET", "PRINT",
     "XOR",
-    "READ", "REM", "REPLACE", "RESTORE", "RETURN", "RIGHT", "RND", "RTRIM", "RVS", "SCREEN", "SCREENCODES", "SPRITECOLLIDE", "SPRITEFRAME", "SPRITETILES", "SPRITEVISIBLE",
+    "READ", "REM", "REPLACE", "RESTORE", "RETURN", "RIGHT", "RND", "RTRIM", "RVS", "SCROLL", "SCREEN", "SCREENCODES", "SPRITECOLLIDE", "SPRITEFRAME", "SPRITETILES", "SPRITEVISIBLE",
     "JOIN",
     "SGN", "SIN", "SLEEP", "SORT", "SPC", "SPLIT", "SPRITEH", "SPRITEW", "SQR", "STEP", "STOP", "STR", "STRING",
-    "DRAWSPRITE", "DRAWSPRITETILE", "JOY", "JOYAXIS", "JOYSTICK", "SYSTEM", "TAB", "TAN", "TEXTAT", "THEN", "TI", "TO", "TRIM", "UCASE", "UNLOADSPRITE", "VAL", "WEND", "WHILE",
+    "DRAWSPRITE", "DRAWSPRITETILE", "JOY", "JOYAXIS", "JOYSTICK", "SCROLLX", "SCROLLY", "SYSTEM", "TAB", "TAN", "TEXTAT", "THEN", "TI", "TO", "TRIM", "UCASE", "UNLOADSPRITE", "VAL", "WEND", "WHILE",
     "DO", "LOOP", "UNTIL", "EXIT",
     NULL
 };
@@ -3219,6 +3221,10 @@ static int function_lookup(const char *name, int len)
         if (len == 11 && name[0] == 'S' && name[1] == 'P' && name[2] == 'R' && name[3] == 'I' &&
             name[4] == 'T' && name[5] == 'E' && name[6] == 'F' && name[7] == 'R' && name[8] == 'A' &&
             name[9] == 'M' && name[10] == 'E') return FN_SPRITEFRAME;
+        if (len == 7 && name[0] == 'S' && name[1] == 'C' && name[2] == 'R' && name[3] == 'O' &&
+            name[4] == 'L' && name[5] == 'L' && name[6] == 'X') return FN_SCROLLX;
+        if (len == 7 && name[0] == 'S' && name[1] == 'C' && name[2] == 'R' && name[3] == 'O' &&
+            name[4] == 'L' && name[5] == 'L' && name[6] == 'Y') return FN_SCROLLY;
         return FN_NONE;
     case 'C':
         if ((len == 3 && name[0] == 'C' && name[1] == 'H' && name[2] == 'R') ||
@@ -3654,6 +3660,52 @@ static void statement_line(char **p)
 #endif
 }
 
+/* SCROLL x, y — viewport offset in pixels (text/bitmap layer + sprites; basic-gfx / canvas WASM). */
+static void statement_scroll(char **p)
+{
+#ifndef GFX_VIDEO
+    (void)p;
+    runtime_error_hint("SCROLL is only available in basic-gfx or canvas WASM",
+                         "SCROLL dx, dy shifts the visible framebuffer (camera-style).");
+#else
+    struct value vx, vy;
+    int dx, dy;
+    skip_spaces(p);
+    vx = eval_expr(p);
+    ensure_num(&vx);
+    skip_spaces(p);
+    if (**p != ',') {
+        runtime_error_hint("SCROLL expects dx, dy",
+                             "Example: SCROLL 8, 0  (pan one character width right).");
+        return;
+    }
+    (*p)++;
+    skip_spaces(p);
+    vy = eval_expr(p);
+    ensure_num(&vy);
+    if (!gfx_vs) {
+        runtime_error_hint("SCROLL requires basic-gfx or canvas WASM", NULL);
+        return;
+    }
+    dx = (int)vx.num;
+    dy = (int)vy.num;
+    if (dx < -32768) {
+        dx = -32768;
+    }
+    if (dx > 32767) {
+        dx = 32767;
+    }
+    if (dy < -32768) {
+        dy = -32768;
+    }
+    if (dy > 32767) {
+        dy = 32767;
+    }
+    gfx_vs->scroll_x = (int16_t)dx;
+    gfx_vs->scroll_y = (int16_t)dy;
+#endif
+}
+
 static void statement_screen(char **p)
 {
 #ifndef GFX_VIDEO
@@ -4574,6 +4626,17 @@ static struct value eval_function(const char *name, char **p)
         runtime_error_hint("JOY/JOYAXIS require basic-gfx (native)", "Terminal basic has no gamepad.");
         return make_num(0.0);
     }
+    if (code == FN_SCROLLX || code == FN_SCROLLY) {
+        if (**p != ')') {
+            runtime_error_hint("Missing ')'", "SCROLLX() and SCROLLY() take no arguments.");
+            return make_num(0.0);
+        }
+        (*p)++;
+        skip_spaces(p);
+        runtime_error_hint("SCROLLX/SCROLLY require basic-gfx or canvas WASM",
+                             "Viewport scroll applies to the PETSCII/bitmap layer in graphics builds.");
+        return make_num(0.0);
+    }
 #endif
 #ifdef GFX_VIDEO
     if (code == FN_SPRITEW || code == FN_SPRITEH) {
@@ -4667,6 +4730,18 @@ static struct value eval_function(const char *name, char **p)
         }
         return make_num(0.0);
     }
+    if (code == FN_SCROLLX || code == FN_SCROLLY) {
+        if (**p != ')') {
+            runtime_error_hint("Missing ')'", "SCROLLX() and SCROLLY() take no arguments.");
+            return make_num(0.0);
+        }
+        (*p)++;
+        skip_spaces(p);
+        if (gfx_vs) {
+            return make_num((double)(code == FN_SCROLLX ? gfx_vs->scroll_x : gfx_vs->scroll_y));
+        }
+        return make_num(0.0);
+    }
     if (code == FN_JOY || code == FN_JOYAXIS) {
         struct value vp, vb;
         int port, btn, ax;
@@ -6131,6 +6206,7 @@ static struct value eval_factor(char **p)
             starts_with_kw(*p, "PEEK") || starts_with_kw(*p, "INKEY") ||
             starts_with_kw(*p, "SPRITEW") || starts_with_kw(*p, "SPRITEH") ||
             starts_with_kw(*p, "SPRITECOLLIDE") || starts_with_kw(*p, "SPRITETILES") || starts_with_kw(*p, "SPRITEFRAME") ||
+            starts_with_kw(*p, "SCROLLX") || starts_with_kw(*p, "SCROLLY") ||
             starts_with_kw(*p, "JOY") || starts_with_kw(*p, "JOYSTICK") || starts_with_kw(*p, "JOYAXIS")) {
             char namebuf[32];
             char *q;
@@ -9196,6 +9272,11 @@ static void execute_statement(char **p)
         statement_screen(p);
         return;
     }
+    if (c == 'S' && starts_with_kw(*p, "SCROLL")) {
+        *p += 6;
+        statement_scroll(p);
+        return;
+    }
     if (c == 'S' && starts_with_kw(*p, "SCREENCODES")) {
         *p += 11;
         statement_screencodes(p);

docs/sprite-features-plan.md

@@ -1,6 +1,6 @@
 # Sprite Features – Planning & Specification
 
-**Status**: **Partially implemented** in `basic-gfx` + canvas WASM: `LOADSPRITE`, optional **tile sheet** `LOADSPRITE slot, "sheet.png", tw, th`, `DRAWSPRITETILE`, `SPRITETILES`, **`SPRITEFRAME`** (default tile for `DRAWSPRITE` without crop), `UNLOADSPRITE`, `DRAWSPRITE` (persistent pose per slot, `z` and optional source rectangle), `SPRITEVISIBLE`, `SPRITEW`/`SPRITEH`, `SPRITECOLLIDE`. **Worked example**: `examples/gfx_game_shell.bas` (PETSCII tile map via `POKE` + PNG player/enemy/HUD); **minimal HUD demo**: `examples/gfx_sprite_hud_demo.bas`. **Gamepad**: `JOY`/`JOYAXIS` in **basic-gfx** and **canvas WASM** (`examples/gfx_joy_demo.bas`). Full **world tilemap engine** (scroll, layers) still planning.
+**Status**: **Partially implemented** in `basic-gfx` + canvas WASM: `LOADSPRITE`, optional **tile sheet** `LOADSPRITE slot, "sheet.png", tw, th`, `DRAWSPRITETILE`, `SPRITETILES`, **`SPRITEFRAME`** (default tile for `DRAWSPRITE` without crop), `UNLOADSPRITE`, `DRAWSPRITE` (persistent pose per slot, `z` and optional source rectangle), `SPRITEVISIBLE`, `SPRITEW`/`SPRITEH`, `SPRITECOLLIDE`. **Worked example**: `examples/gfx_game_shell.bas` (PETSCII tile map via `POKE` + PNG player/enemy/HUD); **minimal HUD demo**: `examples/gfx_sprite_hud_demo.bas`. **Gamepad**: `JOY`/`JOYAXIS` in **basic-gfx** and **canvas WASM** (`examples/gfx_joy_demo.bas`). Full **world tilemap engine** (layers beyond a single viewport) still planning. **Viewport** **`SCROLL dx, dy`** + **`SCROLLX()`/`SCROLLY()`** implement shared camera-style pan for text/bitmap/sprites (see **`examples/tutorial_gfx_scroll.bas`**).
 
 This document outlines a sprite subsystem for `basic-gfx`, designed for modern hardware with no C64-style limits. The goal is to let BASIC programs load PNG images as sprites, draw them at arbitrary positions with depth ordering, and perform collision detection.
 

docs/tutorial-embedding.md

@@ -20,6 +20,7 @@ This produces:
 | `web/vfs-helpers.js` | Shared **upload/download** helpers for `Module.FS` (loaded automatically by tutorial embeds) |
 | `web/tutorial-example.html` | Minimal page with **two** embeds (smoke test reference) |
 | `web/tutorial.html` | **Getting started** walkthrough with **thirteen** lesson embeds (serve `web/` over HTTP) |
+| `web/tutorial-gfx-features.html` | **Static** cheat sheet for **basic-gfx** / **canvas WASM** features (scroll, memory, sprites, gamepad); links to `examples/tutorial_gfx_*.bas` |
 
 Serve the `web/` directory over **HTTP** (WASM is blocked on many browsers for `file://`).
 

examples/tutorial_gfx_gamepad.bas

@@ -0,0 +1,12 @@
+1 REM ============================================================
+2 REM Tutorial: JOY / JOYAXIS (basic-gfx native or canvas WASM)
+3 REM Native: ./basic-gfx examples/tutorial_gfx_gamepad.bas
+4 REM Canvas: connect a controller; see also examples/gfx_joy_demo.bas
+5 REM Button codes 1-15 (Raylib); axes 0-5 scaled to about -1000..1000
+6 REM ============================================================
+10 PRINT "{CLR}{HOME}GAMEPAD — press buttons / move sticks"
+20 PRINT "Port 0, Face A (code 7):"; JOY(0, 7)
+30 PRINT "Left stick X (axis 0):"; JOYAXIS(0, 0)
+40 PRINT "Left stick Y (axis 1):"; JOYAXIS(0, 1)
+50 PRINT "(Values update each frame in a real game loop.)"
+60 END

examples/tutorial_gfx_index.bas

@@ -0,0 +1,14 @@
+1 REM ============================================================
+2 REM Index of graphics / WASM tutorial examples (repo: examples/)
+3 REM Run demos with: ./basic-gfx examples/<file>
+4 REM ============================================================
+5 REM tutorial_gfx_scroll.bas    — SCROLL, SCROLLX(), SCROLLY()
+6 REM tutorial_gfx_memory.bas     — POKE/PEEK memory bases (#OPTION memory)
+7 REM tutorial_gfx_tilemap.bas      — LOADSPRITE tw,th, DRAWSPRITETILE, SPRITEFRAME
+8 REM tutorial_tile_sheet_demo.png — 16x8 asset for tilemap demo
+9 REM gfx_joy_demo.bas              — full gamepad poll loop
+10 REM gfx_poke_demo.bas             — screen RAM from BASIC
+11 REM gfx_jiffy_game_demo.bas       — TI$, INKEY$, PEEK keyboard matrix
+12 REM ============================================================
+20 PRINT "{CLR}{HOME}See REM lines in this file for a feature list."
+30 END

examples/tutorial_gfx_memory.bas

@@ -0,0 +1,19 @@
+1 REM ============================================================
+2 REM Tutorial: virtual memory bases for POKE/PEEK (C64-style layout)
+3 REM Run: ./basic-gfx examples/tutorial_gfx_memory.bas
+4 REM Default: screen $0400, color $D800, charset $3000, keys $DC00, bitmap $2000
+5 REM Use #OPTION in a real project, or -memory on the command line.
+6 REM ============================================================
+10 REM --- Default screen RAM at 1024 (0x0400), same as C64 first screen line
+20 POKE 1024, 32
+30 POKE 1025, 32
+40 REM White letter A (screencode 1) at top-left
+50 POKE 1024, 1
+60 POKE 55296, 1
+70 REM Read back
+80 PRINT "{CLR}{HOME}PEEK screen @1024 ="; PEEK(1024)
+90 PRINT "PEEK colour @55296 ="; PEEK(55296)
+100 PRINT
+110 PRINT "Tip: #OPTION memory c64 | pet | default"
+120 PRINT "     #OPTION screen 1024   (override base)"
+130 END

examples/tutorial_gfx_scroll.bas

@@ -0,0 +1,29 @@
+1 REM ============================================================
+2 REM Tutorial: viewport SCROLL (camera-style pan in basic-gfx / canvas)
+3 REM Run: ./basic-gfx examples/tutorial_gfx_scroll.bas
+4 REM   or open web/canvas.html and load this file into the VFS.
+5 REM SCROLL dx, dy moves the visible layer left/up by dx, dy pixels.
+6 REM SCROLLX() / SCROLLY() return the current offset (see status line).
+7 REM ============================================================
+10 REM Draw a label so you can see the screen shift
+20 COLOR 1
+30 PRINT "{CLR}{HOME}SCROLL DEMO — watch text slide"
+40 PRINT "SCROLL 16,0 pans one column (8px) to the right"
+50 PRINT "SCROLL 0,8 pans one text row up"
+60 REM Pan right in small steps (8 px = one character cell)
+70 FOR I = 1 TO 5
+80 SCROLL I * 8, 0
+90 TEXTAT 0, 24, "SCROLLX=" + STR$(SCROLLX())
+100 SLEEP 0.25
+110 NEXT I
+120 REM Reset then pan down
+130 SCROLL 0, 0
+140 FOR J = 1 TO 3
+150 SCROLL 0, J * 8
+160 TEXTAT 0, 24, "SCROLLY=" + STR$(SCROLLY()) + "   "
+170 SLEEP 0.25
+180 NEXT J
+190 SCROLL 0, 0
+200 PRINT
+210 PRINT "Done — SCROLL 0,0 resets the view."
+220 END

examples/tutorial_gfx_tilemap.bas

@@ -0,0 +1,16 @@
+1 REM ============================================================
+2 REM Tutorial: tile sheet LOADSPRITE, DRAWSPRITETILE, SPRITEFRAME
+3 REM Requires: examples/tutorial_tile_sheet_demo.png (16x8 = two 8x8 tiles)
+4 REM Run: ./basic-gfx examples/tutorial_gfx_tilemap.bas
+5 REM ============================================================
+10 REM Two tiles: red (index 1) and green (index 2)
+20 LOADSPRITE 0, "tutorial_tile_sheet_demo.png", 8, 8
+30 PRINT "{CLR}{HOME}Tiles in sheet:"; SPRITETILES(0)
+40 REM Draw tile 2 at pixel (100, 80), z=50
+50 DRAWSPRITETILE 0, 100, 80, 2, 50
+60 REM Set default frame for DRAWSPRITE (same as tile 1)
+70 SPRITEFRAME 0, 1
+80 DRAWSPRITE 0, 180, 80, 50
+90 PRINT "SPRITEFRAME(0)="; SPRITEFRAME(0)
+100 SLEEP 1
+110 END