After analyzing my render graph and verifying the color targets I was using in the lighting pass and tone mapping pass, I realized that I had made a crucial mistake in the engine.

See, my lighting pass was doing all calculations in linear space, which is correct. However, the internal render targets were being created using the drawable's pixel format. Doing so meant that every platform could change the precision, dynamic range, and even encoding behavior of my internal buffers.

In other words, my lighting results were being stored in formats dictated by the drawable’s target format. That is wrong. The renderer should own its internal formats — not the presentation layer.

Because the drawable format differs per platform (for example, .bgra8Unorm_srgb on Vision Pro), my internal render targets were sometimes:

• 8-bit
• sRGB-encoded
• Not HDR-capable

Even though my lighting calculations were done in linear space, the storage format altered how those results were preserved and interpreted.

So yes — the math was linear, but the buffers holding the results were not consistent across platforms.

That is where the mismatch came from.

To fix this, I explicitly set the color target used in the lighting pass to rgba16Float. By doing this, I ensured:

• Stable precision
• HDR-capable storage
• Linear behavior
• Platform-independent results

Now, my lighting calculations are identical regardless of the platform, because the internal render targets are explicitly defined by the engine — not by the drawable.

The Second Issue: Tone Mapping Is Not Output Encoding

The other issue was more subtle and made me realize that I still have a lot more to learn about tone mapping.

My pipeline originally followed this path:

• Lighting Pass
• Post Processing
• Tone Mapping
• Write to Drawable

The problem with this flow was that I assumed that after tone mapping, the image was ready for the screen.

But that is not true.

Different platforms expect different things:

• Different pixel formats (RGBA vs BGRA)
• Different encoding (linear vs sRGB)
• Different gamuts (sRGB vs Display-P3)
• Different dynamic range behavior (SDR vs EDR)

My pipeline above implicitly assumed that the tone-mapped result already matched whatever the drawable expected.

But tone mapping does not mean “ready for any screen.”

Tone mapping only compresses HDR → display-referred brightness range. It does not:

• Encode to sRGB automatically
• Convert color gamut
• Match the drawable’s storage format
• Handle EDR behavior

So when I wrote directly to the drawable after tone mapping, I was essentially letting the platform decide how the final color should be interpreted.

And since platforms differ, my final image differed.

What Was I Missing?

I needed to separate responsibilities more clearly.

I needed a pass that owned the creative look — fully defined and controlled by the engine:

• Exposure
• White balance
• Contrast
• Tone mapping curve

This defines how the image should look artistically.

And I needed a separate pass that is platform-aware — an Output Transform pass — that defines how the display expects pixels to be formatted:

• Encode to sRGB or not
• Convert to P3 or not
• Clamp or preserve HDR
• BGRA vs RGBA channel order
• EDR behavior

In my original pipeline, I had collapsed Look + Output Transform into one step. I wasn’t explicitly controlling the final encoding, so the platform’s defaults influenced the final image.

With the extra passes and modifications I made, the Look pass now defines the artistic look of the image. The Output Transform defines how that look is encoded for a specific display.

Previously, I was conflating the two — which allowed the platform’s drawable format to influence the final result.

Here is the image after the fix.

Now, the renderer owns the working color space and internal formats, and the drawable only affects the final presentation step.

Thanks for reading.

To make things worse, the run-time errors were cryptic and pointed to different functions each time the application crashed. Sometimes it looked like a type issue. Other times it looked like a Foundation error. Nothing clearly indicated what the real problem was.

However, during debugging, I started to see a pattern. Most of the time, the error pointed to scene or component data access. That’s when I began wondering:

What if, during loading, the system is trying to access data that is not yet stable?

In other words, what if one part of the engine is writing to components while another part is reading from them?

Then another thought came to mind. What if this issue is also present on macOS, but because macOS does not use a dedicated render thread in the same way as Vision Pro, the race condition is simply not exposed?

After a few more debugging sessions, I realized I may have been onto something.

The Real Issue

On Vision Pro, rendering runs on a dedicated render thread. When we load a large scene, the Untold Engine performs loading work on a separate thread so that we don’t block execution.

That means we had two things happening at the same time:

• The render thread traversing the scene graph, iterating component storage, performing culling, and building draw calls.
• The loading thread creating entities, attaching components, recursively tagging entities for static batching, rebuilding batch data, and updating spatial structures such as the octree.

In other words, the render thread was reading from scene/component data while the loading thread was writing to that same data.

This read/write overlap caused race conditions and eventually corrupted state.

Why This Did Not Happen on macOS

The reason this did not happen on macOS is mostly due to timing and threading differences.

On macOS:

• The renderer and update loop are more tightly coupled.
• The mutation window during loading is smaller.
• The render traversal is less likely to intersect with scene mutation at the exact wrong moment.

On Vision Pro:

