Docs: PEEK keyboard uses uppercase ASCII; UCASE$ INKEY$ in gfx_inkey_demo

- gfx_inkey_demo: UCASE$ before ASC so lowercase w matches W=87
- gfx_key_demo: clarify REMs (56320+n is key_state index, not PETSCII)
- README: keyboard polling vs INKEY$ case

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

Author: cursoragent

README.md

@@ -351,7 +351,8 @@ Releases include **basic-gfx** — a full graphical version of the interpreter b
 
 **Keyboard polling (basic-gfx)**:
 
-- BASIC can poll a simple key-down map via `PEEK(56320 + code)` where 56320 is 0xDC00.
+- BASIC can poll a simple key-down map via `PEEK(56320 + code)` where 56320 is 0xDC00 (`GFX_KEY_BASE`).
+- For letters, **code is ASCII of the uppercase key** (e.g. W = 87, same as `ASC("W")`), not the PETSCII screen code. Lowercase **w** is not a separate slot.
 - Supported codes include ASCII `A`–`Z`, `0`–`9`, Space (32), Enter (13), Esc (27), and C64 cursor codes Up (145), Down (17), Left (157), Right (29).
 
 **INPUT (basic-gfx)**:
@@ -361,6 +362,7 @@ Releases include **basic-gfx** — a full graphical version of the interpreter b
 **INKEY$() (basic-gfx)**:
 
 - `INKEY$()` is **non-blocking**: it returns a 1-character string for the next queued keypress, or `""` if none.
+- The character may be **upper or lower case**; use **`UCASE$(INKEY$())`** (or compare to both) if you test with numeric **`ASC`**.
 - This is driven by the raylib host; it is currently available in `basic-gfx` (gfx build) and returns `""` in the terminal build.
 - Example: `./basic-gfx -petscii examples/gfx_inkey_demo.bas`
 

examples/gfx_inkey_demo.bas

@@ -2,7 +2,9 @@
 2 REM Run with: ./basic-gfx -petscii examples/gfx_inkey_demo.bas
 3 REM
 4 REM INKEY$() returns a 1-character string when a keypress is available,
-5 REM or "" if no key was pressed since last call.
+5 REM or "" if none. Letters may be upper or lower case — UCASE$ matches WASD.
+6 REM Compare to gfx_key_demo.bas: PEEK(56320+n) uses n = ASCII of UPPERCASE
+7 REM letter (W=87, A=65, S=83, D=68, ESC=27). INKEY$ gives the real char.
 10 SCR = 1024
 20 COL = 55296
 30 X = 20
@@ -17,20 +19,20 @@
 120 REM Loop
 130 K$ = INKEY$()
 140 IF K$ = "" THEN SLEEP 1 : GOTO 130
-150 K = ASC(K$)
-160 IF K = 27 THEN END
-170 NX = X : NY = Y
-180 IF K = 87 THEN NY = Y - 1
-190 IF K = 83 THEN NY = Y + 1
-200 IF K = 65 THEN NX = X - 1
-210 IF K = 68 THEN NX = X + 1
-220 IF NX < 0 THEN NX = 0
-230 IF NX > 39 THEN NX = 39
-240 IF NY < 0 THEN NY = 0
-250 IF NY > 24 THEN NY = 24
-260 IF NX = X AND NY = Y THEN GOTO 130
-270 POKE SCR + Y*40 + X, 32
-280 X = NX : Y = NY
-290 POKE SCR + Y*40 + X, 0
-300 GOTO 130
-
+150 K$ = UCASE$(K$)
+160 K = ASC(K$)
+170 IF K = 27 THEN END
+180 NX = X : NY = Y
+190 IF K = 87 THEN NY = Y - 1
+200 IF K = 83 THEN NY = Y + 1
+210 IF K = 65 THEN NX = X - 1
+220 IF K = 68 THEN NX = X + 1
+230 IF NX < 0 THEN NX = 0
+240 IF NX > 39 THEN NX = 39
+250 IF NY < 0 THEN NY = 0
+260 IF NY > 24 THEN NY = 24
+270 IF NX = X AND NY = Y THEN GOTO 130
+280 POKE SCR + Y*40 + X, 32
+290 X = NX : Y = NY
+300 POKE SCR + Y*40 + X, 0
+310 GOTO 130

