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(shadow): the atlas records who it turned down, and why
esengineaa4e28a92581
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex dccaf7865..243fd3a8f 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -947,6 +947,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {GpuLight gpu;bool castsMeshShadow = false;ShadowCaster caster;+ caster.light = entity;gpu.color = glm::vec4(rgb, light.intensity);// shadow.x = penumbra softness (all types); shadow.y = directional march distance (only the// directional branch of shadowFactor2D reads it; 0 keeps directional shadows off).@@ -1209,22 +1210,39 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {u32 count = 0;};std::vector<TilePlan> plan(shadow_casters_.size());+ shadow_plan_.clear();+ shadow_plan_.atlasSize = kShadowAtlasSize;+ shadow_plan_.cellSize = kShadowCellSize;for (usize i = 0; i < shadow_casters_.size(); ++i) {- const ShadowShape shape = shadow_casters_[i].shape;- if (shape == ShadowShape::Box) continue;- const u32 want = shape == ShadowShape::Cube ? SHADOW_CUBE_FACES : 1;- const i32 at = shadow_atlas_.allocate(want, 1);- if (at >= 0) plan[i] = {static_cast<u32>(at), want};+ const ShadowCaster& caster = shadow_casters_[i];+ if (caster.shape == ShadowShape::Box) continue;+ const u32 want = caster.shape == ShadowShape::Cube ? SHADOW_CUBE_FACES : 1;+ i32 at = -1;+ const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want, 1, at);+ if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};+ shadow_plan_.grants.push_back(grant);}for (usize i = 0; i < shadow_casters_.size(); ++i) {const ShadowCaster& caster = shadow_casters_[i];if (caster.shape != ShadowShape::Box) continue;// A fixed reach is the author saying what the map covers; splitting it would// hand the rest of the atlas to slices they never asked for.- u32 want = (perspective && caster.extent <= 0.0f) ? MAX_SHADOW_CASCADES : 1;- for (; want > 0; --want) {- const i32 at = shadow_atlas_.allocate(want, kShadowCascadeCells);- if (at >= 0) { plan[i] = {static_cast<u32>(at), want}; break; }+ const u32 want = (perspective && caster.extent <= 0.0f) ? MAX_SHADOW_CASCADES : 1;+ i32 at = -1;+ const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want,+ kShadowCascadeCells, at);+ if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};+ shadow_plan_.grants.push_back(grant);+ }+ for (const ShadowGrant& g : shadow_plan_.grants) {+ shadow_plan_.requestedTiles += g.requested;+ shadow_plan_.grantedTiles += g.granted;+ // The light cap two hundred lines up warns when it drops a light. This is the+ // same contention over the same frame and said nothing at all, which is how a+ // light that stopped casting became a question with no answer in the engine.+ if (g.denied()) {+ ES_LOG_WARN("shadow atlas: light {} asked for {} tile(s) and got none ({})",+ g.light.raw, g.requested, refusalName(g.refusal));}}@@ -1353,6 +1371,11 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {}ES_PROFILE_COUNTER("render.shadow.collects", static_cast<u32>(shadow_views_.size()));+ // Asked for BESIDE handed out: the two being equal is the only reading under+ // which "16 tiles" says the frame got what it wanted.+ ES_PROFILE_COUNTER("render.shadow.requested", shadow_plan_.requestedTiles);+ ES_PROFILE_COUNTER("render.shadow.denied", shadow_plan_.deniedCasters());+ ES_PROFILE_COUNTER("render.shadow.reduced", shadow_plan_.reducedCasters());if (!anyTile) return;// Borrowed, not held for the run: 2048² with depth is ~32MB. External becausediff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 98398025c..1e9146e06 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -8,6 +8,7 @@#include "./RenderContext.hpp"#include "../store/LightConstants.hpp"#include "../store/ShadowAtlas.hpp"+#include "../store/ShadowPlan.hpp"#include "../graph/TargetPool.hpp"#include "../graph/RenderGraph.hpp"#include "../RenderTypePlugin.hpp"@@ -310,6 +311,14 @@ public:/** @brief How many (view, entity) pairs are held up for inspection. */usize lodPreviewCount() const { return lod_view_state_.previewCount(); }+ /**+ * @brief What each caster asked the shadow atlas for last frame, and what it got.+ *+ * @details The answer to "why does this object have no shadow", which the engine+ * could not give at all: tiles handed out were counted, refusals were not.+ */+ const ShadowPlanReport& shadowPlan() const { return shadow_plan_; }+/*** @brief Switch the frame to linear-light rendering (project colorSpace).* @details Sets the global ES_LINEAR shader input, linearizes CPU-side@@ -597,6 +606,9 @@ private:*/struct ShadowCaster {u32 slot = 0;+ /// The light that asked. Carried for the same reason `slot` is — the cap sort+ /// reorders these, and a refusal has to be able to name who was refused.+ Entity light{};ShadowShape shape = ShadowShape::Box;/// Which way it points — the aim, not the direction light travels. A cube aims/// six ways of its own and reads none of it.@@ -676,6 +688,7 @@ private:/// Who owns which square of the atlas. Rebuilt every frame: a tile means/// nothing once the depths in it belong to a frame that is gone.ShadowAtlas shadow_atlas_{kShadowAtlasSize, kShadowCellSize};+ ShadowPlanReport shadow_plan_;/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.u32 shadow_texture_id_ = 0;/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.diff --git a/src/esengine/renderer/store/ShadowAtlas.hpp b/src/esengine/renderer/store/ShadowAtlas.hppindex 44bef358f..fa617b360 100644--- a/src/esengine/renderer/store/ShadowAtlas.hpp+++ b/src/esengine/renderer/store/ShadowAtlas.hpp@@ -22,6 +22,31 @@namespace esengine {+/**+ * @brief Why a claim was turned down. Three different answers on purpose: raising+ * the atlas size fixes @ref NoSpace and neither of the others.+ */+enum class AtlasRefusal : u8 {+ None = 0,+ /// More tiles than the shader's arrays are sized for (@ref MAX_SHADOW_TILES).+ TileBudget,+ /// One tile is wider than the whole atlas — the request cannot fit at any size.+ TooLarge,+ /// The atlas has no free block that size left. The one raising the size fixes.+ NoSpace,+};++/** @brief The refusal as a word, for a log line and, later, for a reader. */+inline const char* refusalName(AtlasRefusal why) {+ switch (why) {+ case AtlasRefusal::TileBudget: return "tile budget";+ case AtlasRefusal::TooLarge: return "tile larger than the atlas";+ case AtlasRefusal::NoSpace: return "atlas full";+ case AtlasRefusal::None: break;+ }+ return "none";+}+/** @brief One tile's square, in atlas texels. */struct ShadowTile {u32 x = 0;@@ -52,18 +77,32 @@ public:/*** @brief Claims @p count tiles of @p cells x @p cells cells each.+ * @param why Set to the reason on a refusal, @ref AtlasRefusal::None otherwise.* @return The first tile's index, or -1 when the atlas or the tile budget has no* room for all of them — all or nothing, so a caller never renders half a* cascade set and leaves the rest reading someone else's depths.+ *+ * @details The reason is an OUT PARAMETER rather than something a caller may ask+ * for: every refusal here is a light that silently stops casting, and a+ * signature nobody had to read is how that went unrecorded for as long+ * as it did.*/- i32 allocate(u32 count, u32 cells) {- if (count == 0 || cells == 0 || cells > cols_) return -1;- if (tiles_.size() + count > MAX_SHADOW_TILES) return -1;+ i32 allocate(u32 count, u32 cells, AtlasRefusal& why) {+ why = AtlasRefusal::None;+ if (count == 0 || cells == 0 || cells > cols_) {+ why = AtlasRefusal::TooLarge;+ return -1;+ }+ if (tiles_.size() + count > MAX_SHADOW_TILES) {+ why = AtlasRefusal::TileBudget;+ return -1;+ }const usize before = tiles_.size();for (u32 i = 0; i < count; ++i) {if (!claim(cells)) {tiles_.resize(before);rebuildUsed();+ why = AtlasRefusal::NoSpace;return -1;}}diff --git a/src/esengine/renderer/store/ShadowPlan.hpp b/src/esengine/renderer/store/ShadowPlan.hppnew file mode 100644index 000000000..ab7b31779--- /dev/null+++ b/src/esengine/renderer/store/ShadowPlan.hpp@@ -0,0 +1,99 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ShadowPlan.hpp+ * @brief What each caster asked the shadow atlas for, and what it got.+ *+ * @details A caster the atlas could not fit kept no tiles and cast nothing, and+ * the frame counted the tiles it DID hand out. So "why does this object+ * have no shadow" had no answer anywhere in the engine — not a missing+ * panel, a missing fact.+ *+ * Header-only and free of the renderer, like LodSelection.hpp: the+ * giving-way rule is the part worth holding to a criterion, and it+ * needs no device to be wrong.+ */+#pragma once++#include "../../core/Types.hpp"+#include "./ShadowAtlas.hpp"++#include <vector>++namespace esengine {++/**+ * @brief One caster's claim on the atlas: what it wanted, what it kept, and why+ * the difference.+ *+ * @details `granted < requested` with no refusal is impossible — something gave+ * way and the reason is the whole point of recording this.+ */+struct ShadowGrant {+ /// The light that asked. Carried so a reader can name it rather than an index.+ Entity light{};+ /// Tiles asked for: a sun's cascade set, a cube's six faces, or one.+ u32 requested = 0;+ /// Tiles kept. 0 means this light casts no shadow at all this frame.+ u32 granted = 0;+ /// Why it did not get what it asked for, from the FIRST attempt that failed —+ /// which is the answer to "why not what I asked", not "why not one less".+ AtlasRefusal refusal = AtlasRefusal::None;++ bool denied() const { return granted == 0; }+ bool reduced() const { return granted > 0 && granted < requested; }+};++/** @brief The frame's whole shadow allocation, as numbers something outside it can check. */+struct ShadowPlanReport {+ u32 atlasSize = 0;+ u32 cellSize = 0;+ u32 requestedTiles = 0;+ u32 grantedTiles = 0;+ std::vector<ShadowGrant> grants;++ void clear() {+ requestedTiles = 0;+ grantedTiles = 0;+ grants.clear();+ }++ u32 deniedCasters() const {+ u32 n = 0;+ for (const ShadowGrant& g : grants) n += g.denied() ? 1u : 0u;+ return n;+ }++ u32 reducedCasters() const {+ u32 n = 0;+ for (const ShadowGrant& g : grants) n += g.reduced() ? 1u : 0u;+ return n;+ }+};++/**+ * @brief Claim as much of @p want as the atlas will give, down to one tile.+ *+ * @details A sun settles for fewer rather than costing a positional light the map+ * it cannot shorten. Giving way and RECORDING what it gave way from are+ * one function, so a caller cannot take the first without the second.+ */+inline ShadowGrant claimTiles(ShadowAtlas& atlas, Entity light, u32 want, u32 cells,+ i32& outFirst) {+ ShadowGrant grant{light, want, 0, AtlasRefusal::None};+ outFirst = -1;+ for (u32 take = want; take > 0; --take) {+ AtlasRefusal why = AtlasRefusal::None;+ const i32 at = atlas.allocate(take, cells, why);+ if (at >= 0) {+ outFirst = at;+ grant.granted = take;+ return grant;+ }+ // The first refusal is the one that answers the question a reader has.+ if (take == want) grant.refusal = why;+ }+ return grant;+}++} // namespace esenginediff --git a/tests/renderer/test_shadow_atlas.cpp b/tests/renderer/test_shadow_atlas.cppindex e501caeaf..6e824952b 100644--- a/tests/renderer/test_shadow_atlas.cpp+++ b/tests/renderer/test_shadow_atlas.cpp@@ -3,6 +3,7 @@// rect — but only the tiles its own fragments land in. The arithmetic is pinned here.#include "esengine/renderer/store/ShadowAtlas.hpp"+#include "esengine/renderer/store/ShadowPlan.hpp"#include <cstdio>#include <cmath>@@ -27,10 +28,11 @@ static bool isRect(const glm::vec4& r, f32 x, f32 y, f32 size) {}int main() {+ AtlasRefusal why = AtlasRefusal::None;// The frame's own atlas: 2048 handed out in 512 cells, a cascade taking 2x2.ShadowAtlas atlas(2048, 512);- const i32 first = atlas.allocate(4, 2);+ const i32 first = atlas.allocate(4, 2, why);CHECK(first == 0, "the first claim starts at tile 0");CHECK(atlas.tileCount() == 4, "four cascades claim four tiles");@@ -50,21 +52,21 @@ int main() {// A full atlas has nothing left, and says so rather than handing out a square// somebody else is already drawing into.- CHECK(atlas.allocate(1, 2) < 0, "a full atlas refuses the next claim");+ CHECK(atlas.allocate(1, 2, why) < 0, "a full atlas refuses the next claim");// All or nothing: a caller that gets half a cascade set would leave the rest// reading depths that belong to another light.ShadowAtlas partial(2048, 512);- CHECK(partial.allocate(3, 2) == 0, "three of the four fit");- CHECK(partial.allocate(2, 2) < 0, "two more do not, and the claim is refused");+ CHECK(partial.allocate(3, 2, why) == 0, "three of the four fit");+ CHECK(partial.allocate(2, 2, why) < 0, "two more do not, and the claim is refused");CHECK(partial.tileCount() == 3, "a refused claim leaves the atlas as it was");- CHECK(partial.allocate(1, 2) == 3, "and the one that does fit still can");+ CHECK(partial.allocate(1, 2, why) == 3, "and the one that does fit still can");// Tiles need not all be one size — which is the whole reason the rect is data.// A spot light taking one cell sits beside a cascade taking four.ShadowAtlas mixed(2048, 512);- CHECK(mixed.allocate(1, 2) == 0, "a 2x2 block lands first");- const i32 small = mixed.allocate(2, 1);+ CHECK(mixed.allocate(1, 2, why) == 0, "a 2x2 block lands first");+ const i32 small = mixed.allocate(2, 1, why);CHECK(small == 1, "single cells claim after it");CHECK(isTile(mixed.tile(1), 1024, 0, 512), "the first single cell clears the block");CHECK(isRect(mixed.unitRect(1), 0.5f, 0.0f, 0.25f), "and reports a quarter-side rect");@@ -73,37 +75,92 @@ int main() {// order the faces are rendered — which is what lets a light name a first tile and a// count rather than six indices.ShadowAtlas cube(2048, 512);- CHECK(cube.allocate(SHADOW_CUBE_FACES, 1) == 0, "a cube claims its six faces at once");+ CHECK(cube.allocate(SHADOW_CUBE_FACES, 1, why) == 0, "a cube claims its six faces at once");CHECK(cube.tileCount() == 6, "and gets all six");CHECK(isTile(cube.tile(0), 0, 0, 512), "face 0 takes the first cell");CHECK(isTile(cube.tile(5), 512, 512, 512), "face 5 the sixth, the row filled in order");// What a sun standing beside it can still have: the cube left a row half used, and a// 2x2 block only starts on a multiple of 2 — so the sun loses cascades, not its map.- CHECK(cube.allocate(4, 2) < 0, "four cascades no longer fit beside a cube");- CHECK(cube.allocate(2, 2) == 6, "two do, in the rows the cube did not reach");+ CHECK(cube.allocate(4, 2, why) < 0, "four cascades no longer fit beside a cube");+ CHECK(cube.allocate(2, 2, why) == 6, "two do, in the rows the cube did not reach");CHECK(isTile(cube.tile(6), 0, 1024, 1024), "the first of them clearing the cube's rows");// The budget is the shader's array bound, not the texture's room: a 4096 atlas// of 512 cells has 64 of them and the block still stops at MAX_SHADOW_TILES.ShadowAtlas wide(4096, 512);- CHECK(wide.allocate(MAX_SHADOW_TILES + 1, 1) < 0, "the tile budget is a hard bound");- CHECK(wide.allocate(MAX_SHADOW_TILES, 1) == 0, "and exactly the bound fits");+ CHECK(wide.allocate(MAX_SHADOW_TILES + 1, 1, why) < 0, "the tile budget is a hard bound");+ CHECK(wide.allocate(MAX_SHADOW_TILES, 1, why) == 0, "and exactly the bound fits");// A frame gives it all back: a tile means nothing once the depths in it are// from a frame that is gone.ShadowAtlas reused(2048, 512);- reused.allocate(4, 2);+ reused.allocate(4, 2, why);reused.reset();CHECK(reused.tileCount() == 0, "reset empties the atlas");- CHECK(reused.allocate(4, 2) == 0, "and the next frame claims the same squares");+ CHECK(reused.allocate(4, 2, why) == 0, "and the next frame claims the same squares");CHECK(isTile(reused.tile(0), 0, 0, 1024), "starting again at the lower-left");// A block larger than the grid has nowhere to go, and a zero-sized claim is not// a claim — both answer rather than indexing something that is not there.ShadowAtlas small2(1024, 512);- CHECK(small2.allocate(1, 4) < 0, "a block wider than the atlas is refused");- CHECK(small2.allocate(0, 2) < 0, "so is a claim for no tiles");- CHECK(small2.allocate(1, 0) < 0, "so is a claim for empty ones");+ CHECK(small2.allocate(1, 4, why) < 0, "a block wider than the atlas is refused");+ CHECK(small2.allocate(0, 2, why) < 0, "so is a claim for no tiles");+ CHECK(small2.allocate(1, 0, why) < 0, "so is a claim for empty ones");++ // Each refusal is a DIFFERENT answer, and only one of them is fixed by a bigger+ // atlas. Folded into one "no room" they would send a reader to raise a size that+ // was never the limit.+ ShadowAtlas reasons(2048, 512);+ reasons.allocate(1, 8, why);+ CHECK(why == AtlasRefusal::TooLarge, "a block wider than the atlas says so");+ reasons.allocate(MAX_SHADOW_TILES + 1, 1, why);+ CHECK(why == AtlasRefusal::TileBudget, "past the shader's array bound says budget");+ ShadowAtlas filled(1024, 512);+ filled.allocate(4, 1, why);+ CHECK(why == AtlasRefusal::None, "a claim that fits refuses nothing");+ filled.allocate(1, 1, why);+ CHECK(why == AtlasRefusal::NoSpace, "and the one after it is out of room, not out of budget");++ // Giving way, and what it gives way FROM. A sun asks for a cascade set and takes+ // fewer rather than costing a positional light its map — which is correct, and was+ // indistinguishable from casting nothing.+ ShadowAtlas contended(2048, 512);+ i32 at = -1;+ const ShadowGrant cubeGrant = claimTiles(contended, Entity::make(1, 1), SHADOW_CUBE_FACES, 1, at);+ CHECK(cubeGrant.granted == SHADOW_CUBE_FACES && at == 0, "the cube claims first and whole");+ const ShadowGrant sun = claimTiles(contended, Entity::make(2, 1), MAX_SHADOW_CASCADES, 2, at);+ CHECK(sun.requested == MAX_SHADOW_CASCADES, "the sun asked for a whole cascade set");+ CHECK(sun.granted > 0 && sun.granted < sun.requested, "and settled for fewer");+ CHECK(sun.reduced() && !sun.denied(), "which is a reduction, not a denial");+ CHECK(sun.refusal == AtlasRefusal::NoSpace,+ "and the reason is the FIRST attempt's, not the last one that happened to work");++ // A smaller atlas is the case a reader hits first, and the one they can act on.+ ShadowAtlas cramped(1024, 512);+ i32 none = -1;+ claimTiles(cramped, Entity::make(3, 1), 4, 1, none);+ const ShadowGrant denied = claimTiles(cramped, Entity::make(4, 1), 1, 1, none);+ CHECK(denied.denied() && none < 0, "a caster the atlas cannot fit keeps nothing");+ CHECK(denied.refusal == AtlasRefusal::NoSpace, "and says the atlas was full");+ CHECK(denied.granted == 0 && denied.requested == 1, "recording both halves of the claim");++ // The report's own arithmetic: what a frame says it handed out is what the atlas+ // actually holds. A grant nobody claimed would make every later number a guess.+ ShadowPlanReport report;+ ShadowAtlas counted(2048, 512);+ for (u32 i = 0; i < 3; ++i) {+ i32 first = -1;+ report.grants.push_back(claimTiles(counted, Entity::make(i + 10, 1), 2, 2, first));+ }+ for (const ShadowGrant& g : report.grants) {+ report.requestedTiles += g.requested;+ report.grantedTiles += g.granted;+ }+ CHECK(report.grantedTiles == counted.tileCount(),+ "the tiles the report says were granted are the tiles the atlas holds");+ CHECK(report.requestedTiles == 6, "and what was asked for is counted apart from it");+ CHECK(report.deniedCasters() + report.reducedCasters() > 0,+ "three two-tile claims do not all fit in four cells, and the report says which");std::printf(g_failures ? "\n%d check(s) failed\n" : "\nall checks passed\n", g_failures);return g_failures == 0 ? 0 : 1;diff --git a/tools/check-shadow-plan.mjs b/tools/check-shadow-plan.mjsnew file mode 100644index 000000000..2769f6a81--- /dev/null+++ b/tools/check-shadow-plan.mjs@@ -0,0 +1,71 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-shadow-plan.mjs — a caster the shadow atlas turns down is recorded.+ *+ * A light the atlas could not fit kept no tiles and cast nothing. The frame+ * counted the tiles it handed OUT, so "why does this object have no shadow" had+ * no answer anywhere in the engine — while the light cap two hundred lines up in+ * the same file logged every light it dropped.+ *+ * What test_shadow_atlas proves about the giving-way rule, this holds about the+ * wiring: the recording path is the ONLY way to claim a tile, the reason is kept,+ * and a denial still reaches a reader. Each is a line somebody could delete+ * without a pixel moving.+ */+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const FRAME = 'src/esengine/renderer/frame/RenderFrame.cpp';+const PLAN = 'src/esengine/renderer/store/ShadowPlan.hpp';++const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');+const problems = [];+const frame = read(FRAME);+const plan = read(PLAN);++// 1. One door. `claimTiles` is the only thing that writes a grant, so a claim made+// around it is a caster that can be refused with nothing recording it — which is+// the state this whole file exists to have left.+const direct = [...frame.matchAll(/shadow_atlas_\.allocate\(/g)].length;+if (direct > 0) {+ problems.push(`${FRAME} claims atlas tiles directly (${direct} site(s)) instead of through`+ + ' claimTiles — a claim that does not go through the recording path is a light that can'+ + ' stop casting with nothing to say why');+}+if (!/claimTiles\(/.test(frame)) {+ problems.push(`${FRAME} never calls claimTiles — nothing is recording what the atlas refused`);+}++// 2. The reason, kept. Which of the three refusals happened decides what a reader+// would do about it: only one of them is fixed by a bigger atlas.+if (!/grant\.refusal = why/.test(plan)) {+ problems.push(`${PLAN} no longer keeps the refusal — a denial becomes a fact with no cause,`+ + ' and "atlas full" stops being distinguishable from "tile budget"');+}+if (!/if \(take == want\)/.test(plan)) {+ problems.push(`${PLAN} no longer takes the FIRST attempt's refusal — the reason a caster did`+ + ' not get what it ASKED for is not the reason one tile fewer also failed');+}++// 3. It reaches somebody. A record nothing reports is the same silence in a struct.+if (!/ES_LOG_WARN\("shadow atlas/.test(frame)) {+ problems.push(`${FRAME} no longer warns on a denied caster — the light cap in this same file`+ + ' warns, and these are the same contention over the same frame');+}+for (const counter of ['render.shadow.denied', 'render.shadow.requested']) {+ if (!frame.includes(counter)) {+ problems.push(`${FRAME} no longer reports ${counter} — tiles handed out without tiles asked`+ + ' for is a number that cannot be read as a shortfall');+ }+}++if (problems.length) {+ console.error(`check-shadow-plan: ${problems.length} problem(s)`);+ for (const p of problems) console.error(` - ${p}`);+ process.exit(1);+}+console.log('check-shadow-plan: every atlas claim goes through the recording path, the refusal is'+ + ' kept, and a denied caster is both warned and counted.');diff --git a/tools/gates.mjs b/tools/gates.mjsindex 439f47466..e02b6edbc 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -186,6 +186,7 @@ export const GATES = [{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },{ id: 'gizmo-coverage', run: 'node tools/check-gizmo-coverage.mjs', needs: 'editor' },{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },+ { id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },{ id: 'decision-inventory', run: 'node tools/check-decision-inventory.mjs', needs: 'editor' },{ id: 'mutator-parity', run: 'node tools/check-mutator-parity.mjs', needs: 'editor' },{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs', needs: 'editor' },diff --git a/tools/lib/runtimeDecisions.mjs b/tools/lib/runtimeDecisions.mjsindex d07a73b9e..22fdef75d 100644--- a/tools/lib/runtimeDecisions.mjs+++ b/tools/lib/runtimeDecisions.mjs@@ -75,14 +75,13 @@ export const DECISIONS = [id: 'shadow.atlasAllocation',what: 'Which casters get shadow tiles, how many cascades the sun keeps, and who is denied.',kind: 'contended-resource',- owner: { path: 'src/esengine/renderer/frame/RenderFrame.cpp', probe: /shadow_atlas_\.allocate\(want, kShadowCascadeCells\)/ },- runtime: {+ owner: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /inline ShadowGrant claimTiles/ },+ runtime: { has: true, cite: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /grant\.refusal = why/ } },+ editor: {has: false,- owed: 'a caster the atlas cannot fit keeps plan[i].count == 0 and casts nothing. Tiles and draws '- + 'are counted; DENIALS are not, and no log names the light. The light cap two hundred lines '- + 'up warns — this one is silent, in the same file',+ owed: 'the frame now records who was refused and why (ShadowPlanReport, render.shadow.denied), '+ + 'and nothing reads it — a light stops casting and the viewport still gives no reason',},- editor: { has: false, owed: 'a light stops casting and the viewport gives no reason' },agent: { has: false, owed: 'nothing to read' },},{