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(engine): one place a seed lives, and particles draw from it

esengineb8e68e525d59
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index b0204eeb2..5855bf139 100644
--- a/cmake/ESEngineSources.cmake
+++ b/cmake/ESEngineSources.cmake
@@ -8,6 +8,7 @@
set(ESENGINE_SOURCES
${ESENGINE_ROOT}/src/esengine/core/EstellaContext.cpp
+ ${ESENGINE_ROOT}/src/esengine/core/RandomSource.cpp
${ESENGINE_ROOT}/src/esengine/core/Log.cpp
${ESENGINE_ROOT}/src/esengine/resource/ResourceManager.cpp
${ESENGINE_ROOT}/src/esengine/resource/ShaderParser.cpp
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 0888237ea..4baaf9bf2 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -48,6 +48,9 @@ const BACKEND = process.env.ESTELLA_VERIFY_BACKEND === 'webgpu' ? 'webgpu' : 'we
// ESTELLA_VERIFY_COLORSPACE=linear boots the linear-light pipeline (sRGB decode
// + linear blending + final OETF) — point expectations must be linear-derived.
const COLORSPACE = process.env.ESTELLA_VERIFY_COLORSPACE === 'linear' ? 'linear' : '';
+// A scene whose emitters roll dice has no constant to assert until the run is
+// seeded; the engine seeds itself from the clock when nobody says otherwise.
+const SEED = process.env.ESTELLA_VERIFY_SEED ?? '';
// ESTELLA_VERIFY_DEPTH_LAYERS=<mask> turns layers into depth-resolved ones (2.5D).
const DEPTH_LAYERS = process.env.ESTELLA_VERIFY_DEPTH_LAYERS ?? '';
@@ -127,7 +130,7 @@ app.whenReady().then(async () => {
let server;
try {
server = await serveDist();
- const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}`;
+ const url = `http://127.0.0.1:${server.address().port}/headless.html?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}${SEED ? `&seed=${SEED}` : ''}`;
// useContentSize: the capture rectangle must be the page area, not the
// outer frame (the same trap the parity runner documents).
diff --git a/desktop/src/engine/EngineHost.ts b/desktop/src/engine/EngineHost.ts
index d40bea332..9392757f4 100644
--- a/desktop/src/engine/EngineHost.ts
+++ b/desktop/src/engine/EngineHost.ts
@@ -526,6 +526,7 @@ class EngineHostImpl {
backend?: 'webgl2' | 'webgpu';
colorSpace?: 'gamma' | 'linear';
depthLayers?: number;
+ randomSeed?: number;
}): Promise<void> {
if (this.booted) return;
this.booted = true;
@@ -540,6 +541,7 @@ class EngineHostImpl {
backend: size.backend,
colorSpace: size.colorSpace,
depthLayers: size.depthLayers,
+ randomSeed: size.randomSeed,
});
} catch (err) {
this.swallowUnwind(err);
@@ -555,7 +557,7 @@ class EngineHostImpl {
opts: {
runLoop: boolean; loadInitialScene: boolean;
backend?: 'webgl2' | 'webgpu'; colorSpace?: 'gamma' | 'linear';
- depthLayers?: number;
+ depthLayers?: number; randomSeed?: number;
},
) {
const backend = opts.backend ?? 'webgl2';
@@ -679,6 +681,7 @@ class EngineHostImpl {
const app = await bootProfiler.phase('createWebApp', () => createWebApp(module, {
renderSurface,
colorSpace: opts.colorSpace,
+ randomSeed: opts.randomSeed,
depthLayers: opts.depthLayers,
getViewportSize: () => ({ width: canvas.width, height: canvas.height }),
// The per-version spine side modules are served next to esengine.wasm
diff --git a/desktop/src/headless.ts b/desktop/src/headless.ts
index e2f71a507..2f8ee3f92 100644
--- a/desktop/src/headless.ts
+++ b/desktop/src/headless.ts
@@ -52,6 +52,10 @@ const width = Number(params.get('w')) || 1280;
const height = Number(params.get('h')) || 720;
const backend = params.get('backend') === 'webgpu' ? 'webgpu' : 'webgl2';
const colorSpace = params.get('colorSpace') === 'linear' ? 'linear' : undefined;
+// A seed makes the run reproduce — a scene with particles has nothing constant
+// to assert without one.
+const seedParam = params.get('seed');
+const randomSeed = seedParam !== null && Number.isFinite(Number(seedParam)) ? Number(seedParam) : undefined;
// A depth-layer mask, so the harness can exercise the 2.5D path the same way a
// project setting would — the engine takes a mask, not a checkbox list.
const depthLayers = Number(params.get('depthLayers')) || undefined;
@@ -74,7 +78,7 @@ function loseContextExtension(): { loseContext(): void; restoreContext(): void }
}
window.__estellaHeadless = {
- ready: EngineHost.bootHeadless({ width, height, backend, colorSpace, depthLayers }),
+ ready: EngineHost.bootHeadless({ width, height, backend, colorSpace, depthLayers, randomSeed }),
api: EditorControlSurface,
device: {
status: () => getDeviceStatus(),
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3f08779bc..da54cf5bf 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2069,6 +2069,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
@@ -2619,6 +2620,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
@@ -8660,6 +8662,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 821c5930a..e7d1bf98d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2077,6 +2077,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
@@ -2627,6 +2628,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
@@ -8853,6 +8855,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 4b25237d6..12724afe6 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
@@ -8655,6 +8657,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index eda685b2c..6b52ee757 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
@@ -8900,6 +8902,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 8f1115efe..6b44422cc 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -218,6 +218,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index a13436261..a3044a158 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefined
engine_getCpuScopes: (() => string) | undefined
engine_getGpuScopes: (() => string) | undefined
engine_setCpuProfiling: ((on: boolean) => void) | undefined
+engine_setRandomSeed: ((seed: number) => void) | undefined
es_getMallocBytes: (() => number) | undefined
esshader_cookInfo: (source: string, featuresCsv: string) => { valid: boolean; error?: string; name: string; domain: string; hasWgslVertex: boolean; hasWgslFragment: boolean; hasSwitches: boolean; vertGlsl: string; fragGlsl: string; textures: Array<{ name: string; unit: number; }>; }
geometry_create: () => number
@@ -8682,6 +8684,7 @@ colorSpace: "gamma" | "linear" | undefined
depthLayers: number | undefined
getViewportSize: (() => { width: number; height: number; }) | undefined
plugins: Plugin[] | undefined
+randomSeed: number | undefined
renderSurface: RenderSurfaceSource | undefined
screenFit: ScreenScalingData | undefined
sideModules: SideModuleHost | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index 24a07903c..5a09c07e0 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -1231,6 +1231,12 @@ export interface WebAppOptions {
* Must be declared at app creation — shaders compile against it.
*/
colorSpace?: 'gamma' | 'linear';
+ /**
+ * Seed the engine's randomness so this run reproduces — a replay, a bug
+ * report, a pixel assertion. Absent, every run differs, which is what a
+ * player wants of particles.
+ */
+ randomSeed?: number;
/**
* Project camera fit (Project Settings → Display). When set with a real
* scaleMode (≥ 0), the MAIN scene camera letterboxes this design resolution
@@ -1256,6 +1262,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
// Always applied (realm reloads must reset a prior session's mode too).
setLinearColorSpace(options?.colorSpace === 'linear');
module.renderer_setColorSpace?.(options?.colorSpace === 'linear' ? 1 : 0);
+ if (options?.randomSeed !== undefined) module.engine_setRandomSeed?.(options.randomSeed >>> 0);
const surface: RenderSurfaceSource = options?.renderSurface ?? { kind: 'default' };
switch (surface.kind) {
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index c81fb4cce..5bd373835 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -429,6 +429,8 @@ export interface ESEngineModule {
renderer_setDepthLayers?(mask: number): void;
renderer_setCullingMask?(mask: number): void;
renderer_setColorSpace?(linear: number): void;
+ /** Reseed the engine's randomness so a run reproduces (core/RandomSource.hpp). */
+ engine_setRandomSeed?(seed: number): void;
renderer_setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void;
// Clip Rect API
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 8f347d121..bfbb59da0 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -26,6 +26,7 @@
#include "../core/Log.hpp"
#ifdef ES_ENABLE_PARTICLES
#include "../particle/ParticleSystem.hpp"
+#include "../core/RandomSource.hpp"
#endif
#include "../trail/TrailSystem.hpp"
@@ -557,6 +558,21 @@ void engine_setCpuProfiling(bool on) {
FrameProfiler::get().setEnabled(on);
}
+void engine_setRandomSeed(u32 seed) {
+ // Valid pre-init, and it has to be: the SDK sets this beside the colour
+ // space, before the context has registered anything. Remembered here, and
+ // adopted by EstellaContext when it creates the source.
+ setPendingRandomSeed(seed);
+ if (auto* source = ctx().tryGet<RandomSource>()) {
+ source->reseed(seed);
+ // Consumers derive a generator once, so each is re-derived here. One
+ // today; this list is where a second one announces itself.
+#ifdef ES_ENABLE_PARTICLES
+ if (auto* particles = g_particleSystem) particles->reseedFrom(*source);
+#endif
+ }
+}
+
std::string engine_getCpuScopes() {
return FrameProfiler::get().lastJson();
}
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 74883f7a6..5fd6f3f9c 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -107,6 +107,9 @@ u32 renderer_getMeshes();
u32 renderer_getCulled();
f32 renderer_getGpuTimeMs();
void engine_setCpuProfiling(bool on);
+/** Reseed the engine's randomness (core/RandomSource.hpp) so a run reproduces.
+ * Unset, every run differs — which is what a player wants of particles. */
+void engine_setRandomSeed(u32 seed);
std::string engine_getCpuScopes();
std::string engine_getCounters();
std::string engine_getGpuScopes();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 86450862e..57568445d 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -607,6 +607,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_getCulled", &esengine::renderer_getCulled);
emscripten::function("renderer_getGpuTimeMs", &esengine::renderer_getGpuTimeMs);
emscripten::function("engine_setCpuProfiling", &esengine::engine_setCpuProfiling);
+ emscripten::function("engine_setRandomSeed", &esengine::engine_setRandomSeed);
emscripten::function("engine_getCpuScopes", &esengine::engine_getCpuScopes);
emscripten::function("engine_getCounters", &esengine::engine_getCounters);
emscripten::function("engine_getGpuScopes", &esengine::engine_getGpuScopes);
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index 3bbad8788..5e65726b5 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -28,6 +28,7 @@
#ifdef ES_ENABLE_PARTICLES
#include "../renderer/plugins/ParticlePlugin.hpp"
#include "../particle/ParticleSystem.hpp"
+#include "RandomSource.hpp"
#endif
#include "../renderer/plugins/TrailPlugin.hpp"
#include "../trail/TrailSystem.hpp"
@@ -176,8 +177,15 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
// they are already present.
registerLogicSystems();
+ // Before the systems that draw from it: a consumer takes its stream at
+ // registration, so the seed has to be the engine's before anyone asks.
+ auto randomSource = makeUnique<RandomSource>();
+ // A seed the SDK set before this context existed (see setPendingRandomSeed).
+ if (u32 pending = 0; takePendingRandomSeed(pending)) randomSource->reseed(pending);
+ services_.registerOwned<RandomSource>(std::move(randomSource));
#ifdef ES_ENABLE_PARTICLES
services_.registerOwned<particle::ParticleSystem>(makeUnique<particle::ParticleSystem>());
+ services_.getService<particle::ParticleSystem>()->reseedFrom(*services_.getService<RandomSource>());
#endif
services_.registerOwned<trail::TrailSystem>(makeUnique<trail::TrailSystem>());
diff --git a/src/esengine/core/RandomSource.cpp b/src/esengine/core/RandomSource.cpp
new file mode 100644
index 000000000..47e054ab0
--- /dev/null
+++ b/src/esengine/core/RandomSource.cpp
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "RandomSource.hpp"
+
+namespace esengine {
+namespace {
+bool g_hasPendingSeed = false;
+u32 g_pendingSeed = 0;
+} // namespace
+
+void setPendingRandomSeed(u32 seed) {
+ g_hasPendingSeed = true;
+ g_pendingSeed = seed;
+}
+
+bool takePendingRandomSeed(u32& out) {
+ if (!g_hasPendingSeed) return false;
+ out = g_pendingSeed;
+ return true;
+}
+
+} // namespace esengine
diff --git a/src/esengine/core/RandomSource.hpp b/src/esengine/core/RandomSource.hpp
new file mode 100644
index 000000000..6e48118db
--- /dev/null
+++ b/src/esengine/core/RandomSource.hpp
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#pragma once
+
+/**
+ * @file RandomSource.hpp
+ * @brief The engine's randomness, and the only place its seed lives.
+ *
+ * Seeded from the clock, so a game nobody configured varies from run to run —
+ * which is what a player wants of particles. Reseeded on demand, so one run can
+ * be reproduced: a replay, a bug report, a pixel assertion about a frame.
+ *
+ * A consumer takes a NAMED stream rather than sharing one generator. Sharing
+ * makes every subsystem's sequence depend on how many numbers its neighbours
+ * drew, so adding an emitter would change what the AI rolled and a seed would
+ * stop meaning anything. The name is folded into the root instead, so streams
+ * are independent of each other and stable as the engine grows.
+ */
+
+#include <chrono>
+#include <random>
+#include <string_view>
+
+#include "Types.hpp"
+
+namespace esengine {
+
+class RandomSource {
+public:
+ RandomSource()
+ : root_(static_cast<u32>(std::chrono::steady_clock::now().time_since_epoch().count())) {}
+
+ explicit RandomSource(u32 root) : root_(root) {}
+
+ /** Make every stream taken from here on reproduce from `root`. */
+ void reseed(u32 root) { root_ = root; }
+
+ u32 root() const { return root_; }
+
+ /** An independent generator for `name`, the same one every time for a root. */
+ std::mt19937 stream(std::string_view name) const {
+ // FNV-1a over the name, mixed with the root: cheap, stable across builds,
+ // and it does not care what order the streams are asked for.
+ u32 h = 2166136261u;
+ for (const char c : name) {
+ h ^= static_cast<u8>(c);
+ h *= 16777619u;
+ }
+ return std::mt19937(h ^ root_);
+ }
+
+private:
+ u32 root_;
+};
+
+/**
+ * A seed set before the engine had a RandomSource to put it in. The SDK sets it
+ * beside the colour space — pre-init on purpose, so shaders and spawns both see
+ * the run's configuration — and {@link EstellaContext} adopts it on creation.
+ */
+void setPendingRandomSeed(u32 seed);
+/** The pending seed, or nothing when the run was never given one. */
+bool takePendingRandomSeed(u32& out);
+
+} // namespace esengine
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index c6dfd3e55..16ed57a8b 100644
--- a/src/esengine/particle/ParticleSystem.cpp
+++ b/src/esengine/particle/ParticleSystem.cpp
@@ -7,10 +7,15 @@
#include <chrono>
#include <cmath>
+#include "../core/RandomSource.hpp"
+
namespace esengine::particle {
-ParticleSystem::ParticleSystem()
- : rng_(static_cast<u32>(std::chrono::steady_clock::now().time_since_epoch().count())) {
+ParticleSystem::ParticleSystem() : rng_(RandomSource().stream(kRandomStream)) {
+}
+
+void ParticleSystem::reseedFrom(const esengine::RandomSource& source) {
+ rng_ = source.stream(kRandomStream);
}
void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
diff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hpp
index 31afc89d5..c0a45d36c 100644
--- a/src/esengine/particle/ParticleSystem.hpp
+++ b/src/esengine/particle/ParticleSystem.hpp
@@ -17,6 +17,8 @@
#include <random>
#include <array>
+namespace esengine { class RandomSource; }
+
namespace esengine::particle {
// Resolution of the per-emitter over-life lookup tables (baked in TS from a
@@ -66,8 +68,15 @@ struct EmitterState {
class ParticleSystem {
public:
+ /** The engine stream this system draws from — see core/RandomSource.hpp. */
+ static constexpr const char* kRandomStream = "particles";
+
ParticleSystem();
+ /** Re-derive this system's generator from the engine's seed. Spawns after
+ * this point reproduce; particles already alive keep the values they got. */
+ void reseedFrom(const esengine::RandomSource& source);
+
void update(ecs::Registry& registry, f32 dt);
void play(Entity entity);
@@ -110,6 +119,7 @@ private:
const ColorLut* colorLut, const SizeLut* sizeLut,
glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace);
f32 randomRange(f32 min, f32 max);
+
glm::vec2 randomDirection(f32 angleMin, f32 angleMax);
glm::vec2 randomShapeOffset(const ecs::ParticleEmitter& emitter);
diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjs
index 44f45793a..e9d3193b1 100644
--- a/tools/goldenProjects.mjs
+++ b/tools/goldenProjects.mjs
@@ -105,6 +105,11 @@ export const GOLDEN = [
// Two textured platforms and the sky behind them. Measured over three runs
// and stable to the byte; the falling player is NOT, which is why it is not
// here. A frame that lost its textures still spreads, and still fails these.
+ //
+ // macOS only, and that is a FINDING: Linux reads an exact sRGB encode of
+ // these on all three points, because WebGPUDevice takes `caps.formats[0]`
+ // and so the surface's sRGB-ness is the driver's answer, not the engine's.
+ desktopPixelsHosts: ['macos'],
desktopPixels: [
{ x: 0.30, y: 0.35, rgb: [121, 76, 32], tol: 12 },
{ x: 0.70, y: 0.20, rgb: [121, 76, 32], tol: 12 },
@@ -348,8 +353,16 @@ export function atlasFor(g) {
* texture and cleared to a gradient passes that, so what drew has to be asked
* for. `x`/`y` are fractions of the surface, `y` from the top.
*/
-export function desktopPixels(g) {
- return g?.desktopPixels ?? null;
+export function desktopPixels(g, host) {
+ if (!g?.desktopPixels) return null;
+ const hosts = g.desktopPixelsHosts;
+ return !hosts || hosts.includes(host) ? g.desktopPixels : null;
+}
+
+/** Why a project's points were skipped on this host, for the run to print. */
+export function desktopPixelsSkip(g, host) {
+ if (!g?.desktopPixels || !g.desktopPixelsHosts || g.desktopPixelsHosts.includes(host)) return null;
+ return `${g.id}: points hold on ${g.desktopPixelsHosts.join(', ')}, not ${host}`;
}
/** Absolute path to a golden project's directory. */
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 7236d5778..622087582 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -59,7 +59,10 @@ export const SCENES = [
{ id: "video", tier: "nightly", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SETTLE_MS: "2500", ESTELLA_VERIFY_SCENE: "/scenes/video-playback.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/video-playback.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":90},{\"x\":0.5,\"y\":0.75,\"rgb\":[0,0,255],\"tol\":90}]" } },
{ id: "video-ui", tier: "nightly", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SETTLE_MS: "2500", ESTELLA_VERIFY_SCENE: "/scenes/video-ui.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/video-ui.textures.json", ESTELLA_VERIFY_W: "800", ESTELLA_VERIFY_H: "600", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.25,\"rgb\":[255,0,0],\"tol\":90},{\"x\":0.5,\"y\":0.75,\"rgb\":[0,0,255],\"tol\":90}]" } },
{ id: "spine", tier: "nightly", rendersOnly: "measured: of 2025 sampled points, none sits in a region flat enough to survive CI's rasterizer — the skeleton has no interior that wide", env: { ESTELLA_VERIFY_SCENE: "/scenes/spine-test.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/spine-test.textures.json" } },
- { id: "particles", tier: "nightly", rendersOnly: "measured: 171 of 2025 points differ between two runs at the same step count, so nothing here is a constant to assert", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-demo.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-demo.textures.json", ESTELLA_VERIFY_STEPS: "90" } },
+ // Seeded on purpose: unseeded, 171 of 2025 sampled points differ between two
+ // runs at the same step count, and a run nobody can reproduce is a run whose
+ // failures cannot be told apart from its variety.
+ { id: "particles", tier: "nightly", rendersOnly: "seeded it reproduces exactly, but its particles are single points — no region is flat enough for a probe to survive CI's rasterizer", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-demo.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-demo.textures.json", ESTELLA_VERIFY_STEPS: "90", ESTELLA_VERIFY_SEED: "1234" } },
{ id: "particles-gradient", tier: "nightly", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gradient.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gradient.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":90}]" } },
{ id: "particles-sizecurve", tier: "nightly", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-sizecurve.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-sizecurve.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":110},{\"x\":0.28,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":50}]" } },
// The bright centre the chain leaves, and a corner it does not reach. Three
diff --git a/tools/verify-desktop-render.mjs b/tools/verify-desktop-render.mjs
index 2bf0e71b8..27fc02f48 100644
--- a/tools/verify-desktop-render.mjs
+++ b/tools/verify-desktop-render.mjs
@@ -28,7 +28,7 @@ import { tmpdir } from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { installedTemplateDir } from '../build-tools/utils/nativeTemplate.js';
-import { atTier, projectDir, GOLDEN, desktopPixels } from './goldenProjects.mjs';
+import { atTier, projectDir, GOLDEN, desktopPixels, desktopPixelsSkip } from './goldenProjects.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const HOST_OS = process.platform === 'darwin' ? 'macos' : process.platform === 'win32' ? 'windows' : 'linux';
@@ -116,7 +116,7 @@ function packageAndRun(project, templateDir, work) {
/** What a golden project says its packaged frame must contain, or null. */
function desktopPixelsFor(id) {
try {
- return desktopPixels(GOLDEN.find((g) => g.id === id));
+ return desktopPixels(GOLDEN.find((g) => g.id === id), HOST_OS);
} catch {
return null;
}
@@ -182,6 +182,10 @@ try {
failed += 1;
} else {
const points = desktopPixelsFor(label);
+ // Never silently: a check that does not run has to say so where the
+ // result is read, or its absence reads as a pass.
+ const skipped = desktopPixelsSkip(GOLDEN.find((g) => g.id === label), HOST_OS);
+ if (skipped) console.log(` … ${skipped}`);
const probes = points ? probePixels(result.raw, verdict, result.output, points) : [];
const bad = probes.filter((r) => !r.ok);
if (bad.length > 0) {