• Rendering runs independently on a dedicated thread.
• Frame submission follows its own cadence.
• The renderer can traverse the scene while it is still being mutated.

Large scenes amplify this issue because static batching and recursive hierarchy processing take longer, increasing the window where the world is in a partially mutated state.

The Solution

The solution was to add a gating mechanism to prevent any read/write collision while loading was taking place.

The idea is simple:

• When a major scene mutation phase begins (for example, during large scene loading or static batch generation), increment a shared counter.
• When the mutation phase finishes, decrement it.
• The render thread checks this counter before traversing the scene.
• If a mutation is in progress, the render thread continues to submit frames but avoids traversing scene or component data that may still be unstable.

It’s important to note that I do not block the render thread on visionOS. I let it continue running, but I prevent it from accessing critical scene data while the loading phase is still mutating that data.

After this fix was in place, loading large scenes with the Untold Engine on Vision Pro no longer caused run-time crashes.

Final Thoughts

In the end, the issue was about concurrency.

• Rendering reads from the world.
• Loading mutates the world.

Without proper synchronization, those two operations cannot safely overlap.

Vision Pro didn’t introduce a new bug into the Untold Engine. It exposed a hidden assumption in my threading model.

And that’s a good thing. Thanks for reading.

Both tasks ended up being more related than I initially expected.

BTW, here is version 0.10.0 of the engine with the Geometry Streaming Support.

Geometry Streaming Wasn’t the Hard Part — Integration Was

Getting Geometry Streaming working on its own wasn’t too bad. The goal was simple enough: render large scenes without having to load the entire scene into VRAM during initialization. Instead, meshes should be loaded and unloaded on demand, without stalling rendering.

The part that caused friction was not streaming itself, but getting it to behave correctly alongside two existing systems:

• the LOD system
• the static batching system

Each of these systems already worked well in isolation. The instability showed up once they had to coexist.

I initially overcomplicated the problem, mostly because I was treating these systems as if they were peers operating at the same level. They’re not.

The Assumption That Broke Everything

The thing that finally made it click was realizing that these systems don’t negotiate with each other — they react to upstream state.

Once I stopped thinking of them as equals and instead thought of them as layers in a pipeline, the engine immediately became more predictable.

A stable frame ended up looking like this:

• Geometry streaming updates asset residency
• LOD selection picks the best available representation
• Static batching groups the selected meshes
• The renderer submits batches to the GPU

Once I enforced this flow in the update loop, a surprising number of bugs simply disappeared.

The key insight here was that ordering matters more than clever logic.
These systems don’t need to know about each other — they just need to run in the right sequence and respond to state changes upstream.

The Kind of Bugs That Only Show Up Once Things Are “Mostly Working”

Getting the ordering right was half the battle. The other half was dealing with the kind of bugs that only appear once the architecture is almost correct.

For example:

• I wasn’t clearing the octree properly, which caused the engine to look for entities that no longer existed.
• One particularly frustrating bug refused to render a specific LOD whenever two or more entities were visible at the same time.

That second one took an entire day to track down.

It turned out the space uniform was getting overwritten during the unload/load phase of the streaming system. Nothing fancy — just a subtle overwrite happening at exactly the wrong time.

That kind of bug is annoying, but it’s also a signal that the system boundaries are finally being exercised in realistic ways.

The Flickering Issue That Didn’t Behave Like a Flicker

The flickering issue was a different kind of problem.

It only showed up in Edit mode, not reliably in Game mode. And it wasn’t the usual continuous flicker you expect when something is wrong. Instead, it would flicker once, stabilize, then flicker again a few seconds later — or sometimes not at all during a debug session.

That made it especially hard to reason about.

At first, I assumed it was a synchronization issue between render passes. I tried adding fences, forcing stricter ordering — none of that helped.

The clue ended up being that the flicker correlated with moments when nothing should have been changing visually.

The Real Cause: State Falling Out of Sync

Eventually, I traced the issue back to the culling system.

In some frames, the culling pass was returning zero visible entities — not because nothing was visible, but because the visibleEntityIds buffer was getting overwritten.

The fix wasn’t to add more synchronization, but to acknowledge reality: the culling system was already using triple buffering, and visibleEntityIds needed to follow the same pattern.

Once I made visibleEntityIds triple-buffered as well, the flickering disappeared completely.

The takeaway here wasn’t “use triple buffering,” but:

Any system that consumes frame-dependent data must respect the buffering strategy of the system producing it.

Final Thoughts

None of the issues this week were caused by exotic bugs or broken math. They all came from small assumptions about ordering, ownership, and state lifetime.

Once those assumptions were corrected, the engine became noticeably more stable — not just faster, but easier to reason about.

That’s usually a good sign that the architecture is moving in the right direction.

Thanks for reading.

It’s me again with a new update on the Untold Engine — this time focused on user experience and performance.

