feat: SPRITEMODULATE for sprite alpha, RGB tint, and scale (gfx + WASM)

- Add gfx_sprite_set_modulate + per-slot state; Raylib DrawTexturePro tint/dest size
- Canvas: bilinear-ish scaled blit with modulate + premultiplied blend
- BASIC: SPRITEMODULATE slot, alpha [, r,g,b [, sx [, sy]]]; document in README/CHANGELOG

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

Author: cursoragent

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Unreleased
 
+- **`SPRITEMODULATE` (basic-gfx + canvas WASM):** Per-slot draw tint and scale until **`LOADSPRITE`** / **`UNLOADSPRITE`**. Syntax: **`SPRITEMODULATE slot, alpha [, r, g, b [, scale_x [, scale_y]]]`** — **`alpha`** and **`r`/`g`/`b`** are **0–255** (**`alpha`** multiplies PNG alpha); **`scale_x`/`scale_y`** stretch the drawn quad (default **1**; one scale sets both). Implemented with Raylib **`Color`** + destination size; canvas uses bilinear-ish sampling + tint. **`gfx_sprite_set_modulate`** in **`basic_api.h`**.
+
 - **Load normalization / identifiers containing `IF`:** **`normalize_keywords_line`** treated **`IF`** inside identifiers as **`IF …`** (e.g. **`JIFFIES_PER_FRAME`** → **`J IF FIES_PER_FRAME`**, breaking assignments). The same **`prev_ident`** guard used for **`FOR`** (avoid splitting **`PLATFORM`**) now applies to the **`IF`** insertion rule. Regression: **`tests/if_inside_ident_normalize.bas`**.
 
 - **`gfx_peek()` keyboard vs colour RAM**: With default bases, **`GFX_KEY_BASE` (0xDC00)** lies inside the colour RAM window **(0xD800 + 2000 bytes)**. **`gfx_peek()`** must resolve **keyboard before colour** or **`PEEK(56320+n)`** reads colour bytes (e.g. **14** for light blue). **`gfx_video.c`** documents the required order (**text → keyboard → colour → charset → bitmap**). **`gfx_video_test`** asserts key wins over colour at the aliased address.

README.md

@@ -390,6 +390,7 @@ Releases include **basic-gfx** — a full graphical version of the interpreter b
 - **Tile sheet / tilemap:** `LOADSPRITE slot, "tiles.png", tw, th` treats the image as a grid of **tw×th** pixels per tile (row-major, left-to-right). Use **`DRAWSPRITETILE slot, x, y, tile_index [, z]`** with **1-based** `tile_index` (first tile = 1). **`SPRITETILES(slot)`** returns how many tiles are in the sheet. **`SPRITEW`/`SPRITEH`** return one tile’s size when a tilemap is loaded. **`DRAWSPRITE`** with **`sx, sy, sw, sh`** still works for arbitrary crops.
 - **Gamepad (basic-gfx and canvas WASM):** **`JOY(port, button)`** returns **1** if pressed, else **0**. **`JOYSTICK`** is an alias for **`JOY`**. **`JOYAXIS(port, axis)`** returns stick/trigger movement scaled to about **-1000..1000** (axes **0–5**: left X/Y, right X/Y, left trigger, right trigger). Port **0** is the first controller. **Native basic-gfx** uses Raylib button codes **1–15** (DPAD/face/triggers; **0** is unknown). **Canvas WASM** maps those codes to the browser **Standard Gamepad** layout via `navigator.getGamepads()` (polls each frame in `canvas.html`). **Terminal** `./basic` has no gamepad. Example: `./basic-gfx examples/gfx_joy_demo.bas`
 - **Tile animation frame:** After **`LOADSPRITE slot, "sheet.png", tw, th`**, **`SPRITEFRAME slot, frame`** sets the **1-based** tile index used when **`DRAWSPRITE`** omits **`sx, sy, sw, sh`** (same as choosing that tile with **`DRAWSPRITETILE`**). **`SPRITEFRAME(slot)`** returns the current frame.
