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.

feat(example): the outpost pays for its own shader before anyone sees it

esenginedb81b129fc5e
diff --git a/examples/third-person-3d/assets/materials/beacon.esmaterial b/examples/third-person-3d/assets/materials/beacon.esmaterial
new file mode 100644
index 000000000..2ef9797e3
--- /dev/null
+++ b/examples/third-person-3d/assets/materials/beacon.esmaterial
@@ -0,0 +1,19 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "builtin:model",
+ "blendMode": 9,
+ "depthTest": true,
+ "depthWrite": true,
+ "cull": 1,
+ "properties": {
+ "u_emissive": {
+ "r": 0.95,
+ "g": 0.78,
+ "b": 0.22,
+ "a": 1
+ },
+ "u_metallic": 0.15,
+ "u_roughness": 0.35
+ }
+}
diff --git a/examples/third-person-3d/assets/materials/beacon.esmaterial.meta b/examples/third-person-3d/assets/materials/beacon.esmaterial.meta
new file mode 100644
index 000000000..07f55b7fc
--- /dev/null
+++ b/examples/third-person-3d/assets/materials/beacon.esmaterial.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "91765692-eb29-4bd0-88d8-f87969ab2b0d",
+ "version": "2.0",
+ "type": "material",
+ "importer": {}
+}
diff --git a/examples/third-person-3d/assets/scenes/main.esscene b/examples/third-person-3d/assets/scenes/main.esscene
index 8faedd18c..ac2bc8804 100644
--- a/examples/third-person-3d/assets/scenes/main.esscene
+++ b/examples/third-person-3d/assets/scenes/main.esscene
@@ -5375,7 +5375,8 @@
"g": 0.85,
"b": 0.4,
"a": 1
- }
+ },
+ "material": "assets/materials/beacon.esmaterial"
}
},
{
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 86e2dc4e9..f0780d0d4 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -703,6 +703,12 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
ES_PROFILE_COUNTER("render.mesh.lodGathers", lodGathers);
ES_PROFILE_COUNTER("render.mesh.programAsks", programAsks);
ES_PROFILE_COUNTER("render.mesh.programCompiles", compiled_this_frame_);
+ // Material-owned programs built so far, CUMULATIVE. Read-only: an observer
+ // that had to ask for readiness to see it would be the one paying, and the
+ // frame it asked about would be clean because of the asking.
+ if (ctx.materials != nullptr) {
+ ES_PROFILE_COUNTER("render.mesh.materialPrograms", ctx.materials->builtVariantCount());
+ }
if (compiled_this_frame_ > 0) {
ES_PROFILE_COUNTER("render.mesh.compiledKey", last_compiled_variant_);
}
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index b1acdb1b4..b23bd1a4d 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -275,9 +275,6 @@ export const EVIDENCE = {
* coverage — the same bargain check-project-settings strikes.
*/
export const KNOWN_GAPS = {
- // A work item, not a dispensation: the staleness check below forces the entry
- // out the moment a project certifies it.
- 'shader-readiness': 'no golden project watches the frame something first appears on; needs a runBy a release criterion schedules',
// Present in the engine and shown by non-golden samples, but never carried
// through the chain by a project the release argues from.
settings: 'Celestial Heights persists language, effects and key bindings and reads them back at boot; volume waits on the game having sound',
@@ -380,7 +377,11 @@ export const GOLDEN = [
{
id: 'third-person-3d',
certifies: ['third-person', 'level-of-detail', 'ssao', 'navigation-3d',
- 'root-motion', 'animation-events', 'world-streaming'],
+ 'root-motion', 'animation-events', 'world-streaming', 'shader-readiness'],
+ // A packaged frame looks the same whether first sight of the outpost cost a
+ // compile or not; the run is what reads the counter on both sides of the
+ // boundary. Scheduled by `a-streamed-place-is-ready-before-it-is-seen`.
+ runBy: 'node tools/verify-third-person.mjs',
targets: ['web'],
tier: 'pr',
// The character walks on the key it declares. What it DOES on the way is
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index 7029ecc4c..4781c1721 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -67,6 +67,17 @@ export const CRITERIA = [
answeredBy: 'node tools/verify-third-person.mjs',
needs: ['tools/verify-third-person.mjs', 'examples/third-person-3d/project.esproject'],
},
+ {
+ id: 'a-streamed-place-is-ready-before-it-is-seen',
+ says: 'a streamed place pays its own shader requirements while it is being prepared,'
+ + ' not on the frame the player first sees it',
+ // The same command as above, deliberately under its own name: deleting the
+ // shader half would leave the character half green, and the registry unable
+ // to say what this command still owes.
+ answeredBy: 'node tools/verify-third-person.mjs',
+ needs: ['tools/verify-third-person.mjs',
+ 'examples/third-person-3d/assets/materials/beacon.esmaterial'],
+ },
{
id: '3d-runs-where-it-ships',
host: 'android',
diff --git a/tools/verify-third-person.mjs b/tools/verify-third-person.mjs
index 0811d0cc3..101cb5330 100644
--- a/tools/verify-third-person.mjs
+++ b/tools/verify-third-person.mjs
@@ -496,18 +496,19 @@ const START = { y: 60, z: 120 };
// on is persistent, and one outpost past the causeway is the only thing cut into
// a cell. The claim is gameplay only a resident cell makes possible.
function excursion({ out, frames, swings = 0, back = 0 }) {
- const holds = [{ key: 'KeyS', from: 0, to: out }];
+ const holds = out > 0 ? [{ key: 'KeyS', from: 0, to: out }] : [];
for (let i = 0; i < swings; i++) holds.push({ key: 'KeyJ', from: 225 + i * 20, to: 228 + i * 20 });
if (back > 0) holds.push({ key: 'KeyW', from: out + 10, to: out + 10 + back });
const r = runElectron([
LAUNCHER, '--dir', dir, '--w', String(W), '--h', String(H),
'--settle', '30', '--timeout', '120000', '--scene', 'main', '--streaming',
'--gameplay', 'Player,Camera', '--combat', 'Player:Sentry,Beacon,Player',
- '--ai', 'Sentry', '--input', JSON.stringify({ holds, frames }),
+ '--ai', 'Sentry', '--render', '--input', JSON.stringify({ holds, frames }),
], { encoding: 'utf8', cwd: ROOT });
return {
at: reading(r.stdout, 'gameplay'),
world: reading(r.stdout, 'streaming'),
+ counters: reading(r.stdout, 'render') ?? {},
combat: reading(r.stdout, 'combat') ?? { targets: {} },
ai: reading(r.stdout, 'ai') ?? { found: false },
};
@@ -565,6 +566,46 @@ const HOME_AGENTS = 1;
+ ` ${seen.combat?.targets?.Sentry === undefined ? 'gone' : 'still there'}`);
}
+// The outpost's beacon carries the project's ONLY material, so a program that
+// path owns cannot have been built by anything at home. `materialPrograms` counts
+// them cumulatively, and reading it asks for nothing.
+const materials = (seen) => seen.counters?.['render.mesh.materialPrograms'] ?? -1;
+
+{
+ // The guard, not the claim: it fails the day the home half gains a material,
+ // which is the day everything below stops being about the outpost.
+ const home = excursion({ out: 0, frames: 40 });
+ check('nothing at home needs the material the outpost brings',
+ materials(home) === 0 && (home.world?.residentCells?.length ?? 9) === 0,
+ `${materials(home)} material program(s) with the outpost unpublished`);
+}
+
+{
+ // Prepared, and nothing of it in the world yet — and the program is built.
+ // This is where the compile is meant to be paid, and it is the reading that
+ // says it was.
+ const near = excursion({ out: 130, frames: 170 });
+ check('the outpost pays for its own shader while it is still only prepared',
+ near.world?.preparedCells?.includes('main.cell_0_2') === true
+ && (near.world?.residentCells?.length ?? 9) === 0 && materials(near) === 1,
+ `prepared ${JSON.stringify(near.world?.preparedCells)}, resident`
+ + ` ${JSON.stringify(near.world?.residentCells)}, ${materials(near)} material program(s)`);
+}
+
+{
+ // And seeing it adds nothing. The counter is cumulative, so one that is
+ // already 1 before publication and 1 after is a frame delta of zero without
+ // sampling every frame to say so.
+ const there = excursion({ out: 300, frames: 400 });
+ check('first sight of the outpost pays no shader compile',
+ there.world?.residentCells?.includes('main.cell_0_2') === true
+ && materials(there) === 1
+ && (there.counters?.['render.mesh.programCompiles'] ?? -1) === 0,
+ `resident ${JSON.stringify(there.world?.residentCells)},`
+ + ` ${materials(there)} material program(s) — the same one preparation built —`
+ + ` and ${there.counters?.['render.mesh.programCompiles']} stock compile(s) on the frame`);
+}
+
const failed = results.filter((r) => !r.ok);
console.log(`\nverify-third-person: ${results.length - failed.length}/${results.length}`
+ ' behaviour(s) hold up in the packaged game.');