You might find this a bit odd coming from an engineer, but user experience matters a lot to me. Sometimes, I even see it as more important than performance itself. I know, that sounds backwards. But honestly, I don’t care how fast a tool is if the user experience is bad. If it’s frustrating to use, then to me, it’s not a good product.

So let’s start with the user-experience improvements I’ve been working on.

BTW, you can read more about version 0.9.0 of the engine here.

Quick USDZ Preview

I was never happy with the fact that every time I wanted to render a model with the Untold Engine, I had to create a full project first. That felt unnecessary and slow.

So I added a Quick Preview feature.

You can now preview a .usdz file directly without creating or importing it into a project. Just click the Quick Preview button, select your .usdz file, and you’re good to go.

Improved Importing Workflow

Next up: importing.

The old importing workflow was confusing at times and a bit error-prone. It was too easy to accidentally import a model into the wrong category, which is never a good experience.

Now, when you click Import, you’re explicitly asked what you want to import. This makes the process clearer and significantly reduces the chances of loading assets into the wrong place.

Scenegraph Parenting Support

At some point, I realized I really wanted to create parent–child relationships between entities directly from the editor — but the Scenegraph didn’t support that at all.

So I added it.

You can now parent entities directly in the Scenegraph by dragging one entity onto another.
To unparent an entity, just right-click it in the Scenegraph and select Unparent.

That said, I think I can make the hierarchy more visually obvious. That might be the next thing I tackle so parent–child relationships are easier to spot at a glance.

Viewport Child Selection

This one was a complete oversight on my end.

If an entity had multiple child meshes and you tried to select one of those meshes in the viewport using a right-click, the parent entity would get selected instead. That’s… not great.

This was a terrible user experience, so I made it a priority to fix.

You can now select child entities directly in the viewport using Shift + Right Mouse Click, which makes working with hierarchical scenes much more intuitive.

Now, let’s talk about performance improvements.

LOD System

The Untold Engine now supports an LOD system.

You can assign an LOD Component to an entity, provide multiple versions of a mesh, and the engine will automatically select the appropriate LOD based on distance. This is especially useful when you want to maintain a steady 60 FPS without rendering fully detailed meshes when they’re not needed.

Static Batching System

The engine now also supports Static Batching.

This is extremely useful for scenes with a large number of static objects. By batching these meshes together, the engine can significantly reduce the number of draw calls it needs to execute.

In one test scene, draw calls dropped from over 2,000 to just 34. That’s a massive improvement and makes a huge difference in frame stability.

That’s all for now.

If you want to follow the development of the engine and stay up to date with future updates, make sure to check out the project on GitHub.

Thanks for reading.

Me again with some updates on the status of the Untold Engine. As always, I’ve been working diligently on the engine. Over the past two weeks, I focused on implementing multi-platform support, fixing several async issues with scene loading, and starting work on a couple of camera behaviors that I needed for benchmarking and game testing. So let me walk you through what’s new Untold Engine Studio

Multi-Platform Xcode Project Support

With the Untold Engine, you’re no longer limited to building a game for a single platform. You can now create an Xcode project with multi-platform support, either through the CLI or directly from the Untold Engine Studio.

This makes game development a lot smoother: you code once, and your game runs on macOS, iOS, iOS + AR, and Vision Pro. The only platform still missing is tvOS, but that will be added soon.

Fixed Async Issues

There was an issue when loading large scenes in async mode that could cause a runtime crash. This was tricky to debug, but I eventually tracked it down, and the crash is no longer present.

If you’ve been following the progress of the engine, you’ll know that one of my core rules is that the engine should never crash. If you do encounter any crashes while loading a scene, please let me know by opening a GitHub issue.

Camera Behaviors

Finally, I started implementing the following camera behaviors:

• Camera path follow using waypoints
• Camera follow with a dead zone

It’s interesting that I still haven’t implemented first-person or third-person camera behaviors, yet I decided to work on these first. The reason is simple: I’ve been benchmarking the engine, and I needed a camera that could follow a predefined path using waypoints. The goal is to measure frame rate as the camera traverses a heavy scene. Since this behavior didn’t exist, I implemented it and made it part of the engine, as I do see it being useful for game development in general.

The second behavior is one you often see in soccer (fútbol) games. The camera only follows the entity if it moves beyond the boundaries of a box; otherwise, the camera remains stationary. I implemented this because I’m currently developing a soccer video game using the new Untold Engine and Editor.

There’s a clear purpose behind developing this game, and the effort has already paid dividends. I’ve run into several bugs and API confusions that I would not have discovered otherwise. Even though I’m not in the business of making games, I do see game development as a core part of building a game engine. I mean, how else would I really test my own tools?

That’s it for now. I’m going to get back to coding. Stay tuned for upcoming features.

Thanks for reading. And don't forget to download the Untold Engine Studio

Faster Scene Loading with Async Asset Loading

