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
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.mdindex 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.jsonindex 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.tsindex 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 Teamimport { 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdnew file mode 100644index 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.mdindex 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: ImageValignwidth: 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.mdindex 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: ImageValignwidth: 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.mdindex 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: ImageValignwidth: 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.mdindex 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: ImageValignwidth: 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.mdindex 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: ImageValignwidth: 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.jsonindex 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.jsindex 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.jsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tssimilarity index 89%rename from sdk/src/scene/nodeVisibility.tsrename to sdk/src/imported-scene/nodeVisibility.tsindex 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.tssimilarity index 100%rename from sdk/src/particle/ParticleModelUnits.tsrename to sdk/src/imported-scene/particleModelUnits.tsdiff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.mjsindex 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.jsindex 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.mjsindex 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':