Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(render): an overlay camera composites over the camera beneath

yhhf69ee378ebd4
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48085631c..bf3c4e1d8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,8 @@ published separately; it ships inside the editor.
### Fixed
+- **A first-person view model no longer hides the world in a linear or tone-mapped project.** A camera that keeps the colour under it (clears depth only, as the held-gun camera of `FirstPersonViewModel` does) still draws through a capture of its own when the frame is linear or has an output transform; that capture started black and was copied over the camera beneath, so the world went black around the gun. It is now laid over by coverage. Gate: overlay-camera-linear.
+- **Post-process volumes skip a camera that draws over another one.** Such a camera was given the scene's global stack too, which ran fog, sky and the look over the whole finished picture again with its own cleared depth — the world under a held gun went to fog. Local volumes now also weigh a camera by where it is in the world, not by its position under its parent.
- **The editor's MCP server starts its editor again after the editor goes away.** When a call found the editor unreachable before the editor's exit was seen, every later call in the session failed at once with "the editor host is not running" and no editor was started.
- **A scene whose only 3D physics is a compound collider or a ragdoll gets a physics world.** The scene loader did not count `CompoundCollider3D` or `Ragdoll` as 3D physics, so a scene with nothing else ran with neither moving.
- **Geometry with no lightmap UV set still stands in a bake's light.** It was left out of the bake altogether, so it cast no shadow on the baked surfaces and the probes saw straight through it. It now shadows them and hides the sky from the probes, while receiving no baked light itself (the import still says to generate lightmap UVs for that).
diff --git a/fixtures/scenes/overlay-camera-linear.esscene b/fixtures/scenes/overlay-camera-linear.esscene
new file mode 100644
index 000000000..cd1008865
--- /dev/null
+++ b/fixtures/scenes/overlay-camera-linear.esscene
@@ -0,0 +1,136 @@
+{
+ "version": 4,
+ "name": "Overlay camera over a linear frame",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0,
+ "cullingMask": 4293918719
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "MidGray",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 300,
+ "y": 300
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "texture": "@uuid:5d6b1a2e-90c4-4f7a-8b3d-2f81c0a4e5f6"
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 2,
+ "name": "OverlayCamera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 1,
+ "clearFlags": 2,
+ "cullingMask": 1048576
+ }
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Held",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -220,
+ "y": 0,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "size": {
+ "x": 100,
+ "y": 100
+ },
+ "color": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "layer": 20,
+ "texture": "@uuid:5d6b1a2e-90c4-4f7a-8b3d-2f81c0a4e5f6"
+ }
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/overlay-camera-linear.textures.json b/fixtures/scenes/overlay-camera-linear.textures.json
new file mode 100644
index 000000000..f0adc78c2
--- /dev/null
+++ b/fixtures/scenes/overlay-camera-linear.textures.json
@@ -0,0 +1,3 @@
+{
+ "5d6b1a2e-90c4-4f7a-8b3d-2f81c0a4e5f6": "/scenes/srgb-midtone.png"
+}
diff --git a/sdk/src/postprocess/volumeSystem.ts b/sdk/src/postprocess/volumeSystem.ts
index 364a7a550..1240d44fe 100644
--- a/sdk/src/postprocess/volumeSystem.ts
+++ b/sdk/src/postprocess/volumeSystem.ts
@@ -7,7 +7,7 @@ import { EDITOR_VIEW_ENTITY } from '../camera/uiLayoutRect';
import { defineResource, Res } from '../ecs/resource';
import { Query } from '../ecs/query';
import type { Entity } from '../types';
-import { PostProcessVolume, Transform, Camera, ProjectionType, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';
+import { PostProcessVolume, Transform, Camera, ProjectionType, ClearFlags, type PostProcessVolumeData, type TransformData, type CameraData } from '../ecs/component';
import { PostProcess, deviceHasCompute, type PostProcessAPI } from './PostProcessAPI';
import { getEffectDef } from './effects';
import { blendVolumeEffects, computeVolumeFactor, type ActiveVolume, type BlendedEffect, type VolumeTransform } from './volumeBlending';
@@ -195,6 +195,15 @@ export function withTemporalAntialiasing(api: PostProcessAPI, effects: ResolvedE
return out;
}
+/** Let a camera's volume stack go, when it has one. */
+function releaseStack(api: PostProcessAPI, camera: Entity): void {
+ const existing = api.volumeStacks.get(camera);
+ if (!existing) return;
+ api.unbind(camera);
+ existing.destroy();
+ api.volumeStacks.delete(camera);
+}
+
function applyBlendedEffects(
api: PostProcessAPI,
camera: Entity,
@@ -363,7 +372,15 @@ export const postProcessVolumeSystem = defineSystem(
let first = true;
for (const [cameraEntity, cameraData, cameraTransform] of cameraQuery) {
if (!cameraData.isActive) continue;
- const p = cameraTransform.position;
+ // A camera that keeps the colour under it (a first-person view model's, any overlay) draws over another camera's
+ // finished image. A stack of its own would run fog, sky and the look over that whole image again, with this camera's
+ // cleared depth reading as "infinitely far": the world under a held gun went to fog and sky.
+ if (cameraData.clearFlags === ClearFlags.Depth || cameraData.clearFlags === ClearFlags.Nothing) {
+ releaseStack(api, cameraEntity);
+ continue;
+ }
+ // Where the camera IS: a camera under a player has a local position near zero.
+ const p = cameraTransform.worldPosition ?? cameraTransform.position;
const effects = effectsAt(volumes, p.x, p.y, p.z);
// The scene has one environment: the first camera's sky lights it.
if (first) { skies.game = lightingSky(effects); first = false; }
diff --git a/sdk/tests/volume-overlay-camera.test.ts b/sdk/tests/volume-overlay-camera.test.ts
new file mode 100644
index 000000000..66d113aa3
--- /dev/null
+++ b/sdk/tests/volume-overlay-camera.test.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Which cameras a post-process volume gives a stack to.
+ *
+ * A first-person view model is a second camera that clears depth only and draws the held gun over the world's finished
+ * image. Given the scene's global stack too, it ran height fog and sky over that whole image with its own cleared depth
+ * reading as infinitely far, and the world under the gun was painted out (Saltline, 2026-11-11). And a camera under a
+ * player was placed at its LOCAL position, near the origin, for the weight of a local volume.
+ */
+import { describe, it, expect } from 'vitest';
+import { postProcessVolumeSystem } from '../src/postprocess/volumeSystem';
+import type { Entity } from '../src/types';
+
+/** A stack that takes every call, and an API that records which camera holds one. */
+function fakeApi() {
+ const anyCall: ProxyHandler<object> = { get: (_t, key) => (key === 'then' ? undefined : () => undefined) };
+ const bound = new Set<number>();
+ const base = {
+ volumeStacks: new Map<Entity, unknown>(),
+ // Every effect's shader already made: the test is about which camera gets a stack, not about compiling one.
+ volumeShaders: { get: () => 1, set: () => undefined },
+ // A stack that reports a pass, as one built from the volume's effects would.
+ createStack: () => new Proxy({ destroy: () => undefined, enabledPassCount: 1, displayLut: { amount: 0 } },
+ { get: (t, key) => (key in t ? (t as Record<string | symbol, unknown>)[key] : anyCall.get!(t, key, t)) }),
+ bind: (camera: Entity) => { bound.add(camera as number); },
+ unbind: (camera: Entity) => { bound.delete(camera as number); },
+ };
+ const api = new Proxy(base, { get: (t, key) => (key in t ? (t as Record<string | symbol, unknown>)[key] : undefined) });
+ return { api, bound };
+}
+
+const at = (x: number, y: number, z: number, world?: { x: number; y: number; z: number }) => ({
+ position: { x, y, z }, worldPosition: world ?? { x, y, z },
+});
+const camera = (clearFlags: number) => ({ isActive: true, clearFlags, projectionType: 0 });
+const vignette = { type: 'vignette', enabled: true, uniforms: { u_intensity: 0.4, u_softness: 0.5 } };
+
+const run = (api: unknown, volumes: unknown[], cameras: unknown[]) =>
+ (postProcessVolumeSystem as unknown as { _fn: (...a: unknown[]) => void })._fn(api, volumes, cameras);
+
+describe('which cameras a volume gives a stack to', () => {
+ it('gives none to a camera that draws over another camera (clears depth only, or nothing)', () => {
+ const { api, bound } = fakeApi();
+ const volume = [1, { isGlobal: true, priority: 0, weight: 1, effects: [vignette] }, at(0, 0, 0)];
+ run(api, [volume], [[10, camera(3), at(0, 1, 0)], [11, camera(2), at(0, 1, 0)], [12, camera(0), at(0, 1, 0)]]);
+ expect([...bound]).toEqual([10]);
+ });
+
+ it('lets go of a stack a camera held before it became an overlay', () => {
+ const { api, bound } = fakeApi();
+ const volume = [1, { isGlobal: true, priority: 0, weight: 1, effects: [vignette] }, at(0, 0, 0)];
+ run(api, [volume], [[11, camera(3), at(0, 1, 0)]]);
+ expect(bound.has(11)).toBe(true);
+ run(api, [volume], [[11, camera(2), at(0, 1, 0)]]);
+ expect(bound.has(11)).toBe(false);
+ });
+
+ it('weighs a local volume where a child camera is in the world, not at its local position', () => {
+ const { api, bound } = fakeApi();
+ const local = [1, { isGlobal: false, shape: 0, size: { x: 4, y: 4, z: 4 }, blendDistance: 0, priority: 0, weight: 1, effects: [vignette] }, at(50, 0, 0)];
+ // An eye 0.7 above its player, the player standing inside the volume at x = 50.
+ run(api, [local], [[10, camera(3), at(0, 0.7, 0, { x: 50, y: 0.7, z: 0 })]]);
+ expect(bound.has(10)).toBe(true);
+ });
+});
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index eb3a07a9b..a9c2b2fdf 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -713,13 +713,16 @@ void PostProcessPipeline::drawScreenQuad() {
device_.drawArrays(0, 3);
}
-void PostProcessPipeline::applyPassPipeline(const Shader& shader) {
+void PostProcessPipeline::applyPassPipeline(const Shader& shader, bool over) {
ensureScreenQuad();
- // Fullscreen passes overwrite every pixel: no blend, no depth, no stencil.
+ // Fullscreen passes overwrite every pixel: no blend, no depth, no stencil. The one exception is the present of a
+ // camera that keeps the colour under it, which lays its picture over by coverage. The capture was cleared to
+ // transparent, so its colour is already weighted by its alpha (a resolve averages both): premultiplied.
PipelineDesc desc{};
desc.program = shader.handle();
desc.vertexLayout = screen_quad_layout_;
- desc.blendEnabled = false;
+ desc.blendEnabled = over;
+ if (over) desc.blend = BlendMode::PremultipliedAlpha;
desc.depthTest = false;
desc.depthWrite = false;
device_.setPipeline(device_.createPipeline(desc));
@@ -805,6 +808,7 @@ void PostProcessPipeline::chainDone() {
device_.invalidatePipelineCache();
inFrame_ = false;
output_target_fbo_ = FramebufferHandle::Default;
+ present_over_ = false;
// Per-frame, like the target above: a camera that asked for a present must not
// leave the next one engaged for a frame it never asked about.
present_required_ = false;
@@ -1116,7 +1120,7 @@ void PostProcessPipeline::blitPass() {
device_.setViewport(output_vp_x_, output_vp_y_, output_vp_w_, output_vp_h_);
}
- applyPassPipeline(*shader);
+ applyPassPipeline(*shader, present_over_);
if (shader->hasUniform("u_texture")) shader->setUniform("u_texture", 0);
shader->commitParams();
bindBlitInputs(outputHandle);
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index d5700040e..ef3950de3 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -428,6 +428,16 @@ public:
void setComputeNeedsDepth(bool needs) { compute_needs_depth_ = needs; }
void setPresentRequired(bool required) { present_required_ = required; }
+ /**
+ * @brief This camera keeps the colour under it: its present composites over the target by coverage.
+ *
+ * @details A camera that does not clear colour (a first-person view model, any overlay) still goes through a capture when
+ * the frame is linear or has an output transform, and the capture starts empty. Copied over the target as it
+ * was, it replaced the camera underneath with black. Set by the frame when it opens such a camera's pass (its
+ * capture is then cleared to transparent); cleared when the camera's chain is done.
+ */
+ void setPresentOver(bool over) { present_over_ = over; }
+
/**
* @brief Whether the present is a whole-multiple upscale of the chain.
*
@@ -594,7 +604,8 @@ private:
void ensureGraph();
void ensureScreenQuad();
void drawScreenQuad();
- void applyPassPipeline(const Shader& shader);
+ /// @p over: composite onto the target by the source's coverage (premultiplied) instead of replacing it.
+ void applyPassPipeline(const Shader& shader, bool over = false);
void renderPass(PostProcessPass& pass, const rg::PassContext& ctx);
/// A compute pass: its params and the size into a block each, the picture, the depth and the output bound, one dispatch over it.
void computePass(PostProcessPass& pass, const rg::PassContext& ctx);
@@ -679,6 +690,7 @@ private:
u32 output_vp_x_ = 0;
u32 output_vp_y_ = 0;
bool present_required_ = false;
+ bool present_over_ = false;
bool compute_needs_depth_ = false;
u32 output_vp_w_ = 0;
u32 output_vp_h_ = 0;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index c999a7f9e..ea47f3466 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -516,6 +516,13 @@ void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle t
if (usePostProcess && post_process_->sceneCoverageWanted()) {
for (f32& channel : pass.clearColorValue) channel = 0.0f;
}
+ // A camera that keeps the colour under it still draws into a capture of its own when the frame is linear or has an
+ // output transform. The capture starts transparent and the present lays it over the camera beneath by coverage, rather
+ // than replacing that camera's picture with black around a held gun.
+ if (usePostProcess && !clear.color) {
+ for (f32& channel : pass.clearColorValue) channel = 0.0f;
+ post_process_->setPresentOver(true);
+ }
#endif
pass.clearX = clear.x;
pass.clearY = clear.y;
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 5181e89c5..dcebf9bb1 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -594,6 +594,10 @@ export const SCENES = [
// 0.3242, the OETF encodes that to 154. Applied ONCE — twice would read 182,
// and linear-midtone beside this one reads 128 with no transform at all.
{ id: "output-aces-linear", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/srgb-midtone.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/srgb-midtone.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_OUTPUT_TRANSFORM: "aces", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[154,154,154],\"tol\":4}]" } },
+ // A second camera that clears depth only, over a linear frame: how every first-person view model is drawn. A linear frame
+ // sends each camera through a capture of its own, and the overlay's started black and was copied over the first camera's
+ // picture whole — the grey in the middle read 0 and only the held red square was left. Composited by coverage, both stay.
+ { id: "overlay-camera-linear", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/overlay-camera-linear.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/overlay-camera-linear.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[128,128,128],\"tol\":8},{\"x\":0.133,\"y\":0.5,\"rgb\":[128,0,0],\"tol\":12},{\"x\":0.85,\"y\":0.15,\"rgb\":[0,0,0],\"tol\":10}]" } },
// Post-process chain guards — bloom's first CI pixel coverage. The gamma scene pins the LDR multi-pass chain; the linear scene is the HDR discriminator: threshold 1.5 sits above anything an 8-bit chain can store, so glow OUTSIDE the sprite (x=0.64) proves over-range light survived the float intermediates — the same scene blooms NOTHING in gamma mode.
{ id: "bloom-ldr", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/bloom-ldr.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/bloom-ldr.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "10", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.61,\"y\":0.5,\"rgb\":[0,130,0],\"tol\":35},{\"x\":0.70,\"y\":0.5,\"rgb\":[0,32,0],\"tol\":25},{\"x\":0.85,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":12}]" } },
{ id: "hdr-bloom", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_COLORSPACE: "linear", ESTELLA_VERIFY_SCENE: "/scenes/hdr-bloom.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/hdr-bloom.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "10", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":25},{\"x\":0.64,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":35},{\"x\":0.85,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":12}]" } },