One of the main issues I fixed in v0.7.0 was the long wait times when loading heavy scenes. I don’t have hard numbers, but it was definitely taking longer than what’s acceptable for a game engine. The main issue was that we didn’t have an async loading system in place. All models were being loaded synchronously, which caused long stalls.

With v0.7.0, scenes are now loaded through an async loading system, which makes the overall experience much better and more responsive.

Here is an example of how you can use the new async loading:

// Create entity
let entityId = createEntity()

// Load mesh asynchronously (fire and forget)
setEntityMeshAsync( entityId: entityId, filename: "large_model", withExtension: "usdz")

For more info, read the UsingAsyncLoading.md under the docs folder.

SSAO Performance Improvements (Especially on Vision Pro)

Another issue I worked on was improving SSAO performance, especially on mobile and Vision Pro. I added three quality modes for SSAO computation:

• Fast
• Balanced
• High

Fast mode is the most performant but has the lowest quality, while High mode provides the best quality at the cost of performance. Fast mode did improve performance on Vision Pro, but unfortunately, not enough—the FPS is still not acceptable. Until I find a better solution, I recommend disabling SSAO entirely when using Vision Pro.

To use it in code, simply set the quality as shown below:

SSAOParams.shared.quality = .balanced //.fast or .high

Command-Line Project Creation (Xcode Integration)

The third feature I added, which I think will be really helpful, is the ability to create an Xcode game project with Untold Engine as a dependency directly from the command line. This is especially useful for users who want to bypass the editor and work directly in Xcode. That said, this doesn’t mean you can’t use the editor later—projects created this way can still be opened in Untold Engine Studio.

Here is an example on how to install and use the cli tool:

# clone the repo
git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine

# Install the CLI globally:
./scripts/install-create.sh

# Verify installation:
untoldengine-create --version
untoldengine-create --help

# After installing the CLI, create a project from anywhere:

#  Create project directory
cd ~/anywhere
mkdir MyGame && cd MyGame

#  Create the project
untoldengine-create create MyGame

#  Open in Xcode
open MyGame/MyGame.xcodeproj

For more information, see: Tools/UntoldEngineCLI/README.md

Editor Workflow Improvements

I also spent time improving the user experience in the Untold Editor. The workflow is starting to take shape:

1. User opens Untold Engine Studio
2. Creates a new project or opens an existing one
3. Populates the scene
4. Writes game logic using Swift or scripting
5. Builds & plays
6. Repeat steps 3–5

This is still a work in progress, but I’m liking how everything is coming together.

What’s Next

For this week, I’m planning to focus on:

1. Benchmarking + metrics harness
2. Improving performance on Vision Pro and iOS

That’s the plan.
Feel free to checkout the the Untold Engine Studio v0.7.0.

Thanks for reading.

I started in 2013, back when I didn’t even know what version control was. The early versions of the engine were crude, fragile, and limited—but seeing it improve, fix by fix, was deeply motivating.

There were many points along the way where I wanted to quit. Days where I was tired of touching the engine at all. At one point, I stopped entirely for about six months before coming back.

What I learned over time is that building a game engine isn’t technically hard in the way people expect. The real difficulty isn’t math, rendering, or architecture—it’s consistency. Showing up every day after the excitement wears off. Continuing when motivation is gone.

That’s the part most people underestimate.

I eventually realized something about myself: I’m not a good engineer because I write good code. I’m a good engineer because I don’t leave problems unfinished. I stay with them. I’ve done that since I was a kid—I just didn’t recognize it until much later.

That persistence is the reason Untold Engine still exists today.

After rebuilding the engine twice—from C++ to Swift—the project is finally reaching a point where it feels grown up. Today, I’m releasing Untold Engine Studio, the first bundled desktop release of the Untold Engine ecosystem.

This release exists for one reason: to remove friction.

With Untold Engine Studio, developers can:

• Download a single DMG and start immediately
• Skip repository cloning and local build setup
• Create and manage projects from a standalone app
• Work visually with scenes, assets, and entities
• Iterate quickly using Play Mode and Scripting language

From the beginning, my focus has been user experience. I’m not trying to compete with Unreal on performance or Unity on market share. My goal is simpler—and harder: to build a tool that feels intuitive, stable, and dependable. Something that doesn’t fight you. Something that just works.

That’s not easy. It requires constant iteration and restraint. But this release is a meaningful step in that direction.

If you’re curious, I encourage you to download Untold Engine Studio and try it for yourself. Your feedback—good or bad—is genuinely valuable, and you can share it through the Untold Engine GitHub issues.

I’ve also invested a significant amount of time in documentation to make getting started easier, and I hope it helps.

As 2025 comes to a close, I’m proud of where Untold Engine is today. I have ambitious plans for 2026, and I’m excited to see how much further this project can go.

Thank you for reading.

Gaussian Splats

