Repository navigation
How to build the example projects? #48
Description
Activity
I tried a different setup:
npm i
perry initthen added the following to the toml file:
[package] name = "test-gltf-watch" version = "1.0.0" entry = "main.ts" [dependencies] bloom = "0.1.0" [build] out_dir = "dist" opt_level = 2 [assets] bundle = "assets/"Using perry run built the binary and ran it but I get some errors for that project:
In Device::create_bind_group, label = 'outline_bg' Texture binding 1 expects sample type Float { filterable: true }, but was given a view with format R32Float (sample type Float { filterable: false })I tried the Sponza example and it loaded the window but it gives some runtime errors saying the native build of the engine is for a newer macOS version, even though I built the native files on macOS 15:
ld: warning: object file (BloomEngine/engine/native/macos/target/release/libbloom_macos.a[179](TwoBodyConstraint.cpp.o)) was built for newer 'macOS' version (26.2) than being linked (15.0)Some dependencies are being built with the newest macOS build target. Using otool -l on engine/native/macos/target/release/libbloom_macos.a, there are two libraries being built with minOS 26 while the others are minOS 11:
bloom-jolt
minimp3I'll try to modify bloom-jolt build files to target a lower OS.
To get the bloom-jolt to build to a lower minimum OS target, I added the following to the top of native/third_party/bloom_jolt/CMakeLists.txt that is created when running the following inside native/macos:
cargo clean && cargo build --release
set(CMAKE_OSX_DEPLOYMENT_TARGET "11.0" CACHE STRING "Minimum macOS deployment target")This was just a warning message though and not the cause of the crashes. The simpler examples build and run ok. The more complex ones have errors.
bistro loads but renders a black screen with random pixels
dungeon-crawl crashes with the following error:Undefined symbols for architecture arm64: "_perry_fn_src_core_colors_ts__Color", referenced from: _main in examples_dungeon_crawl_main_ts.ointel-sponza loads, renders black screen with random pixels
isometric-rpg same as dungeon-crawl
kart-racer same as dungeon-crawl
pbr-spheres loads ok but renders spheres as solid color on a red background, no lighting
pong same as dungeon-crawl
renderer-test loads ok but all geometry renders as solid color and flickering shadows
scene-graph crashes with error:wgpu-29.0.1/src/backend/wgpu_core.rs:2653:18: wgpu error: Validation Error Caused by: In a CommandEncoder, label = 'bloom_encoder' Buffer ResourceErrorIdent { type: "Buffer", label: "scene_node_ib" } associated index count not divisible by 3 (count: 16space-blaster same as dungeon-crawl
sponza same as bistro but the pre-made executable in the git repo renders better with geometry and textures, just flickering shadows and key presses give an error sound
test-gltf-watch gives the following error:wgpu-29.0.1/src/backend/wgpu_core.rs:1277:26: wgpu error: Validation Error Caused by: In Device::create_bind_group, label = 'outline_bg' Texture binding 1 expects sample type Float { filterable: true }, but was given a view with format R32Float (sample type Float { filterable: false })test-scene-watch loads and runs ok but possibly renders incorrectly, shows a spinning glowing solid white cube on the left and solid black cube on the right
test-3d seems to load ok, solid red cube shows on a grey background
voxel-sandbox same as dungeon-crawlHi @adevart — thanks so much for the incredibly detailed report. Going through example-by-example like that is really helpful, and you've already diagnosed a couple of things correctly. Let me address what we know.
What you ran into is real
A few of these are genuine bugs on our side, not setup mistakes:
1.
outline_bgvalidation error (test-gltf-watch, possibly the cause of black screens elsewhere)This is a bug in
native/shared/src/postfx.rs— the outline post-pass binds anR32Floatobject-ID texture asFloat { filterable: true }, which requires the wgpuFLOAT32_FILTERABLEfeature. Apple GPUs don't advertise that feature, so on macOS this whole post-FX chain fails to build. We need to either declare the binding asfilterable: false(we don't actually need filtering for object-ID lookups — it should be atextureLoad) or request the feature where supported. I suspect this is the root cause of several of the black-screen / weird-rendering examples too, since post-FX chain init failing tends to cascade.2. Undefined
_perry_fn_src_core_colors_ts__Color(pong, dungeon-crawl, kart-racer, isometric-rpg, space-blaster, voxel-sandbox)In
src/core/index.tswe re-exportColorConstantsunder an alias:export { ColorConstants as Color } from './colors';
Perry doesn't seem to be following the rename when emitting symbols — it emits
_perry_fn_src_core_colors_ts__ColorConstants, but the linker is looking for_perry_fn_src_core_colors_ts__Color. The examples that useColor.Redhit this; the ones that useColors.RED(liketest3d) work fine. We'll either fix it on our side (add a realexport const Color = ColorConstantsso the symbol exists) or upstream in Perry.3. macOS deployment target warning
You're right that it's just a warning, not the cause of the crashes — well spotted. We landed an on-disk SDF cache last week that brought in the bloom_jolt build path, and I should set
CMAKE_OSX_DEPLOYMENT_TARGETin our CMakeLists rather than expecting users to patch it. Will fix.4.
scene_node_ibindex count not divisible by 3This one I haven't seen before — that's a bug in our scene-graph mesh path (
scene.rs:682). Looks like a node was added with a non-triangle index buffer. If you can share whatscene-graph/main.tsis doing when it crashes (or just confirm it's the unmodified example from the repo) that would help.To help us narrow down the rendering glitches
A few things would be really useful:
- What Mac and GPU? (Apple Silicon vs Intel, and which chip — M1/M2/M3/M4 or Intel + AMD/Intel iGPU). The black screens on
bistro/intel-sponza/sponzaare most likely format/feature-related, and Apple GPU generation matters. - Perry version — you're on 0.5.107 and the latest is 0.5.463. Worth running
perry updateand trying again before we dig deeper into the Perry-side symbol issue; some of these might already be fixed upstream. - The pre-built
sponzabinary in the repo renders better for you than your local build — that's a useful data point. It means it's something that regressed since that binary was built, not a hardware incompatibility.
On the build flow
You found the right path (
npm i+perry init+perry run). We don't currently ship per-exampleperry.tomlfiles or a top-level README walking through this — that's an oversight on our end. I'll open a tracking issue to get example READMEs and pre-committedperry.tomlfiles in place.Thanks again for taking the time on this — going to triage the post-FX and Color export bugs now.
- What Mac and GPU? (Apple Silicon vs Intel, and which chip — M1/M2/M3/M4 or Intel + AMD/Intel iGPU). The black screens on
Quick update — opened #51 with fixes for the two confirmed bugs:
- outline_bg validation error — switched binding 1 to
Float { filterable: false }and the shader totextureLoadfor the object-ID lookup, so we no longer require theFLOAT32_FILTERABLEwgpu feature on macOS. This should unblocktest-gltf-watchand is a likely fix for some of the black-screen examples too. - Missing
_perry_fn_src_core_colors_ts__Colorsymbol —Coloris now a real top-level binding incolors.tsinstead of an aliased re-export, so Perry emits the symbol the linker is looking for. This should fix pong / dungeon-crawl / kart-racer / isometric-rpg / space-blaster / voxel-sandbox.
Once #51 lands, would you mind pulling and re-running the affected examples to confirm? The other items (scene_node_ib divisibility, the bistro/sponza black screens, pbr-spheres flat lighting, macOS deployment target) are still on our list — those will get separate PRs once we've narrowed them down, and the Mac/GPU details would still help us a lot there.
- outline_bg validation error — switched binding 1 to
- added a commit that references this issue
on May 1, 2026 #51 is merged into main (
d687ac2) — fixes for theoutline_bgvalidation error and the missingColorsymbol are in. Pull main and the affected examples should build/run again on macOS. Leaving this issue open to track the remaining items (scene_node_ib divisibility, bistro/sponza black screens, pbr-spheres flat lighting, macOS deployment target warning) — Mac/GPU info from you would still help us narrow those down.Thanks for the detailed replies and fixes. I'll pull the update and test again.
My hardware is M3 Max running macOS 15.7.5.
After testing with the latest build, here are the results:
bistro same
dungeon-crawl works correctly but crashes after a while running.
intel-sponza same
isometric-rpg now loads, shows some graphics but hangs then crashes
kart-racer now loads, shows some graphics but also hangs then crashes
pbr-spheres same with solid color
pong works correctly, seems to be stable, only thing is FPS looks unstable, graphics are stuttering
renderer-test same as before
scene-graph same as before (this is unmodified from the repo)
space-blaster runs ok but crashes after a short time running
sponza renders black as before but now crashes on load
test-glft-watch has a new error:wgpu-29.0.1/src/backend/wgpu_core.rs:1081:30: wgpu error: Validation Error Caused by: In Device::create_shader_module, label = 'outline_shader' Shader 'outline_shader' parsing error: redefinition of `VertexOutput` ┌─ wgsl:2:8 │ 2 │ struct VertexOutput { │ ^^^^^^^^^^^^ previous definition of `VertexOutput` · 31 │ struct VertexOutput { │ ^^^^^^^^^^^^ redefinition of `VertexOutput`test-scene-watch same as before
test3d same as before
voxel-sandbox now runs and shows some voxels but the rendering looks incorrect and crashes after a whileThe crashes happen while the processes are running idle. Memory usage looks like it spikes when it crashes but overall memory usage looks reasonable at 1-2GB. Possibly a memory leak somewhere. Pong is stable.
Examples with text have some text rendering issues with some characters rendering as squares.
Perry update wasn't available for Mac previously but is available now, will do some testing with 0.5.465.
Thanks for re-testing — really useful breakdown. Lots of forward progress in there:
What #51 fixed (confirmed by your test)
All six examples that were hitting the missing `Color` symbol now build and run:
- pong, dungeon-crawl, isometric-rpg, kart-racer, space-blaster, voxel-sandbox — link error gone.
What #51 surfaced (and how we're fixing it now)
Removing the bind-group validation error in `outline_bg` revealed a latent shader-compile bug that naga had been masking behind it: `FULLSCREEN_VERT` and `OUTLINE_FRAG` both declared `struct VertexOutput`, and once they get concatenated into one source string you get the redefinition error you're now seeing on `test-gltf-watch`. This is also what's causing sponza to crash on load now (the post-FX init fails before the renderer can come up), and likely makes things worse on a few of the others too.
I've put up #52 with the one-line fix (drop the duplicate). Validated locally with naga 29.0.0 — clean parse. Will merge as soon as CI is green; should be in within an hour.
What's still real after #52 lands
The crashes-while-idle pattern (dungeon-crawl, isometric-rpg, kart-racer, space-blaster, voxel-sandbox all crash after a while running, memory spikes at the moment of crash) sounds like a leak somewhere in the per-frame path. We're going to need a sample/leaks profile to track that down — would you mind, when one of these crashes, running:
```bash
sample 5 -file /tmp/bloom_sample.txt
```…on the running process before it dies, and attaching the output? Even one for any of the crashing examples would help. M3 Max + macOS 15.7.5 — that's a useful baseline, thanks.
Other items still on our list and not fixed yet:
- bistro / intel-sponza / pbr-spheres — same as before, no improvement (these are likely separate renderer issues, not post-FX cascade)
- scene-graph — the `scene_node_ib` divisibility bug (unmodified repo example, so we can repro locally)
- renderer-test, test-scene-watch — rendering glitches
- Text rendering squares — likely a font glyph cache miss; we'll look at that separately
- pong stutter — frame-pacing issue, opening a separate ticket
Perry 0.5.465 being available for Mac now is great news — please do try with it. If anything in the linker / FFI behavior shifts, that'd narrow down whether the remaining issues are engine-side or compiler-side.
- added a commit that references this issue
on May 1, 2026 #52 is in main (
2170437).test-gltf-watchshould now compile its outline shader successfully, andsponzashould stop crashing on load. Other items still tracked above.Tested latest version of the engine, test-gltf-watch now loads but shows empty window. The post FX are working, vignette, film_grain etc but bloom/models/loadModel on assets/Buggy.glb and the other glb files is returning an empty default object.
sponza still crashes on load. Possibly it's the same issue with the glb assets not loading. There are no errors about asset load failing, it maybe catches the error and returns a default object.
I ran a sample on the crashing process when idle, I have attached the sample log.
I tested perry 0.5.465 but all the examples give errors about missing definitions and don't run so I reverted to 0.5.107 for now.
The asset loading is to do with a path issue. In the test-gltf-watch example, where it loads the model:
https://github.com/Bloom-Engine/engine/blob/main/examples/test-gltf-watch/main.ts#L40
const buggy = loadModel("assets/Buggy.glb");When it reaches the engine, the path "assets/Buggy.glb" is getting its first 4 characters removed so becomes "ts/Buggy.glb" and some NUL characters are added to the string. If I add 4 characters at the start and remove NUL characters in the engine, the glb loads ok.
Two of the models don't display correctly (possibly a texture/shader issue), they only show a small part of the model, but the Fox model displays ok.
Roadmap coordination update: this legacy report is now explicitly linked from epic #126.
Its scopes are split deliberately:
- the discoverable build flow, checked example inventory, manifest correctness, and clean starter experience belong to [DX] Ship a one-command starter and compile/run every canonical example #142;
- generated/native string and buffer correctness belongs to [API] Generate the FFI surface from one schema and remove pointer-only APIs #141 and [Platform] Package shader runtime dependencies and enforce UTF-8 end to end #145 where applicable;
- individual rendering/runtime failures still need their own reproducible acceptance evidence and should not be considered fixed merely because an example compiles.
Draft PR #147 has added a completeness-checked inventory of all 20 canonical package/main examples, fixed ten stale native-library allowlists, and proven Perry code generation for all 20 locally. It does not close this report: clean-machine linked execution and the remaining runtime/render defects are still outstanding.
If I run:
cd examples/test-gltf-watch
npm i
perry compile -v main.ts -o main
I get the following output: