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
build: the foundation is held underneath, and it caught three misfilings
esengineed56bf069b8a
diff --git a/package.json b/package.jsonindex 6ddbb1b60..7791a4225 100644--- a/package.json+++ b/package.json@@ -17,7 +17,7 @@"emsdk:setup": "node build-tools/toolchain/setup-emsdk.js","asset-meta": "node tools/asset-meta.js","migrate-asset-refs": "node tools/migrate-asset-refs.js",- "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs",+ "verify": "pnpm --filter ./sdk exec tsc --noEmit && node tools/api-surface.mjs --check && node tools/check-cycles.mjs && node tools/check-layers.mjs","prepare": "git config core.hooksPath .githooks || true"},"dependencies": {diff --git a/sdk/src/ai/bt/BtPlugin.ts b/sdk/src/ai/bt/BtPlugin.tsindex 616b5288d..118f64ae7 100644--- a/sdk/src/ai/bt/BtPlugin.ts+++ b/sdk/src/ai/bt/BtPlugin.ts@@ -18,7 +18,7 @@ import { defineSystem, Schedule, GetWorld } from '../../ecs/system';import { Res, Time, type TimeData } from '../../ecs/resource';import { defineResource } from '../../ecs/resource';import { Commands, type CommandsInstance } from '../../ecs/commands';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import type { AnyComponentDef, ComponentData } from '../../ecs/component';import { Assets } from '../../asset/AssetPlugin';import { resolveAssetKey } from '../../asset/resolveAssetKey';diff --git a/sdk/src/ai/builtins.ts b/sdk/src/ai/builtins.tsindex ed93f9de8..8897ffe06 100644--- a/sdk/src/ai/builtins.ts+++ b/sdk/src/ai/builtins.ts@@ -17,7 +17,7 @@ import { aiRegistry, type AiContext } from './fsm/AiContext';import type { AiAction, AiCondition, AiParamValue } from './fsm/registry';import { TimelinePlayer } from '../timeline/TimelinePlugin';import { SpriteAnimator } from '../animation/SpriteAnimator';-import { setEntityProperty } from '../util/propertyPath';+import { setEntityProperty } from '../ecs/propertyPath';/*** Register the engine's built-in actions/conditions. Idempotent (and safe afterdiff --git a/sdk/src/ai/fsm/FsmPlugin.ts b/sdk/src/ai/fsm/FsmPlugin.tsindex 71b4336c5..934dde272 100644--- a/sdk/src/ai/fsm/FsmPlugin.ts+++ b/sdk/src/ai/fsm/FsmPlugin.ts@@ -18,7 +18,7 @@ import { defineSystem, Schedule, GetWorld } from '../../ecs/system';import { Res, Time, type TimeData } from '../../ecs/resource';import { defineResource } from '../../ecs/resource';import { Commands, type CommandsInstance } from '../../ecs/commands';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import type { AnyComponentDef, ComponentData } from '../../ecs/component';import { Assets } from '../../asset/AssetPlugin';import { resolveAssetKey } from '../../asset/resolveAssetKey';diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.tsindex 747e78c9f..2c57b6c43 100644--- a/sdk/src/ai/nav/NavPlugin.ts+++ b/sdk/src/ai/nav/NavPlugin.ts@@ -21,7 +21,7 @@ import {type AnyComponentDef,type ComponentData,} from '../../ecs/component';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { Navigation, Nav } from './Navigation';import { NavAgent } from './NavAgent';import { advanceAlongPath } from './follow';diff --git a/sdk/src/ai/perception/PerceptionPlugin.ts b/sdk/src/ai/perception/PerceptionPlugin.tsindex 1f543018f..ce6640293 100644--- a/sdk/src/ai/perception/PerceptionPlugin.ts+++ b/sdk/src/ai/perception/PerceptionPlugin.ts@@ -14,7 +14,7 @@import type { App, Plugin } from '../../app/app';import type { Entity } from '../../types';import { defineSystem, Schedule, GetWorld } from '../../ecs/system';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { Transform } from '../../ecs/component';import type { AnyComponentDef, ComponentData } from '../../ecs/component';import { Physics, type PhysicsAPI } from '../../physics';diff --git a/sdk/src/animation/AnimationPlugin.ts b/sdk/src/animation/AnimationPlugin.tsindex 07f484f42..ae2d7205b 100644--- a/sdk/src/animation/AnimationPlugin.ts+++ b/sdk/src/animation/AnimationPlugin.ts@@ -19,7 +19,7 @@ import { SpriteAnimation, SpriteAnimationAPI } from './SpriteAnimator';import { AnimatorController, AnimatorControllerAPI } from './Animator';import { Assets } from '../asset/AssetPlugin';import { resolveAssetKey } from '../asset/resolveAssetKey';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { SystemLabel } from '../ecs/systemLabels';export class AnimationPlugin implements Plugin {diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex e3096fcd6..803c9f80f 100644--- a/sdk/src/app/app.ts+++ b/sdk/src/app/app.ts@@ -23,7 +23,7 @@ import type { SceneConfig } from '../scene/sceneManager';import { SceneManager } from '../scene/sceneManager';import { sceneManagerPlugin } from '../scene/scenePlugin';import { getDefaultContext } from '../ecs/context';-import { setLinearColorSpace } from '../util/env';+import { setLinearColorSpace } from '../ecs/env';import { seedEngineComponents } from '../ecs/component';import { cameraPlugin } from '../camera/CameraPlugin';import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from '../camera/ScreenScaling';diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.tsindex cdfc98400..0ee6a0084 100644--- a/sdk/src/app/pluginSets.ts+++ b/sdk/src/app/pluginSets.ts@@ -30,7 +30,7 @@ import { mesh2dPlugin } from '../render/mesh2d';import { tilemapPlugin } from '../tilemap';import { postProcessPlugin } from '../postprocess';import { timelinePlugin } from '../timeline';-import { timerPlugin } from '../util/timer';+import { timerPlugin } from '../ecs/timer';import { velocityPlugin } from '../velocity';import { lifecyclePlugin } from '../ecs/lifecycle';import { navPlugin, fsmPlugin, btPlugin, perceptionPlugin } from '../ai';diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex a8e81d23a..74e471f31 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { AssetLoader, LoadContext, TextureResult } from '../AssetLoader';-import { linearColorSpace } from '../../util/env';+import { linearColorSpace } from '../../ecs/env';import { platformCreateCanvas, platformCreateImage } from '../../platform/base';import type { PlatformCanvas, PlatformCanvas2DContext, PlatformImage } from '../../platform/types';import { decodeImageBitmap } from '../imageDecode';diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex c89773a6a..366ac1b66 100644--- a/sdk/src/audio/AudioPlugin.ts+++ b/sdk/src/audio/AudioPlugin.ts@@ -10,7 +10,7 @@ import { WorldTransform, type WorldTransformData } from '../ecs/component';import { platformCreateAudioBackend, platformOnMemoryWarning } from '../platform/base';import { calculateAttenuation, calculatePanning, type SpatialAudioConfig, AttenuationModel } from './SpatialAudio';import type { AudioHandle } from './PlatformAudioBackend';-import { isEditor, isPlayMode } from '../util/env';+import { isEditor, isPlayMode } from '../ecs/env';import { log } from '../util/logger';export interface AudioPluginConfig {diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex 15cde1bad..911453b09 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -9,7 +9,7 @@ import type { App, Plugin } from '../app/app';import type { SystemDef } from '../ecs/system';import { Schedule, defineSystem } from '../ecs/system';import { Res, Time, type TimeData } from '../ecs/resource';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { followUpdate } from './FollowTarget';import type { ESEngineModule, CppRegistry } from '../wasm';import type { World } from '../ecs/world';diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 0c810a93c..c73292c0e 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -421,7 +421,7 @@ export {setFxEditPreview,isFxEditPreview,fxPreviewOrPlayMode,-} from './util/env';+} from './ecs/env';export type { RunCondition } from './app/app';diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 1e53f9994..d7052cc5f 100644--- a/sdk/src/core-sys.ts+++ b/sdk/src/core-sys.ts@@ -186,7 +186,7 @@ export {TimerHandle,TimerRes,timerPlugin,-} from './util/timer';+} from './ecs/timer';export { velocityPlugin, velocitySystem } from './velocity';diff --git a/sdk/src/util/env.ts b/sdk/src/ecs/env.tssimilarity index 98%rename from sdk/src/util/env.tsrename to sdk/src/ecs/env.tsindex 1c106065c..66d6a1e6a 100644--- a/sdk/src/util/env.ts+++ b/sdk/src/ecs/env.ts@@ -9,7 +9,7 @@* functions are the stable public surface; gameplay systems gate on* {@link playModeOnly}.*/-import { getDefaultContext } from '../ecs/context';+import { getDefaultContext } from './context';export function setEditorMode(active: boolean): void {getDefaultContext().editorMode = active;diff --git a/sdk/src/util/propertyPath.ts b/sdk/src/ecs/propertyPath.tssimilarity index 96%rename from sdk/src/util/propertyPath.tsrename to sdk/src/ecs/propertyPath.tsindex 0829355df..2d54da4eb 100644--- a/sdk/src/util/propertyPath.ts+++ b/sdk/src/ecs/propertyPath.ts@@ -14,9 +14,9 @@* path would corrupt (see TimelineEvaluator). Merging them is a real change, not* a rename.*/-import type { World } from '../ecs/world';+import type { World } from './world';import type { Entity } from '../types';-import { getComponent } from '../ecs/component';+import { getComponent } from './component';export function getNestedProperty(obj: Record<string, any>, path: string): unknown {const parts = path.split('.');diff --git a/sdk/src/util/timer.ts b/sdk/src/ecs/timer.tssimilarity index 96%rename from sdk/src/util/timer.tsrename to sdk/src/ecs/timer.tsindex b41732570..8a6a3bf2f 100644--- a/sdk/src/util/timer.ts+++ b/sdk/src/ecs/timer.ts@@ -5,12 +5,12 @@* @brief Frame-based timer system integrated with engine loop*/-import { defineResource, Res } from '../ecs/resource';-import { defineSystem } from '../ecs/system';-import { Schedule } from '../ecs/system';-import { Time } from '../ecs/resource';+import { defineResource, Res } from './resource';+import { defineSystem } from './system';+import { Schedule } from './system';+import { Time } from './resource';import { playModeOnly } from './env';-import { log } from './logger';+import { log } from '../util/logger';import type { Plugin } from '../app/app';// =============================================================================diff --git a/sdk/src/eventBinding.ts b/sdk/src/eventBinding.tsindex 007e00b2b..9154d6f02 100644--- a/sdk/src/eventBinding.ts+++ b/sdk/src/eventBinding.ts@@ -32,7 +32,7 @@ import type { World } from './ecs/world';import { defineSystem, Schedule } from './ecs/system';import { Commands, type CommandsInstance } from './ecs/commands';import { Res, Time, type TimeData } from './ecs/resource';-import { playModeOnly } from './util/env';+import { playModeOnly } from './ecs/env';import { log } from './util/logger';import { ensureEntityEvents, EntityEventQueue, type EntityEvent, type Unsubscribe } from './ecs/entityEvents';import { Blackboard } from './ai/fsm/Blackboard';diff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.tsindex f09fcda73..276a0dbae 100644--- a/sdk/src/particle/ParticlePlugin.ts+++ b/sdk/src/particle/ParticlePlugin.ts@@ -4,7 +4,7 @@ import type { App, Plugin } from '../app/app';import { defineSystem, Schedule } from '../ecs/system';import { Res } from '../ecs/resource';import { Time, type TimeData } from '../ecs/resource';-import { fxPreviewOrPlayMode } from '../util/env';+import { fxPreviewOrPlayMode } from '../ecs/env';import type { CppRegistry } from '../wasm';import { engineApi } from '../ecs/bridge/engineApi';import { registerSceneComponentCodec } from '../scene/scene';diff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.tsindex 4e1f727ce..47c0370a7 100644--- a/sdk/src/physics/CharacterController.ts+++ b/sdk/src/physics/CharacterController.ts@@ -26,7 +26,7 @@ import { defineComponent, Transform, type TransformData } from '../ecs/componentimport { Schedule, defineSystem, GetWorld } from '../ecs/system';import { Query, Mut } from '../ecs/query';import { Res, Time, type TimeData } from '../ecs/resource';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { Physics, type PhysicsAPI } from './Physics';import { BoxCollider, CircleCollider, CapsuleCollider } from './PhysicsComponents';import type {diff --git a/sdk/src/physics/PhysicsEventBridge.ts b/sdk/src/physics/PhysicsEventBridge.tsindex 93e954c13..d3a601428 100644--- a/sdk/src/physics/PhysicsEventBridge.ts+++ b/sdk/src/physics/PhysicsEventBridge.ts@@ -17,7 +17,7 @@import type { App } from '../app/app';import { Schedule, defineSystem } from '../ecs/system';import { Res } from '../ecs/resource';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { ensureEntityEvents } from '../ecs/entityEvents';import { PhysicsEvents, type PhysicsEventsData } from './PhysicsTypes';import type { Entity } from '../types';diff --git a/sdk/src/physics/PhysicsSystem.ts b/sdk/src/physics/PhysicsSystem.tsindex 656ed5a1e..23b49e4e7 100644--- a/sdk/src/physics/PhysicsSystem.ts+++ b/sdk/src/physics/PhysicsSystem.ts@@ -16,7 +16,7 @@ import type { TransformData, ParentData, CanvasData } from '../ecs/component';import { Transform, Parent, Canvas } from '../ecs/component';import { Res, Time, type TimeData } from '../ecs/resource';import { Schedule, defineSystem } from '../ecs/system';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import type { PhysicsWasmModule } from './PhysicsModuleLoader';import { Physics } from './Physics';import {diff --git a/sdk/src/runtime/runtimeAssets.ts b/sdk/src/runtime/runtimeAssets.tsindex eff1be3e3..76dc2b3d7 100644--- a/sdk/src/runtime/runtimeAssets.ts+++ b/sdk/src/runtime/runtimeAssets.ts@@ -7,10 +7,10 @@* builder runtime loader and the spine scene loader (and any editor that* drives the same load path). Kept in its own module so neither the* runtime loader nor the spine loader has to import the other.-import { linearColorSpace } from '../util/env';+import { linearColorSpace } from '../ecs/env';*/import type { ESEngineModule } from '../wasm';-import { linearColorSpace } from '../util/env';+import { linearColorSpace } from '../ecs/env';import type { Backend } from '../asset/Backend';import type { ParsedTextureImportSettings } from '../asset/textureImportSettings';import { requireResourceManager } from '../wasm/resourceManager';diff --git a/sdk/src/scene/scenePlugin.ts b/sdk/src/scene/scenePlugin.tsindex fe1f6d55d..cb0db5a69 100644--- a/sdk/src/scene/scenePlugin.ts+++ b/sdk/src/scene/scenePlugin.ts@@ -11,7 +11,7 @@ import { SceneStreaming, SceneStreamingController } from './sceneStreaming';import { defineSystem, Schedule, GetWorld } from '../ecs/system';import { Res, ResMut, Time } from '../ecs/resource';import { Transform, type TransformData } from '../ecs/component';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import type { SystemDef } from '../ecs/system';import type { World } from '../ecs/world';import { log } from '../util/logger';diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.tsindex 5c5342c26..39a845dc8 100644--- a/sdk/src/tilemap/tilemapPlugin.ts+++ b/sdk/src/tilemap/tilemapPlugin.ts@@ -22,7 +22,7 @@ import { decodeTilemapChunks } from './chunkCodec';import { Assets } from '../asset/AssetPlugin';import { resolveAssetKey } from '../asset/resolveAssetKey';import { Time } from '../ecs/resource';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { log } from '../util/logger';import type { Entity } from '../types';diff --git a/sdk/src/timeline/TimelinePlugin.ts b/sdk/src/timeline/TimelinePlugin.tsindex 59d9d46e1..645f2ac08 100644--- a/sdk/src/timeline/TimelinePlugin.ts+++ b/sdk/src/timeline/TimelinePlugin.ts@@ -5,7 +5,7 @@ import { defineSystem, Schedule } from '../ecs/system';import { Res } from '../ecs/resource';import { Time, type TimeData } from '../ecs/resource';import { defineComponent, getComponent } from '../ecs/component';-import { playModeOnly } from '../util/env';+import { playModeOnly } from '../ecs/env';import { Assets } from '../asset/AssetPlugin';import { resolveAssetKey } from '../asset/resolveAssetKey';import { Audio, type AudioAPI } from '../audio/Audio';diff --git a/sdk/src/trail/TrailPlugin.ts b/sdk/src/trail/TrailPlugin.tsindex f530e717d..4370f302a 100644--- a/sdk/src/trail/TrailPlugin.ts+++ b/sdk/src/trail/TrailPlugin.ts@@ -4,7 +4,7 @@ import type { App, Plugin } from '../app/app';import { defineSystem, Schedule } from '../ecs/system';import { Res } from '../ecs/resource';import { Time, type TimeData } from '../ecs/resource';-import { fxPreviewOrPlayMode } from '../util/env';+import { fxPreviewOrPlayMode } from '../ecs/env';import type { CppRegistry } from '../wasm';import { engineApi } from '../ecs/bridge/engineApi';import { TrailRenderer } from '../ecs/component';diff --git a/sdk/src/ui/behavior/plugin.ts b/sdk/src/ui/behavior/plugin.tsindex 8cd75c697..37a62928c 100644--- a/sdk/src/ui/behavior/plugin.ts+++ b/sdk/src/ui/behavior/plugin.ts@@ -5,7 +5,7 @@ import { Res, Time, type TimeData } from '../../ecs/resource';import { defineSystem, Schedule } from '../../ecs/system';import { Input, type InputState } from '../../input/input';import { Transform, type TransformData } from '../../ecs/component';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import type { Entity, Vec2 } from '../../types';import { UIEvents, UIEventQueue } from '../core/events';diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex ec0234a5a..b5a7409c9 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -424,7 +424,7 @@ export {getEntityProperty,setEntityProperty,type ParsedPropertyPath,-} from '../util/propertyPath';+} from '../ecs/propertyPath';// Rich Textexport {diff --git a/sdk/src/ui/input/drag.ts b/sdk/src/ui/input/drag.tsindex 97a2fcd82..352a0567e 100644--- a/sdk/src/ui/input/drag.ts+++ b/sdk/src/ui/input/drag.ts@@ -19,7 +19,7 @@ import type { UIInteractionData } from './interactable';import { UIEvents, UIEventQueue } from '../core/events';import { UICameraInfo } from '../core/ui-camera-info';import type { UICameraData } from '../core/ui-camera-info';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { getEntityDepth } from '../util/helpers';import { SystemLabel, PluginName } from '../../ecs/systemLabels';import { quaternionToAngle2D } from '../util/math';diff --git a/sdk/src/ui/input/focus.ts b/sdk/src/ui/input/focus.tsindex c7220d8b7..044651808 100644--- a/sdk/src/ui/input/focus.ts+++ b/sdk/src/ui/input/focus.ts@@ -16,7 +16,7 @@ import type { UIInteractionData } from './interactable';import { TextInput } from '../text/text-input';import { UIDialog, isDialogOpen } from '../behavior/dialog';import { walkParentChain } from '../util/helpers';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { UIEvents, UIEventQueue, UIEventType } from '../core/events';import { PluginName } from '../../ecs/systemLabels';import type { CppRegistry } from '../../wasm';diff --git a/sdk/src/ui/input/interaction.ts b/sdk/src/ui/input/interaction.tsindex 6819e041b..c8648e6cd 100644--- a/sdk/src/ui/input/interaction.ts+++ b/sdk/src/ui/input/interaction.ts@@ -8,7 +8,7 @@ import { Input } from '../../input/input';import type { InputState } from '../../input/input';import type { Entity } from '../../types';import type { World } from '../../ecs/world';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { Interactable } from './interactable';import { UIInteraction } from './interactable';import type { UIInteractionData } from './interactable';diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 59ae14173..191a42dc2 100644--- a/sdk/src/ui/text/text-input-plugin.ts+++ b/sdk/src/ui/text/text-input-plugin.ts@@ -16,7 +16,7 @@ import { UICameraInfo, type UICameraData } from '../core/ui-camera-info';import { Transform, type TransformData } from '../../ecs/component';import { UIEvents, UIEventQueue } from '../core/events';import { Res } from '../../ecs/resource';-import { playModeOnly } from '../../util/env';+import { playModeOnly } from '../../ecs/env';import { ensureComponent, getUINodeWidth, getUINodeHeight } from '../util/helpers';import { spawnUIEntity } from '../core/compose';import { px } from '../core/dimension';diff --git a/sdk/src/velocity.ts b/sdk/src/velocity.tsindex 1a4a02e5d..05c054fbb 100644--- a/sdk/src/velocity.ts+++ b/sdk/src/velocity.ts@@ -8,7 +8,7 @@ import type { Plugin } from './app/app';import { defineSystem, Schedule, GetWorld } from './ecs/system';import { Query, Mut } from './ecs/query';import { Res, Time, type TimeData } from './ecs/resource';-import { playModeOnly } from './util/env';+import { playModeOnly } from './ecs/env';import { Transform, Velocity, getComponentRegistry } from './ecs/component';import type { TransformData, VelocityData } from './ecs/component';import type { Entity } from './types';diff --git a/sdk/src/video/VideoPlugin.ts b/sdk/src/video/VideoPlugin.tsindex 6762a7773..3801b940d 100644--- a/sdk/src/video/VideoPlugin.ts+++ b/sdk/src/video/VideoPlugin.ts@@ -16,7 +16,7 @@ import type { VideoStreamHandle } from './PlatformVideoBackend';import { NullVideoBackend } from './NullVideoBackend';import { Audio } from '../audio/Audio';import { getPlatform } from '../platform/base';-import { isEditor, isPlayMode } from '../util/env';+import { isEditor, isPlayMode } from '../ecs/env';import { log } from '../util/logger';const UI_VISUAL_IMAGE = 2; // UIVisualType.Image — samples the texturediff --git a/sdk/src/video/WebVideoBackend.ts b/sdk/src/video/WebVideoBackend.tsindex 4330cc89a..ba5260776 100644--- a/sdk/src/video/WebVideoBackend.ts+++ b/sdk/src/video/WebVideoBackend.ts@@ -8,7 +8,7 @@ import type { PlatformVideoBackend, VideoStreamHandle, VideoStreamOptions } fromimport { createTextureFromPixels, updateTextureSubregion } from '../runtime/runtimeAssets';import { requireResourceManager } from '../wasm/resourceManager';import { findWebGL2Context } from '../asset/loaders/TextureLoader';-import { linearColorSpace } from '../util/env';+import { linearColorSpace } from '../ecs/env';import { log } from '../util/logger';let nextId_ = 1;diff --git a/sdk/tests/fx-despawn-cleanup.test.ts b/sdk/tests/fx-despawn-cleanup.test.tsindex 5dbf282bc..40706fec9 100644--- a/sdk/tests/fx-despawn-cleanup.test.ts+++ b/sdk/tests/fx-despawn-cleanup.test.ts@@ -9,7 +9,7 @@import { describe, it, expect, vi } from 'vitest';import { App } from '../src/app/app';import { AppContext, setDefaultContext } from '../src/ecs/context';-import { setEditorMode, setPlayMode } from '../src/util/env';+import { setEditorMode, setPlayMode } from '../src/ecs/env';import { createMockModule } from './mocks/wasm';import { Mesh2DPlugin, Meshes2D } from '../src/render/mesh2d';import { ParticlePlugin } from '../src/particle/ParticlePlugin';diff --git a/sdk/tests/fx-edit-preview.test.ts b/sdk/tests/fx-edit-preview.test.tsindex 38f87fac5..2a4437999 100644--- a/sdk/tests/fx-edit-preview.test.ts+++ b/sdk/tests/fx-edit-preview.test.ts@@ -9,7 +9,7 @@*/import { describe, it, expect, afterEach } from 'vitest';import { App } from '../src/app/app';-import { setEditorMode, setPlayMode, setFxEditPreview, isFxEditPreview } from '../src/util/env';+import { setEditorMode, setPlayMode, setFxEditPreview, isFxEditPreview } from '../src/ecs/env';import { particlePlugin, Particle } from '../src/particle';import { trailPlugin, Trail } from '../src/trail';diff --git a/sdk/tests/helpers/mockApp.ts b/sdk/tests/helpers/mockApp.tsindex 6f2f1c60a..1a67b956f 100644--- a/sdk/tests/helpers/mockApp.ts+++ b/sdk/tests/helpers/mockApp.ts@@ -14,7 +14,7 @@*/import { App } from '../../src/app/app';import { AppContext, setDefaultContext } from '../../src/ecs/context';-import { setEditorMode, setPlayMode } from '../../src/util/env';+import { setEditorMode, setPlayMode } from '../../src/ecs/env';import { createMockModule } from '../mocks/wasm';import type { ESEngineModule } from '../../src/wasm';diff --git a/sdk/tests/propertyPath.test.ts b/sdk/tests/propertyPath.test.tsindex 9281da8f0..8c4e96b23 100644--- a/sdk/tests/propertyPath.test.ts+++ b/sdk/tests/propertyPath.test.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, it, expect } from 'vitest';-import { getNestedProperty, setNestedProperty, parsePropertyPath } from '../src/util/propertyPath';+import { getNestedProperty, setNestedProperty, parsePropertyPath } from '../src/ecs/propertyPath';describe('propertyPath', () => {describe('getNestedProperty', () => {diff --git a/sdk/tests/run-mode.test.ts b/sdk/tests/run-mode.test.tsindex ddad6ecb1..eafd03de2 100644--- a/sdk/tests/run-mode.test.ts+++ b/sdk/tests/run-mode.test.ts@@ -12,7 +12,7 @@import { describe, expect, it, afterEach } from 'vitest';import { App } from '../src/app/app';import { Schedule, defineSystem } from '../src/ecs/system';-import { setEditorMode, setPlayMode, isEditor, isPlayMode, isRuntime, playModeOnly } from '../src/util/env';+import { setEditorMode, setPlayMode, isEditor, isPlayMode, isRuntime, playModeOnly } from '../src/ecs/env';import { getDefaultContext } from '../src/ecs/context';function namedSystem(name: string, trace: string[]) {diff --git a/sdk/tests/timer.test.ts b/sdk/tests/timer.test.tsindex 8cdbf8b72..3fa8600c6 100644--- a/sdk/tests/timer.test.ts+++ b/sdk/tests/timer.test.ts@@ -1,7 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, it, expect, beforeEach, vi } from 'vitest';-import { TimerManager } from '../src/util/timer';+import { TimerManager } from '../src/ecs/timer';describe('TimerManager', () => {let manager: TimerManager;diff --git a/sdk/tests/ui-plugin-cleanup.test.ts b/sdk/tests/ui-plugin-cleanup.test.tsindex 826daac56..ae8207150 100644--- a/sdk/tests/ui-plugin-cleanup.test.ts+++ b/sdk/tests/ui-plugin-cleanup.test.ts@@ -11,7 +11,7 @@ import { uiPlugin } from '../src/ui/ui-plugin';import { safeAreaPlugin } from '../src/ui/layout/safe-area';import { textInputPlugin, TextInputPlugin } from '../src/ui/text/text-input-plugin';import { AppContext, setDefaultContext } from '../src/ecs/context';-import { setEditorMode, setPlayMode } from '../src/util/env';+import { setEditorMode, setPlayMode } from '../src/ecs/env';import { createMockModule } from './mocks/wasm';import { setPlatform } from '../src/platform/base';import { webAdapter } from '../src/platform/web';diff --git a/tools/check-layers.mjs b/tools/check-layers.mjsnew file mode 100644index 000000000..720440864--- /dev/null+++ b/tools/check-layers.mjs@@ -0,0 +1,74 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-layers.mjs — the foundation stays underneath.+ *+ * `util/` and `math/` are what everything else is built ON: a helper, a vector.+ * Neither has any business knowing that scenes, audio or physics exist. Let one+ * reach upward and it stops being a foundation — the cheap import of a helper+ * starts dragging a subsystem behind it.+ *+ * That is ALL this checks, and the scope was earned the hard way. A full+ * low-to-high layering was tried and rejected: it flagged 149 imports, and the+ * overwhelming majority were correct — `asset/loaders/AudioAssetLoader`+ * importing `audio/` IS what an asset loader does, and every `*Plugin.ts`+ * importing `app/` is what a plugin is. `platform/` and `wasm/` were then tried+ * as foundation too and are NOT: a platform adapter exists to implement audio,+ * video and net for one host, and the wasm bridge routes aborts through the+ * app's context. Both are legitimately above the domains they name.+ *+ * A rule that is wrong 149 times teaches everyone to ignore it. This one is+ * narrow enough to be true.+ */+import { readdirSync, readFileSync, statSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const SRC = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'sdk', 'src');++// Checked: may not import a domain.+const FOUNDATION = new Set(['util', 'math']);+// Allowed as a target but not checked as a source. `platform/` is two things at+// once — the host's primitives (storage, fetch) AND that host's audio/video/net+// adapters. A helper reaching for a primitive is fine; the adapter half is why+// platform itself cannot be held to the foundation rule.+const ALLOWED = new Set([...FOUNDATION, 'platform']);++function walk(dir, out = []) {+ for (const e of readdirSync(dir, { withFileTypes: true })) {+ const abs = path.join(dir, e.name);+ if (e.isDirectory()) walk(abs, out);+ else if (e.name.endsWith('.ts')) out.push(abs);+ }+ return out;+}++/** Top-level directory a file sits in, or null when it is in the package root. */+const areaOf = (abs) => {+ const rel = path.relative(SRC, abs);+ return rel.includes(path.sep) ? rel.split(path.sep)[0] : null;+};++const SPEC_RE = /\bfrom\s*['"](\.[^'"]*)['"]/g;+const violations = [];++for (const file of walk(SRC)) {+ const from = areaOf(file);+ if (!FOUNDATION.has(from)) continue;+ for (const [, spec] of readFileSync(file, 'utf8').matchAll(SPEC_RE)) {+ const resolved = path.resolve(path.dirname(file), spec.split('?')[0]);+ if (!resolved.startsWith(SRC)) continue;+ const isDir = statSync(resolved, { throwIfNoEntry: false })?.isDirectory();+ const to = areaOf(isDir ? path.join(resolved, 'index.ts') : resolved);+ if (to === null || ALLOWED.has(to)) continue;+ violations.push(`${path.relative(SRC, file)} → ${to}/`);+ }+}++if (violations.length > 0) {+ console.log(`check-layers: ${violations.length} import(s) out of the foundation:`);+ for (const v of violations) console.log(' ' + v);+ console.log('\nMove the shared piece down, or the importing code up. Do not widen FOUNDATION.');+ process.exit(1);+}+console.log(`check-layers: foundation (${[...FOUNDATION].join(', ')}) imports nothing above it.`);