The first major update is that the Untold Engine now supports Gaussian Splat Rendering. This is a feature I’ve wanted to implement since I first learned about Gaussian Splatting last year. Other priorities kept delaying it, but a few weeks ago I finally had enough time to focus on it—and I got it working.

Gaussian Splats now run inside the Untold Editor, on iOS, in AR, and on the Vision Pro, running directly on the device. This means both 3D models and splats render natively on visionOS hardware, not just the simulator.

There are a few current limitations:

• I’m using Bitonic Sort instead of Radix Sort for depth sorting. Bitonic Sort works, but it is slower for large splat counts. Radix Sort is the long-term goal.
• Spherical Harmonics support is not implemented yet. I’m hoping to add this before the end of the year.

Even with these limitations, this is a major step forward for the engine’s rendering capabilities.

Scripting Support

The engine now supports runtime scripting directly through the Untold Editor.

You can write game logic in Xcode, attach scripts to entities, and instantly see the results while the engine is running. All scripts appear in the Asset Browser, and you can add, link, or reload them with a click. This makes the development workflow smoother and faster.

This feature was long overdue, but I approached it carefully because of past experience integrating scripting languages. Instead of Lua or Python, I built a lightweight DSL (Domain-Specific Language) specifically for the Untold Engine. I used ChatGPT heavily at the beginning to help with the initial structure, and once everything made sense, I took over and customized the system for the engine.

If you see anything that can be improved, please let me know—this is a brand-new system and will evolve with feedback.

Feel free to check out the Scripting Section in the Docs to learn more.

Build System

Another major milestone is the new Build System.

After you set up your scene in the editor and attach scripts, the Untold Engine can now generate a macOS build of your game. The Build System packages your scenes, assets, and scripts and produces an app ready for the App Store. All you need to do is provide a project name and a destination path.

At the moment, the Build System supports macOS only, but iOS and visionOS support is planned.

What’s Next?

I’m currently working on a packaged app bundle for the Untold Engine. The idea is to let developers download a .dmg file and start building games immediately—without cloning the repo or setting up dependencies. Developers who want full control can still clone and build from source.

This bundled version will be called Untold Engine Studio, and it will include everything required: the Untold Engine, the Untold Editor, and all dependencies. My goal is to make the development experience as smooth and accessible as possible.

More updates coming soon. Thanks for following the journey!

Let me tell you all about it.

Engine & Editor

You may recall that I had both the core and the editor integrated tightly in the engine. It worked nicely, but the coupling was going to give us headaches in the future.

Thanks to the effort of our first contributor miogds, the core of the engine and the editor are now de-coupled.

So, this is the new architecture of the engine:

• Core: Handles the runtime — rendering, physics, ECS, and all engine systems.
• Editor: A dedicated app for scene creation, entity manipulation, and asset management.

This separation makes development cleaner, more modular, and sets the stage for headless or custom integration workflows.

Additionally, the core engine will continue in its original repository UntoldEngine, while the editor now lives in a new, dedicated repo UntoldEditor.

Unit Tests & Workflows

I've also been working on making the Untold Engine repository more professional.
This includes adding unit tests, GitHub Actions workflows, and automatic formatting and linting.

My hope is that these improvements will make contributing to the project much easier and more reliable.

Website & Documentation

Another area of progress has been the new website and documentation.
The documentation site covers how to install the engine, explore the APIs, and contribute to development.

You can check it out here: Untold Engine

Each engine release will include its own version of the docs for consistent developer onboarding.

VisionOS Support

Lastly, the engine now compiles and runs on the VisionOS simulator — the first step toward supporting Apple’s Vision Pro platform.

However, this is still early support — the engine has not yet been tested on an actual Vision Pro device.
We’ve already received an issue report related to Vision Pro hardware, so if you happen to have one and would like to help debug, you’re more than welcome to contribute!

Thanks for reading.

So, I opened up Instruments to profile the issue. I noticed warnings that the engine was holding on to the drawable too long. I tried restructuring things to hold on to the drawable for as short a time as possible, but nothing helped.

According to Instruments, the engine was not CPU-bound or GPU-bound. There was no clear indication of the root cause of the flickering.

Digging Deeper

At that point, I decided to record a short video of the issue. I slowed it down and went frame by frame. What I saw wasn’t the usual kind of flickering—it was different.

• Frame 1: a certain set of models was visible.
• Frame 2: a completely different set was visible.
• Frame 3: some disappeared, others suddenly appeared.

Models were popping in and out, almost as if something was out of sync.

This was a huge hint: it looked like a data race.

The Culprit

Looking at the code confirmed it.

In the frustum culling command buffer completion handler, I was updating the visibleEntityId array. This array held all the entities that passed the culling test.

The problem was that the GPU calls this completion handler asynchronously, while the CPU was already using that same array during the rendering passes (shadow and geometry).

In other words, the CPU was iterating over visibleEntityId at the same time the GPU might be modifying it.

