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.

build: the foundation is held underneath, and it caught three misfilings

esengineed56bf069b8a
diff --git a/package.json b/package.json
index 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.ts
index 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.ts
index 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 after
diff --git a/sdk/src/ai/fsm/FsmPlugin.ts b/sdk/src/ai/fsm/FsmPlugin.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 Team
import 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 98%
rename from sdk/src/util/env.ts
rename to sdk/src/ecs/env.ts
index 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.ts
similarity index 96%
rename from sdk/src/util/propertyPath.ts
rename to sdk/src/ecs/propertyPath.ts
index 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.ts
similarity index 96%
rename from sdk/src/util/timer.ts
rename to sdk/src/ecs/timer.ts
index 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.ts
index 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.ts
index 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.ts
index 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/component
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 Text
export {
diff --git a/sdk/src/ui/input/drag.ts b/sdk/src/ui/input/drag.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 texture
diff --git a/sdk/src/video/WebVideoBackend.ts b/sdk/src/video/WebVideoBackend.ts
index 4330cc89a..ba5260776 100644
--- a/sdk/src/video/WebVideoBackend.ts
+++ b/sdk/src/video/WebVideoBackend.ts
@@ -8,7 +8,7 @@ import type { PlatformVideoBackend, VideoStreamHandle, VideoStreamOptions } from
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 Team
import { 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.ts
index 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.ts
index 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 Team
import { 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.ts
index 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.mjs
new file mode 100644
index 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.`);