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(editor): Preview FX covers trails; timing edits restart the emitter

yhh6a2f9ba17da6
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 05f6645a2..de911871c 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -135,12 +135,12 @@ export class SceneCommandsImpl {
// value read at `endGesture`, and the pair recorded as one model-op step.
private gesture: { label: string; touched: Map<string, FieldEdit> } | null = null;
- // Optional observer/interceptor on the field-edit door — the Sequencer's record
- // mode registers it to auto-key edits. Returning true
- // SUPPRESSES the scene write (reserved for future non-destructive record);
- // the recorder returns false (observe-only) so the edit still lands normally.
- // Kept generic: SceneCommands knows nothing about timelines.
- private editHook: EditHook | null = null;
+ // Observers/interceptors on the field-edit door — the Sequencer's record mode
+ // auto-keys edits, the FX preview restarts emitters on timing edits. Any hook
+ // returning true SUPPRESSES the scene write (reserved for future
+ // non-destructive record); observers return false so the edit lands normally.
+ // Kept generic: SceneCommands knows nothing about the consumers.
+ private readonly editHooks = new Set<EditHook>();
// An in-progress tilemap paint stroke: the chunk blob snapshotted at stroke start
// ({@link beginTilePaint}), committed as one undo step at {@link endTilePaint}.
private tilePaint: { sourceId: number; before: string } | null = null;
@@ -150,9 +150,10 @@ export class SceneCommandsImpl {
private readonly history: EditorHistoryImpl,
) {}
- /** Register (or clear) the field-edit hook. One slot; last writer wins. */
- setEditHook(fn: EditHook | null): void {
- this.editHook = fn;
+ /** Register a field-edit hook; returns the unsubscribe. */
+ addEditHook(fn: EditHook): () => void {
+ this.editHooks.add(fn);
+ return () => this.editHooks.delete(fn);
}
/** The current model value of one field, or undefined. */
@@ -250,8 +251,13 @@ export class SceneCommandsImpl {
type: InspectorFieldType,
value: InspectorFieldValue,
): void {
- // The edit hook (Sequencer record) may observe — or, returning true, suppress.
- if (this.editHook && this.editHook(sourceId, compName, key, type, value)) return;
+ // Edit hooks may observe — or, any returning true, suppress. Evaluated
+ // eagerly (no short-circuit) so every observer sees every edit.
+ let suppressed = false;
+ for (const hook of this.editHooks) {
+ if (hook(sourceId, compName, key, type, value)) suppressed = true;
+ }
+ if (suppressed) return;
// Flipping a UINode to Absolute bakes its current layout box into concrete px
// insets (below) so it holds its on-screen spot and gains a real, draggable
diff --git a/desktop/src/engine/fxPreview.ts b/desktop/src/engine/fxPreview.ts
index ffe17ba31..7e09ac792 100644
--- a/desktop/src/engine/fxPreview.ts
+++ b/desktop/src/engine/fxPreview.ts
@@ -3,25 +3,67 @@
/**
* @file fxPreview.ts
* @brief Applies the editor's FX-preview toggle to the live engine: flips the
- * SDK's edit-preview flag (which unfreezes the particle sim in edit
- * mode) and restarts every emitter so both edges are clean — enabling
- * replays from t=0, disabling clears residue instead of freezing
- * particles mid-air.
+ * SDK's edit-preview flag (which unfreezes the particle + trail sims in
+ * edit mode) and restarts every effect so both edges are clean —
+ * enabling replays from t=0, disabling clears residue instead of
+ * freezing particles mid-air / stranding trail streaks. Also wires the
+ * Details-edit glue: editing a cycle-timing emitter field restarts that
+ * emitter, because those fields only manifest at cycle start (everything
+ * else — rate, colors, shape — already applies live to the running sim).
*/
-import { setParticleEditPreview, Particle, ParticleEmitter } from 'esengine';
+import { setFxEditPreview, Particle, ParticleEmitter, Trail, TrailRenderer } from 'esengine';
import { EngineHost } from './EngineHost';
+import { SceneCommands } from './SceneCommands';
+import { SceneModel } from './SceneModel';
+import { useEditorStore } from '@/store/editorStore';
export function applyFxPreview(enabled: boolean): void {
- setParticleEditPreview(enabled);
+ setFxEditPreview(enabled);
const world = EngineHost.world;
+ if (!world) return;
const particle = EngineHost.getResource(Particle);
- if (!world || !particle) return;
- for (const e of world.getEntitiesWithComponents([ParticleEmitter])) {
- particle.reset(e);
- // reset() lowers the playing flag and the lazy first-update auto-play
- // was already consumed, so a playOnStart emitter is re-kicked by hand.
- if (enabled && (world.get(e, ParticleEmitter) as { playOnStart?: boolean }).playOnStart) {
- particle.play(e);
+ if (particle) {
+ for (const e of world.getEntitiesWithComponents([ParticleEmitter])) {
+ particle.reset(e);
+ // reset() lowers the playing flag and the lazy first-update auto-play
+ // was already consumed, so a playOnStart emitter is re-kicked by hand.
+ if (enabled && (world.get(e, ParticleEmitter) as { playOnStart?: boolean }).playOnStart) {
+ particle.play(e);
+ }
}
}
+ const trail = EngineHost.getResource(Trail);
+ if (trail) {
+ for (const e of world.getEntitiesWithComponents([TrailRenderer])) {
+ trail.clear(e);
+ }
+ }
+}
+
+// Emitter fields that only manifest when a cycle starts — a live sim shows an
+// edit to them only after a restart. Everything else applies continuously.
+const CYCLE_TIMING_FIELDS = new Set(['duration', 'looping', 'playOnStart', 'burstCount', 'burstInterval']);
+
+/** Wire the Details-edit → emitter-restart glue (call once at editor boot). */
+export function initFxPreviewEditRestart(): void {
+ SceneCommands.addEditHook((sourceId, compName, key) => {
+ if (compName === 'ParticleEmitter' && CYCLE_TIMING_FIELDS.has(key)
+ && useEditorStore.getState().previewFx) {
+ // The hook fires BEFORE the write lands; restart after it has, so
+ // the replay runs with the edited value (playOnStart included).
+ queueMicrotask(() => restartEmitter(sourceId));
+ }
+ return false; // observe-only
+ });
+}
+
+function restartEmitter(sourceId: number): void {
+ const rt = SceneModel.runtimeFor(sourceId);
+ const world = EngineHost.world;
+ const particle = EngineHost.getResource(Particle);
+ if (rt == null || !world || !particle || !world.has(rt, ParticleEmitter)) return;
+ particle.reset(rt);
+ if ((world.get(rt, ParticleEmitter) as { playOnStart?: boolean }).playOnStart) {
+ particle.play(rt);
+ }
}
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 7e1718e54..1d7d67409 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -43,7 +43,7 @@ import { EditorControlSurface } from './engine/EditorSession';
import { SceneModel } from './engine/SceneModel';
import { EngineHost } from './engine/EngineHost';
import { UINode, UIVisual, Particle } from 'esengine';
-import { applyFxPreview } from './engine/fxPreview';
+import { applyFxPreview, initFxPreviewEditRestart } from './engine/fxPreview';
import { commands } from './commands/registry';
import { ViewportController } from './engine/ViewportController';
import { PerfMonitor } from './engine/PerfMonitor';
@@ -65,8 +65,10 @@ initFsWatch();
initBackgroundThrottle();
// Sync the FX-preview default into the engine flag before anything boots (the
-// flag is module-scoped; emitters auto-play lazily once a scene loads).
+// flag is module-scoped; emitters auto-play lazily once a scene loads), and
+// wire the Details-edit → emitter-restart glue.
applyFxPreview(useEditorStore.getState().previewFx);
+initFxPreviewEditRestart();
// Automation hook (screenshots / visual-regression): with `?automation=1`, expose the
// minimum to drive the launcher→editor flow from a headless driver. Gated so the normal
diff --git a/desktop/src/timeline/TimelineRecorder.ts b/desktop/src/timeline/TimelineRecorder.ts
index 7de3360dc..4cc8e134a 100644
--- a/desktop/src/timeline/TimelineRecorder.ts
+++ b/desktop/src/timeline/TimelineRecorder.ts
@@ -57,7 +57,7 @@ class TimelineRecorderImpl {
attach(): void {
if (this.attached) return;
this.attached = true;
- SceneCommands.setEditHook((sourceId, compName, key, type, value) =>
+ SceneCommands.addEditHook((sourceId, compName, key, type, value) =>
this.onEdit(sourceId, compName, key, type, value),
);
// Flush the pending burst the moment recording is switched off.
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
index 770a52bdf..ef6f0701b 100644
--- a/docs/astro/src/content/docs/guides/particle.mdx
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -33,8 +33,9 @@ curve by default, or a full **gradient/curve** for precise control (see below).
Particle simulation is **gameplay**: it advances in play mode and in the
standalone runtime, and is frozen in the editor's edit mode (like physics,
animation, and timelines) — with one authoring exception: the editor's
- **Preview FX** toggle (toolbar ✨, on by default) simulates emitters live
- while you tune them, no Play needed. Re-toggling it replays from t=0.
+ **Preview FX** toggle (toolbar ✨, on by default) simulates emitters (and
+ motion trails) live while you tune them, no Play needed. Cycle-timing edits
+ (duration, bursts, looping) restart the emitter; re-toggling replays from t=0.
</Aside>
## Setup
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
index 9787298aa..2490a4ca0 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -28,7 +28,8 @@ CPU 模拟粒子,并按发射器**GPU 实例化**为单次 draw call 渲染,所
<Aside type="note">
粒子模拟属于**玩法**:它在播放模式和独立运行时里推进,在编辑器编辑模式下冻结(与物理、
动画、时间轴一致)——唯一的创作例外是编辑器的 **Preview FX** 开关(工具栏 ✨,默认开):
- 调参的同时发射器实时模拟,不用进 Play。重新切换 = 从 t=0 重播。
+ 调参的同时发射器(和运动拖尾)实时模拟,不用进 Play。周期时序类编辑(duration、
+ burst、looping)会自动重启该发射器;重新切换开关 = 全部从 t=0 重播。
</Aside>
## 安装
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index cf786288c..c10dfac08 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1119 stable · 17 beta · 1 deprecated
+Symbols: 1120 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -1921,7 +1921,7 @@ world: World
```
EstellaContext: new () => CppEngineContext
FS: EmscriptenFS
-GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
+GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; contexts?: ({ GLctx: WebGLRenderingContext | WebGL2RenderingContext; } | null)[]; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
HEAPF32: Float32Array<ArrayBufferLike>
HEAPU32: Uint32Array<ArrayBufferLike>
HEAPU8: Uint8Array<ArrayBufferLike>
@@ -7555,6 +7555,11 @@ FocusPlugin
FsmPlugin
```
+## fxPreviewOrPlayMode — function
+```
+(): boolean
+```
+
## getAddressableType — function
```
(path: string): AddressableAssetType | null
@@ -7875,14 +7880,14 @@ InputRouter
(world: World, entity: Entity): boolean
```
-## isKnownAssetExtension — function
+## isFxEditPreview — function
```
-(ext: string): boolean
+(): boolean
```
-## isParticleEditPreview — function
+## isKnownAssetExtension — function
```
-(): boolean
+(ext: string): boolean
```
## isPlatformInitialized — function
@@ -8470,6 +8475,11 @@ Plugin
(world: World, entity: Entity, visible: boolean): void
```
+## setFxEditPreview — function
+```
+(enabled: boolean): void
+```
+
## setImageResolver — function
```
(resolver: ImageResolver | null): void
@@ -8490,11 +8500,6 @@ Plugin
(world: World, entity: Entity, target: Vec2): void
```
-## setParticleEditPreview — function
-```
-(enabled: boolean): void
-```
-
## setPlayMode — function
```
(active: boolean): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 0ce80266a..b2d8d1abd 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1118 stable · 19 beta · 1 deprecated
+Symbols: 1119 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -1916,7 +1916,7 @@ world: World
```
EstellaContext: new () => CppEngineContext
FS: EmscriptenFS
-GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
+GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; contexts?: ({ GLctx: WebGLRenderingContext | WebGL2RenderingContext; } | null)[]; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
HEAPF32: Float32Array<ArrayBufferLike>
HEAPU32: Uint32Array<ArrayBufferLike>
HEAPU8: Uint8Array<ArrayBufferLike>
@@ -7550,6 +7550,11 @@ FocusPlugin
FsmPlugin
```
+## fxPreviewOrPlayMode — function
+```
+(): boolean
+```
+
## getAddressableType — function
```
(path: string): AddressableAssetType | null
@@ -7870,14 +7875,14 @@ InputRouter
(world: World, entity: Entity): boolean
```
-## isKnownAssetExtension — function
+## isFxEditPreview — function
```
-(ext: string): boolean
+(): boolean
```
-## isParticleEditPreview — function
+## isKnownAssetExtension — function
```
-(): boolean
+(ext: string): boolean
```
## isPlatformInitialized — function
@@ -8475,6 +8480,11 @@ Plugin
(world: World, entity: Entity, visible: boolean): void
```
+## setFxEditPreview — function
+```
+(enabled: boolean): void
+```
+
## setImageResolver — function
```
(resolver: ImageResolver | null): void
@@ -8495,11 +8505,6 @@ Plugin
(world: World, entity: Entity, target: Vec2): void
```
-## setParticleEditPreview — function
-```
-(enabled: boolean): void
-```
-
## setPlayMode — function
```
(active: boolean): void
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 74019ff82..2d14a7c45 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -169,7 +169,7 @@ updateTextureSubregion: (handle: number, x: number, y: number, width: number, he
```
EstellaContext: new () => CppEngineContext
FS: EmscriptenFS
-GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
+GL: { registerContext(ctx: WebGLRenderingContext | WebGL2RenderingContext, options: { majorVersion: number; minorVersion: number; enableExtensionsByDefault?: boolean; }): number; currentContext?: { GLctx: WebGLRenderingContext | WebGL2RenderingContext; }; contexts?: ({ GLctx: WebGLRenderingContext | WebGL2RenderingContext; } | null)[]; getNewId(pool: Record<number, unknown>): number; textures: Record<number, WebGLTexture>; }
HEAPF32: Float32Array<ArrayBufferLike>
HEAPU32: Uint32Array<ArrayBufferLike>
HEAPU8: Uint8Array<ArrayBufferLike>
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 805f5ce80..ccf493bd4 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -308,8 +308,6 @@ export {
ParticleAPI,
ParticlePlugin,
particlePlugin,
- setParticleEditPreview,
- isParticleEditPreview,
} from './particle';
// =============================================================================
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 730c58710..629ef64db 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -370,6 +370,9 @@ export {
setPlayMode,
isPlayMode,
playModeOnly,
+ setFxEditPreview,
+ isFxEditPreview,
+ fxPreviewOrPlayMode,
} from './env';
export type { RunCondition } from './app';
diff --git a/sdk/src/env.ts b/sdk/src/env.ts
index f9adce3e2..aecd95622 100644
--- a/sdk/src/env.ts
+++ b/sdk/src/env.ts
@@ -41,3 +41,26 @@ export function playModeOnly(): boolean {
const ctx = getDefaultContext();
return !ctx.editorMode || ctx.playMode;
}
+
+// FX authoring preview: the ONE exception to the edit-mode freeze — effect
+// simulations (particles, motion trails) may advance in edit mode so they are
+// live while being tuned. Deliberately a module global rather than AppContext
+// state: only an editor's edit realm ever flips it (play realms and shipped
+// runtimes are separate module instances where it stays false and playModeOnly
+// rules alone), and it must survive a context reset (the editor re-syncs its
+// own toggle, not the context lifecycle).
+let fxEditPreview = false;
+
+/** Editor-only: advance FX simulations (particles, trails) in edit mode. */
+export function setFxEditPreview(enabled: boolean): void {
+ fxEditPreview = enabled;
+}
+
+export function isFxEditPreview(): boolean {
+ return fxEditPreview;
+}
+
+/** Run condition for FX systems: gameplay rules, plus the authoring preview. */
+export function fxPreviewOrPlayMode(): boolean {
+ return fxEditPreview || playModeOnly();
+}
diff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.ts
index 3ef5cc747..7f9bbdd50 100644
--- a/sdk/src/particle/ParticlePlugin.ts
+++ b/sdk/src/particle/ParticlePlugin.ts
@@ -4,30 +4,13 @@ import type { App, Plugin } from '../app';
import { defineSystem, Schedule } from '../system';
import { Res } from '../resource';
import { Time, type TimeData } from '../resource';
-import { playModeOnly } from '../env';
+import { fxPreviewOrPlayMode } from '../env';
import type { ESEngineModule, CppRegistry } from '../wasm';
import { registerSceneComponentCodec } from '../scene';
import { Particle, ParticleAPI } from './ParticleAPI';
import { bakeGradient, type Gradient } from './gradient';
import { bakeCurve, type Curve } from './curve';
-// Editor authoring preview: lets the particle simulation advance in EDIT mode
-// too, so emitters are live while they are being tuned. Module-scoped rather
-// than per-App: only an editor's edit realm ever flips it — the play realm and
-// shipped runtimes are separate module instances where it stays false and
-// playModeOnly rules alone.
-let editPreview_ = false;
-
-/** Editor-only: advance the particle simulation in edit mode (live authoring
- * preview). No effect outside an editor (playModeOnly already passes there). */
-export function setParticleEditPreview(enabled: boolean): void {
- editPreview_ = enabled;
-}
-
-export function isParticleEditPreview(): boolean {
- return editPreview_;
-}
-
export class ParticlePlugin implements Plugin {
name = 'particle';
@@ -69,14 +52,14 @@ export class ParticlePlugin implements Plugin {
// Particle advance is gameplay — frozen in editor edit mode, runs in
// play mode / standalone runtime (matches animation/physics/timeline).
- // The edit-preview flag is the one authoring exception (see above).
+ // The FX edit-preview flag is the one authoring exception (env.ts).
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Particle)],
(time: TimeData, particle: ParticleAPI) => {
particle.update(time.delta);
},
{ name: 'ParticleSystem' }
- ), { runIf: () => editPreview_ || playModeOnly() });
+ ), { runIf: fxPreviewOrPlayMode });
}
}
diff --git a/sdk/src/particle/index.ts b/sdk/src/particle/index.ts
index a7117ade9..42a919d26 100644
--- a/sdk/src/particle/index.ts
+++ b/sdk/src/particle/index.ts
@@ -1,11 +1,6 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
export { Particle, ParticleAPI } from './ParticleAPI';
-export {
- ParticlePlugin,
- particlePlugin,
- setParticleEditPreview,
- isParticleEditPreview,
-} from './ParticlePlugin';
+export { ParticlePlugin, particlePlugin } from './ParticlePlugin';
export { bakeGradient, GRADIENT_LUT_SIZE, type Gradient, type GradientStop } from './gradient';
export { bakeCurve, type Curve, type CurveKey } from './curve';
diff --git a/sdk/src/trail/TrailPlugin.ts b/sdk/src/trail/TrailPlugin.ts
index 0f581af45..a4383270f 100644
--- a/sdk/src/trail/TrailPlugin.ts
+++ b/sdk/src/trail/TrailPlugin.ts
@@ -4,7 +4,7 @@ import type { App, Plugin } from '../app';
import { defineSystem, Schedule } from '../system';
import { Res } from '../resource';
import { Time, type TimeData } from '../resource';
-import { playModeOnly } from '../env';
+import { fxPreviewOrPlayMode } from '../env';
import type { ESEngineModule, CppRegistry } from '../wasm';
import { Trail, TrailAPI } from './TrailAPI';
@@ -19,13 +19,15 @@ export class TrailPlugin implements Plugin {
// Trail point recording is gameplay — frozen in editor edit mode, runs in
// play mode / standalone runtime (matches particles/animation/physics).
+ // The FX edit-preview flag is the one authoring exception (env.ts):
+ // with it on, dragging an entity in the viewport draws its trail live.
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Trail)],
(time: TimeData, trail: TrailAPI) => {
trail.update(time.delta);
},
{ name: 'TrailSystem' }
- ), { runIf: playModeOnly });
+ ), { runIf: fxPreviewOrPlayMode });
}
}
diff --git a/sdk/tests/fx-edit-preview.test.ts b/sdk/tests/fx-edit-preview.test.ts
new file mode 100644
index 000000000..8663cd5a1
--- /dev/null
+++ b/sdk/tests/fx-edit-preview.test.ts
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * FX edit preview: particle and trail simulations stay frozen in editor edit
+ * mode by default (the playModeOnly contract), and the editor-only FX-preview
+ * flag (env.ts) is the one authoring exception — flipping it advances BOTH
+ * sims live while effects are being tuned. Outside an editor the flag is
+ * irrelevant.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { App } from '../src/app';
+import { setEditorMode, setPlayMode, setFxEditPreview, isFxEditPreview } from '../src/env';
+import { particlePlugin, Particle } from '../src/particle';
+import { trailPlugin, Trail } from '../src/trail';
+
+const STEP = 1 / 60;
+
+afterEach(() => {
+ setEditorMode(false);
+ setPlayMode(false);
+ setFxEditPreview(false);
+});
+
+function makeApp(): { app: App; particleUpdates: () => number; trailUpdates: () => number } {
+ const app = App.new();
+ app.addPlugin(particlePlugin);
+ app.addPlugin(trailPlugin);
+ let particles = 0;
+ let trails = 0;
+ app.getResource(Particle).update = () => { particles++; };
+ app.getResource(Trail).update = () => { trails++; };
+ return { app, particleUpdates: () => particles, trailUpdates: () => trails };
+}
+
+describe('FX edit preview (particles + trails share the env flag)', () => {
+ it('edit mode: frozen by default, both sims live while the preview flag is on', async () => {
+ setEditorMode(true);
+ const { app, particleUpdates, trailUpdates } = makeApp();
+
+ await app.tick(STEP);
+ expect(particleUpdates()).toBe(0); // edit mode → gameplay frozen (unchanged)
+ expect(trailUpdates()).toBe(0);
+
+ setFxEditPreview(true);
+ expect(isFxEditPreview()).toBe(true);
+ await app.tick(STEP);
+ expect(particleUpdates()).toBe(1); // the preview unfreezes the FX sims only
+ expect(trailUpdates()).toBe(1);
+
+ setFxEditPreview(false);
+ await app.tick(STEP);
+ expect(particleUpdates()).toBe(1); // re-freezes
+ expect(trailUpdates()).toBe(1);
+ });
+
+ it('play mode and standalone runtime are untouched by the flag', async () => {
+ const { app, particleUpdates, trailUpdates } = makeApp();
+ await app.tick(STEP);
+ expect(particleUpdates()).toBe(1); // standalone: playModeOnly already passes
+ expect(trailUpdates()).toBe(1);
+
+ setEditorMode(true);
+ setPlayMode(true);
+ await app.tick(STEP);
+ expect(particleUpdates()).toBe(2); // editor play mode: runs regardless of the flag
+ expect(trailUpdates()).toBe(2);
+ });
+});
diff --git a/sdk/tests/particle-edit-preview.test.ts b/sdk/tests/particle-edit-preview.test.ts
deleted file mode 100644
index 763e57dbf..000000000
--- a/sdk/tests/particle-edit-preview.test.ts
+++ /dev/null
@@ -1,62 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-/**
- * Edit-mode particle preview: the simulation stays frozen in editor edit mode
- * by default (the playModeOnly contract), and the editor-only preview flag is
- * the one authoring exception — flipping it advances the sim live while
- * emitters are being tuned. Outside an editor the flag is irrelevant.
- */
-import { describe, it, expect, afterEach } from 'vitest';
-import { App } from '../src/app';
-import { setEditorMode, setPlayMode } from '../src/env';
-import {
- particlePlugin, Particle,
- setParticleEditPreview, isParticleEditPreview,
-} from '../src/particle';
-
-const STEP = 1 / 60;
-
-afterEach(() => {
- setEditorMode(false);
- setPlayMode(false);
- setParticleEditPreview(false);
-});
-
-function makeApp(): { app: App; updates: () => number } {
- const app = App.new();
- app.addPlugin(particlePlugin);
- let count = 0;
- const api = app.getResource(Particle);
- api.update = () => { count++; };
- return { app, updates: () => count };
-}
-
-describe('particle edit preview', () => {
- it('edit mode: frozen by default, live while the preview flag is on', async () => {
- setEditorMode(true);
- const { app, updates } = makeApp();
-
- await app.tick(STEP);
- expect(updates()).toBe(0); // edit mode → gameplay frozen (unchanged)
-
- setParticleEditPreview(true);
- expect(isParticleEditPreview()).toBe(true);
- await app.tick(STEP);
- expect(updates()).toBe(1); // preview unfreezes the sim only
-
- setParticleEditPreview(false);
- await app.tick(STEP);
- expect(updates()).toBe(1); // re-freezes
- });
-
- it('play mode and standalone runtime are untouched by the flag', async () => {
- const { app, updates } = makeApp();
- await app.tick(STEP);
- expect(updates()).toBe(1); // standalone: playModeOnly already passes
-
- setEditorMode(true);
- setPlayMode(true);
- await app.tick(STEP);
- expect(updates()).toBe(2); // editor play mode: runs regardless of the flag
- });
-});