Classic data race.

The Fix: Triple Buffering

The solution was to add a triple-buffered visible entity list.

During culling, the GPU writes results into buffer n+1.

During rendering, the CPU continues to read from buffer n.

When the frame finishes and the render command buffer’s completion handler triggers, I update the index so the CPU reads from the freshly written buffer n+1 on the next frame.

This guarantees that the CPU never reads data being modified by the GPU. The renderer always sees a stable snapshot of the visible entities.

The Result

With triple buffering in place, the flickering disappeared instantly. Models no longer popped in and out between frames.

This bug was a good reminder: sometimes what looks like a rendering artifact isn’t a math error at all, but a synchronization issue between CPU and GPU.

Lesson Learned

Whenever the GPU produces results asynchronously, the CPU should never iterate over those results directly. Always work with a snapshot. Triple buffering (or even double buffering) is a small architectural change that guarantees stability and avoids subtle bugs that can masquerade as rendering issues.

This experience reinforced for me how crucial synchronization and data ownership are when building GPU-driven systems—sometimes the hardest-looking bugs aren’t about shaders or math, but about who’s allowed to touch the data, and when.

So, I launched the engine, loaded a scene, and then deleted the scene.

The moment I did that, the console log started flooding with messages like:

• Entity is missing or does not exist.
• Does not have a Render Component.

This was the first time I had ever seen the engine behave like this when removing all entities from a scene. My first reaction was: the formatter broke something.

But the formatter’s changes were only cosmetic. There was no reason for this kind of bug.

At that point I was lost. So, I asked ChatGPT for some guidance, and it mentioned something interesting: maybe the formatter’s modifications had affected timing. That hint got me thinking.

After tinkering a bit, I realized the truth: this bug was always there. The formatter just exposed it earlier.

The Real Problem

My engine’s editor runs asynchronously from the engine’s core functions. When I clicked the button to remove all entities, the editor tried to clear the scene immediately — even if those entities were still being processed by a kernel or the render graph.

In other words, the engine was destroying entities while they were still in use. That’s why systems started complaining about missing entities and missing components.

The Solution: A Mini Garbage Collector

What I needed was a safe way to destroy entities. The fix was to implement a simple “garbage collector” for my ECS, with two phases:

• Mark Phase – Instead of destroying entities right away, I mark them as pendingDestroy.
• Sweep Phase – Once I know the command buffer has completed, I set a flag. In the next update() call, that flag triggers the sweep, where I finally destroy all entities that were marked.

This way, entity destruction only happens at a safe point in the loop, when nothing else is iterating over them.

Conclusion

What looked like a weird formatter bug turned out to be a timing bug in my engine. Immediate destruction was unsafe — the real fix was to defer destruction until the right time.

By adding a simple mark-and-sweep system, I now have a mini garbage collector for entities. It keeps the engine stable, avoids “entity does not exist” spam, and gives me confidence that clearing a scene won’t blow everything up mid-frame.

Thanks for reading.

Profiling with Xcode Instruments pointed the finger at Metal’s encoder preparation, which appeared to take ~15 ms. Based on that, my next move seemed obvious: switch to a bindless rendering.

What does that mean? Instead of rebinding textures and material properties for every draw call, I would move everything into a single argument buffer. Each draw would reference materials by index. In theory, this should drastically cut CPU overhead and pair nicely with GPU-driven culling.

But reality didn’t match theory. After spending days moving to a bindless model, I ran the engine with 500 models — and the performance needle didn’t budge. In fact, things got worse: encoder prep time increased from ~15 ms to ~17 ms.

You can imagine my disappointment. But I kept digging. And then I found the real bottleneck. Instruments showed the CPU was spending almost 9.5 ms just preparing data for GPU frustum culling.

So the encoder wasn’t the problem after all. As I dug into the code, I discovered the true culprit: a single function that queries all entities with specific component IDs.

Here’s what was happening:

👉 My component mask was stored as an array of 64 booleans. Every time I checked an entity, the code looped through all 64 slots, read from two arrays, and branched on each one. With 500 entities, that meant tens of thousands of tiny checks every single frame. No wonder the CPU was choking.

The fix? Replace the boolean array with a single 64-bit integer and use a bitwise AND. That collapses the entire check into just two instructions. Here’s the new function:

That one change dropped the CPU frame time from 26.7 ms down to 16.7 ms. The GPU frame time sits at 9.3 ms.

In other words, the engine now runs at a solid 60 fps.

I’m happy with the results: the engine is no longer CPU-bound or GPU-bound.

But I’m not done yet. The next step is implementing occlusion culling — and I’m excited to see how far I can push performance.

Thanks for reading.

At the moment, rendering around 214,000 vertices (500 models), the engine was only hitting 29.51 FPS. That’s rough for real-time rendering. Clearly, something needed fixing.

Profiling the Problem