+- **Tint / opacity / scale:** **`SPRITEMODULATE slot, alpha [, r, g, b [, scale_x [, scale_y]]]`** — **`alpha`** and **`r`/`g`/`b`** are **0–255** (defaults **255**; **`alpha`** multiplies the PNG’s alpha). Optional **`scale_x`/`scale_y`** stretch the drawn sprite (default **1**; one number sets both). Resets to opaque white at **1×** on each **`LOADSPRITE`** / **`UNLOADSPRITE`**.
 - `UNLOADSPRITE slot` frees that slot’s texture and clears its draw state so you can `LOADSPRITE` again (e.g. swap art or reclaim memory). No-op if the slot was empty.
 - `DRAWSPRITE slot, x, y [, z [, sx, sy [, sw, sh ]]]` sets the **persistent** pose for that slot: the same image is drawn **every frame** until you call `DRAWSPRITE` again for that slot or the program exits (textures are freed when the window closes). **`x`, `y`** are **pixel** coordinates on the 320×200 framebuffer (not character rows): row *r* starts at **`y = r × 8`**. **`z`**: larger values paint **on top** (e.g. text/bitmap at 0, HUD at 200). Omit **`sx, sy`** to use the top-left of the image; omit **`sw, sh`** (or use ≤0) to use the rest of the texture from `(sx,sy)`. **Alpha** in the PNG is respected (transparency over text or bitmap).
 - `SPRITEVISIBLE slot, 0|1` hides or shows a loaded sprite without unloading.

basic.c

@@ -2162,6 +2162,7 @@ static void statement_line(char **p);
 static void statement_loadsprite(char **p);
 static void statement_drawsprite(char **p);
 static void statement_spritevisible(char **p);
+static void statement_spritemodulate(char **p);
 #endif
 static void statement_unloadsprite(char **p);  /* basic-gfx only; terminal errors */
 static void statement_else(char **p);
@@ -2469,7 +2470,7 @@ 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", "SCROLL", "SCREEN", "SCREENCODES", "SPRITECOLLIDE", "SPRITEFRAME", "SPRITETILES", "SPRITEVISIBLE",
+    "READ", "REM", "REPLACE", "RESTORE", "RETURN", "RIGHT", "RND", "RTRIM", "RVS", "SCROLL", "SCREEN", "SCREENCODES", "SPRITECOLLIDE", "SPRITEFRAME", "SPRITEMODULATE", "SPRITETILES", "SPRITEVISIBLE",
     "JOIN",
     "SGN", "SIN", "SLEEP", "SORT", "SPC", "SPLIT", "SPRITEH", "SPRITEW", "SQR", "STEP", "STOP", "STR", "STRING",
     "DRAWSPRITE", "DRAWSPRITETILE", "HTTP", "HTTPSTATUS", "JOY", "JOYAXIS", "JOYSTICK", "SCROLLX", "SCROLLY", "SYSTEM", "TAB", "TAN", "TEXTAT", "THEN", "TI", "TO", "TRIM", "UCASE", "UNLOADSPRITE", "VAL", "WEND", "WHILE",
@@ -4113,6 +4114,84 @@ static void statement_spritevisible(char **p)
     }
     gfx_sprite_enqueue_visible(slot, on);
 }
+
+/* SPRITEMODULATE slot, alpha [, r, g, b [, scale_x [, scale_y]]] — alpha/r/g/b 0..255; scales default 1. */
+static void statement_spritemodulate(char **p)
+{
+    struct value v;
+    int slot;
+    int alpha;
+    int r = 255, g = 255, b = 255;
+    double sx = 1.0, sy = 1.0;
+    skip_spaces(p);
+    v = eval_expr(p);
+    ensure_num(&v);
+    slot = (int)v.num;
+    skip_spaces(p);
+    if (**p != ',') {
+        runtime_error_hint("SPRITEMODULATE expects slot, alpha [, r, g, b [, scale_x [, scale_y]]]",
+                             "Example: SPRITEMODULATE 1, 128  or  SPRITEMODULATE 1, 255, 200, 200, 255, 1.2, 0.6");
+        return;
+    }
+    (*p)++;
+    skip_spaces(p);
+    v = eval_expr(p);
+    ensure_num(&v);
+    alpha = (int)v.num;
+    skip_spaces(p);
+    if (**p == ',') {
+        (*p)++;
+        skip_spaces(p);
+        v = eval_expr(p);
+        ensure_num(&v);
+        r = (int)v.num;
+        skip_spaces(p);
+        if (**p != ',') {
+            runtime_error_hint("SPRITEMODULATE: r, g, b need three values",
+                                 "After alpha: give all three tint channels 0..255.");
+            return;
+        }
+        (*p)++;
+        skip_spaces(p);
+        v = eval_expr(p);
+        ensure_num(&v);
+        g = (int)v.num;
+        skip_spaces(p);
+        if (**p != ',') {
+            runtime_error_hint("SPRITEMODULATE: need b after r, g",
+                                 NULL);
+            return;
+        }
+        (*p)++;
+        skip_spaces(p);
+        v = eval_expr(p);
+        ensure_num(&v);
+        b = (int)v.num;
+        skip_spaces(p);
+        if (**p == ',') {
+            (*p)++;
+            skip_spaces(p);
+            v = eval_expr(p);
+            ensure_num(&v);
+            sx = v.num;
+            skip_spaces(p);
+            if (**p == ',') {
+                (*p)++;
+                skip_spaces(p);
+                v = eval_expr(p);
+                ensure_num(&v);
+                sy = v.num;
+            } else {
+                sy = sx;
+            }
+        }
+    }
+    if (!gfx_vs) {
+        runtime_error_hint("SPRITEMODULATE requires basic-gfx or canvas WASM", NULL);
+        return;
+    }
+    gfx_sprite_set_modulate(slot, alpha, r, g, b, (float)sx, (float)sy);
+}
 #endif /* GFX_VIDEO */
 
 /* UNLOADSPRITE slot — free texture and clear draw state (basic-gfx only). */
