refactor: reorganize package structure and decouple framework packages (#338)

* refactor: reorganize package structure and decouple framework packages

## Package Structure Reorganization
- Reorganized 55 packages into categorized subdirectories:
  - packages/framework/ - Generic framework (Laya/Cocos compatible)
  - packages/engine/ - ESEngine core modules
  - packages/rendering/ - Rendering modules (WASM dependent)
  - packages/physics/ - Physics modules
  - packages/streaming/ - World streaming
  - packages/network-ext/ - Network extensions
  - packages/editor/ - Editor framework and plugins
  - packages/rust/ - Rust WASM engine
  - packages/tools/ - Build tools and SDK

## Framework Package Decoupling
- Decoupled behavior-tree and blueprint packages from ESEngine dependencies
- Created abstracted interfaces (IBTAssetManager, IBehaviorTreeAssetContent)
- ESEngine-specific code moved to esengine/ subpath exports
- Framework packages now usable with Cocos/Laya without ESEngine

## CI Configuration
- Updated CI to only type-check and lint framework packages
- Added type-check:framework and lint:framework scripts

## Breaking Changes
- Package import paths changed due to directory reorganization
- ESEngine integrations now use subpath imports (e.g., '@esengine/behavior-tree/esengine')

* fix: update es-engine file path after directory reorganization

* docs: update README to focus on framework over engine

* ci: only build framework packages, remove Rust/WASM dependencies

* fix: remove esengine subpath from behavior-tree and blueprint builds

ESEngine integration code will only be available in full engine builds.
Framework packages are now purely engine-agnostic.

* fix: move network-protocols to framework, build both in CI

* fix: update workflow paths from packages/core to packages/framework/core

* fix: exclude esengine folder from type-check in behavior-tree and blueprint

* fix: update network tsconfig references to new paths

* fix: add test:ci:framework to only test framework packages in CI

* fix: only build core and math npm packages in CI

* fix: exclude test files from CodeQL and fix string escaping security issue

packages/rendering/camera/module.json

@@ -0,0 +1,39 @@
+{
+  "id": "camera",
+  "name": "@esengine/camera",
+  "globalKey": "camera",
+  "displayName": "Camera",
+  "description": "Camera and viewport management | 相机和视口管理",
+  "version": "1.0.0",
+  "category": "Rendering",
+  "icon": "Video",
+  "tags": [
+    "camera",
+    "viewport",
+    "rendering"
+  ],
+  "isCore": false,
+  "defaultEnabled": true,
+  "isEngineModule": true,
+  "canContainContent": false,
+  "platforms": [
+    "web",
+    "desktop",
+    "mobile"
+  ],
+  "dependencies": [
+    "core",
+    "math"
+  ],
+  "exports": {
+    "components": [
+      "CameraComponent"
+    ],
+    "systems": [
+      "CameraSystem"
+    ]
+  },
+  "requiresWasm": false,
+  "outputPath": "dist/index.js",
+  "pluginExport": "CameraPlugin"
+}

packages/rendering/camera/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@esengine/camera",
+    "version": "1.0.0",
+    "description": "Camera component and systems for 2D/3D rendering",
+    "esengine": {
+        "plugin": true,
+        "pluginExport": "CameraPlugin",
+        "category": "core",
+        "isEnginePlugin": true
+    },
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "build:watch": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "clean": "rimraf dist"
+    },
+    "devDependencies": {
+        "@esengine/ecs-framework": "workspace:*",
+        "@esengine/ecs-framework-math": "workspace:*",
+        "@esengine/engine-core": "workspace:*",
+        "@esengine/build-config": "workspace:*",
+        "rimraf": "^5.0.5",
+        "tsup": "^8.0.0",
+        "typescript": "^5.3.3"
+    },
+    "keywords": [
+        "ecs",
+        "camera",
+        "2d",
+        "3d",
+        "rendering"
+    ],
+    "author": "yhh",
+    "license": "MIT"
+}

packages/rendering/camera/src/CameraComponent.ts