I fired up Xcode’s GPU tools and the results were clear: the engine is CPU-bound.

• CPU Frame Time: ~33.9ms
• GPU Frame Time: ~8.1ms

So while the GPU was waiting around, the CPU was overloaded preparing work.

Looking deeper with Instruments, I found the major culprit: Metal Encoder Setup Time. The CPU was spending ~31ms every frame just encoding commands into the GPU.

Why So Slow?

The bottleneck came from the Shadow and Geometry passes. Each frame, the CPU had to prepare encoders and push all material data for every model—base color, roughness, metallic textures, etc. With hundreds of models, this ballooned into a huge overhead.

First Fix: GPU Frustum Culling

The engine didn’t have any form of culling, so I decided to implement Frustum Culling. To avoid piling more work on the CPU, I pushed this logic onto the GPU.

The approach:

• Construct the camera frustum.
• Compute each entity’s world-space AABB.
• Send bounding boxes to the GPU.
• GPU checks if each AABB is inside the frustum.
• If visible, the entity ID is written into an array via an atomic add.

The key here is that once the GPU returned the list of visible entities, the CPU only needed to encode draw calls for those entities—cutting encoder overhead. It’s a brute-force implementation, but it worked.

The Results

From the same view location,

• FPS jumped from 29 → 37.
• CPU Frame Time: 33.9ms → 26.7ms
• Metal Encoder Setup Time: 31.0ms → 14.6ms
• GPU Frame Time: 8.1ms (unchanged)

Summary

Here’s the before-and-after snapshot:

• FPS: 29 to 37 (+27% improvement)
• CPU Frame Time: 33.9 ms to 26.7 ms (Encoder bottleneck reduced)
• GPU Frame Time: 8.1 ms to 8.1 ms (Unchanged)
• Metal Encoder Setup Time: 31.0 ms to 14.6 ms (Biggest gain)

Where Things Stand

The engine is still CPU-bound, but it’s in a noticeably better state than it was a week ago. By filtering out invisible objects early, I reduced the CPU’s workload and freed up encoder time. It’s not at 60 FPS yet—but the path forward is clearer.

What’s Next

Frustum culling was just the first step. To keep pushing toward 60 FPS, here are the next optimization I plan to explore:

• Metal Bindless Rendering – Instead of rebinding textures and material properties for every draw, I’ll move to a bindless model. All materials will live in a single argument buffer, and each draw will reference them with a simple index. This should drastically cut down CPU encoder overhead and pair nicely with GPU-driven culling.

That’s where the engine stands today: better than last week, not yet where it needs to be. But the direction is clear, and each step forward is one step closer to real-time rendering.

Thanks for reading.

I decided to start with the Light Pass. For testing, I loaded a scene with around 214,000 vertices. Not a huge scene, but enough to get meaningful profiler data. After running the profiler, these were the numbers for the Light Pass:

• GPU Time: 2.53 ms
• ALU Limiter: 37.65%
• ALU Utilization: 35.77%
• Texture Read Limiter: 57.8%
• Texture Read Utilization: 26.83%
• MMU Limiter: 32.19%

The biggest limiter was Texture Read, at almost 58%. This means the GPU was spending a lot of time fetching data from textures—likely because they weren’t being cached efficiently. In hindsight, I should have started by tackling the biggest limiter. Instead, I first focused on improving the MMU. Not the best choice, but that’s how you learn.

MMU Limiter means your GPU performance is constrained by memory address lookups and fetches, not arithmetic.

Optimization 1: Buffer Pre-Loading

Buffer pre-loading combines related data into a single buffer so the GPU can fetch it more efficiently, instead of bouncing between multiple buffers. In my original shader, I was sending light data through separate buffers:

constant PointLightUniform *pointLights [[buffer(lightPassPointLightsIndex)]]

constant int *pointLightsCount [[buffer(lightPassPointLightsCountIndex)]]

I restructured this into a single struct that packages light data together. This change reduced the MMU Limiter from 32.19% → 26.43%.

Optimization 2: Use .read() Instead of .sample()

During the Light Pass, I fetch data from multiple G-buffer textures such as Position, Normal, Albedo, and SSAO. Originally, I used .sample(), but this does more work than necessary—it applies filtering and mipmap logic, which adds both memory traffic and math. Switching to .read() (a direct texel fetch) gave a noticeable improvement:

• Texture Read Limiter: 57.8% → 46.79%
• Texture Read Utilization: 26.83% → 30.03%

Optimization 3: Reduce G-Buffer Resolution

Next, I reduced the G-Buffer textures from float to half. I expected this to lower bandwidth usage, but to my surprise it made things worse:

• Texture Read Limiter: 46.79% → 56.9%
• Texture Read Utilization: 30.03% → 32.31%

Sometimes optimizations backfire, and this was one of those cases.

Optimization 4: Half-Precision Math in Lighting

