How to build the example projects?

[adevart]

If I run:

cd examples/test-gltf-watch
npm i
perry compile -v main.ts -o main

I get the following output:

Collecting modules...
  Native library: bloom/core (376 FFI functions)
  Native library: bloom/scene (376 FFI functions)
  Native library: bloom/models (376 FFI functions)
Found 7 module(s): 7 native, 0 JavaScript
Generating code...

Module init order (6 modules):
  [0] src/core/types.ts
  [1] src/core/colors.ts
  [2] src/core/keys.ts
  [3] src/core/index.ts
  [4] src/models/index.ts
  [5] src/scene/index.ts

Wrote object file: examples_test_gltf_watch_main_ts.o
Wrote object file: src_core_colors_ts.o
Wrote object file: src_core_index_ts.o
Wrote object file: src_core_keys_ts.o
Wrote object file: src_core_types_ts.o
Wrote object file: src_models_index_ts.o
Wrote object file: src_scene_index_ts.o
  auto-optimize: Perry workspace source not found, using prebuilt libperry_runtime.a + libperry_stdlib.a
Linking (runtime-only)...
Building native library: bloom/core ...

Update: 0.5.107 → 0.5.463 available
  Run perry update to update, or visit https://github.com/PerryTS/perry/releases/tag/v0.5.463
Error: No such file or directory (os error 2)

[adevart]

I tried a different setup:

npm i
perry init

then 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
minimp3

I'll try to modify bloom-jolt build files to target a lower OS.

[adevart]

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.o

intel-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: 16

space-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-crawl

[proggeramlug]

Hi @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_bg validation 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 an R32Float object-ID texture as Float { filterable: true }, which requires the wgpu FLOAT32_FILTERABLE feature. 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 as filterable: false (we don't actually need filtering for object-ID lookups — it should be a textureLoad) 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.ts we re-export ColorConstants under 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 use Color.Red hit this; the ones that use Colors.RED (like test3d) work fine. We'll either fix it on our side (add a real export const Color = ColorConstants so 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_TARGET in our CMakeLists rather than expecting users to patch it. Will fix.

4. scene_node_ib index count not divisible by 3

This 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 what scene-graph/main.ts is 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:

1. 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/sponza are most likely format/feature-related, and Apple GPU generation matters.
2. Perry version — you're on 0.5.107 and the latest is 0.5.463. Worth running perry update and trying again before we dig deeper into the Perry-side symbol issue; some of these might already be fixed upstream.
3. The pre-built sponza binary 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-example perry.toml files 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-committed perry.toml files in place.

Thanks again for taking the time on this — going to triage the post-FX and Color export bugs now.

[proggeramlug]

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 to textureLoad for the object-ID lookup, so we no longer require the FLOAT32_FILTERABLE wgpu feature on macOS. This should unblock test-gltf-watch and is a likely fix for some of the black-screen examples too.
• Missing _perry_fn_src_core_colors_ts__Color symbol — Color is now a real top-level binding in colors.ts instead 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.

[proggeramlug]

#51 is merged into main (d687ac2) — fixes for the outline_bg validation error and the missing Color symbol 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.

[adevart]

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.

[adevart]

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 while

The 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.

[proggeramlug]

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.

[proggeramlug]

#52 is in main (2170437). test-gltf-watch should now compile its outline shader successfully, and sponza should stop crashing on load. Other items still tracked above.

[adevart]

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.

bloom_sample.txt.zip

[adevart]

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.