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.

refactor(sdk): node visibility and particle model units ship in esengine/imported-scene, installed only where the content uses them

yhha9ff8c23bc70
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c11bfeaa8..75e6eac7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ published separately; it ships inside the editor.
### Added
-- **An imported scene keeps its materials, animation, particles and colliders.** A glTF scene brings the materials, animation, particle emitters and physics shapes it describes rather than geometry alone, and a Godot project can export a scene in that form with the bridge script in `pipeline/bridges/godot`.
+- **An imported scene keeps its materials, animation, particles and colliders.** A glTF scene brings the materials, animation, particle emitters and physics shapes it describes rather than geometry alone, and a Godot project can export a scene in that form with the bridge script in `pipeline/bridges/godot`. The two components only an imported scene writes, `NodeVisibility` and `ParticleModelUnits`, live in `esengine/imported-scene`, which an export adds only when the shipped content uses them.
- **A 3D body can be several shapes, and a scaled model collides at its scale.** `CompoundCollider3D` makes one body out of child shapes, on Jolt and PhysX alike, and a mesh collider follows its model's scale.
- **A generated building stands on its ground, and generated roads keep foliage off them.** World generation fits an upright building's base to a grid of ground samples over its whole rotated footprint, and refuses a site that is water, too steep, or rises and falls more than a given relief, reporting how deep the foundation has to reach. Foliage takes the zones a WorldGen world reserves for roads and buildings (and any extra tags) as places it does not grow, with an optional clearance. The world rules editor and the editor's agents can set both.
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 2dd5afd66..d44faee20 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 176,
- "experimental": 2858,
+ "experimental": 2859,
"deprecated": 3
},
- "total": 3149,
+ "total": 3150,
"subsystems": [
{
"id": "mobile-controls",
@@ -393,6 +393,18 @@
"SplineCurve"
]
},
+ {
+ "id": "imported-scene",
+ "title": "Imported scene runtime",
+ "titleZh": "导入场景运行时",
+ "tier": "experimental",
+ "why": "what a glTF scene brings beside geometry, a node shown or hidden by its animation and particles authored in model units, is checked against the importer, but only imported scenes write it so far",
+ "whyZh": "glTF 场景在几何体之外带来的东西(随动画显隐的节点、按模型单位写的粒子)已经和导入器一起检查过,但目前只有导入的场景会写它们",
+ "entry": [
+ "NodeVisibility",
+ "ParticleModelUnits"
+ ]
+ },
{
"id": "water",
"title": "Water",
diff --git a/pipeline/src/assets/gltfPhysics.ts b/pipeline/src/assets/gltfPhysics.ts
index d5498683a..f7fc9a350 100644
--- a/pipeline/src/assets/gltfPhysics.ts
+++ b/pipeline/src/assets/gltfPhysics.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { MeshChannel, MeshChannelType, packChannels, q, type Vec3, type Quat } from 'esengine';
import type { ImportedMesh, ImportedNode, Trs } from './modelImport';
-import type { CompoundColliderPart3D } from 'esengine';
+import type { CompoundColliderPart3D } from 'esengine/physics3d';
interface BodySource {
motion?: { type?: string; mass?: number; [key: string]: unknown };
diff --git a/pipeline/src/assets/modelImport.ts b/pipeline/src/assets/modelImport.ts
index c6cfdf927..21b3b8a2c 100644
--- a/pipeline/src/assets/modelImport.ts
+++ b/pipeline/src/assets/modelImport.ts
@@ -18,7 +18,7 @@ import {
} from 'esengine';
import { canSimplify, simplifyMesh, type SimplifierFlag } from './meshSimplify';
import { SPARSE_LIGHTMAP_UV, OVERLAPPING_LIGHTMAP_UV } from '../../../sdk/src/lightmap/atlas';
-import type { CompoundColliderPart3D } from 'esengine';
+import type { CompoundColliderPart3D } from 'esengine/physics3d';
/** One primitive's worth of geometry, named for the file it will be written to. */
export interface ImportedMesh {
diff --git a/pipeline/src/bundle/engineSubpaths.ts b/pipeline/src/bundle/engineSubpaths.ts
index 232fa5adb..7004d9264 100644
--- a/pipeline/src/bundle/engineSubpaths.ts
+++ b/pipeline/src/bundle/engineSubpaths.ts
@@ -21,6 +21,7 @@ export const ESENGINE_SUBPATHS: Readonly<Record<string, string>> = {
'esengine/worldgen': 'worldgen/index.js',
'esengine/water': 'water/index.js',
'esengine/spline': 'spline/index.js',
+ 'esengine/imported-scene': 'imported-scene/index.js',
'esengine/character-shaders': 'character-shaders/index.js',
'esengine/logic': 'logic/index.js',
'esengine/debug-channel': 'debug-channel/index.js',
diff --git a/pipeline/src/project/targetSupport.ts b/pipeline/src/project/targetSupport.ts
index dd4642872..1904f664c 100644
--- a/pipeline/src/project/targetSupport.ts
+++ b/pipeline/src/project/targetSupport.ts
@@ -27,7 +27,7 @@ import { NATIVE_PLATFORMS, type ExportPlatform } from './platforms';
/** An engine subsystem a build target may lack. */
export type Subsystem =
- | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
+ | 'text' | 'tilemap' | 'terrain' | 'foliage' | 'worldgen' | 'water' | 'spline' | 'importedScene' | 'characterShaders' | 'timeline' | 'fxBasic' | 'fxAtmosphere' | 'fxLighting' | 'particles' | 'postprocess' | 'physics' | 'physics3d'
| 'spine' | 'dragonbones' | 'video' | 'ai' | 'logic' | 'replication' | 'gameplay';
/**
@@ -49,6 +49,7 @@ export const SUBSYSTEM_COMPONENTS: Readonly<Record<Subsystem, readonly string[]>
worldgen: ['WorldGen', 'WorldZone'],
water: ['WaterBody', 'WaterZone', 'Floating'],
spline: ['Spline', 'PathFollower', 'TerrainBand2D'],
+ importedScene: ['NodeVisibility', 'ParticleModelUnits'],
// Hair, Skin and Eye are shaders, not components: a character's materials are what name them (see SHADER_SUBSYSTEM).
characterShaders: [],
particles: ['ParticleEmitter', 'ParticleForceField'],
@@ -115,6 +116,7 @@ export const SUBSYSTEM_LABEL: Readonly<Record<Subsystem, string>> = {
worldgen: 'Generated worlds (biomes, zones, placement)',
water: 'Water',
spline: 'Splines',
+ importedScene: 'Imported scene (node visibility, particle units)',
characterShaders: 'Character shaders (hair, skin, eye)',
particles: 'Particles',
postprocess: 'Post-processing',
@@ -149,6 +151,7 @@ export const SUBSYSTEM_INSTALL: Readonly<Record<Subsystem, string>> = {
worldgen: 'esengine/worldgen',
water: 'esengine/water',
spline: 'esengine/spline',
+ importedScene: 'esengine/imported-scene',
characterShaders: 'esengine/character-shaders',
physics: 'esengine/physics',
physics3d: 'esengine/physics3d',
diff --git a/pipeline/tests/engine-installs.test.ts b/pipeline/tests/engine-installs.test.ts
index a9839dfe8..ebcf731b6 100644
--- a/pipeline/tests/engine-installs.test.ts
+++ b/pipeline/tests/engine-installs.test.ts
@@ -42,6 +42,10 @@ describe('the engine modules a package installs', () => {
expect(engineInstalls({ subsystems: ['characterShaders'] }).subpaths).toEqual(['esengine/character-shaders']);
});
+ it('takes the imported-scene runtime from what a glTF scene writes, so a game without one carries none', () => {
+ expect(engineInstalls({ subsystems: ['importedScene'] }).subpaths).toEqual(['esengine/imported-scene']);
+ });
+
it('takes splines from a Spline, so a game without one carries none', () => {
expect(engineInstalls({ subsystems: ['spline'] }).subpaths).toEqual(['esengine/spline']);
});
diff --git a/sdk/etc/imported-scene.api.md b/sdk/etc/imported-scene.api.md
new file mode 100644
index 000000000..f7cd36387
--- /dev/null
+++ b/sdk/etc/imported-scene.api.md
@@ -0,0 +1,24 @@
+# API surface — esengine/imported-scene
+
+<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
+Symbols: 0 public · 0 beta · 3 experimental · 0 deprecated
+
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
+## NodeVisibility — const @experimental
+```
+ComponentDef<{ visible: boolean; }>
+```
+
+## ParticleModelUnits — const @experimental
+```
+ComponentDef<{ startSizeMin: number; startSizeMax: number; endSizeMin: number; endSizeMax: number; speedMin: number; speedMax: number; gravity: Vec3; }>
+```
+
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index fee4db8b9..922fb109c 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: 115 public · 164 beta · 2058 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2059 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5187,6 +5187,15 @@ valign: ImageValign
width: number
```
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
## Impostor — const @experimental
```
BuiltinComponentDef<ImpostorData>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8d1c50a2b..24e87a382 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 169 beta · 2077 experimental · 3 deprecated
+Symbols: 115 public · 169 beta · 2078 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5195,6 +5195,15 @@ valign: ImageValign
width: number
```
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
## Impostor — const @experimental
```
BuiltinComponentDef<ImpostorData>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a5acc962a..63c42537a 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: 115 public · 166 beta · 2057 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2058 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5182,6 +5182,15 @@ valign: ImageValign
width: number
```
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
## Impostor — const @experimental
```
BuiltinComponentDef<ImpostorData>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f1d419705..031a339eb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2079 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2080 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5182,6 +5182,15 @@ valign: ImageValign
width: number
```
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
## Impostor — const @experimental
```
BuiltinComponentDef<ImpostorData>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index e4125d527..053254529 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 164 beta · 2070 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2071 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5189,6 +5189,15 @@ valign: ImageValign
width: number
```
+## ImportedScenePlugin — class @experimental
+```
+build: (app: App) => void
+cleanup: () => void
+name: string
+static new (): ImportedScenePlugin
+static prototype: ImportedScenePlugin
+```
+
## Impostor — const @experimental
```
BuiltinComponentDef<ImpostorData>
diff --git a/sdk/package.json b/sdk/package.json
index 9441a6df1..9e7ef9fc5 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -26,6 +26,7 @@
"./dist/worldgen/index.js",
"./dist/water/index.js",
"./dist/spline/index.js",
+ "./dist/imported-scene/index.js",
"./dist/character-shaders/index.js",
"./dist/logic/index.js",
"./dist/debug-channel/index.js",
@@ -119,6 +120,10 @@
"import": "./dist/spline/index.js",
"types": "./dist/spline/index.d.ts"
},
+ "./imported-scene": {
+ "import": "./dist/imported-scene/index.js",
+ "types": "./dist/imported-scene/index.d.ts"
+ },
"./character-shaders": {
"import": "./dist/character-shaders/index.js",
"types": "./dist/character-shaders/index.d.ts"
diff --git a/sdk/rolldown.config.js b/sdk/rolldown.config.js
index e64bd2ab8..0d6296e1b 100644
--- a/sdk/rolldown.config.js
+++ b/sdk/rolldown.config.js
@@ -112,6 +112,7 @@ export default defineConfig([
'worldgen/index': 'src/worldgen/index.ts',
'water/index': 'src/water/index.ts',
'spline/index': 'src/spline/index.ts',
+ 'imported-scene/index': 'src/imported-scene/index.ts',
'character-shaders/index': 'src/character/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
diff --git a/sdk/rollup.config.js b/sdk/rollup.config.js
index 22d284126..b2555ad84 100644
--- a/sdk/rollup.config.js
+++ b/sdk/rollup.config.js
@@ -34,6 +34,7 @@ export default [
'worldgen/index': 'src/worldgen/index.ts',
'water/index': 'src/water/index.ts',
'spline/index': 'src/spline/index.ts',
+ 'imported-scene/index': 'src/imported-scene/index.ts',
'character-shaders/index': 'src/character/index.ts',
'logic/index': 'src/logic/index.ts',
'debug-channel/index': 'src/debug-channel/index.ts',
diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.ts
index e03a8f5b0..ae8112ebe 100644
--- a/sdk/src/app/pluginSets.ts
+++ b/sdk/src/app/pluginSets.ts
@@ -71,7 +71,7 @@ export const presentationBasePlugins = (): Plugin[] => [
*/
export const PLUGIN_BUILD_ORDER: readonly string[] = [
'Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'audio', 'video',
- 'particle', 'trail', 'springBone', 'meshRenderer', 'staticBatch', 'compositeBatch', 'impostor', 'textureStreaming', 'terrain', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline',
+ 'importedScene', 'particle', 'trail', 'springBone', 'meshRenderer', 'staticBatch', 'compositeBatch', 'impostor', 'textureStreaming', 'terrain', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline',
'gameplay',
'perception', 'fsm', 'bt', 'scriptGraph', 'nav', 'eventBinding', 'replication',
'services',
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index f02360387..23a8bc616 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -306,8 +306,7 @@ export {
} from './scene/sceneStreaming';
export { sceneManagerPlugin } from './scene/scenePlugin';
-export { NodeVisibility } from './scene/nodeVisibility';
-export { CompoundCollider3D, type CompoundCollider3DData, type CompoundColliderPart3D } from './physics3d/CompoundCollider3D';
+export { NodeVisibility, ParticleModelUnits, ImportedScenePlugin } from './imported-scene';
// =============================================================================
// World Residency
@@ -1020,4 +1019,3 @@ export {
export type { CompareOp, BlackboardGuard } from './ai/fsm/types';
-export { ParticleModelUnits } from './particle/ParticleModelUnits';
diff --git a/sdk/src/imported-scene/importedScenePlugin.ts b/sdk/src/imported-scene/importedScenePlugin.ts
new file mode 100644
index 000000000..fcbbc7fb3
--- /dev/null
+++ b/sdk/src/imported-scene/importedScenePlugin.ts
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { App, Plugin } from '../app/app';
+import { defineSystem, Schedule } from '../ecs/system';
+import { fxPreviewOrPlayMode } from '../ecs/env';
+import { registerWorldSceneExportFilter } from '../scene/scene';
+import { NodeVisibilityState } from './nodeVisibility';
+import { ParticleModelUnitState } from './particleModelUnits';
+
+export class ImportedScenePlugin implements Plugin {
+ name = 'importedScene';
+ private release_: (() => void) | null = null;
+
+ build(app: App): void {
+ const visibility = new NodeVisibilityState();
+ const modelUnits = new ParticleModelUnitState();
+ this.release_ = registerWorldSceneExportFilter(app.world,
+ (entity, component, data) => visibility.exportData(entity, component, data));
+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {
+ app.world.ensureTransformsComposed();
+ modelUnits.update(app.world);
+ }, { name: 'ParticleModelUnitSystem' }), { runIf: fxPreviewOrPlayMode });
+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => visibility.update(app.world),
+ { name: 'NodeVisibilitySystem' }));
+ }
+
+ cleanup(): void {
+ this.release_?.();
+ this.release_ = null;
+ }
+}
diff --git a/sdk/src/imported-scene/importedSceneSupport.ts b/sdk/src/imported-scene/importedSceneSupport.ts
new file mode 100644
index 000000000..e84796f88
--- /dev/null
+++ b/sdk/src/imported-scene/importedSceneSupport.ts
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { addEntryPlugin } from '../runtime/entryPlugins';
+import { ImportedScenePlugin } from './importedScenePlugin';
+
+export function registerImportedSceneSupport(): void {
+ addEntryPlugin('importedScene', () => new ImportedScenePlugin());
+}
diff --git a/sdk/src/imported-scene/index.ts b/sdk/src/imported-scene/index.ts
new file mode 100644
index 000000000..170392709
--- /dev/null
+++ b/sdk/src/imported-scene/index.ts
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+export { NodeVisibility } from './nodeVisibility';
+export { ParticleModelUnits } from './particleModelUnits';
+export { ImportedScenePlugin } from './importedScenePlugin';
+
+import { registerImportedSceneSupport } from './importedSceneSupport';
+
+registerImportedSceneSupport();
diff --git a/sdk/src/scene/nodeVisibility.ts b/sdk/src/imported-scene/nodeVisibility.ts
similarity index 89%
rename from sdk/src/scene/nodeVisibility.ts
rename to sdk/src/imported-scene/nodeVisibility.ts
index f8bb44750..b56650e5b 100644
--- a/sdk/src/scene/nodeVisibility.ts
+++ b/sdk/src/imported-scene/nodeVisibility.ts
@@ -8,13 +8,6 @@ import type { Entity } from '../types';
export const NodeVisibility = defineComponent('NodeVisibility', { visible: true }, { animatableFields: ['visible'] });
type Masked = { def: RenderableComponentDef; value: unknown };
-const states = new WeakMap<World, NodeVisibilityState>();
-
-/** Preserve authored renderer flags when saving a world with a hidden subtree. */
-export function exportNodeVisibility(world: World, entity: Entity, component: string, data: Record<string, unknown>): void {
- const masked = states.get(world)?.masked.get(entity)?.find(row => row.def._name === component);
- if (masked) data[masked.def.renderableField] = masked.value;
-}
/** No hierarchy walk or renderer write when the gates and scene structure are unchanged. */
export class NodeVisibilityState {
@@ -22,8 +15,13 @@ export class NodeVisibilityState {
private gates = new Map<Entity, boolean>();
private version = -1;
+ /** Preserve authored renderer flags when saving a world with a hidden subtree. */
+ exportData(entity: Entity, component: string, data: Record<string, unknown>): void {
+ const masked = this.masked.get(entity)?.find(row => row.def._name === component);
+ if (masked) data[masked.def.renderableField] = masked.value;
+ }
+
update(world: World): void {
- states.set(world, this);
const controls = world.getEntitiesWithComponents([NodeVisibility]);
if (controls.length === 0 && this.masked.size === 0 && this.gates.size === 0) return;
const version = world.getWorldVersion();
diff --git a/sdk/src/particle/ParticleModelUnits.ts b/sdk/src/imported-scene/particleModelUnits.ts
similarity index 100%
rename from sdk/src/particle/ParticleModelUnits.ts
rename to sdk/src/imported-scene/particleModelUnits.ts
diff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.ts
index b396725e6..faa3ee671 100644
--- a/sdk/src/particle/ParticlePlugin.ts
+++ b/sdk/src/particle/ParticlePlugin.ts
@@ -8,7 +8,6 @@ import { fxPreviewOrPlayMode } from '../ecs/env';
import type { CppRegistry } from '../wasm';
import { engineApi } from '../ecs/bridge/engineApi';
import { registerSceneComponentCodec } from '../scene/scene';
-import { ParticleModelUnitState } from './ParticleModelUnits';
import { Particle, ParticleAPI } from './ParticleAPI';
import { particleQueryResolver } from './ParticleCollisionBridge';
import { ParticleCollisionEvent, type ParticleCollisionEventPayload } from './collision';
@@ -40,7 +39,6 @@ export class ParticlePlugin implements Plugin {
// the resource, and every call through it no-ops.
const engine = engineApi(app) ?? {};
const registry = app.world.getCppRegistry() as CppRegistry;
- const modelUnits = new ParticleModelUnitState();
const api = new ParticleAPI(engine, registry, particleQueryResolver(app));
app.insertResource(Particle, api);
this.overlay_ = `particle-collision:${++overlayId}`;
@@ -99,8 +97,6 @@ export class ParticlePlugin implements Plugin {
app.addSystemToSchedule(Schedule.Update, defineSystem(
[Res(Time), Res(Particle), EventWriter(ParticleCollisionEvent)],
(time: TimeData, particle: ParticleAPI, events: EventWriterInstance<ParticleCollisionEventPayload>) => {
- app.world.ensureTransformsComposed();
- modelUnits.update(app.world);
particle.update(time.delta);
for (const hit of particle.collisionEvents) events.send(hit);
},
diff --git a/sdk/src/platform/nativeModuleRegistry.ts b/sdk/src/platform/nativeModuleRegistry.ts
index 1b318e2d5..031163ece 100644
--- a/sdk/src/platform/nativeModuleRegistry.ts
+++ b/sdk/src/platform/nativeModuleRegistry.ts
@@ -33,6 +33,7 @@ import * as FoliageModule from '../foliage';
import * as WorldGenModule from '../worldgen';
import * as WaterModule from '../water';
import * as SplineModule from '../spline';
+import * as ImportedSceneModule from '../imported-scene';
import * as CharacterShadersModule from '../character';
import * as ScriptGraphModule from '../logic';
import * as AiModule from '../ai';
@@ -63,6 +64,7 @@ export const NATIVE_MODULE_NAMESPACES: Readonly<Record<string, unknown>> = {
'esengine/worldgen': WorldGenModule,
'esengine/water': WaterModule,
'esengine/spline': SplineModule,
+ 'esengine/imported-scene': ImportedSceneModule,
'esengine/character-shaders': CharacterShadersModule,
'esengine/logic': ScriptGraphModule,
'esengine/ai': AiModule,
diff --git a/sdk/src/runtime/optionalPlugins.ts b/sdk/src/runtime/optionalPlugins.ts
index d3bd64c71..005d0df61 100644
--- a/sdk/src/runtime/optionalPlugins.ts
+++ b/sdk/src/runtime/optionalPlugins.ts
@@ -29,6 +29,7 @@ import { registerFoliageSupport } from '../foliage/foliageSupport';
import { registerWorldGenSupport } from '../worldgen/worldgenSupport';
import { registerWaterSupport } from '../water/waterSupport';
import { registerSplineSupport } from '../spline/splineSupport';
+import { registerImportedSceneSupport } from '../imported-scene/importedSceneSupport';
import { registerCharacterShaders } from '../character/characterSupport';
import { registerScriptGraphSupport } from '../logic/logicSupport';
import { registerAiSupport } from '../ai/aiSupport';
@@ -51,6 +52,7 @@ export function installOptionalPlugins(): void {
registerWorldGenSupport();
registerWaterSupport();
registerSplineSupport();
+ registerImportedSceneSupport();
registerCharacterShaders();
registerScriptGraphSupport();
registerAiSupport();
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index 74d3cd864..823cc495e 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -6,7 +6,6 @@
*/
import { World } from '../ecs/world';
-import { exportNodeVisibility } from './nodeVisibility';
import { Entity, INVALID_ENTITY } from '../types';
import { upgradeEntityComponents } from './legacyComponents';
import { isPrefabEntry, type SceneEntry } from './sceneEntry';
@@ -273,6 +272,21 @@ export function registerWorldSceneComponentCodec(world: World, type: string, cod
};
}
+export type SceneExportFilter = (entity: Entity, component: string, data: Record<string, unknown>) => void;
+
+const worldExportFilters = new WeakMap<World, Set<SceneExportFilter>>();
+
+/** @internal Lets a plugin rewrite any component's saved record in one world. */
+export function registerWorldSceneExportFilter(world: World, filter: SceneExportFilter): () => void {
+ let filters = worldExportFilters.get(world);
+ if (!filters) worldExportFilters.set(world, filters = new Set());
+ filters.add(filter);
+ return () => {
+ filters.delete(filter);
+ if (filters.size === 0) worldExportFilters.delete(world);
+ };
+}
+
function sceneComponentCodec(world: World, type: string): SceneComponentCodec | undefined {
return worldComponentCodecs.get(world)?.get(type) ?? sceneComponentCodecs.get(type);
}
@@ -868,7 +882,7 @@ export function serializeEntityComponents(world: World, entity: Entity): SceneCo
// Components with out-of-band state (e.g. TilemapLayer chunks) fold
// it into the record via their registered codec.
sceneComponentCodec(world, typeName)?.exportData?.(entityNum, payload);
- exportNodeVisibility(world, entity, typeName, payload);
+ for (const filter of worldExportFilters.get(world) ?? []) filter(entity, typeName, payload);
components.push({
type: typeName,
data: payload,
diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.ts
index 93d15c3d7..663eb10dc 100644
--- a/sdk/src/scene/scenePlugin.ts
+++ b/sdk/src/scene/scenePlugin.ts
@@ -17,7 +17,6 @@ import type { SystemDef } from '../ecs/system';
import type { World } from '../ecs/world';
import { log } from '../util/logger';
import { ensureSceneAiRegistrations } from './ai-builtins';
-import { NodeVisibilityState } from './nodeVisibility';
const sceneTransitionSystem = defineSystem(
[ResMut(SceneManager), Res(Time)],
@@ -62,9 +61,6 @@ export const sceneManagerPlugin: Plugin = {
// app assemblies: a cell IS an additive scene, so an assembly that can load
// one can stream one, and a fourth place to remember is a place to forget.
app.addPlugin(worldResidencyPlugin);
- const visibility = new NodeVisibilityState();
- app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => visibility.update(app.world),
- { name: 'NodeVisibilitySystem' }));
const initSystem: SystemDef = {
_id: Symbol('SceneInitSystem'),
diff --git a/sdk/tests/node-visibility.test.ts b/sdk/tests/node-visibility.test.ts
index 075741c6f..f7a47443e 100644
--- a/sdk/tests/node-visibility.test.ts
+++ b/sdk/tests/node-visibility.test.ts
@@ -4,8 +4,8 @@ import { describe, expect, it, vi } from 'vitest';
import { World } from '../src/ecs/world';
import { Camera, Sprite, ensureBuiltinComponentsRegistered } from '../src/ecs/component';
import { BoxCollider2D } from '../src/physics/components';
-import { NodeVisibility, NodeVisibilityState } from '../src/scene/nodeVisibility';
-import { serializeEntityComponents } from '../src/scene/scene';
+import { NodeVisibility, NodeVisibilityState } from '../src/imported-scene/nodeVisibility';
+import { registerWorldSceneExportFilter, serializeEntityComponents } from '../src/scene/scene';
import { setNestedProperty } from '../src/timeline/TimelineRuntime';
import { createMockModule } from './mocks/wasm';
@@ -20,7 +20,9 @@ function fixture() {
world.insert(child, Camera, { isActive: true });
world.insert(child, BoxCollider2D, { enabled: true });
world.insert(leaf, Sprite, { enabled: true });
- return { world, root, child, leaf, state: new NodeVisibilityState() };
+ const state = new NodeVisibilityState();
+ registerWorldSceneExportFilter(world, (entity, component, data) => state.exportData(entity, component, data));
+ return { world, root, child, leaf, state };
}
describe('hierarchical visual visibility', () => {
diff --git a/sdk/tests/particle-model-units.test.ts b/sdk/tests/particle-model-units.test.ts
index 95f2b77b2..5b97101a1 100644
--- a/sdk/tests/particle-model-units.test.ts
+++ b/sdk/tests/particle-model-units.test.ts
@@ -3,7 +3,7 @@
import { describe, expect, it, vi } from 'vitest';
import { World } from '../src/ecs/world';
import { ParticleEmitter, Transform, ensureBuiltinComponentsRegistered } from '../src/ecs/component';
-import { ParticleModelUnits, ParticleModelUnitState } from '../src/particle/ParticleModelUnits';
+import { ParticleModelUnits, ParticleModelUnitState } from '../src/imported-scene/particleModelUnits';
import { createMockModule } from './mocks/wasm';
describe('particle model units', () => {
diff --git a/tools/apiSubsystems.mjs b/tools/apiSubsystems.mjs
index 7f7005142..6b9ca28c8 100644
--- a/tools/apiSubsystems.mjs
+++ b/tools/apiSubsystems.mjs
@@ -335,6 +335,16 @@ export const SUBSYSTEMS = [
whyZh: '曲线和按距离度量已经有检查,但目前只有河流会沿着它走,编辑器里也还没有绘制它的工具',
entry: ['Spline', 'SplineCurve'],
},
+ {
+ id: 'imported-scene',
+ title: 'Imported scene runtime',
+ titleZh: '导入场景运行时',
+ source: ['imported-scene'],
+ tier: 'experimental',
+ why: 'what a glTF scene brings beside geometry, a node shown or hidden by its animation and particles authored in model units, is checked against the importer, but only imported scenes write it so far',
+ whyZh: 'glTF 场景在几何体之外带来的东西(随动画显隐的节点、按模型单位写的粒子)已经和导入器一起检查过,但目前只有导入的场景会写它们',
+ entry: ['NodeVisibility', 'ParticleModelUnits'],
+ },
{
id: 'water',
title: 'Water',
diff --git a/tools/lib/sdkProgram.mjs b/tools/lib/sdkProgram.mjs
index 05bc407c5..b183a5560 100644
--- a/tools/lib/sdkProgram.mjs
+++ b/tools/lib/sdkProgram.mjs
@@ -68,6 +68,7 @@ export const ENTRIES = {
'worldgen': 'src/worldgen/index.ts',
'water': 'src/water/index.ts',
'spline': 'src/spline/index.ts',
+ 'imported-scene': 'src/imported-scene/index.ts',
'character-shaders': 'src/character/index.ts',
'logic': 'src/logic/index.ts',
'debug-channel': 'src/debug-channel/index.ts',
diff --git a/tools/nativeScriptModules.js b/tools/nativeScriptModules.js
index da25b4184..0f4cff491 100644
--- a/tools/nativeScriptModules.js
+++ b/tools/nativeScriptModules.js
@@ -74,6 +74,7 @@ export const MODULES = {
'esengine/worldgen': { disposition: 'native-subpath' },
'esengine/water': { disposition: 'native-subpath' },
'esengine/spline': { disposition: 'native-subpath' },
+ 'esengine/imported-scene': { disposition: 'native-subpath' },
'esengine/character-shaders': { disposition: 'native-subpath' },
'esengine/logic': { disposition: 'native-subpath' },
'esengine/ai': { disposition: 'native-subpath' },
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 15f88b610..c918d8b55 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'refactor(sdk): node visibility and particle model units ship in esengine/imported-scene, installed only where the content uses them':
+ {"note":"An imported scene keeps its materials, animation, particles and colliders."},
'fix(cyber-rooftop): restore wetness masks and fit fixture shadows':
{"internal":"the cyber-rooftop example's own scene and texture settings; the engine and editor are unchanged"},
'fix(render): allocate complete point shadows and report new denials':