@@ -0,0 +1,72 @@
+import { Component, ECSComponent, Serializable, Serialize, Property } from '@esengine/ecs-framework';
+
+export enum ECameraProjection {
+    Perspective = 'perspective',
+    Orthographic = 'orthographic'
+}
+
+@ECSComponent('Camera')
+@Serializable({ version: 1, typeId: 'Camera' })
+export class CameraComponent extends Component {
+    @Serialize()
+    @Property({
+        type: 'enum',
+        label: 'Projection',
+        options: [
+            { label: 'Orthographic', value: ECameraProjection.Orthographic },
+            { label: 'Perspective', value: ECameraProjection.Perspective }
+        ]
+    })
+    public projection: ECameraProjection = ECameraProjection.Orthographic;
+
+    /** 透视模式下的视野角度，范围 [1, 179] 度 */
+    @Serialize()
+    @Property({ type: 'number', label: 'Field of View', min: 1, max: 179 })
+    public fieldOfView: number = 60;
+
+    /** 正交模式下的可见区域半高度（世界单位） */
+    @Serialize()
+    @Property({ type: 'number', label: 'Orthographic Size', min: 0.1, step: 0.1 })
+    public orthographicSize: number = 5;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Near Clip', min: 0.01, step: 0.1 })
+    public nearClipPlane: number = 0.1;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Far Clip', min: 1, step: 10 })
+    public farClipPlane: number = 1000;
+
+    /** 视口归一化坐标，范围 [0, 1] */
+    @Serialize()
+    @Property({ type: 'number', label: 'Viewport X', min: 0, max: 1, step: 0.01 })
+    public viewportX: number = 0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Viewport Y', min: 0, max: 1, step: 0.01 })
+    public viewportY: number = 0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Viewport Width', min: 0, max: 1, step: 0.01 })
+    public viewportWidth: number = 1;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Viewport Height', min: 0, max: 1, step: 0.01 })
+    public viewportHeight: number = 1;
+
+    /** 渲染优先级，值越大越后渲染（覆盖在上层） */
+    @Serialize()
+    @Property({ type: 'integer', label: 'Depth' })
+    public depth: number = 0;
+
+    @Serialize()
+    @Property({ type: 'color', label: 'Background Color' })
+    public backgroundColor: string = '#000000';
+
+    constructor() {
+        super();
+    }
+}
+
+/** @deprecated 使用 ECameraProjection 代替 */
+export const CameraProjection = ECameraProjection;

packages/rendering/camera/src/CameraManager.ts

