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(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.mjs
index 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) && !unmeasur
const 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.cpp
index 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.hpp
index 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.cpp
index 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.cpp
index 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.hpp
index 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.mjs
index 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);