@@ -9303,6 +9382,11 @@ static void execute_statement(char **p)
             statement_spritevisible(p);
             return;
         }
+        if (starts_with_kw(*p, "SPRITEMODULATE")) {
+            *p += 15;
+            statement_spritemodulate(p);
+            return;
+        }
         if (starts_with_kw(*p, "SPRITEFRAME")) {
             *p += 11;
             statement_spriteframe(p);

basic_api.h

@@ -73,6 +73,9 @@ void gfx_sprite_enqueue_unload(int slot);  /* BASIC: UNLOADSPRITE slot */
 void gfx_sprite_enqueue_visible(int slot, int on);
 /* sw/sh <= 0 means use full sub-texture from (sx,sy) to bottom-right. */
 void gfx_sprite_enqueue_draw(int slot, float x, float y, int z, int sx, int sy, int sw, int sh);
+/* Per-slot draw tint/scale until next LOADSPRITE/UNLOADSPRITE (basic-gfx / canvas WASM).
+ * alpha 0–255 (255 = opaque), r/g/b 0–255, scale 1.0 = natural pixel size of crop. */
+void gfx_sprite_set_modulate(int slot, int alpha, int r, int g, int b, float scale_x, float scale_y);
 int gfx_sprite_slot_width(int slot);
 int gfx_sprite_slot_height(int slot);
 /* Axis-aligned bounding box overlap of last DRAWSPRITE rects (basic-gfx / canvas). */

gfx/gfx_raylib.c

@@ -49,6 +49,9 @@ typedef struct {
     int tiles_x, tiles_y; /* grid dimensions */
     int tile_count;       /* tiles_x * tiles_y, or 1 for single */
     int draw_frame;       /* 1-based tile index for DRAWSPRITE default crop */
+    /* Per-slot modulation (SPRITEMODULATE); default opaque white, scale 1,1. */
+    int mod_a, mod_r, mod_g, mod_b;
+    float mod_sx, mod_sy;
     /* Persistent draw state (last DRAWSPRITE for this slot until UNLOAD). */
     int draw_active;
     float draw_x, draw_y;
@@ -61,6 +64,8 @@ typedef struct {
     float x, y;
     int z;
     int sx, sy, sw, sh;
+    int mod_a, mod_r, mod_g, mod_b;
+    float mod_sx, mod_sy;
 } GfxSpriteDraw;
 
 static void gfx_sprite_process_queue(void);
@@ -223,6 +228,51 @@ void gfx_sprite_enqueue_draw(int slot, float x, float y, int z, int sx, int sy,
     (void)sprite_q_push(&c);
 }
 
+void gfx_sprite_set_modulate(int slot, int alpha, int r, int g, int b, float scale_x, float scale_y)
+{
+    if (slot < 0 || slot >= GFX_SPRITE_MAX_SLOTS) {
+        return;
+    }
+    if (alpha < 0) {
+        alpha = 0;
+    }
+    if (alpha > 255) {
+        alpha = 255;
+    }
+    if (r < 0) {
+        r = 0;
+    }
+    if (r > 255) {
+        r = 255;
+    }
+    if (g < 0) {
+        g = 0;
+    }
+    if (g > 255) {
+        g = 255;
+    }
+    if (b < 0) {
+        b = 0;
+    }
+    if (b > 255) {
+        b = 255;
+    }
+    if (scale_x <= 0.0f) {
+        scale_x = 1.0f;
+    }
+    if (scale_y <= 0.0f) {
+        scale_y = 1.0f;
+    }
+    pthread_mutex_lock(&g_sprite_mutex);
+    g_sprite_slots[slot].mod_a = alpha;
+    g_sprite_slots[slot].mod_r = r;
+    g_sprite_slots[slot].mod_g = g;
+    g_sprite_slots[slot].mod_b = b;
+    g_sprite_slots[slot].mod_sx = scale_x;
+    g_sprite_slots[slot].mod_sy = scale_y;
+    pthread_mutex_unlock(&g_sprite_mutex);
+}
+
 int gfx_sprite_slot_width(int slot)
 {
     int w = 0;
@@ -446,12 +496,12 @@ int gfx_sprite_slots_overlap_aabb(int slot_a, int slot_b)
         }
         ax = a->draw_x;
         ay = a->draw_y;
-        aw = swa;
-        ah = sha;
+        aw = swa * a->mod_sx;
+        ah = sha * a->mod_sy;
         bx = b->draw_x;
         by = b->draw_y;
-        bw = swb;
-        bh = shb;
+        bw = swb * b->mod_sx;
+        bh = shb * b->mod_sy;
     }
     pthread_mutex_unlock(&g_sprite_mutex);
 
@@ -537,6 +587,12 @@ static void gfx_sprite_process_queue(void)
                     g_sprite_slots[c->slot].tile_h = 0;
                     g_sprite_slots[c->slot].draw_frame = 1;
                 }
