Feature/physics and tilemap enhancement (#247)

* feat(behavior-tree,tilemap): 修复编辑器连线缩放问题并增强插件系统 * feat(node-editor,blueprint): 新增通用节点编辑器和蓝图可视化脚本系统 * feat(editor,tilemap): 优化编辑器UI样式和Tilemap编辑器功能 * fix: 修复CodeQL安全警告和CI类型检查错误 * fix: 修复CodeQL安全警告和CI类型检查错误 * fix: 修复CodeQL安全警告和CI类型检查错误
2025-11-29 23:00:48 +08:00
parent f03b73b58e
commit 359886c72f
198 changed files with 33879 additions and 13121 deletions
--- a/packages/tilemap/src/physics/TilemapCollider2DComponent.ts
+++ b/packages/tilemap/src/physics/TilemapCollider2DComponent.ts
@@ -0,0 +1,280 @@
+/**
+ * TilemapCollider2D Component
+ * Tilemap 碰撞体组件
+ *
+ * 将 TilemapComponent 的碰撞数据转换为物理碰撞体。
+ * 使用优化算法合并相邻碰撞格子，减少碰撞体数量。
+ */
+
+import { Component, Property, Serialize, ECSComponent, Serializable } from '@esengine/ecs-framework';
+
+/**
+ * 碰撞体生成模式
+ */
+export enum TilemapColliderMode {
+    /** 每个碰撞格子单独创建碰撞体 */
+    PerTile = 0,
+    /** 合并相邻碰撞格子为更大的矩形 */
+    Merged = 1,
+    /** 只生成边缘碰撞体（优化性能） */
+    EdgeOnly = 2,
+}
+
+/**
+ * 合并后的碰撞矩形
+ */
+export interface CollisionRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/**
+ * TilemapCollider2D 组件
+ *
+ * 自动从同一实体的 TilemapComponent 读取碰撞数据，
+ * 并生成对应的物理碰撞体。
+ */
+@ECSComponent('TilemapCollider2D')
+@Serializable({ version: 1, typeId: 'TilemapCollider2D' })
+export class TilemapCollider2DComponent extends Component {
+    /**
+     * 碰撞体生成模式
+     */
+    @Serialize()
+    @Property({
+        type: 'enum',
+        label: 'Collider Mode',
+        options: [
+            { label: 'Per Tile', value: TilemapColliderMode.PerTile },
+            { label: 'Merged', value: TilemapColliderMode.Merged },
+            { label: 'Edge Only', value: TilemapColliderMode.EdgeOnly },
+        ],
+    })
+    public colliderMode: TilemapColliderMode = TilemapColliderMode.Merged;
+
+    /**
+     * 碰撞层（该碰撞体所在的层）
+     */
+    @Serialize()
+    @Property({ type: 'collisionLayer', label: 'Collision Layer' })
+    public collisionLayer: number = 1; // Default layer
+
+    /**
+     * 碰撞掩码（该碰撞体可以与哪些层碰撞）
+     */
+    @Serialize()
+    @Property({ type: 'collisionMask', label: 'Collision Mask' })
+    public collisionMask: number = 0xFFFF; // All layers
+
+    /**
+     * 摩擦系数
+     */
+    @Serialize()
+    @Property({ type: 'number', label: 'Friction', min: 0, max: 1, step: 0.01 })
+    public friction: number = 0.5;
+
+    /**
+     * 弹性系数
+     */
+    @Serialize()
+    @Property({ type: 'number', label: 'Restitution', min: 0, max: 1, step: 0.01 })
+    public restitution: number = 0;
+
+    /**
+     * 是否为触发器
+     */
+    @Serialize()
+    @Property({ type: 'boolean', label: 'Is Trigger' })
+    public isTrigger: boolean = false;
+
+    /**
+     * 生成的碰撞矩形缓存
+     * @internal
+     */
+    public _collisionRects: CollisionRect[] = [];
+
+    /**
+     * 碰撞体句柄列表
+     * @internal
+     */
+    public _colliderHandles: number[] = [];
+
+    /**
+     * 是否需要重建碰撞体
+     * @internal
+     */
+    public _needsRebuild: boolean = true;
+
+    /**
+     * 碰撞数据版本（用于检测变化）
+     * @internal
+     */
+    public _lastCollisionVersion: number = -1;
+
+    /**
+     * 从碰撞数据生成碰撞矩形
+     * @param collisionData 碰撞数据数组
+     * @param width 地图宽度（格子数）
+     * @param height 地图高度（格子数）
+     * @param tileWidth 格子宽度（像素）
+     * @param tileHeight 格子高度（像素）
+     */
+    public generateCollisionRects(
+        collisionData: Uint32Array,
+        width: number,
+        height: number,
+        tileWidth: number,
+        tileHeight: number
+    ): CollisionRect[] {
+        if (collisionData.length === 0) {
+            this._collisionRects = [];
+            return [];
+        }
+
+        switch (this.colliderMode) {
+            case TilemapColliderMode.PerTile:
+                this._collisionRects = this._generatePerTileRects(
+                    collisionData, width, height, tileWidth, tileHeight
+                );
+                break;
+            case TilemapColliderMode.Merged:
+                this._collisionRects = this._generateMergedRects(
+                    collisionData, width, height, tileWidth, tileHeight
+                );
+                break;
+            case TilemapColliderMode.EdgeOnly:
+                // Edge-only 模式暂时使用合并模式
+                this._collisionRects = this._generateMergedRects(
+                    collisionData, width, height, tileWidth, tileHeight
+                );
+                break;
+        }
+
+        this._needsRebuild = true;
+        return this._collisionRects;
+    }
+
+    /**
+     * 每个格子单独生成矩形
+     */
+    private _generatePerTileRects(
+        collisionData: Uint32Array,
+        width: number,
+        height: number,
+        tileWidth: number,
+        tileHeight: number
+    ): CollisionRect[] {
+        const rects: CollisionRect[] = [];
+
+        for (let row = 0; row < height; row++) {
+            for (let col = 0; col < width; col++) {
+                if (collisionData[row * width + col] > 0) {
+                    rects.push({
+                        x: col * tileWidth,
+                        y: row * tileHeight,
+                        width: tileWidth,
+                        height: tileHeight,
+                    });
+                }
+            }
+        }
+
+        return rects;
+    }
+
+    /**
+     * 合并相邻格子生成更大的矩形（贪心算法）
+     *
+     * 使用行优先扫描，合并水平相邻的碰撞格子，
+     * 然后尝试垂直合并相同宽度的矩形。
+     */
+    private _generateMergedRects(
+        collisionData: Uint32Array,
+        width: number,
+        height: number,
+        tileWidth: number,
+        tileHeight: number
+    ): CollisionRect[] {
+        // 创建已处理标记数组
+        const processed = new Array(width * height).fill(false);
+        const rects: CollisionRect[] = [];
+
+        for (let row = 0; row < height; row++) {
+            for (let col = 0; col < width; col++) {
+                const index = row * width + col;
+
+                // 跳过已处理或无碰撞的格子
+                if (processed[index] || collisionData[index] === 0) {
+                    continue;
+                }
+
+                // 找到水平方向最大范围
+                let endCol = col;
+                while (
+                    endCol < width &&
+                    collisionData[row * width + endCol] > 0 &&
+                    !processed[row * width + endCol]
+                ) {
+                    endCol++;
+                }
+                const rectWidth = endCol - col;
+
+                // 找到垂直方向最大范围（保持相同宽度）
+                let endRow = row;
+                let canExtend = true;
+                while (canExtend && endRow < height) {
+                    // 检查这一行是否都有碰撞且未处理
+                    for (let c = col; c < endCol; c++) {
+                        const idx = endRow * width + c;
+                        if (collisionData[idx] === 0 || processed[idx]) {
+                            canExtend = false;
+                            break;
+                        }
+                    }
+                    if (canExtend) {
+                        endRow++;
+                    }
+                }
+                const rectHeight = endRow - row;
+
+                // 标记所有包含的格子为已处理
+                for (let r = row; r < endRow; r++) {
+                    for (let c = col; c < endCol; c++) {
+                        processed[r * width + c] = true;
+                    }
+                }
+
+                // 添加合并后的矩形
+                rects.push({
+                    x: col * tileWidth,
+                    y: row * tileHeight,
+                    width: rectWidth * tileWidth,
+                    height: rectHeight * tileHeight,
+                });
+            }
+        }
+
+        return rects;
+    }
+
+    /**
+     * 获取碰撞矩形数量
+     */
+    public getCollisionRectCount(): number {
+        return this._collisionRects.length;
+    }
+
+    /**
+     * 标记需要重建
+     */
+    public markNeedsRebuild(): void {
+        this._needsRebuild = true;
+    }
+
+    public override onRemovedFromEntity(): void {
+        this._collisionRects = [];
+        this._colliderHandles = [];
+    }
+}
--- a/packages/tilemap/src/physics/TilemapPhysicsSystem.ts
+++ b/packages/tilemap/src/physics/TilemapPhysicsSystem.ts
@@ -0,0 +1,186 @@
+/**
+ * TilemapPhysicsSystem
+ * Tilemap 物理系统
+ *
+ * 负责将 TilemapComponent 的碰撞数据同步到物理世界。
+ * 需要与 Physics2DSystem 配合使用。
+ */
+
+import { EntitySystem, Matcher, ECSSystem, type Entity, type Scene } from '@esengine/ecs-framework';
+import { TransformComponent } from '@esengine/ecs-components';
+import { TilemapComponent } from '../TilemapComponent';
+import { TilemapCollider2DComponent, type CollisionRect } from './TilemapCollider2DComponent';
+
+/**
+ * 物理世界接口（避免直接依赖 physics-rapier2d）
+ */
+export interface IPhysicsWorld {
+    createStaticCollider(
+        entityId: number,
+        position: { x: number; y: number },
+        halfExtents: { x: number; y: number },
+        collisionLayer: number,
+        collisionMask: number,
+        friction: number,
+        restitution: number,
+        isTrigger: boolean
+    ): number | null;
+    removeCollider(handle: number): void;
+}
+
+/**
+ * 物理系统接口
+ */
+export interface IPhysics2DSystem {
+    world: IPhysicsWorld;
+}
+
+/**
+ * Tilemap 物理系统
+ *
+ * 监听带有 TilemapComponent 和 TilemapCollider2DComponent 的实体，
+ * 自动将碰撞数据转换为物理碰撞体。
+ */
+@ECSSystem('TilemapPhysics', { updateOrder: 50 })
+export class TilemapPhysicsSystem extends EntitySystem {
+    private _physicsWorld: IPhysicsWorld | null = null;
+    private _pendingEntities: Entity[] = [];
+
+    constructor() {
+        super(Matcher.empty().all(TilemapComponent, TilemapCollider2DComponent));
+    }
+
+    /**
+     * 设置物理世界引用
+     */
+    public setPhysicsWorld(world: IPhysicsWorld): void {
+        this._physicsWorld = world;
+
+        // 处理待处理的实体
+        for (const entity of this._pendingEntities) {
+            this._createColliders(entity);
+        }
+        this._pendingEntities = [];
+    }
+
+    protected override onAdded(entity: Entity): void {
+        if (!this._physicsWorld) {
+            this._pendingEntities.push(entity);
+            return;
+        }
+        this._createColliders(entity);
+    }
+
+    protected override onRemoved(entity: Entity): void {
+        this._removeColliders(entity);
+
+        const idx = this._pendingEntities.indexOf(entity);
+        if (idx >= 0) {
+            this._pendingEntities.splice(idx, 1);
+        }
+    }
+
+    protected override process(entities: readonly Entity[]): void {
+        if (!this._physicsWorld) return;
+
+        for (const entity of entities) {
+            const tilemap = entity.getComponent(TilemapComponent);
+            const collider = entity.getComponent(TilemapCollider2DComponent);
+
+            if (!tilemap || !collider) continue;
+
+            // 检查碰撞数据是否变化
+            const currentVersion = tilemap.renderDirty ? Date.now() : collider._lastCollisionVersion;
+            if (collider._needsRebuild || currentVersion !== collider._lastCollisionVersion) {
+                this._rebuildColliders(entity);
+                collider._lastCollisionVersion = currentVersion;
+            }
+        }
+    }
+
+    /**
+     * 创建碰撞体
+     */
+    private _createColliders(entity: Entity): void {
+        const tilemap = entity.getComponent(TilemapComponent);
+        const collider = entity.getComponent(TilemapCollider2DComponent);
+        const transform = entity.getComponent(TransformComponent);
+
+        if (!tilemap || !collider || !this._physicsWorld) return;
+
+        // 生成碰撞矩形
+        const collisionData = tilemap.collisionData;
+        collider.generateCollisionRects(
+            collisionData,
+            tilemap.width,
+            tilemap.height,
+            tilemap.tileWidth,
+            tilemap.tileHeight
+        );
+
+        // 获取实体位置偏移
+        const offsetX = transform?.position.x ?? 0;
+        const offsetY = transform?.position.y ?? 0;
+
+        // 计算地图总高度（像素），用于 Y 轴翻转
+        // Calculate total map height (pixels) for Y-axis flip
+        const mapPixelHeight = tilemap.height * tilemap.tileHeight;
+
+        // 为每个碰撞矩形创建物理碰撞体
+        for (const rect of collider._collisionRects) {
+            // Y 轴翻转：rect.y 是从顶部计算的，需要翻转到底部
+            // Y-axis flip: rect.y is calculated from top, needs flip to bottom
+            const flippedY = mapPixelHeight - rect.y - rect.height;
+
+            const handle = this._physicsWorld.createStaticCollider(
+                entity.id,
+                {
+                    x: offsetX + rect.x + rect.width / 2,
+                    y: offsetY + flippedY + rect.height / 2,
+                },
+                {
+                    x: rect.width / 2,
+                    y: rect.height / 2,
+                },
+                collider.collisionLayer,
+                collider.collisionMask,
+                collider.friction,
+                collider.restitution,
+                collider.isTrigger
+            );
+
+            if (handle !== null) {
+                collider._colliderHandles.push(handle);
+            }
+        }
+
+        collider._needsRebuild = false;
+        this.logger.debug(`Created ${collider._colliderHandles.length} colliders for tilemap entity ${entity.name}`);
+    }
+
+    /**
+     * 移除碰撞体
+     */
+    private _removeColliders(entity: Entity): void {
+        const collider = entity.getComponent(TilemapCollider2DComponent);
+        if (!collider || !this._physicsWorld) return;
+
+        for (const handle of collider._colliderHandles) {
+            this._physicsWorld.removeCollider(handle);
+        }
+        collider._colliderHandles = [];
+    }
+
+    /**
+     * 重建碰撞体
+     */
+    private _rebuildColliders(entity: Entity): void {
+        this._removeColliders(entity);
+        this._createColliders(entity);
+    }
+
+    protected override onDestroy(): void {
+        this._physicsWorld = null;
+        this._pendingEntities = [];
+    }
+}