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
fix(verify): a shot walks engine time, so frame 90 is the same moment on every host
yhh445e0f3e68ad
diff --git a/bench/aot-native/frame-bench.mjs b/bench/aot-native/frame-bench.mjsindex 851c19a23..c9970808f 100644--- a/bench/aot-native/frame-bench.mjs+++ b/bench/aot-native/frame-bench.mjs@@ -107,6 +107,11 @@ const RENDER = GATE || process.env.BENCH_RENDER === '1';* headroom over today. Submitting every sprite twice takes 59 ns/sprite to 109;* healthy runs read 3.65-4.21 and that one 5.94. A ceiling of 4 was tried at* 32,000 entities, where the same sabotage read 3.90 and passed.+ *+ * On a CPU rasterizer the span pays to rasterize the sprites too; the host says+ * so (`adapter` in the bench line) and the report repeats it. No ceiling of its+ * own: the runner's first reading, 5.37 (2026-09-02), was a regression this GPU+ * also shows (5.06 at 122 ns/sprite), which a derived ceiling would have hidden.*/const RENDER_MAX_RATIO = Number(process.env.BENCH_RENDER_MAX_RATIO ?? 5);@@ -523,9 +528,13 @@ if (render.drawing && render.holding && !unmeasured(render.drawing) && !unmeasurconst holding = render.holding.cpu.p50;const ratio = drawing / holding;const nsPerSprite = ((drawing - holding) * 1e6) / RENDER_ENTITIES;+ // Said, not judged by a rule of its own: a CPU rasterizer pays for the sprites+ // inside this span too, and a reading there has to be read as one.+ const onCpu = render.drawing.adapter === 'cpu';console.log(`\ndrawing: ${RENDER_ENTITIES} sprites make the frame ${ratio.toFixed(2)}x the one that `+ `only holds them (${holding.toFixed(2)} ms -> ${drawing.toFixed(2)} ms, `- + `${nsPerSprite.toFixed(0)} ns/sprite, ${render.drawing.draws} draw(s))`);+ + `${nsPerSprite.toFixed(0)} ns/sprite, ${render.drawing.draws} draw(s)`+ + `${onCpu ? ', rasterized on the CPU' : ''})`);if (GATE && !(ratio <= RENDER_MAX_RATIO)) {console.error(`✗ drawing: the frame is ${ratio.toFixed(2)}x the one that only holds the same `+ `entities, over the ${RENDER_MAX_RATIO}x ceiling — submitting a sprite got dearer`);diff --git a/native/host/Bench.cpp b/native/host/Bench.cppindex a6d4dd629..47cece6d8 100644--- a/native/host/Bench.cpp+++ b/native/host/Bench.cpp@@ -89,6 +89,8 @@ struct BenchState {* number in the report reads that wait as cost. */double busyCpuMs = 0.0, busyWallMs = 0.0, cpuAtSpanBegin = -1.0;unsigned draws = 0, sprites = 0;+ /** The adapter class Dawn reported, see benchNoteAdapter. */+ std::string adapter = "unknown";/** This frame's running totals, and the last timed frame's — the same shape* `draws` has, so the report reads one frame rather than an average that* hides a system which stopped being dispatched to halfway through. */@@ -163,7 +165,7 @@ void report() {"\"cpu\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},""\"frame\":{\"min\":%.4f,\"p50\":%.4f,\"p90\":%.4f},""\"draws\":%u,\"sprites\":%u,\"aotCandidates\":%u,\"aotPacked\":%u,"- "\"tickShareOfCpu\":%.4f,\"busy\":%.4f}",+ "\"tickShareOfCpu\":%.4f,\"busy\":%.4f,\"adapter\":\"%s\"}",// The FRAME span's count is the authority on how many frames were// sampled: a frame can be abandoned after it began and reach no other span.s.label.c_str(), s.warmup, s.frame.ms.size(), s.dt,@@ -171,7 +173,8 @@ void report() {at(s.pump.ms, 0.0), p50, at(s.pump.ms, 0.9),at(s.cpu.ms, 0.0), c50, at(s.cpu.ms, 0.9),at(s.frame.ms, 0.0), at(s.frame.ms, 0.5), at(s.frame.ms, 0.9),- s.draws, s.sprites, s.aotCandidatesFrame, s.aotPackedFrame, share, busy);+ s.draws, s.sprites, s.aotCandidatesFrame, s.aotPackedFrame, share, busy,+ s.adapter.c_str());}} // namespace@@ -221,6 +224,12 @@ void benchNoteDraws(unsigned draws, unsigned sprites) {state().sprites = sprites;}+void benchNoteAdapter(const char* kind) {+ // Whether or not a bench was asked for: the adapter is known long before the+ // first timed frame, and there is nothing to time here.+ if (kind != nullptr && kind[0] != '\0') state().adapter = kind;+}+void benchNoteAotCandidates(unsigned candidates, unsigned packed) {BenchState& s = state();if (!s.asked || s.reported) return;diff --git a/native/host/Bench.hpp b/native/host/Bench.hppindex 4d197f460..c9c8b5f9d 100644--- a/native/host/Bench.hpp+++ b/native/host/Bench.hpp@@ -91,6 +91,12 @@ void benchBeforePresent();* a cost that lands somewhere the report cannot see reads as the system's. */void benchNoteDraws(unsigned draws, unsigned sprites);+/** What DRAWS it: "discrete", "integrated", "cpu" or "unknown", as Dawn classes+ * the adapter. In the report because a ceiling on drawing time belongs to the+ * rasterizer: a CPU one also rasterizes every sprite inside the span `cpu`+ * measures, and a GPU-calibrated ratio reads a healthy frame there as over. */+void benchNoteAdapter(const char* kind);+/*** What a compiled system covered, and what it had to write, added to this* frame's totals.diff --git a/native/host/Host.cpp b/native/host/Host.cppindex f43273e32..4fdef5a86 100644--- a/native/host/Host.cpp+++ b/native/host/Host.cpp@@ -168,6 +168,11 @@ void logAdapter(HostState& h) {if (wgpuAdapterGetInfo(h.adapter, &info) != WGPUStatus_Success) return;bootNote("gpu: %s %s (%s) — %s", svText(info.vendor).c_str(), svText(info.device).c_str(),svText(info.architecture).c_str(), svText(info.description).c_str());+ // The class, for the bench: a ceiling on what a frame spends drawing is one+ // number on a GPU and another on a rasterizer that draws on the CPU it times.+ benchNoteAdapter(info.adapterType == WGPUAdapterType_DiscreteGPU ? "discrete"+ : info.adapterType == WGPUAdapterType_IntegratedGPU ? "integrated"+ : info.adapterType == WGPUAdapterType_CPU ? "cpu" : "unknown");wgpuAdapterInfoFreeMembers(info);}@@ -328,9 +333,10 @@ void frame() {}h.lastFrameAt = nowAt;h.haveLastFrame = true;- // A bench steps at a fixed rate, so two builds of the same project move the- // same distance and can be held against each other.- deltaSeconds = benchDelta(deltaSeconds);+ // A shot steps at a fixed rate too, so "frame 90" is the same moment of the+ // game on every host (Shot.hpp); a bench at its own, so two builds move the+ // same distance and can be held against each other. The bench's rate wins.+ deltaSeconds = benchDelta(shotDelta(deltaSeconds));// Booked before the game renders, because the copy is served from inside the// renderer's own endFrame (see Shot.hpp).diff --git a/native/host/Shot.cpp b/native/host/Shot.cppindex 129f48dcb..e3455c86f 100644--- a/native/host/Shot.cpp+++ b/native/host/Shot.cpp@@ -95,6 +95,14 @@ void logVerdict(const std::vector<u8>& rgba, u32 w, u32 h, bool bgra) {bool shotWanted() { return state().asked; }+double shotDelta(double wall) {+ // Fixed for the whole run, not only up to the capture: a scene that moved at+ // one rate before the shot and another after it is two scenes, and a shot+ // that does not quit keeps being looked at.+ constexpr double kShotDt = 1.0 / 60.0;+ return state().asked ? kShotDt : wall;+}+void shotBeforeFrame(esengine::WebGPUDevice& gfx, u64 frame, u32 w, u32 h) {ShotState& s = state();if (!s.asked || s.started || s.done || frame < s.atFrame || w == 0 || h == 0) return;diff --git a/native/host/Shot.hpp b/native/host/Shot.hppindex 047ef76e2..8c79e4602 100644--- a/native/host/Shot.hpp+++ b/native/host/Shot.hpp@@ -23,6 +23,14 @@* for a first scene to have loaded its assets).* - `ESTELLA_SHOT_QUIT` `1` to exit once the verdict is out, which is* what a CI run wants.+ * While a capture is armed the frames are the ENGINE's, one fixed+ * 1/60 at a time (`shotDelta`). A shot at "frame 90" counted on wall+ * time is a shot at whatever moment the runner reached 90 frames: with+ * no display to wait for, a software-rendered runner walks 90 frames+ * in a third of a second, and a scene whose first mover appears after+ * 0.8 s of game time has not spawned it yet — which a verifier then+ * reports as a compiled system that was never dispatched to. Same rule+ * as a bench (Bench.hpp) and as the web driver's fixed step.** @author ESEngine Team* @date 2026@@ -42,6 +50,10 @@ namespace eshost {* swapchain has to be configured for copying BEFORE it exists. */bool shotWanted();+/** The step this frame advances by: a fixed 1/60 while a capture is armed, and+ * @p wall untouched otherwise — a shipped game is not stepped by this file. */+double shotDelta(double wall);+/** Book the capture if @p frame is the one asked for. Call BEFORE the frame is* rendered: the copy itself is performed inside the renderer's endFrame, since* that is the last instant the swapchain image belongs to us. */diff --git a/tools/verify-aot-native.mjs b/tools/verify-aot-native.mjsindex 4cdf5a349..59cbf5bce 100644--- a/tools/verify-aot-native.mjs+++ b/tools/verify-aot-native.mjs@@ -28,7 +28,12 @@ import { desktopExecutableIn } from '../build-tools/utils/desktopApp.js';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');/** The example whose system carries the marker. */const PROJECT = path.join(ROOT, 'examples', 'ecs-basics');-/** Frames to let run before the shot: enough for a pool to exist and be bound. */+/**+ * Frames to let run before the shot: enough for a pool to exist and be bound.+ * Engine frames, at the host's fixed shot step (Shot.hpp): ecs-basics spawns its+ * first `Mover` 0.8 s into the game, and 90 frames of wall time on a runner with+ * no display to wait for is a third of that.+ */const SHOT_FRAME = '90';const version = JSON.parse(@@ -93,7 +98,10 @@ try {if (problems.length > 0) {console.error('✗ aot native: ' + problems.join('; '));- for (const line of log.split('\n').filter((l) => /aot|AOT|error|ERROR/.test(l)).slice(0, 10)) {+ // ALSA says "error" a dozen times on a runner with no sound card, and those+ // took every one of these ten lines the first time this ran on one.+ const telling = (l) => /aot|AOT|error|ERROR/.test(l) && !/^ALSA lib /.test(l);+ for (const line of log.split('\n').filter(telling).slice(0, 10)) {console.error(` ${line.trim()}`);}process.exit(1);