@@ -0,0 +1,320 @@
+/**
+ * 相机管理器 - 提供相机相关的全局服务
+ * Camera Manager - Provides global camera services
+ *
+ * 主要功能：
+ * - 管理主相机
+ * - 屏幕坐标与世界坐标转换
+ *
+ * Main features:
+ * - Manage main camera
+ * - Screen to world coordinate conversion
+ */
+
+import type { Entity, IScene } from '@esengine/ecs-framework';
+import type { IVector2 } from '@esengine/ecs-framework-math';
+import { TransformComponent } from '@esengine/engine-core';
+import { CameraComponent, ECameraProjection } from './CameraComponent';
+
+/**
+ * 相机管理器接口
+ * Camera manager interface
+ */
+export interface ICameraManager {
+    /**
+     * 设置场景引用
+     * Set scene reference
+     */
+    setScene(scene: IScene | null): void;
+
+    /**
+     * 设置视口尺寸
+     * Set viewport size
+     */
+    setViewportSize(width: number, height: number): void;
+
+    /**
+     * 获取主相机实体
+     * Get main camera entity
+     */
+    getMainCamera(): Entity | null;
+
+    /**
+     * 获取主相机组件
+     * Get main camera component
+     */
+    getMainCameraComponent(): CameraComponent | null;
+
+    /**
+     * 屏幕坐标转世界坐标
+     * Convert screen coordinates to world coordinates
+     *
+     * @param screenX 屏幕 X 坐标 | Screen X coordinate
+     * @param screenY 屏幕 Y 坐标 | Screen Y coordinate
+     * @returns 世界坐标 | World coordinates
+     */
+    screenToWorld(screenX: number, screenY: number): IVector2;
+
+    /**
+     * 世界坐标转屏幕坐标
+     * Convert world coordinates to screen coordinates
+     *
+     * @param worldX 世界 X 坐标 | World X coordinate
+     * @param worldY 世界 Y 坐标 | World Y coordinate
+     * @returns 屏幕坐标 | Screen coordinates
+     */
+    worldToScreen(worldX: number, worldY: number): IVector2;
+}
+
+/**
+ * 相机管理器实现
+ * Camera manager implementation
+ *
+ * @example
+ * ```typescript
+ * // 获取全局实例
+ * import { CameraManager } from '@esengine/camera';
+ *
+ * // 设置场景和视口
+ * CameraManager.setScene(scene);
+ * CameraManager.setViewportSize(800, 600);
+ *
+ * // 屏幕坐标转世界坐标
+ * const worldPos = CameraManager.screenToWorld(mouseX, mouseY);
+ * console.log(`World position: ${worldPos.x}, ${worldPos.y}`);
+ * ```
+ */
+export class CameraManagerImpl implements ICameraManager {
+    private _scene: IScene | null = null;
+    private _viewportWidth: number = 800;
+    private _viewportHeight: number = 600;
+    private _mainCameraEntity: Entity | null = null;
+    private _mainCameraEntityDirty: boolean = true;
+
+    /**
+     * 设置场景引用
+     * Set scene reference
+     */
+    setScene(scene: IScene | null): void {
+        this._scene = scene;
+        this._mainCameraEntityDirty = true;
+        this._mainCameraEntity = null;
+    }
+
+    /**
+     * 设置视口尺寸
+     * Set viewport size
+     */
+    setViewportSize(width: number, height: number): void {
+        this._viewportWidth = Math.max(1, width);
+        this._viewportHeight = Math.max(1, height);
+    }
+
+    /**
+     * 获取视口宽度
+     * Get viewport width
+     */
+    get viewportWidth(): number {
+        return this._viewportWidth;
+    }
+
+    /**
+     * 获取视口高度
+     * Get viewport height
+     */
+    get viewportHeight(): number {
+        return this._viewportHeight;
+    }
+
+    /**
+     * 获取视口宽高比
+     * Get viewport aspect ratio
+     */
+    get aspectRatio(): number {
+        return this._viewportWidth / this._viewportHeight;
+    }
+
+    /**
+     * 标记主相机需要重新查找
+     * Mark main camera as dirty (needs re-lookup)
+     */
+    invalidateMainCamera(): void {
+        this._mainCameraEntityDirty = true;
+    }
+
+    /**
+     * 获取主相机实体
+     * Get main camera entity
+     */
+    getMainCamera(): Entity | null {
+        if (this._mainCameraEntityDirty || !this._mainCameraEntity) {
+            this._mainCameraEntity = this._findMainCamera();
+            this._mainCameraEntityDirty = false;
+        }
+        return this._mainCameraEntity;
+    }
+
+    /**
+     * 获取主相机组件
+     * Get main camera component
+     */
+    getMainCameraComponent(): CameraComponent | null {
+        const entity = this.getMainCamera();
+        return entity?.getComponent(CameraComponent) ?? null;
+    }
+
+    /**
+     * 查找主相机（depth 最小的相机）
+     * Find main camera (camera with lowest depth)
+     */
+    private _findMainCamera(): Entity | null {
+        if (!this._scene) return null;
+
+        let mainCamera: Entity | null = null;
+        let lowestDepth = Infinity;
+
+        // 使用 entities.buffer 遍历实体列表
+        // Use entities.buffer to iterate entity list
+        const entities = this._scene.entities.buffer;
+        for (let i = 0; i < entities.length; i++) {
+            const entity = entities[i];
+            if (!entity.enabled) continue;
+
+            const camera = entity.getComponent(CameraComponent);
+            if (camera && camera.depth < lowestDepth) {
+                lowestDepth = camera.depth;
+                mainCamera = entity;
+            }
+        }
+
+        return mainCamera;
+    }
+
+    /**
+     * 屏幕坐标转世界坐标
+     * Convert screen coordinates to world coordinates
+     *
+     * 对于正交相机：
+     * - 屏幕坐标 (0, 0) 在左上角
+     * - orthographicSize 是可见区域的半高度
+     *
+     * For orthographic camera:
+     * - Screen coordinates (0, 0) at top-left
+     * - orthographicSize is half-height of visible area
+     */
+    screenToWorld(screenX: number, screenY: number): IVector2 {
+        const camera = this.getMainCameraComponent();
+        const cameraEntity = this.getMainCamera();
+
+        if (!camera || !cameraEntity) {
+            // 没有相机时，返回简单的偏移 | No camera, return simple offset
+            return {
+                x: screenX - this._viewportWidth / 2,
+                y: screenY - this._viewportHeight / 2
+            };
+        }
+
+        // 获取相机位置 | Get camera position
+        const transform = cameraEntity.getComponent(TransformComponent);
+        const cameraX = transform?.worldPosition.x ?? 0;
+        const cameraY = transform?.worldPosition.y ?? 0;
+
+        if (camera.projection === ECameraProjection.Orthographic) {
+            return this._screenToWorldOrthographic(screenX, screenY, camera, cameraX, cameraY);
+        } else {
+            // 透视相机暂不支持，返回正交结果
+            // Perspective camera not supported yet, return orthographic result
+            return this._screenToWorldOrthographic(screenX, screenY, camera, cameraX, cameraY);
+        }
+    }
+
+    /**
+     * 正交相机的屏幕到世界转换
+     * Screen to world conversion for orthographic camera
+     */
+    private _screenToWorldOrthographic(
+        screenX: number,
+        screenY: number,
+        camera: CameraComponent,
+        cameraX: number,
+        cameraY: number
+    ): IVector2 {
+        const orthoSize = camera.orthographicSize;
+        const aspect = this.aspectRatio;
+
+        // 归一化设备坐标 (NDC) [-1, 1]
+        // Normalized Device Coordinates (NDC) [-1, 1]
+        const ndcX = (screenX / this._viewportWidth) * 2 - 1;
+        const ndcY = 1 - (screenY / this._viewportHeight) * 2; // Y 轴翻转 | Flip Y axis
+
+        // 世界坐标 | World coordinates
+        const worldX = cameraX + ndcX * orthoSize * aspect;
+        const worldY = cameraY + ndcY * orthoSize;
+
+        return { x: worldX, y: worldY };
+    }
+
+    /**
+     * 世界坐标转屏幕坐标
+     * Convert world coordinates to screen coordinates
+     */
+    worldToScreen(worldX: number, worldY: number): IVector2 {
+        const camera = this.getMainCameraComponent();
+        const cameraEntity = this.getMainCamera();
+
+        if (!camera || !cameraEntity) {
+            // 没有相机时，返回简单的偏移 | No camera, return simple offset
+            return {
+                x: worldX + this._viewportWidth / 2,
+                y: worldY + this._viewportHeight / 2
+            };
+        }
+
+        // 获取相机位置 | Get camera position
+        const transform = cameraEntity.getComponent(TransformComponent);
+        const cameraX = transform?.worldPosition.x ?? 0;
+        const cameraY = transform?.worldPosition.y ?? 0;
+
+        if (camera.projection === ECameraProjection.Orthographic) {
+            return this._worldToScreenOrthographic(worldX, worldY, camera, cameraX, cameraY);
+        } else {
+            // 透视相机暂不支持 | Perspective camera not supported yet
+            return this._worldToScreenOrthographic(worldX, worldY, camera, cameraX, cameraY);
+        }
+    }
+
+    /**
+     * 正交相机的世界到屏幕转换
+     * World to screen conversion for orthographic camera
+     */
+    private _worldToScreenOrthographic(
+        worldX: number,
+        worldY: number,
+        camera: CameraComponent,
+        cameraX: number,
+        cameraY: number
+    ): IVector2 {
+        const orthoSize = camera.orthographicSize;
+        const aspect = this.aspectRatio;
+
+        // 相对于相机的偏移 | Offset relative to camera
+        const offsetX = worldX - cameraX;
+        const offsetY = worldY - cameraY;
+
+        // NDC 坐标 | NDC coordinates
+        const ndcX = offsetX / (orthoSize * aspect);
+        const ndcY = offsetY / orthoSize;
+
+        // 屏幕坐标 | Screen coordinates
+        const screenX = (ndcX + 1) * 0.5 * this._viewportWidth;
+        const screenY = (1 - ndcY) * 0.5 * this._viewportHeight; // Y 轴翻转 | Flip Y axis
+
+        return { x: screenX, y: screenY };
+    }
+}
+
+/**
+ * 全局相机管理器实例
+ * Global camera manager instance
+ */
+export const CameraManager = new CameraManagerImpl();

