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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): an environment can be seen, not only reflected
esengine439afa91a358
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dea98e92c..2dc00af70 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,26 @@ published separately; it ships inside the editor.## [Unreleased]+### Added++- **An environment can be seen, not only reflected.** A baked `.esenv` gave a+ scene its irradiance and a prefiltered reflection, so a metal ball had a sky in+ it — and behind the ball was a flat clear colour. The same panorama was half+ visible and half not, for no reason anyone chose.++ `Light2D.drawEnvironment` draws it as the background: a quad on the far plane,+ shaded by the direction from the eye through each pixel, which is the direction+ the reflection already samples. Off by default, so a scene that adopts an+ environment for its lighting does not also acquire a sky it did not ask for; and+ only where there is a prefiltered reflection to look at, since the nine+ irradiance coefficients are that sky averaged over every direction — as a+ background, one flat colour.++ It is not a renderable: a sky belongs to no transform, is culled by nothing, and+ sorts first by being in the Background stage. Its own vertex stream, because the+ Batch one spends every sampler slot on a per-vertex merge and the sky has to+ reach the environment atlas on the unit the shaders pin it to.+### Fixed- **Whether a surface has normals no longer decides where its light is.** Twodiff --git a/desktop/public/scenes/mesh-sky.esscene b/desktop/public/scenes/mesh-sky.esscenenew file mode 100644index 000000000..bc276336c--- /dev/null+++ b/desktop/public/scenes/mesh-sky.esscene@@ -0,0 +1,70 @@+{+ "version": 1,+ "name": "MeshSky",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 0,+ "fov": 90,+ "nearPlane": 1,+ "farPlane": 1000,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Sky",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Light2D",+ "data": {+ "type": 2,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "intensity": 1,+ "environment": "/scenes/studio.esenv",+ "drawEnvironment": true+ }+ }+ ]+ }+ ]+}diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 6d6ce3e0c..60273d86a 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1634,6 +1634,12 @@"default": "none","doc": "Baked environment (.esenv) this Ambient light casts."},+ {+ "key": "drawEnvironment",+ "type": "boolean",+ "default": "false",+ "doc": "Draw this environment as the sky behind the scene."+ },{"key": "enabled","type": "boolean",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 217f49dd8..71bb89bd3 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1458 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"ea9373ff870f868a"+"9169449040ae1dcb"```## ANCHOR_AXES — const @experimental@@ -3982,6 +3982,7 @@ BuiltinComponentDef<Light2DData>color: Colordirection: Vec2directionZ: number+drawEnvironment: booleanenabled: booleanenvironment: numberinnerAngle: numberdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 0a8e2f1fc..173a16eea 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1477 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"ea9373ff870f868a"+"9169449040ae1dcb"```## ANCHOR_AXES — const @experimental@@ -3990,6 +3990,7 @@ BuiltinComponentDef<Light2DData>color: Colordirection: Vec2directionZ: number+drawEnvironment: booleanenabled: booleanenvironment: numberinnerAngle: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ec72669f3..403d4cd74 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -3977,6 +3977,7 @@ BuiltinComponentDef<Light2DData>color: Colordirection: Vec2directionZ: number+drawEnvironment: booleanenabled: booleanenvironment: numberinnerAngle: numberdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 7a3e3d3d2..51f981f36 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -3977,6 +3977,7 @@ BuiltinComponentDef<Light2DData>color: Colordirection: Vec2directionZ: number+drawEnvironment: booleanenabled: booleanenvironment: numberinnerAngle: numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex b0850d1fe..7ce7fb711 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -3984,6 +3984,7 @@ BuiltinComponentDef<Light2DData>color: Colordirection: Vec2directionZ: number+drawEnvironment: booleanenabled: booleanenvironment: numberinnerAngle: numberdiff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex 98a5a7fb2..b0eaa70a3 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -699,6 +699,7 @@ export interface Light2DPtrData {meshShadows: boolean;shadowExtent: number;environment: number;+ drawEnvironment: boolean;enabled: boolean;}@@ -719,7 +720,8 @@ export function fillLight2D(out.meshShadows = u8[ptr + 56] !== 0;out.shadowExtent = f32[(ptr + 60) >> 2];out.environment = u32[(ptr + 64) >> 2];- out.enabled = u8[ptr + 68] !== 0;+ out.drawEnvironment = u8[ptr + 68] !== 0;+ out.enabled = u8[ptr + 69] !== 0;}export function writeLight2D(@@ -739,7 +741,8 @@ export function writeLight2D(u8[ptr + 56] = data.meshShadows ? 1 : 0;f32[(ptr + 60) >> 2] = data.shadowExtent;u32[(ptr + 64) >> 2] = data.environment;- u8[ptr + 68] = data.enabled ? 1 : 0;+ u8[ptr + 68] = data.drawEnvironment ? 1 : 0;+ u8[ptr + 69] = data.enabled ? 1 : 0;}export function createLight2DData(): Light2DPtrData {@@ -757,6 +760,7 @@ export function createLight2DData(): Light2DPtrData {meshShadows: false,shadowExtent: 0,environment: 0,+ drawEnvironment: false,enabled: false,};}diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 0dd9f5835..23de78fd1 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = 'ea9373ff870f868a';+export const ABI_LAYOUT_HASH = '9169449040ae1dcb';/*** One asset-valued field of a component: which field, and what kind of@@ -401,6 +401,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {meshShadows: false,shadowExtent: 0,environment: 0,+ drawEnvironment: false,enabled: true,},renderableField: 'enabled',@@ -421,6 +422,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional)." },shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true },environment: { tooltip: "Baked environment (.esenv) this Ambient light casts." },+ drawEnvironment: { tooltip: "Draw this environment as the sky behind the scene." },},},Mesh2D: {@@ -1213,6 +1215,7 @@ export interface Light2DData {meshShadows: boolean;shadowExtent: number;environment: number;+ drawEnvironment: boolean;enabled: boolean;}diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 465f7e270..96b599ba5 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -212,7 +212,8 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'meshShadows', type: 'bool', offset: 56 },{ name: 'shadowExtent', type: 'f32', offset: 60 },{ name: 'environment', type: 'u32', offset: 64 },- { name: 'enabled', type: 'bool', offset: 68 },+ { name: 'drawEnvironment', type: 'bool', offset: 68 },+ { name: 'enabled', type: 'bool', offset: 69 },],},Mesh2D: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex 381c2df12..df092dfb5 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -384,6 +384,7 @@ export interface Light2D {meshShadows: boolean;shadowExtent: number;environment: number;+ drawEnvironment: boolean;enabled: boolean;}diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 718919a5f..c7af766c9 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash 5c60fe026ad2d679+ * @schema_hash 77c5905fcad9c63e*/-#define ES_EDITOR_API_SCHEMA_HASH "5c60fe026ad2d679"+#define ES_EDITOR_API_SCHEMA_HASH "77c5905fcad9c63e"#include <emscripten/bind.h>#include <string>@@ -303,6 +303,7 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"meshShadows","type":"bool","group":"Light2D"},{"key":"shadowExtent","type":"float","group":"Light2D"},{"key":"environment","type":"asset","group":"Light2D"},+ {"key":"drawEnvironment","type":"bool","group":"Light2D"},{"key":"enabled","type":"bool","group":"Light2D"}])JSON";} else if (name == "Mesh2D") {@@ -2369,6 +2370,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::stif (!reg.has<esengine::ecs::Light2D>(entity)) return false;auto& c = reg.get<esengine::ecs::Light2D>(entity);if (field == "meshShadows") { c.meshShadows = value; }+ else if (field == "drawEnvironment") { c.drawEnvironment = value; }else if (field == "enabled") { c.enabled = value; }else { return false; }return true;@@ -2580,6 +2582,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::stif (!reg.has<esengine::ecs::Light2D>(entity)) return false;const auto& c = reg.get<esengine::ecs::Light2D>(entity);if (field == "meshShadows") { return c.meshShadows; }+ else if (field == "drawEnvironment") { return c.drawEnvironment; }else if (field == "enabled") { return c.enabled; }} else if (comp == "Mesh2D") {if (!reg.has<esengine::ecs::Mesh2D>(entity)) return false;diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 0a586d7bb..ce2c45cfc 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -485,6 +485,7 @@ struct Light2DJS {bool meshShadows;f32 shadowExtent;u32 environment;+ bool drawEnvironment;bool enabled;};@@ -502,6 +503,7 @@ void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {c.meshShadows = js.meshShadows;c.shadowExtent = js.shadowExtent;c.environment = resource::EnvironmentHandle(js.environment);+ c.drawEnvironment = js.drawEnvironment;c.enabled = js.enabled;}@@ -526,6 +528,7 @@ Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {js.meshShadows = c.meshShadows;js.shadowExtent = c.shadowExtent;js.environment = c.environment.id();+ js.drawEnvironment = c.drawEnvironment;js.enabled = c.enabled;return js;}@@ -1446,6 +1449,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("meshShadows", &Light2DJS::meshShadows).field("shadowExtent", &Light2DJS::shadowExtent).field("environment", &Light2DJS::environment)+ .field("drawEnvironment", &Light2DJS::drawEnvironment).field("enabled", &Light2DJS::enabled);value_object<Mesh2DJS>("Mesh2D")@@ -2791,7 +2795,8 @@ static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 52, "ABI offsestatic_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 56, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 56)");static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 60, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 60)");static_assert(offsetof(esengine::ecs::Light2D, environment) == 64, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 64)");-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 68, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 68)");+static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 68, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 68)");+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 69, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 69)");static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");@@ -3024,7 +3029,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "ea9373ff870f868a";+static const char* kEsAbiLayoutHash = "9169449040ae1dcb";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/data/shaders/sky.esshader b/src/esengine/data/shaders/sky.esshadernew file mode 100644index 000000000..d05186546--- /dev/null+++ b/src/esengine/data/shaders/sky.esshader@@ -0,0 +1,75 @@+#pragma shader "Sky"+#pragma version 300 es+#pragma domain Lit2D++// The background half of an environment. The reflection in a metal ball and the+// sky behind it are the same baked panorama; without this only one of them was+// ever visible, and a scene lit by a sky sat in front of a flat clear colour.+//+// Geometry is a quad on the far plane, so the vertex stage needs no matrix of its+// own — the fragment's direction is the one from the eye through it, which is+// what viewDirection() already answers (negated: it points AT the viewer).++#pragma vertex+layout(location = 0) in vec3 a_position;++out highp vec3 v_worldPos;++void main() {+ gl_Position = u_projection * vec4(a_position, 1.0);+ v_worldPos = a_position;+}+#pragma end++#pragma fragment+precision highp float;++in highp vec3 v_worldPos;+out vec4 fragColor;++void main() {+ // Mip 0: the sharpest level of the prefiltered atlas is the sky as it was+ // photographed. The rougher ones exist to be reflected, not to be looked at.+ fragColor = vec4(envSampleMip(-viewDirection(v_worldPos), 0.0), 1.0);+}+#pragma end++#pragma vertex wgsl+struct VSIn {+ @location(0) a_position : vec3f,+};+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_worldPos : vec3f,+};++@vertex fn vs_main(v : VSIn) -> VSOut {+ var out : VSOut;+ out.pos = frame.projection * vec4f(v.a_position, 1.0);+ out.v_worldPos = v.a_position;+ return out;+}+#pragma end++#pragma fragment wgsl+// Slot 0 is bound and never read — a draw fills it so the walk that pins the+// atlas one slot on has somewhere to start. The atlas itself is on 3, and+// without these two the injected sampler names identifiers this twin never+// declared: an invalid pipeline that does not mention a shader.+@group(1) @binding(0) var t0 : texture_2d<f32>;+@group(1) @binding(8) var s0 : sampler;+@group(1) @binding(3) var t3 : texture_2d<f32>;+@group(1) @binding(11) var s3 : sampler;++// Declared again: each WGSL block is compiled on its own, so a struct defined in+// the vertex one is an undeclared name here — and that reaches anyone as an+// invalid pipeline with nothing in the log about a shader.+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_worldPos : vec3f,+};++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ return vec4f(envSampleMip(-viewDirection(v.v_worldPos), 0.0), 1.0);+}+#pragma enddiff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hppindex 99c23a3e4..b6960ee9b 100644--- a/src/esengine/ecs/components/Light2D.hpp+++ b/src/esengine/ecs/components/Light2D.hpp@@ -119,6 +119,13 @@ struct Light2D {ES_PROPERTY(asset = environment, tooltip="Baked environment (.esenv) this Ambient light casts.")resource::EnvironmentHandle environment;+ /** @brief Draw @ref environment as the background as well as reflecting it. Off by+ * default, so a scene that adopts an environment for its lighting does not+ * also acquire a sky it did not ask for. Ignored without one — and the+ * camera still decides whether the background is drawn at all. */+ ES_PROPERTY(tooltip="Draw this environment as the sky behind the scene.")+ bool drawEnvironment{false};+/** @brief Disabled lights are skipped during collection. */ES_PROPERTY()bool enabled{true};diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 216ee70bf..1eb94ec09 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -4,6 +4,7 @@#include "../rhi/Shader.hpp"#include "../rhi/ShaderEmbeds.generated.hpp"#include "../store/LightStore.hpp"+#include "../draw/BatchBuilder.hpp"#include "../../ecs/components/Transform.hpp"#include "../../ecs/components/Light2D.hpp"#include "../../ecs/components/ShadowCaster2D.hpp"@@ -17,6 +18,7 @@#include <algorithm>#include <cmath>+#include <limits>#include <vector>namespace esengine {@@ -649,6 +651,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {lights.clear();shadow_light_slot_ = -1;environment_texture_id_ = 0;+ draw_sky_ = false;// Gather non-ambient lights, then (if over the UBO's cap) keep the most intense — the// brightest contribute most, and an explicit importance cull beats silently dropping@@ -768,6 +771,9 @@ bool RenderFrame::collectEnvironment(const ecs::Light2D& light, const glm::vec3&return false;}environment_texture_id_ = textureId;+ // Only a reflection can be looked at directly: the nine coefficients are the+ // sky averaged over every direction, which as a background is one flat colour.+ draw_sky_ = light.drawEnvironment && textureId != 0;return true;}@@ -1011,6 +1017,58 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {device_.setViewport(sceneViewport.x, sceneViewport.y, sceneViewport.w, sceneViewport.h);}+/**+ * The background an environment is, as a quad on the far plane. Not a plugin and+ * not an entity: a sky belongs to no transform and is culled by nothing. Its+ * corners are the far plane's, unprojected, so a fragment's direction is the one+ * from the eye through it — which viewDirection() already answers.+ */+void RenderFrame::collectSky(RenderCollectContext& ctx) {+ if (!draw_sky_ || environment_texture_id_ == 0) return;+ if (!sky_compiled_) {+ sky_compiled_ = true;+ auto parsed = resource::ShaderParser::parse(ShaderEmbeds::SKY);+ const auto target = resource_manager_.preferredShaderTarget();+ const std::vector<std::string> features{"ES_ENV_MAP"};+ resource::ShaderHandle handle = resource_manager_.createShaderWithBindings(+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Vertex, "",+ features, target),+ resource::ShaderParser::assembleStage(parsed, resource::ShaderStage::Fragment, "",+ features, target),+ {}, resource_manager_.preferredShaderLanguage());+ if (auto* shader = resource_manager_.getShader(handle)) sky_program_ = shader->getProgramId();+ }+ if (sky_program_ == 0) return;++ // The far plane's four corners in world space. Clip z = 1 is that plane under+ // both backends' shared projection, and w divides out whichever it is.+ const glm::mat4 invVP = glm::inverse(ctx.frame_context.view_projection);+ glm::vec3 corners[4];+ const glm::vec2 ndc[4] = {{-1.0f, -1.0f}, {1.0f, -1.0f}, {1.0f, 1.0f}, {-1.0f, 1.0f}};+ for (u32 i = 0; i < 4; ++i) {+ const glm::vec4 p = invVP * glm::vec4(ndc[i], 1.0f, 1.0f);+ corners[i] = glm::vec3(p) / p.w;+ }++ BatchDrawKey key{};+ key.stage = RenderStage::Background;+ key.layer = std::numeric_limits<i32>::min();+ key.shaderId = sky_program_;+ key.blend = BlendMode::None;+ key.layoutId = LayoutId::Sky;+ // Slot 0 is filled with white and never sampled: the atlas rides the unit the+ // shaders pin it to, and the fill is what the slot walk below it expects.+ key.textureId = ctx.frame_context.white_texture_id;+ key.envTextureId = environment_texture_id_;+ key.type = RenderType::Mesh;+ // Neither tested nor written: the sky is behind everything by being first, and+ // depth of its own would fight the geometry that draws over it.+ key.depthTest = false;+ key.depthWrite = false;+ appendIndexedDraw(ctx.buffer_pool, ctx.draw_list, ctx.clip_state, corners, 4,+ BATCH_QUAD_INDICES, 6, key);+}+void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {ES_PROFILE_SCOPE("render.collect");buildClipState();@@ -1021,6 +1079,7 @@ void RenderFrame::collectAll(ecs::Registry& registry, u32 skipFlags) {RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_, ctx,computeCameraWorldRect(ctx.view_projection)};+ collectSky(collectCtx);for (auto& plugin : plugins_) {if (skipFlags != 0 && (skipFlags & plugin->skipFlag()) != 0) continue;plugin->collect(collectCtx);diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 1090ddebc..d8fe03fc8 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -336,6 +336,13 @@ private:u32 shadow_texture_id_ = 0;/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.u32 environment_texture_id_ = 0;+ /// Whether that environment is also the background this frame.+ bool draw_sky_ = false;+ /// The far-plane quad's program, compiled on first use.+ u32 sky_program_ = 0;+ bool sky_compiled_ = false;+ /// Emits the background quad when an environment asked to be seen behind the scene.+ void collectSky(RenderCollectContext& ctx);// processMasks scratch, reused across cameras/frames.std::vector<Entity> mask_scissor_scratch_;diff --git a/src/esengine/renderer/rhi/GfxEnums.hpp b/src/esengine/renderer/rhi/GfxEnums.hppindex e5cae28ac..f819188a2 100644--- a/src/esengine/renderer/rhi/GfxEnums.hpp+++ b/src/esengine/renderer/rhi/GfxEnums.hpp@@ -85,9 +85,13 @@ enum class LayoutId : u8 {/// pool's; the layout belongs to the mesh, which is the one that knows what/// its own vertices look like.MeshInstance = 3,+ /// The background quad: a world position and nothing else. Its own stream+ /// because the Batch one spends every sampler slot on a per-vertex merge, and+ /// the sky has to reach the environment atlas on the slot the shaders pin it to.+ Sky = 4,};-static constexpr u32 LAYOUT_COUNT = 4;+static constexpr u32 LAYOUT_COUNT = 5;/// One per-object record for a resident mesh: a model matrix and a tint.static constexpr u32 MESH_INSTANCE_STRIDE = 68;diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex 2d68d37d1..e75c62a6d 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -794,4 +794,81 @@ struct VSOut {#pragma end)esshader";+inline constexpr const char* SKY = R"esshader(#pragma shader "Sky"+#pragma version 300 es+#pragma domain Lit2D++// The background half of an environment. The reflection in a metal ball and the+// sky behind it are the same baked panorama; without this only one of them was+// ever visible, and a scene lit by a sky sat in front of a flat clear colour.+//+// Geometry is a quad on the far plane, so the vertex stage needs no matrix of its+// own — the fragment's direction is the one from the eye through it, which is+// what viewDirection() already answers (negated: it points AT the viewer).++#pragma vertex+layout(location = 0) in vec3 a_position;++out highp vec3 v_worldPos;++void main() {+ gl_Position = u_projection * vec4(a_position, 1.0);+ v_worldPos = a_position;+}+#pragma end++#pragma fragment+precision highp float;++in highp vec3 v_worldPos;+out vec4 fragColor;++void main() {+ // Mip 0: the sharpest level of the prefiltered atlas is the sky as it was+ // photographed. The rougher ones exist to be reflected, not to be looked at.+ fragColor = vec4(envSampleMip(-viewDirection(v_worldPos), 0.0), 1.0);+}+#pragma end++#pragma vertex wgsl+struct VSIn {+ @location(0) a_position : vec3f,+};+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_worldPos : vec3f,+};++@vertex fn vs_main(v : VSIn) -> VSOut {+ var out : VSOut;+ out.pos = frame.projection * vec4f(v.a_position, 1.0);+ out.v_worldPos = v.a_position;+ return out;+}+#pragma end++#pragma fragment wgsl+// Slot 0 is bound and never read — a draw fills it so the walk that pins the+// atlas one slot on has somewhere to start. The atlas itself is on 3, and+// without these two the injected sampler names identifiers this twin never+// declared: an invalid pipeline that does not mention a shader.+@group(1) @binding(0) var t0 : texture_2d<f32>;+@group(1) @binding(8) var s0 : sampler;+@group(1) @binding(3) var t3 : texture_2d<f32>;+@group(1) @binding(11) var s3 : sampler;++// Declared again: each WGSL block is compiled on its own, so a struct defined in+// the vertex one is an undeclared name here — and that reaches anyone as an+// invalid pipeline with nothing in the log about a shader.+struct VSOut {+ @builtin(position) pos : vec4f,+ @location(0) v_worldPos : vec3f,+};++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {+ return vec4f(envSampleMip(-viewDirection(v.v_worldPos), 0.0), 1.0);+}+#pragma end+)esshader";+} // namespace esengine::ShaderEmbedsdiff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cppindex f61e232ec..2f9d522de 100644--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp@@ -18,6 +18,7 @@ void TransientBufferPool::init(u32 initialVertexBytes, u32 initialIndexCount) {initial_index_count_ = initialIndexCount;for (auto layout : {LayoutId::Batch, LayoutId::ParticleInstance, LayoutId::Shape,+ LayoutId::Sky,LayoutId::MeshInstance}) {setupStream(layout);}@@ -280,6 +281,13 @@ void TransientBufferPool::setupStream(LayoutId layout) {desc.attributes[2] = {2, 4, GfxDataType::Float, false, 16, 0};desc.attributes[3] = {3, 4, GfxDataType::Float, false, 32, 0};break;+ case LayoutId::Sky:+ // One vec3 and nothing else: a layout may not declare an attribute its+ // shader does not consume, which is why this is not the Batch one.+ desc.attributeCount = 1;+ desc.strides[0] = 12;+ desc.attributes[0] = {0, 3, GfxDataType::Float, false, 0, 0};+ break;default:break;}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex fb1569bfc..6b338065d 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -80,6 +80,7 @@ export const SCENES = [// A baked panorama lighting a surface BY DIRECTION: two coplanar triangles, one// white colour, normals up and down under a sky blue above and red below. A flat// ambient term draws the halves identically, which is why the probes invert.+ { id: "mesh-sky", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-sky.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.15,\"rgb\":[0,0,153],\"tol\":20},{\"x\":0.5,\"y\":0.85,\"rgb\":[153,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[106,0,33],\"tol\":20},{\"x\":0.15,\"y\":0.5,\"rgb\":[76,0,70],\"tol\":20}]" } },{ id: "mat-env", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-env.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.25,\"y\":0.55,\"rgb\":[0,6,149],\"tol\":20},{\"x\":0.75,\"y\":0.55,\"rgb\":[148,8,0],\"tol\":20},{\"x\":0.5,\"y\":0.55,\"rgb\":[0,0,0],\"tol\":20}]" } },// The same sky in a MIRROR: two metal quads, roughness 0 and 1. A head-on// surface reflects +Z, which is the image centre — green there, and the whole