examples/gfx_key_demo.bas

@@ -1,40 +1,41 @@
 1 REM GFX KEY DEMO: poll host keyboard via PEEK and move a character
 2 REM Run with: ./basic-gfx examples/gfx_key_demo.bas
 3 REM
-4 REM Keyboard map (via gfx video peek):
-5 REM   PEEK(56320 + ASCII) is 1 while that key is held down.
-6 REM   Supported here: WASD, ESC.
+4 REM PEEK(GFX_KEY_BASE + n) reads key_state[n]: 1 while key is held.
+5 REM GFX_KEY_BASE is 56320 (0xDC00). For letters, n is ASCII of the
+6 REM UPPERCASE key (same as ASC("W") not PETSCII screen code): W=87 A=65 S=83 D=68.
+7 REM ESC = 27. This matches Raylib/basic-gfx and canvas wasmGfxKeyIndex().
 10 SCR = 1024
 20 COL = 55296
 30 X = 20
 40 Y = 12
 50 C = 1
-60 REM Clear screen to spaces and set colour to light blue (14)
-70 FOR I = 0 TO 999
-80 POKE SCR + I, 32
-90 POKE COL + I, 14
-100 NEXT I
-110 REM Draw initial @
-120 POKE SCR + Y*40 + X, 0
-130 POKE COL + Y*40 + X, C
-140 REM Main loop
-150 REM ESC (27) to exit, WASD to move
-160 IF PEEK(56320+27) <> 0 THEN END
-170 NX = X
-180 NY = Y
-190 IF PEEK(56320+87) <> 0 THEN NY = Y - 1
-200 IF PEEK(56320+83) <> 0 THEN NY = Y + 1
-210 IF PEEK(56320+65) <> 0 THEN NX = X - 1
-220 IF PEEK(56320+68) <> 0 THEN NX = X + 1
-230 IF NX < 0 THEN NX = 0
-240 IF NX > 39 THEN NX = 39
-250 IF NY < 0 THEN NY = 0
-260 IF NY > 24 THEN NY = 24
-270 IF NX = X AND NY = Y THEN GOTO 320
-280 REM Erase old, draw new
-290 POKE SCR + Y*40 + X, 32
-300 X = NX : Y = NY
-310 POKE SCR + Y*40 + X, 0
-320 SLEEP 1
-330 GOTO 160
-
+60 REM Optional named constants (same numbers as gfx_inkey_demo after UCASE$)
+70 REM KW=87 : KA=65 : KS=83 : KD=68 : KESC=27
+80 REM Clear screen to spaces and set colour to light blue (14)
+90 FOR I = 0 TO 999
+100 POKE SCR + I, 32
+110 POKE COL + I, 14
+120 NEXT I
+130 REM Draw initial @
+140 POKE SCR + Y*40 + X, 0
+150 POKE COL + Y*40 + X, C
+160 REM Main loop: ESC to exit, WASD to move (hold key to repeat each SLEEP)
+190 IF PEEK(56320+27) <> 0 THEN END
+200 NX = X
+210 NY = Y
+220 IF PEEK(56320+87) <> 0 THEN NY = Y - 1
+230 IF PEEK(56320+83) <> 0 THEN NY = Y + 1
+240 IF PEEK(56320+65) <> 0 THEN NX = X - 1
+250 IF PEEK(56320+68) <> 0 THEN NX = X + 1
+260 IF NX < 0 THEN NX = 0
+270 IF NX > 39 THEN NX = 39
+280 IF NY < 0 THEN NY = 0
+290 IF NY > 24 THEN NY = 24
+300 IF NX = X AND NY = Y THEN GOTO 340
+310 REM Erase old, draw new
+320 POKE SCR + Y*40 + X, 32
+330 X = NX : Y = NY
+340 POKE SCR + Y*40 + X, 0
+350 SLEEP 1
+360 GOTO 190