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(engine): one place a seed lives, and particles draw from it
esengineb8e68e525d59
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmakeindex 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.cppdiff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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.tsindex 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.wasmdiff --git a/desktop/src/headless.ts b/desktop/src/headless.tsindex 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.mdindex 3f08779bc..da54cf5bf 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2069,6 +2069,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefined@@ -2619,6 +2620,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 821c5930a..e7d1bf98d 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -2077,6 +2077,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefined@@ -2627,6 +2628,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 4b25237d6..12724afe6 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefined@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex eda685b2c..6b52ee757 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefined@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 8f1115efe..6b44422cc 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -218,6 +218,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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: () => numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex a13436261..a3044a158 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2064,6 +2064,7 @@ colorSpace: "gamma" | "linear" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefined@@ -2614,6 +2615,7 @@ engine_getCounters: (() => string) | undefinedengine_getCpuScopes: (() => string) | undefinedengine_getGpuScopes: (() => string) | undefinedengine_setCpuProfiling: ((on: boolean) => void) | undefined+engine_setRandomSeed: ((seed: number) => void) | undefinedes_getMallocBytes: (() => number) | undefinedesshader_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" | undefineddepthLayers: number | undefinedgetViewportSize: (() => { width: number; height: number; }) | undefinedplugins: Plugin[] | undefined+randomSeed: number | undefinedrenderSurface: RenderSurfaceSource | undefinedscreenFit: ScreenScalingData | undefinedsideModules: SideModuleHost | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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.tsindex 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 APIdiff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 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.hppindex 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.cppindex 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.cppindex 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_PARTICLESservices_.registerOwned<particle::ParticleSystem>(makeUnique<particle::ParticleSystem>());+ services_.getService<particle::ParticleSystem>()->reseedFrom(*services_.getService<RandomSource>());#endifservices_.registerOwned<trail::TrailSystem>(makeUnique<trail::TrailSystem>());diff --git a/src/esengine/core/RandomSource.cpp b/src/esengine/core/RandomSource.cppnew file mode 100644index 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 esenginediff --git a/src/esengine/core/RandomSource.hpp b/src/esengine/core/RandomSource.hppnew file mode 100644index 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 esenginediff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cppindex 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.hppindex 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.mjsindex 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.mjsindex 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. Threediff --git a/tools/verify-desktop-render.mjs b/tools/verify-desktop-render.mjsindex 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) {