fix: pair bgfx 0.20.0 with core 1.32.0 in the examples and the init scaffold (#731 follow-up)

build.zig

@@ -18,12 +18,16 @@ pub fn build(b: *std.Build) void {
     // fetcher then mapped to a bogus `vdev` git ref (issue #159).
     // Keep this trio a MUTUALLY COMPATIBLE set: a fresh `labelle init` resolves
     // these defaults, so a mismatch fails `labelle build` before any user code.
-    // Set verified end-to-end (init → install → generate → full compile, on
-    // both the raylib_desktop and null_desktop targets, against the published
-    // release tarballs) for core 1.28.0 / engine 2.12.2 / gfx 1.30.1 with
-    // cli 1.61.2 — which is exactly `labelle-cli` v1.61.2's `versions.zon`,
-    // the set its own `labelle upgrade all` writes. Keep the two in step: when
-    // they drift, `init` scaffolds a project the very next `upgrade` rewrites.
+    // Set verified end-to-end STANDALONE (init → install → generate → full
+    // compile against the published release tarballs, scratch LABELLE_HOME,
+    // no sibling checkouts) for core 1.32.0 / engine 2.12.2 / gfx 1.30.1 with
+    // cli 1.61.2, on the bgfx_desktop, null_desktop, raylib_desktop and
+    // sokol_desktop targets. engine/gfx/cli are exactly `labelle-cli` v1.61.2's
+    // `versions.zon`, the set its own `labelle upgrade all` writes; core is
+    // AHEAD of it (that file still says 1.28.0 through cli v1.67.0) — see the
+    // bgfx paragraph below for why, and bump the cli side to match. Keep the
+    // two in step: when they drift, `init` scaffolds a project the very next
+    // `upgrade` rewrites.
     //
     // The hard floor inside the trio (#679): gfx >= 1.30.0 re-exports
     // `core.TextureId` instead of declaring its own (labelle-gfx#328,
@@ -51,11 +55,28 @@ pub fn build(b: *std.Build) void {
     //
     // (v0.96.0 bumped engine 2.7.0 → 2.11.0 while leaving core at 1.26.0, so
     // every fresh `labelle init` scaffold failed to compile.)
+    //
+    // core 1.32.0 (#731 follow-up): the builtin `.bgfx` provider default
+    // (`src/config.zig` builtinProvider) is labelle-bgfx 0.20.0, the lowest
+    // bgfx that survives core v1.32.0's `MaterialEffect.pixel_water`. Its
+    // HARD core floor is 1.28.0 (`core.BackendTextureId`, a struct field
+    // type, bgfx >= 0.15.0) — 0.20.0 does compile against core 1.28.0,
+    // verified standalone; the v1.32.0 `PixelWaterDraw` / `PIXEL_WATER_*`
+    // names it takes from `backend_contract` are reached only through
+    // `@hasField(MaterialEffect, "pixel_water")`-gated paths or lazy
+    // top-level aliases. 1.32.0 is a CURATED floor like the gfx 1.28 one: it
+    // is the core bgfx 0.20.0 was released against (its own build.zig.zon),
+    // the only core on which the pixel_water effect the default backend
+    // ships is reachable, and the pairing labelle-bgfx's own examples run
+    // on. A `labelle init --backend=bgfx` scaffold should not pair a backend
+    // with a core older than the backend's own pin. `src/init_cmd.zig`'s
+    // "scaffold core default pairs with the builtin bgfx provider" test
+    // asserts both floors.
     // Bump all three together when moving the engine default (their
     // build.zig.zon pins/floors must agree — read them from the tags), and
     // keep `src/init_cmd.zig`'s "scaffold pins a MUTUALLY COMPATIBLE trio"
     // test satisfied — it encodes the floors below as assertions.
-    const core_version: []const u8 = b.option([]const u8, "core_version", "Default core library version") orelse "1.28.0";
+    const core_version: []const u8 = b.option([]const u8, "core_version", "Default core library version") orelse "1.32.0";
     const engine_version: []const u8 = b.option([]const u8, "engine_version", "Default engine library version") orelse "2.12.2";
     const gfx_version: []const u8 = b.option([]const u8, "gfx_version", "Default gfx library version") orelse "1.30.1";
     // Version this assembler binary stamps into a freshly scaffolded

docs/showcase-plan.md

@@ -89,10 +89,13 @@ generate+build CI assertion above.
 
 ### Games 6–9 (labelle-assembler#611) — released runtime, in-tree assembler
 
-Games 6–9 pin the **released RUNTIME** package set (core 1.26.0 / engine
-2.6.0 / gfx 1.28.1 / cli 1.58.0) + released backends, but — like every
-sibling example in this repo — pin the **assembler at `local:../../`** (the
-in-tree source). Two reasons the assembler is in-tree, not a release
+Games 6–9 pin a **released RUNTIME** package set + released backends —
+tile-explorer and sprite-runner on core 1.26.0 / engine 2.6.0 / gfx 1.28.1,
+the two bgfx games (pack-city, material-demo) on core 1.32.0 / engine 2.12.2
+/ gfx 1.30.1 because their bgfx 0.20.0 pin has a hard core floor of 1.28.0
+and was released against 1.32.0 (see their `project.labelle`), all on cli
+1.58.0 — but, like every sibling example in this repo, pin the **assembler
+at `local:../../`** (the in-tree source). Two reasons the assembler is in-tree, not a release
 number:
 
 1. `examples/` exist to validate the assembler *under test*. Numbered

examples/material-demo/README.md

@@ -44,16 +44,16 @@ sources.
 
 ## Scope note — the two halves of gfx#305
 
-gfx#305 shipped TWO surfaces. This demo exercises the **post-fx** half,
-which is wired end-to-end for games in the released engine (2.6.0). The
-**per-entity material** half (`palette_swap` / `flash` / `dissolve` /
-`outline`) is plumbed through core + gfx (`SpriteVisual.material`) but the
-released engine `2.6.0` exposes **no game-facing authoring surface** for
-it — there is no `Sprite.material` field and no `setMaterial` on the game,
-so a game cannot drive per-entity materials yet. That engine bridge is the
-tracked follow-up ([labelle-engine#789](https://github.com/labelle-toolkit/labelle-engine/issues/789));
-when it lands, this demo grows a second scene that flashes / dissolves
-individual orbs.
+gfx#305 shipped TWO surfaces. This demo exercises the **post-fx** half
+only, wired end-to-end for games since engine 2.6.0 (the demo's original
+pin). The **per-entity material** half (`palette_swap` / `flash` /
+`dissolve` / `outline`) is plumbed through core + gfx
+(`SpriteVisual.material`), and the engine now pinned here (`2.12.2`) does
+expose `game.setMaterial(entity, material)` (`src/game/visuals.zig`) — it
+was `2.6.0` that had no game-facing authoring surface for it. This demo
+still does **not** drive per-entity materials; the second scene that
+flashes / dissolves individual orbs is the tracked follow-up
+([labelle-engine#789](https://github.com/labelle-toolkit/labelle-engine/issues/789)).
 
 Files:
 
@@ -70,19 +70,28 @@ The **runtime** packages + bgfx backend pin the **released** set; the
 see the pins note in `tile-explorer/README.md`):
 
 ```zig
-.core_version = "1.26.0", .engine_version = "2.6.0", .gfx_version = "1.28.1",
+.core_version = "1.32.0", .engine_version = "2.12.2", .gfx_version = "1.30.1",
 .labelle_version = "1.58.0", .assembler_version = "local:../../",
 .backend_package = .{ .name = "bgfx", … .version = "0.20.0" },
 ```
 
-> **Backend pin bumped to `0.20.0` (labelle-core v1.32.0).** That core
-> appended `MaterialEffect.pixel_water`; every bgfx release before
-> `0.20.0` switches exhaustively over that enum with no arm for the new
-> tag, so it stops compiling against it. `0.20.0` implements the effect
-> behind `@hasField(MaterialEffect, "pixel_water")` probes and builds
-> against old and new core alike. CI clones `labelle-core` at `main` as a
-> sibling checkout and the assembler builds that sibling in preference to
-> the `.core_version` pin above, so the old backend pin failed there.
+> **Backend pin `0.20.0`, and the runtime trio raised with it.**
+> labelle-core v1.32.0 appended `MaterialEffect.pixel_water`; every bgfx
+> release before `0.20.0` switches exhaustively over that enum with no arm
+> for the new tag, so it stops compiling against that core — and CI clones
+> `labelle-core` at `main` as a sibling checkout that the assembler builds
+> in preference to the `.core_version` pin. `0.20.0` implements the effect
+> behind `@hasField(MaterialEffect, "pixel_water")` probes.
+>
+> The core pin follows the backend. bgfx `0.20.0` has a **hard** core floor
+> of `1.28.0` (`core.BackendTextureId`, a struct field type), so the earlier
+> `core_version = "1.26.0"` pairing (#731) failed a **standalone** `labelle
+> build` inside the backend (`labelle-bgfx/src/gfx/types.zig:17:38: … no
+> member named 'BackendTextureId'`) — CI never saw it because the sibling
+> core is `main` and the bgfx games are generate-only there (#732). The pin
+> is `1.32.0`, the core bgfx `0.20.0` was released against and the one the
+> curated `labelle init` trio carries; the trio here is that curated set.
+> `project.labelle` spells out the reasoning.
 
 On the fully-released `labelle` path this game builds on assembler
 `0.94.0` (bgfx takes the generic desktop `unifyCoreDiamond` codegen,

examples/material-demo/project.labelle

@@ -13,27 +13,53 @@
 // in a single screenshot.
 //
 // SCOPE NOTE (precise): gfx#305 has TWO halves. This demo exercises the
-// POST-FX half, which is wired end-to-end for games in the released engine
-// (2.6.0). The PER-ENTITY MATERIAL half (palette_swap / flash / dissolve /
-// outline) is plumbed through core + gfx (`SpriteVisual.material`) but the
-// released engine 2.6.0 exposes NO game-facing authoring surface for it
-// (no `Sprite.material`, no `setMaterial`) — so a game cannot drive
-// per-entity materials yet. Tracked as the material-demo follow-up; see
-// README.md.
+// POST-FX half only. The PER-ENTITY MATERIAL half (palette_swap / flash /
+// dissolve / outline) is plumbed through core + gfx (`SpriteVisual.material`)
+// and the pinned engine 2.12.2 DOES expose `game.setMaterial(entity, m)`
+// (labelle-engine `src/game/visuals.zig`) — it was engine 2.6.0, this
+// demo's original pin, that had no authoring surface. The demo still does
+// not drive per-entity materials; that is the follow-up in README.md.
 //
 // VERSION PINS: the RUNTIME packages (core/engine/gfx/cli) + the backend
 // pin the RELEASED set — this game proves the released runtime path (see
-// tile-explorer's note). bgfx is pinned explicitly to 0.20.0: 0.13.1 first
-// carried the post-fx shaders this demo needs (the registry enum default
-// predates them), but labelle-core 1.32.0 appended
+// tile-explorer's note). bgfx is pinned explicitly (the registry enum
+// default predates the post-fx shaders this demo needs, which 0.13.1 first
+// carried), and that pin is 0.20.0: labelle-core 1.32.0 appended
 // `MaterialEffect.pixel_water` and every bgfx release before 0.20.0
 // switches EXHAUSTIVELY over that enum with no arm for it. CI clones
-// labelle-core at `main` as a sibling checkout and the assembler's monorepo
-// auto-discovery builds that sibling INSTEAD of the `.core_version` pin
-// below, so a pre-0.20.0 bgfx compiles against the NEW core and fails sema.
-// 0.20.0 IMPLEMENTS pixel_water behind a
-// `@hasField(MaterialEffect, "pixel_water")` gate, so it builds against
-// both the pinned 1.26.0 and core `main`.
+// labelle-core at `main` as a sibling checkout and the assembler's
+// monorepo auto-discovery builds that sibling INSTEAD of the
+// `.core_version` pin below, so a pre-0.20.0 bgfx failed sema there.
+//
+// The core pin FOLLOWS the backend pin, not the other way round. The
+// assembler unifies every package onto `.core_version`, and released bgfx
+// 0.20.0 has a HARD core floor of 1.28.0: `src/gfx/types.zig` types a
+// struct field as `core.BackendTextureId` (core#328 phase 3, bgfx >=
+// 0.15.0), which is analyzed eagerly. So on a STANDALONE checkout — no
+// sibling labelle-core, i.e. the documented `labelle build` path — bgfx
+// 0.20.0 over the previous core 1.26.0 pin died inside the backend:
+//   labelle-bgfx/src/gfx/types.zig:17:38: error: root source file struct
+//   'root' has no member named 'BackendTextureId'
+// #731 shipped that pairing claiming it "builds against the pinned
+// 1.26.0"; CI never saw it because the sibling core at `main` is >= 1.32.0
+// AND the bgfx games are generate-only there (labelle-assembler#732). The
+// v1.32.0 names bgfx 0.20.0 takes from `backend_contract` (`PixelWaterDraw`,
+// `PIXEL_WATER_*`) are NOT a compile floor: they are reached only through
+// `@hasField(MaterialEffect, "pixel_water")`-gated paths or lazily-analyzed
+// top-level aliases, so 0.20.0 does compile against core 1.28.0 (proven
+// standalone with a `labelle init --backend=bgfx` scaffold).
+// The pin is 1.32.0 anyway: the core labelle-bgfx 0.20.0 was released
+// against (its own build.zig.zon), the one on which the pixel_water effect
+// the backend ships is reachable at all, and the core the curated `labelle
+// init` trio now carries — so this demo and a fresh scaffold prove ONE
+// pairing (core 1.32.0 / engine 2.12.2 / gfx 1.30.1), at or above
+// labelle-bgfx's own `examples/bgfx-android` pins (core 1.32.0 / engine
+// 2.11.0 / gfx 1.30.0). It satisfies every trio floor in build.zig /
+// `src/init_cmd.zig:checkTrioFloors` (engine >= 2.11.0 → core >= 1.27.0 +
+// gfx >= 1.28.0; gfx >= 1.30.0 → core >= 1.28.0 + engine >= 2.12.1).
+// Verified STANDALONE (scratch LABELLE_HOME, registry tarballs at these
+// exact tags, no sibling checkouts): install → generate → full `zig build`,
+// exit 0.
 // The ASSEMBLER is `local:../../` (in-tree source, the examples
 // convention). On the fully-RELEASED `labelle` path this game builds on
 // assembler 0.94.0 — bgfx takes the generic desktop `unifyCoreDiamond`
@@ -70,9 +96,9 @@
         // Subtle CRT: slight curve + scanlines + shadow mask.
         .{ .crt = .{ .curvature = 0.08, .scanline = 0.35, .mask = 0.25, .aberration = 0.12 } },
     },
-    .core_version = "1.26.0",
-    .engine_version = "2.6.0",
-    .gfx_version = "1.28.1",
+    .core_version = "1.32.0",
+    .engine_version = "2.12.2",
+    .gfx_version = "1.30.1",
     .labelle_version = "1.58.0",
     // In-tree assembler (examples convention). Fully-released path: 0.94.0.
     .assembler_version = "local:../../",

examples/pack-city/README.md

@@ -53,19 +53,28 @@ to the current release, which carries the material/post-fx work; the
 registry enum default predates it:
 
 ```zig
-.core_version = "1.26.0", .engine_version = "2.6.0", .gfx_version = "1.28.1",
+.core_version = "1.32.0", .engine_version = "2.12.2", .gfx_version = "1.30.1",
 .labelle_version = "1.58.0", .assembler_version = "local:../../",
 .backend_package = .{ .name = "bgfx", … .version = "0.20.0" },
 ```
 
-> **Backend pin bumped to `0.20.0` (labelle-core v1.32.0).** That core
-> appended `MaterialEffect.pixel_water`; every bgfx release before
-> `0.20.0` switches exhaustively over that enum with no arm for the new
-> tag, so it stops compiling against it. `0.20.0` implements the effect
-> behind `@hasField(MaterialEffect, "pixel_water")` probes and builds
-> against old and new core alike. CI clones `labelle-core` at `main` as a
-> sibling checkout and the assembler builds that sibling in preference to
-> the `.core_version` pin above, so the old backend pin failed there.
+> **Backend pin `0.20.0`, and the runtime trio raised with it.**
+> labelle-core v1.32.0 appended `MaterialEffect.pixel_water`; every bgfx
+> release before `0.20.0` switches exhaustively over that enum with no arm
+> for the new tag, so it stops compiling against that core — and CI clones
+> `labelle-core` at `main` as a sibling checkout that the assembler builds
+> in preference to the `.core_version` pin. `0.20.0` implements the effect
+> behind `@hasField(MaterialEffect, "pixel_water")` probes.
+>
+> The core pin follows the backend. bgfx `0.20.0` has a **hard** core floor
+> of `1.28.0` (`core.BackendTextureId`, a struct field type), so the earlier
+> `core_version = "1.26.0"` pairing (#731) failed a **standalone** `labelle
+> build` inside the backend (`labelle-bgfx/src/gfx/types.zig:17:38: … no
+> member named 'BackendTextureId'`) — CI never saw it because the sibling
+> core is `main` and the bgfx games are generate-only there (#732). The pin
+> is `1.32.0`, the core bgfx `0.20.0` was released against and the one the
+> curated `labelle init` trio carries; the trio here is that curated set.
+> `project.labelle` spells out the reasoning.
 
 On the fully-released `labelle` path this game builds on assembler
 `0.94.0` (bgfx takes the generic desktop `unifyCoreDiamond` codegen,

examples/pack-city/project.labelle

@@ -18,11 +18,35 @@
 // every bgfx release before 0.20.0 switches EXHAUSTIVELY over that enum
 // with no arm for it. CI clones labelle-core at `main` as a sibling
 // checkout and the assembler's monorepo auto-discovery builds that sibling
-// INSTEAD of the `.core_version` pin below, so a pre-0.20.0 bgfx compiles
-// against the NEW core and fails sema. 0.20.0 IMPLEMENTS the effect behind
-// a `@hasField(MaterialEffect, "pixel_water")` gate, so it builds against
-// both the pinned 1.26.0 and core `main`. The ASSEMBLER is
-// `local:../../` (in-tree source, the examples convention). On the
+// INSTEAD of the `.core_version` pin below, so a pre-0.20.0 bgfx failed
+// sema there.
+//
+// The core pin FOLLOWS the backend pin, not the other way round. The
+// assembler unifies every package onto `.core_version`, and released bgfx
+// 0.20.0 has a HARD core floor of 1.28.0: `src/gfx/types.zig` types a
+// struct field as `core.BackendTextureId` (core#328 phase 3, bgfx >=
+// 0.15.0), which is analyzed eagerly. So on a STANDALONE checkout — no
+// sibling labelle-core, i.e. the documented `labelle build` path — bgfx
+// 0.20.0 over the previous core 1.26.0 pin died inside the backend:
+//   labelle-bgfx/src/gfx/types.zig:17:38: error: root source file struct
+//   'root' has no member named 'BackendTextureId'
+// #731 shipped that pairing claiming it "builds against the pinned
+// 1.26.0"; CI never saw it because the sibling core at `main` is >= 1.32.0
+// AND the bgfx games are generate-only there (labelle-assembler#732). The
+// v1.32.0 names bgfx 0.20.0 takes from `backend_contract` (`PixelWaterDraw`,
+// `PIXEL_WATER_*`) are NOT a compile floor — they sit behind
+// `@hasField(MaterialEffect, "pixel_water")`-gated paths or lazy top-level
+// aliases, and 0.20.0 does compile against core 1.28.0 — but the pin is
+// 1.32.0 anyway: the core labelle-bgfx 0.20.0 was released against (its
+// own build.zig.zon), the one on which its pixel_water effect is reachable
+// at all, and the core the curated `labelle init` trio now carries. So this
+// game and a fresh scaffold prove ONE pairing (core 1.32.0 / engine 2.12.2
+// / gfx 1.30.1), at or above labelle-bgfx's own `examples/bgfx-android`
+// pins (core 1.32.0 / engine 2.11.0 / gfx 1.30.0), satisfying every floor
+// in build.zig / `src/init_cmd.zig:checkTrioFloors`. Verified STANDALONE
+// (scratch LABELLE_HOME, registry tarballs at these exact tags, no sibling
+// checkouts): install → generate → full `zig build`, exit 0. The ASSEMBLER
+// is `local:../../` (in-tree source, the examples convention). On the
 // fully-RELEASED `labelle` path this game builds on assembler 0.94.0 —
 // bgfx takes the generic desktop `unifyCoreDiamond` codegen, unaffected by
 // the sokol-desktop byte-anchor gap #611 fixes.
@@ -48,9 +72,9 @@
         .{ .name = "buildings", .repo = "@packs/buildings" },
         .{ .name = "traffic", .repo = "@packs/traffic" },
     },
-    .core_version = "1.26.0",
-    .engine_version = "2.6.0",
-    .gfx_version = "1.28.1",
+    .core_version = "1.32.0",
+    .engine_version = "2.12.2",
+    .gfx_version = "1.30.1",
     .labelle_version = "1.58.0",
     // In-tree assembler (examples convention). Fully-released path: 0.94.0.
     .assembler_version = "local:../../",