+                g_sprite_slots[c->slot].mod_a = 255;
+                g_sprite_slots[c->slot].mod_r = 255;
+                g_sprite_slots[c->slot].mod_g = 255;
+                g_sprite_slots[c->slot].mod_b = 255;
+                g_sprite_slots[c->slot].mod_sx = 1.0f;
+                g_sprite_slots[c->slot].mod_sy = 1.0f;
             }
             pthread_mutex_unlock(&g_sprite_mutex);
             break;
@@ -559,6 +615,12 @@ static void gfx_sprite_process_queue(void)
                 g_sprite_slots[c->slot].tiles_x = g_sprite_slots[c->slot].tiles_y = 0;
                 g_sprite_slots[c->slot].tile_count = 0;
                 g_sprite_slots[c->slot].draw_frame = 0;
+                g_sprite_slots[c->slot].mod_a = 255;
+                g_sprite_slots[c->slot].mod_r = 255;
+                g_sprite_slots[c->slot].mod_g = 255;
+                g_sprite_slots[c->slot].mod_b = 255;
+                g_sprite_slots[c->slot].mod_sx = 1.0f;
+                g_sprite_slots[c->slot].mod_sy = 1.0f;
             }
             pthread_mutex_unlock(&g_sprite_mutex);
             break;
@@ -634,6 +696,12 @@ static void gfx_sprite_composite(const GfxVideoState *vs, RenderTexture2D target
         draws[nd].sy = g_sprite_slots[i].draw_sy;
         draws[nd].sw = g_sprite_slots[i].draw_sw;
         draws[nd].sh = g_sprite_slots[i].draw_sh;
+        draws[nd].mod_a = g_sprite_slots[i].mod_a;
+        draws[nd].mod_r = g_sprite_slots[i].mod_r;
+        draws[nd].mod_g = g_sprite_slots[i].mod_g;
+        draws[nd].mod_b = g_sprite_slots[i].mod_b;
+        draws[nd].mod_sx = g_sprite_slots[i].mod_sx;
+        draws[nd].mod_sy = g_sprite_slots[i].mod_sy;
         nd++;
     }
     pthread_mutex_unlock(&g_sprite_mutex);
@@ -680,14 +748,24 @@ static void gfx_sprite_composite(const GfxVideoState *vs, RenderTexture2D target
             continue;
         }
         src = (Rectangle){ sx, sy, sw, sh };
-        dest = (Rectangle){ d->x - scx, d->y - scy, sw, sh };
+        dest = (Rectangle){
+            d->x - scx,
+            d->y - scy,
+            sw * d->mod_sx,
+            sh * d->mod_sy
+        };
         DrawTexturePro(
             t,
             src,
             dest,
             (Vector2){ 0, 0 },
             0.0f,
-            WHITE);
+            (Color){
+                (unsigned char)d->mod_r,
+                (unsigned char)d->mod_g,
+                (unsigned char)d->mod_b,
+                (unsigned char)d->mod_a
+            });
     }
     EndBlendMode();
     EndTextureMode();