packages/rendering/camera/src/CameraPlugin.ts

@@ -0,0 +1,43 @@
+import type { IComponentRegistry, IScene } from '@esengine/ecs-framework';
+import type { IRuntimeModule, IRuntimePlugin, ModuleManifest, SystemContext } from '@esengine/engine-core';
+import { RenderConfigServiceToken } from '@esengine/engine-core';
+import { CameraComponent } from './CameraComponent';
+import { CameraSystem } from './CameraSystem';
+
+class CameraRuntimeModule implements IRuntimeModule {
+    registerComponents(registry: IComponentRegistry): void {
+        registry.register(CameraComponent);
+    }
+
+    createSystems(scene: IScene, context: SystemContext): void {
+        // 从服务注册表获取渲染配置服务 | Get render config service from registry
+        const renderConfig = context.services.get(RenderConfigServiceToken);
+        if (!renderConfig) {
+            console.warn('[CameraPlugin] RenderConfigService not found, CameraSystem will not be created');
+            return;
+        }
+
+        // 创建并添加 CameraSystem | Create and add CameraSystem
+        const cameraSystem = new CameraSystem(renderConfig);
+        scene.addSystem(cameraSystem);
+    }
+}
+
+const manifest: ModuleManifest = {
+    id: 'camera',
+    name: '@esengine/camera',
+    displayName: 'Camera',
+    version: '1.0.0',
+    description: '2D/3D 相机组件',
+    category: 'Rendering',
+    isCore: false,
+    defaultEnabled: true,
+    isEngineModule: true,
+    dependencies: ['core', 'math'],
+    exports: { components: ['CameraComponent'] }
+};
+
+export const CameraPlugin: IRuntimePlugin = {
+    manifest,
+    runtimeModule: new CameraRuntimeModule()
+};

