Showcase: pack-city, sprite-runner, tile-explorer, material-demo (+ sokol material-seam fix) - #645
Conversation
…aterial-demo) + sokol material-seam fix Adds the four remaining showcase games from docs/showcase-plan.md (rows 6-9), each a small, legible, complete game pinning the RELEASED package set (core 1.26.0 / engine 2.6.0 / gfx 1.28.1 / cli 1.58.0 / assembler 0.94.0) to prove the released path — not the local: sibling pins the in-tree fixture examples use. - tile-explorer (raylib): engine built-in `Tilemap` (.tmx, T2 Phase 4) + camera-prefabs seed + scripted follow-cam clamped to the map. - sprite-runner (sokol): both animation tiers — `AnimationDef` comptime rig for the runner, engine-driven `SpriteAnimation` for coin spin. - pack-city (bgfx): the packs wall as a real game — a `buildings` pack and a `traffic` pack that cooperates only across the exposed query. - material-demo (bgfx): the gfx#305 post-fx set (bloom/vignette/ color_grade/crt) via the declarative `.post_fx` seed. All four generate + `zig build` green on the released pins. The examples-integration CI generates all four and builds the raylib + sokol games (sprite-runner guards the fix below); the bgfx builds are covered locally. Each ships a README + a deterministic scene preview and documents `labelle run --screenshot=` capture. Assembler fix (surfaced by proving the released path): the sokol-desktop byte-anchor codegen never unified the backend's gfx-module `labelle-core` onto the app core. gfx#305's material seam gave that module a direct core import, so two `MaterialEffect` instances failed sema on any gfx#305-era sokol-desktop build. Unroll the `backend_gfx` core-diamond edge into the anchor tail (matching the generic desktop path bgfx/raylib already use); 4 sokol-desktop goldens updated. bgfx/raylib were never affected. Refs #611. Closes #611. Claude-Session: https://claude.ai/code/session_011szWvquoss1yNX7KWSKCaM
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 32 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthroughFour released-pinned showcase games are added with assets, scenes, gameplay scripts, documentation, and CI validation. The desktop code generator and sokol golden builds also unify backend ChangesReleased showcase games
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant MainScene
participant TrafficScript
participant BuildingsQuery
participant ECS
MainScene->>TrafficScript: Instantiate pack prefabs
TrafficScript->>BuildingsQuery: Count Building entities
BuildingsQuery->>ECS: Iterate Building view
ECS-->>BuildingsQuery: Return count
TrafficScript->>ECS: Move and wrap Car entities
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Cite the filed engine issue (no game-facing per-entity Material authoring surface) from material-demo's README and the showcase plan. Refs #611. Claude-Session: https://claude.ai/code/session_011szWvquoss1yNX7KWSKCaM
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds four new showcase games (games 6–9) to verify the released package path: material-demo, pack-city, sprite-runner, and tile-explorer. It also fixes a sokol-desktop build issue by unifying the app core onto the sokol gfx module in the desktop codegen. A review comment correctly identifies a compilation issue in the buildings pack query where game.ecs_backend is accessed directly instead of via game.active_world.ecs_backend.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| /// Number of standing buildings. | ||
| pub fn count(game: anytype) u32 { | ||
| var n: u32 = 0; | ||
| var view = game.ecs_backend.view(.{Building}, .{}); |
There was a problem hiding this comment.
In all other scripts in this pull request (such as 10_bob.zig, 20_drive.zig, 10_run.zig, and 10_explore.zig), the ECS backend is accessed via game.active_world.ecs_backend rather than directly on game. Accessing game.ecs_backend directly here will likely result in a compilation error.
var view = game.active_world.ecs_backend.view(.{Building}, .{});
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a62db4e037
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| .engine_version = "2.6.0", | ||
| .gfx_version = "1.28.1", | ||
| .labelle_version = "1.58.0", | ||
| .assembler_version = "0.94.0", |
There was a problem hiding this comment.
When this example is built through the documented labelle build/labelle run path, the CLI will honor this assembler_version and run assembler 0.94.0, but the same change notes that 0.94.0 lacks the sokol backend_gfx core-unification fix needed by labelle-sokol 0.5.0/gfx 1.28.1. CI bypasses that by invoking the freshly built $ASM directly, so the checked-in example still fails for users unless they manually override the assembler; pin this to the fixed local/next assembler instead of the unfixed release.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 956c964. Pinned .assembler_version = "local:../../" (the in-tree cohort option). A 0.95.0 pin is not buildable anywhere today: it's unreleased, and a numbered pin also stages the bundled ecs/zig-ecs adapter from ~/.labelle/packages/assembler/0.95.0/ which cannot exist yet (confirmed locally — the link fails with source ... does not exist). local: resolves the fix + the adapter from the in-tree tree, so it builds in CI. The README states plainly that the fully-released path needs assembler ≥0.95.0.
| .width = 640, | ||
| .height = 360, | ||
| .target_fps = 60, | ||
| .backend = .raylib, |
There was a problem hiding this comment.
Because this uses the implicit .raylib provider, it resolves through the assembler's built-in shorthand to labelle-raylib 0.3.0 (src/config.zig), and that release's renderer does not expose the TileMapRendererType seam that engine 2.6.0 requires before Tilemap draws. The example will still generate/build, but the showcased island map renders as a no-op; add an explicit backend_package pin for a raylib release with the tilemap seam (or choose a backend that has it) so this tilemap showcase actually displays the TMX layer.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Verified + fixed in 956c964. labelle-raylib 0.3.0 ships no tilemap code, but it still renders the map: tilemap rendering is backend-generic — the tile draw pass lives in labelle-gfx (TileMapRendererWith(B), wired by the RetainedEngine) and draws each tile through the standard drawTexturePro call, which raylib 0.3.0 implements (src/gfx.zig:84). So the capability is pinned by gfx 1.28.1, not the backend. Added an explicit .backend_package raylib 0.3.0 pin + a comment documenting this.
Round-1 review (gemini HIGH): the exposed `count` query reached the world via `game.ecs_backend` while every tick script in the PR uses `game.active_world.ecs_backend`. Align it so the query keeps working once the active world matters (scene swap / multi-world), not just today. Regenerated + built pack-city (bgfx) green. Refs #611. Claude-Session: https://claude.ai/code/session_011szWvquoss1yNX7KWSKCaM
|
Round-1 review addressed (gemini HIGH, The exposed Fixed in 907792b. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/showcase-plan.md`:
- Around line 82-88: Update the “Games 6–9” section to clarify that CI validates
the released package pins using the PR’s in-tree assembler binary, not released
assembler 0.94.0. Remove or qualify the claim that this cohort proves the
released assembler path, and retain the existing build-coverage details.
- Around line 71-74: Align the showcase table entries for pack-city,
sprite-runner, tile-explorer, and material-demo with the actual CI workflow:
either add deterministic screenshot generation, upload, and image comparison to
the workflow, or revise their documented verification scope to generate/build
only. Update the affected status descriptions in the showcase plan to match the
chosen behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: f99f6eaa-8c29-4ce9-a0e3-307bd2c3ab13
⛔ Files ignored due to path filters (11)
examples/material-demo/assets/glow.pngis excluded by!**/*.pngexamples/material-demo/preview.pngis excluded by!**/*.pngexamples/pack-city/assets/city.pngis excluded by!**/*.pngexamples/pack-city/packs/buildings/assets/buildings.pngis excluded by!**/*.pngexamples/pack-city/packs/traffic/assets/traffic.pngis excluded by!**/*.pngexamples/pack-city/preview.pngis excluded by!**/*.pngexamples/sprite-runner/assets/runner.pngis excluded by!**/*.pngexamples/sprite-runner/preview.pngis excluded by!**/*.pngexamples/tile-explorer/assets/explorer.pngis excluded by!**/*.pngexamples/tile-explorer/assets/tileset.pngis excluded by!**/*.pngexamples/tile-explorer/preview.pngis excluded by!**/*.png
📒 Files selected for processing (51)
.github/workflows/ci.ymldocs/showcase-plan.mdexamples/material-demo/.gitignoreexamples/material-demo/README.mdexamples/material-demo/assets/glow.jsonexamples/material-demo/components/orb.zigexamples/material-demo/project.labelleexamples/material-demo/scenes/main.jsoncexamples/material-demo/scripts/playing/10_bob.zigexamples/pack-city/.gitignoreexamples/pack-city/README.mdexamples/pack-city/assets/city.jsonexamples/pack-city/packs/buildings/assets/buildings.jsonexamples/pack-city/packs/buildings/components/building.zigexamples/pack-city/packs/buildings/pack.labelleexamples/pack-city/packs/buildings/prefabs/house.jsoncexamples/pack-city/packs/buildings/prefabs/shop.jsoncexamples/pack-city/packs/buildings/prefabs/tower.jsoncexamples/pack-city/packs/buildings/queries.zigexamples/pack-city/packs/traffic/assets/traffic.jsonexamples/pack-city/packs/traffic/components/car.zigexamples/pack-city/packs/traffic/pack.labelleexamples/pack-city/packs/traffic/prefabs/car_blue.jsoncexamples/pack-city/packs/traffic/prefabs/car_red.jsoncexamples/pack-city/packs/traffic/scripts/playing/20_drive.zigexamples/pack-city/project.labelleexamples/pack-city/scenes/main.jsoncexamples/sprite-runner/.gitignoreexamples/sprite-runner/README.mdexamples/sprite-runner/animations/runner.zonexamples/sprite-runner/assets/runner.jsonexamples/sprite-runner/components/cloud.zigexamples/sprite-runner/components/coin.zigexamples/sprite-runner/components/runner.zigexamples/sprite-runner/components/sprite_animation.zigexamples/sprite-runner/project.labelleexamples/sprite-runner/scenes/main.jsoncexamples/sprite-runner/scripts/playing/10_run.zigexamples/tile-explorer/.gitignoreexamples/tile-explorer/README.mdexamples/tile-explorer/assets/explorer.jsonexamples/tile-explorer/assets/island.tmxexamples/tile-explorer/components/explorer.zigexamples/tile-explorer/project.labelleexamples/tile-explorer/scenes/main.jsoncexamples/tile-explorer/scripts/playing/10_explore.zigsrc/codegen/manifest_v2_splice/desktop.zigtest/goldens/sokol_desktop_v2.build.zigtest/goldens/sokol_desktop_v2_gamepad_off.build.zigtest/goldens/sokol_desktop_v2_hidapi.build.zigtest/goldens/sokol_desktop_v2_plugins.build.zig
…der note Round-2 review (4 findings, all valid): 1. (coderabbit Major) The docs claimed the cohort proves the RELEASED assembler 0.94.0 path, but CI uses the IN-TREE assembler. Corrected: the games pin the released RUNTIME set (core/engine/gfx/cli) + released backends, and — like every sibling example — pin the ASSEMBLER at `local:../../`. Two reasons stated plainly: examples validate the assembler under test, and a numbered pin needs that version's source tree cached under ~/.labelle/packages/assembler/<ver>/ (only a released `labelle` populates it; CI does not). Fully-released compatibility is documented per backend: bgfx/raylib on 0.94.0, sokol needs >= 0.95.0. 2. (codex P2) sprite-runner assembler pin: 0.95.0 is unreleased AND an unreleased numbered pin has no cached ecs adapter, so it cannot build anywhere. Pinned `local:../../` (in-tree fix) per the reviewer's "in-tree cohort" option; README states the released path needs >= 0.95.0. 3. (codex P2) tile-explorer raylib/tilemap: verified tilemap rendering is backend-generic (gfx `TileMapRendererWith(B)` -> `drawTexturePro`, which labelle-raylib 0.3.0 implements), so 0.3.0 renders the map; capability is pinned by gfx 1.28.1, not the backend. Added an explicit raylib 0.3.0 backend pin + a comment documenting this. 4. (coderabbit Minor) Table promised "generate + build (+ screenshot)" but CI does no screenshot. Dropped the screenshot claim; documented that each game ships a committed deterministic preview.png and the true engine screenshot is captured manually (windowed backends need a GUI session / xvfb). All four still generate + `zig build` green (released runtime + in-tree assembler). `zig build test` unchanged (baseline flow_catalog lanes). Refs #611. Claude-Session: https://claude.ai/code/session_011szWvquoss1yNX7KWSKCaM
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 956c964d12
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| for g in tile-explorer sprite-runner pack-city material-demo; do | ||
| echo "== $g: install + generate (released pins) ==" | ||
| ( cd labelle-assembler/examples/$g | ||
| $ASM install --project-root . |
There was a problem hiding this comment.
In this job, $ASM install --project-root . does not fetch the pinned core/engine/gfx releases because the workflow has already checked out labelle-core, labelle-engine, and labelle-gfx as siblings; fetchFrameworkWithFallback populates the requested version cache from those local checkouts before falling back to remote tarballs (src/cache_cmd.zig:571-587). As a result the new "released runtime pins" guard is actually generating/building against whatever branches those sibling checkouts point at, so a regression present in core 1.26.0 / engine 2.6.0 / gfx 1.28.1 can pass CI; run this step with the local-framework fallback disabled or without those sibling dirs when validating the released path.
Useful? React with 👍 / 👎.
| // Cinematic edge darkening toward a cool tint. | ||
| .{ .vignette = .{ .intensity = 0.55, .radius = 0.85, .softness = 0.45, .tint = .{ 0.02, 0.02, 0.06 } } }, | ||
| // Gentle overall grade lift. | ||
| .{ .color_grade = .{ .strength = 0.35, .lut = 0 } }, |
There was a problem hiding this comment.
When this demo runs on the pinned bgfx 0.13.1 backend, color_grade with .lut = 0 is explicitly treated as a passthrough blit in the backend's applyPostPass path for zero/dead LUT handles. That means this showcased color_grade pass does not apply any grading despite the README/project comments claiming the full post-fx set is visible; either provide a real LUT texture/handle before seeding the stack or drop this pass from the demo.
Useful? React with 👍 / 👎.
1 participant
Delivers the four remaining showcase games from
docs/showcase-plan.md(rows 6-9), plus a precise assembler fix the released path surfaced.Closes #611
The games (examples/)
Each is small, legible, complete, and pins the released package set (core 1.26.0 / engine 2.6.0 / gfx 1.28.1 / cli 1.58.0 / assembler 0.94.0) — not the
local:sibling pins the in-tree fixtures use — to prove the released path end-to-end (thecli#322scaffold-versions lesson). Each ships a README + a deterministic scene preview and documentslabelle run --screenshot=(LABELLE_SCREENSHOT_PATH) capture.Tilemap(.tmx, T2 Phase 4) + camera-prefabs seed + scripted follow-camAnimationDefcomptime rig + engine-drivenSpriteAnimationbuildingspack +trafficpack cooperating only across the exposed query.post_fxseedAll four
generate+zig buildgreen on the released pins (verified locally). CI (examples-integration) generates all four and builds the raylib + sokol games; the two bgfx desktop builds (heavy C++ compile) are covered locally and left generate-only in CI as a follow-up.Assembler fix — sokol-desktop material-seam core-unify
Proving the released path surfaced a real bug: the sokol-desktop byte-anchor codegen path unrolls the core-diamond overrides by hand but never unified the backend's gfx module
labelle-coreonto the app core. gfx#305's material seam gave that module a directlabelle-coreimport (forMaterialEffect/PostPassKind), so on any gfx#305-era sokol-desktop build the two core instances yield distinctMaterialEffecttypes and sema fails (expected MaterialEffect, found MaterialEffect).This PR unrolls the
backend_gfxcore-diamond edge into the anchor tail — the same edge the generic desktop path (bgfx/raylib) already emits viaunifyCoreDiamond. 4 sokol-desktop goldens updated to match. bgfx and raylib were never affected. Released assembler 0.94.0 cannot build a sokol-desktop game against a gfx#305-era backend until the next release carries this fix; sprite-runner is the regression guard.Scope note — per-entity materials
gfx#305 shipped two halves.
material-demoexercises the post-fx half, which is game-wired in released engine 2.6.0 (.post_fx→setPostFx). The per-entity material half (palette_swap/flash/dissolve/outline) is plumbed in core+gfx (SpriteVisual.material) but engine 2.6.0 exposes no game authoring surface (Sprite.material/setMaterial) — a tracked engine follow-up, documented in the demo's README +docs/showcase-plan.md.Testing
generate+zig buildgreen for all four games (in-tree assembler + released pins, the CI path).zig build test: 2144/2150 (the 2 failures are a pre-existing environmentalflow_catalogdeps-staging issue on the clean base, unrelated); the 4 sokol-desktop goldens pass with the fix.https://claude.ai/code/session_011szWvquoss1yNX7KWSKCaM
Need help on this PR? Tag
/codesmithwith what you need. Autofix is disabled.Summary by CodeRabbit