I then focused on ALU utilization by switching parts of my lighting calculations to use half-precision (half) math. Specifically:

• Diffuse contribution → half precision
• Specular contribution → full precision (float)

The results were underwhelming:

• ALU Limiter: 37.65% → 37.55%
• ALU Utilization: 35.77% → 35.83%
• F32 Utilization: 27.86% → 25.12%
• F16 Utilization: 0% → 1.11%

Half-precision math showed up in the counters, but didn’t change the overall bottleneck.

Final Results

Here’s the overall improvement from all the optimizations:

Before → After

• GPU Time: 2.53 ms → 2.31 ms (~8.7% faster)
• Texture Read Limiter: 57.81% → 50.93%
• MMU Limiter: 32.19% → 23.41%
• ALU Limiter: 37.65% → 37.55% (flat)
• F32 Utilization: 27.86% → 25.12%
• F16 Utilization: 0.00% → 1.11%
• Integer & Complex Limiter: 14.25% → 8.82%
• Texture Read Utilization: 26.83% → 31.62%

What the Numbers Say

• I shaved about 9% off the Light Pass—a real improvement, but not dramatic.
• The biggest wins came from reducing memory-side pressure (MMU ↓, Texture Read Limiter ↓).
• ALU stayed flat, which shows the pass is still memory/texture-bound, not math-bound.
• Half-precision math registered, but didn’t help much since math wasn’t the bottleneck.
• Removing unnecessary integer/complex math improved things locally, but again, the frame was dominated by texture fetch bandwidth.

Takeaway

Optimizations don’t always yield big wins, but each attempt brings clarity. In this case, the profiler clearly shows that the Light Pass is memory/texture-bound. My next steps will focus directly on reducing texture fetch cost, rather than trimming ALU math.

Thanks for reading.

Permalink

]]>Optimizing My Engine’s Light Pass: Lessons from GPU ProfilingGame Engine DevelopmentHarold SerranoTue, 05 Aug 2025 06:16:32 +0000https://www.haroldserrano.com/blog/how-ssao-instantly-improved-my-engines-visuals54851541e4b0fb60932ad015:54851687e4b016eb8428ff4b:6891a118016d5d300e5a0c33In this video, you’ll see:

• Before/after comparisons of SSAO in action
• A quick explanation of how SSAO works
• Why it’s worth adding to your renderer
• How I integrated it into my lighting pipeline

If you're building your own engine or renderer, or just want to level up your graphics knowledge, this one's for you.

Enjoy.

Through sheer work and pushing myself everyday, I have managed to add several features to the renderer such as:

• Multiple light types: Spot and Area lights
• Gizmo tools to translate, rotate and scale
• Post-processing shaders such as: Depth of field, Chromatic Aberration, Bloom, Color Grading, White Balance, Vignette effects.
• Gizmo tools to manipulate light meshes
• Improved Editor's user experience

Overall, the renderer feels more complete. While setting up your scene, you can manipulate the position, orientation and scale of each model through the use Gizmo tools. If curious, you can get a quick look at the different PBR textures attached to your model, and if desired, you can update them as well.
If desired, you can add any of the four types of lights into your scene: Directional, Point, Spot and Area light. And you can modify their direction by simply dragging the gizmo tool.

Once your scene is ready, you can add several Post-processing effects as mentioned above. Each effect's properties can be manipulated through the editor and you get visual feedback of the effect.

I feel very proud of the stage of the renderer. I fixed several bugs in the renderer and while fixing each bug; I learned a lot more than I expected. However, working on the renderer daily was hard. Between my full-time job and my beautiful family, I was able to spare an hour or so on the renderer. Every day, I had to force myself to wake up before my kids did, so I can focus on getting some work done, even when my energy level was close to zero. Somehow, I managed to get the renderer to its current state, and it is something I feel proud of.

There are several issues with the Renderer and that is OK, because everyday I wake up with the idea that I will make the engine a bit better than it was the day before, and I'm convinced that this mindset will take the engine to the next level.

Building the editor was one of the hardest parts of this journey. From the Scenegraph to the Inspector, the Asset Browser to mouse selection (Ray Picker) — every system needed to work together seamlessly. There were moments when I seriously considered scrapping the editor entirely. But deep down, I knew that if I wanted my engine to be flexible and developer-friendly, this feature had to exist.

In this devlog, I walk through the emotional build-up leading to the moment of truth: hitting Play and seeing if everything works. This test isn’t just about a feature — it’s about proving that the foundation I’ve been building can support the kind of dynamic, user-driven workflows I wanted. It's a small feature, but a huge step for my engine.

No more hacking things in through code—everything can be controlled visually. I’ll show you the problems I ran into, how I solved them, and what the engine looks like now in action.

This update brings the editor one step closer to becoming a fully usable game creation tool—and I’d love to hear your thoughts on where to take it next.

Thanks for watching.

Thanks for watching.

Enjoy