packages/rendering/camera/src/CameraSystem.ts

@@ -0,0 +1,52 @@
+/**
+ * Camera System
+ * 相机系统
+ */
+
+import { EntitySystem, Matcher, Entity, ECSSystem } from '@esengine/ecs-framework';
+import type { IRenderConfigService } from '@esengine/engine-core';
+import { CameraComponent } from './CameraComponent';
+
+@ECSSystem('Camera', { updateOrder: -100 })
+export class CameraSystem extends EntitySystem {
+    private renderConfig: IRenderConfigService;
+    private lastAppliedCameraId: number | null = null;
+
+    constructor(renderConfig: IRenderConfigService) {
+        // Match entities with CameraComponent
+        super(Matcher.empty().all(CameraComponent));
+        this.renderConfig = renderConfig;
+    }
+
+    protected override onBegin(): void {
+        // Will process cameras in process()
+    }
+
+    protected override process(entities: readonly Entity[]): void {
+        // Use first enabled camera
+        for (const entity of entities) {
+            if (!entity.enabled) continue;
+
+            const camera = entity.getComponent(CameraComponent);
+            if (!camera) continue;
+
+            // Only apply if camera changed
+            if (this.lastAppliedCameraId !== entity.id) {
+                this.applyCamera(camera);
+                this.lastAppliedCameraId = entity.id;
+            }
+
+            // Only use first active camera
+            break;
+        }
+    }
+
+    private applyCamera(camera: CameraComponent): void {
+        // Apply background color
+        const bgColor = camera.backgroundColor || '#000000';
+        const r = parseInt(bgColor.slice(1, 3), 16) / 255;
+        const g = parseInt(bgColor.slice(3, 5), 16) / 255;
+        const b = parseInt(bgColor.slice(5, 7), 16) / 255;
+        this.renderConfig.setClearColor(r, g, b, 1.0);
+    }
+}

packages/rendering/camera/src/index.ts

@@ -0,0 +1,8 @@
+export { CameraComponent, ECameraProjection, CameraProjection } from './CameraComponent';
+export { CameraSystem } from './CameraSystem';
+export { CameraPlugin } from './CameraPlugin';
+export { CameraManager, CameraManagerImpl, type ICameraManager } from './CameraManager';
+
+// Service Tokens
+// 服务令牌
+export { CameraManagerToken } from './tokens';

packages/rendering/camera/src/tokens.ts

@@ -0,0 +1,20 @@
+/**
+ * Camera Module Service Tokens
+ * 相机模块服务令牌
+ *
+ * 遵循"谁定义接口，谁导出 Token"原则。
+ * Following "who defines interface, who exports Token" principle.
+ */
+
+import { createServiceToken } from '@esengine/ecs-framework';
+import type { ICameraManager } from './CameraManager';
+
+// Re-export interface for consumers
+// 重新导出接口供消费者使用
+export type { ICameraManager };
+
+/**
+ * 相机管理器服务令牌
+ * Camera manager service token
+ */
+export const CameraManagerToken = createServiceToken<ICameraManager>('cameraManager');

packages/rendering/camera/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+    "extends": "../../../tsconfig.base.json",
+    "compilerOptions": {
+        "composite": false,
+        "declaration": true,
+        "declarationMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

packages/rendering/camera/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ],
+  "references": [
+    {
+      "path": "../../framework/core"
+    }
+  ]
+}

packages/rendering/camera/tsup.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'tsup';
+import { runtimeOnlyPreset } from '../../tools/build-config/src/presets/plugin-tsup';
+
+export default defineConfig({
+    ...runtimeOnlyPreset(),
+    tsconfig: 'tsconfig.build.json'
+});