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
This commit is contained in:
YHH
GitHub
331
packages/framework/spatial/src/ISpatialQuery.ts
Normal file
331
packages/framework/spatial/src/ISpatialQuery.ts
Normal file
@@ -0,0 +1,331 @@
|
||||
/**
|
||||
* @zh 空间查询接口
|
||||
* @en Spatial Query Interface
|
||||
*
|
||||
* @zh 提供空间查询的核心抽象
|
||||
* @en Provides core abstractions for spatial queries
|
||||
*/
|
||||
|
||||
import type { IVector2 } from '@esengine/ecs-framework-math';
|
||||
|
||||
// =============================================================================
|
||||
// 基础类型 | Basic Types
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* @zh 空间边界框
|
||||
* @en Spatial bounding box
|
||||
*/
|
||||
export interface IBounds {
|
||||
/**
|
||||
* @zh 最小 X 坐标
|
||||
* @en Minimum X coordinate
|
||||
*/
|
||||
readonly minX: number;
|
||||
|
||||
/**
|
||||
* @zh 最小 Y 坐标
|
||||
* @en Minimum Y coordinate
|
||||
*/
|
||||
readonly minY: number;
|
||||
|
||||
/**
|
||||
* @zh 最大 X 坐标
|
||||
* @en Maximum X coordinate
|
||||
*/
|
||||
readonly maxX: number;
|
||||
|
||||
/**
|
||||
* @zh 最大 Y 坐标
|
||||
* @en Maximum Y coordinate
|
||||
*/
|
||||
readonly maxY: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 可定位对象接口
|
||||
* @en Positionable object interface
|
||||
*/
|
||||
export interface IPositionable {
|
||||
/**
|
||||
* @zh 获取对象位置
|
||||
* @en Get object position
|
||||
*/
|
||||
readonly position: IVector2;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 可定位且有边界的对象接口
|
||||
* @en Positionable object with bounds interface
|
||||
*/
|
||||
export interface IBoundable extends IPositionable {
|
||||
/**
|
||||
* @zh 获取对象边界
|
||||
* @en Get object bounds
|
||||
*/
|
||||
readonly bounds: IBounds;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 射线检测结果
|
||||
* @en Raycast hit result
|
||||
*/
|
||||
export interface IRaycastHit<T> {
|
||||
/**
|
||||
* @zh 命中的对象
|
||||
* @en Hit object
|
||||
*/
|
||||
readonly target: T;
|
||||
|
||||
/**
|
||||
* @zh 命中点
|
||||
* @en Hit point
|
||||
*/
|
||||
readonly point: IVector2;
|
||||
|
||||
/**
|
||||
* @zh 命中点的法线
|
||||
* @en Normal at hit point
|
||||
*/
|
||||
readonly normal: IVector2;
|
||||
|
||||
/**
|
||||
* @zh 距离射线起点的距离
|
||||
* @en Distance from ray origin
|
||||
*/
|
||||
readonly distance: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 过滤器函数类型
|
||||
* @en Filter function type
|
||||
*/
|
||||
export type SpatialFilter<T> = (item: T) => boolean;
|
||||
|
||||
// =============================================================================
|
||||
// 空间查询接口 | Spatial Query Interface
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* @zh 空间查询接口
|
||||
* @en Spatial query interface
|
||||
*
|
||||
* @zh 提供空间查询能力，支持范围查询、最近邻查询和射线检测
|
||||
* @en Provides spatial query capabilities including range queries, nearest neighbor queries, and raycasting
|
||||
*/
|
||||
export interface ISpatialQuery<T> {
|
||||
/**
|
||||
* @zh 查找半径内的所有对象
|
||||
* @en Find all objects within radius
|
||||
*
|
||||
* @param center - @zh 中心点 @en Center point
|
||||
* @param radius - @zh 半径 @en Radius
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 半径内的对象数组 @en Array of objects within radius
|
||||
*/
|
||||
findInRadius(center: IVector2, radius: number, filter?: SpatialFilter<T>): T[];
|
||||
|
||||
/**
|
||||
* @zh 查找矩形区域内的所有对象
|
||||
* @en Find all objects within rectangle
|
||||
*
|
||||
* @param bounds - @zh 边界框 @en Bounding box
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 区域内的对象数组 @en Array of objects within bounds
|
||||
*/
|
||||
findInRect(bounds: IBounds, filter?: SpatialFilter<T>): T[];
|
||||
|
||||
/**
|
||||
* @zh 查找最近的对象
|
||||
* @en Find nearest object
|
||||
*
|
||||
* @param center - @zh 查询中心点 @en Query center point
|
||||
* @param maxDistance - @zh 最大搜索距离 @en Maximum search distance
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 最近的对象，没有则返回 null @en Nearest object or null
|
||||
*/
|
||||
findNearest(center: IVector2, maxDistance?: number, filter?: SpatialFilter<T>): T | null;
|
||||
|
||||
/**
|
||||
* @zh 查找最近的 K 个对象
|
||||
* @en Find K nearest objects
|
||||
*
|
||||
* @param center - @zh 查询中心点 @en Query center point
|
||||
* @param k - @zh 返回的对象数量 @en Number of objects to return
|
||||
* @param maxDistance - @zh 最大搜索距离 @en Maximum search distance
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 最近的 K 个对象数组 @en Array of K nearest objects
|
||||
*/
|
||||
findKNearest(center: IVector2, k: number, maxDistance?: number, filter?: SpatialFilter<T>): T[];
|
||||
|
||||
/**
|
||||
* @zh 射线检测
|
||||
* @en Raycast
|
||||
*
|
||||
* @param origin - @zh 射线起点 @en Ray origin
|
||||
* @param direction - @zh 射线方向（应归一化）@en Ray direction (should be normalized)
|
||||
* @param maxDistance - @zh 最大检测距离 @en Maximum detection distance
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 命中结果数组，按距离排序 @en Array of hit results sorted by distance
|
||||
*/
|
||||
raycast(origin: IVector2, direction: IVector2, maxDistance: number, filter?: SpatialFilter<T>): IRaycastHit<T>[];
|
||||
|
||||
/**
|
||||
* @zh 射线检测（仅返回第一个命中）
|
||||
* @en Raycast (return first hit only)
|
||||
*
|
||||
* @param origin - @zh 射线起点 @en Ray origin
|
||||
* @param direction - @zh 射线方向（应归一化）@en Ray direction (should be normalized)
|
||||
* @param maxDistance - @zh 最大检测距离 @en Maximum detection distance
|
||||
* @param filter - @zh 过滤函数 @en Filter function
|
||||
* @returns @zh 第一个命中结果，没有则返回 null @en First hit result or null
|
||||
*/
|
||||
raycastFirst(origin: IVector2, direction: IVector2, maxDistance: number, filter?: SpatialFilter<T>): IRaycastHit<T> | null;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// 空间索引接口 | Spatial Index Interface
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* @zh 空间索引接口
|
||||
* @en Spatial index interface
|
||||
*
|
||||
* @zh 提供空间索引的管理能力
|
||||
* @en Provides spatial index management capabilities
|
||||
*/
|
||||
export interface ISpatialIndex<T> extends ISpatialQuery<T> {
|
||||
/**
|
||||
* @zh 插入对象
|
||||
* @en Insert object
|
||||
*
|
||||
* @param item - @zh 要插入的对象 @en Object to insert
|
||||
* @param position - @zh 对象位置 @en Object position
|
||||
*/
|
||||
insert(item: T, position: IVector2): void;
|
||||
|
||||
/**
|
||||
* @zh 移除对象
|
||||
* @en Remove object
|
||||
*
|
||||
* @param item - @zh 要移除的对象 @en Object to remove
|
||||
* @returns @zh 是否成功移除 @en Whether removal was successful
|
||||
*/
|
||||
remove(item: T): boolean;
|
||||
|
||||
/**
|
||||
* @zh 更新对象位置
|
||||
* @en Update object position
|
||||
*
|
||||
* @param item - @zh 要更新的对象 @en Object to update
|
||||
* @param newPosition - @zh 新位置 @en New position
|
||||
* @returns @zh 是否成功更新 @en Whether update was successful
|
||||
*/
|
||||
update(item: T, newPosition: IVector2): boolean;
|
||||
|
||||
/**
|
||||
* @zh 清空索引
|
||||
* @en Clear index
|
||||
*/
|
||||
clear(): void;
|
||||
|
||||
/**
|
||||
* @zh 获取索引中的对象数量
|
||||
* @en Get number of objects in index
|
||||
*/
|
||||
readonly count: number;
|
||||
|
||||
/**
|
||||
* @zh 获取所有对象
|
||||
* @en Get all objects
|
||||
*/
|
||||
getAll(): T[];
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// 工具函数 | Utility Functions
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* @zh 创建边界框
|
||||
* @en Create bounding box
|
||||
*/
|
||||
export function createBounds(minX: number, minY: number, maxX: number, maxY: number): IBounds {
|
||||
return { minX, minY, maxX, maxY };
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 从中心点和尺寸创建边界框
|
||||
* @en Create bounding box from center and size
|
||||
*/
|
||||
export function createBoundsFromCenter(center: IVector2, width: number, height: number): IBounds {
|
||||
const halfWidth = width / 2;
|
||||
const halfHeight = height / 2;
|
||||
return {
|
||||
minX: center.x - halfWidth,
|
||||
minY: center.y - halfHeight,
|
||||
maxX: center.x + halfWidth,
|
||||
maxY: center.y + halfHeight
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 从圆形创建边界框
|
||||
* @en Create bounding box from circle
|
||||
*/
|
||||
export function createBoundsFromCircle(center: IVector2, radius: number): IBounds {
|
||||
return {
|
||||
minX: center.x - radius,
|
||||
minY: center.y - radius,
|
||||
maxX: center.x + radius,
|
||||
maxY: center.y + radius
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 检查点是否在边界框内
|
||||
* @en Check if point is inside bounds
|
||||
*/
|
||||
export function isPointInBounds(point: IVector2, bounds: IBounds): boolean {
|
||||
return point.x >= bounds.minX && point.x <= bounds.maxX &&
|
||||
point.y >= bounds.minY && point.y <= bounds.maxY;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 检查两个边界框是否相交
|
||||
* @en Check if two bounding boxes intersect
|
||||
*/
|
||||
export function boundsIntersect(a: IBounds, b: IBounds): boolean {
|
||||
return a.minX <= b.maxX && a.maxX >= b.minX &&
|
||||
a.minY <= b.maxY && a.maxY >= b.minY;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 检查边界框是否与圆形相交
|
||||
* @en Check if bounds intersects with circle
|
||||
*/
|
||||
export function boundsIntersectsCircle(bounds: IBounds, center: IVector2, radius: number): boolean {
|
||||
const closestX = Math.max(bounds.minX, Math.min(center.x, bounds.maxX));
|
||||
const closestY = Math.max(bounds.minY, Math.min(center.y, bounds.maxY));
|
||||
const distanceX = center.x - closestX;
|
||||
const distanceY = center.y - closestY;
|
||||
return (distanceX * distanceX + distanceY * distanceY) <= (radius * radius);
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 计算两点之间的距离平方
|
||||
* @en Calculate squared distance between two points
|
||||
*/
|
||||
export function distanceSquared(a: IVector2, b: IVector2): number {
|
||||
const dx = a.x - b.x;
|
||||
const dy = a.y - b.y;
|
||||
return dx * dx + dy * dy;
|
||||
}
|
||||
|
||||
/**
|
||||
* @zh 计算两点之间的距离
|
||||
* @en Calculate distance between two points
|
||||
*/
|
||||
export function distance(a: IVector2, b: IVector2): number {
|
||||
return Math.sqrt(distanceSquared(a, b));
|
||||
}
|
||||
Reference in New Issue
Block a user