From a2aedb39697d8096471eb38b9204a3dd05b6e48e Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Thu, 10 Sep 2026 09:35:21 +0800 Subject: [PATCH] refactor(02-04): restore authorized path contract - Match path/types.ts to the user-authored baseline plus nullable returns - Keep graph contracts implementation-owned and preserve the mover bridge --- packages-user/data-system/src/path/finder.ts | 8 +- packages-user/data-system/src/path/graph.ts | 80 ++++++++++++++++-- packages-user/data-system/src/path/system.ts | 13 ++- packages-user/data-system/src/path/types.ts | 89 ++------------------ 4 files changed, 91 insertions(+), 99 deletions(-) diff --git a/packages-user/data-system/src/path/finder.ts b/packages-user/data-system/src/path/finder.ts index fa7e3b2..ed8e87e 100644 --- a/packages-user/data-system/src/path/finder.ts +++ b/packages-user/data-system/src/path/finder.ts @@ -7,12 +7,8 @@ import { } from '@user/data-base'; import { isNil } from 'lodash-es'; import { PathfindingGraphBuilder } from './graph'; -import { - IPathfinder, - IPathfindingStep, - IPathGraph, - PathCostFunction -} from './types'; +import { IPathfinder, IPathfindingStep, PathCostFunction } from './types'; +import { IPathGraph } from './graph'; interface IDistanceHeapEntry { /** 条目的键值，堆中键值最小的条目最先取出 */ diff --git a/packages-user/data-system/src/path/graph.ts b/packages-user/data-system/src/path/graph.ts index 8d5e89c..3b9bf83 100644 --- a/packages-user/data-system/src/path/graph.ts +++ b/packages-user/data-system/src/path/graph.ts @@ -15,13 +15,79 @@ import { IPassPredicate } from '@user/data-base'; import { isNil } from 'lodash-es'; -import { - IPathGraph, - IPathGraphEdge, - IPathGraphNode, - IPathfindingGraphBuilder, - PathCostFunction -} from './types'; +import { PathCostFunction } from './types'; + +export interface IPathGraphEdge { + /** 本条边对应的移动方向 */ + readonly dir: FaceDirection; + /** 边指向的节点索引，值为 y * width + x */ + readonly to: number; +} + +export interface IPathGraphNode { + /** 节点索引，值为 y * width + x */ + readonly index: number; + /** 节点横坐标 */ + readonly x: number; + /** 节点纵坐标 */ + readonly y: number; + /** 节点对应的位置信息 */ + readonly block: ILayerLocation; + /** 进入该节点的损失，构建图时由损失函数计算 */ + readonly cost: number; + /** 该节点是否仅可作为路径终点，不可作为中间节点 */ + readonly terminal: boolean; + /** 该节点的全部出边 */ + readonly edges: readonly IPathGraphEdge[]; +} + +export interface IPathGraph { + /** 图宽度 */ + readonly width: number; + /** 图高度 */ + readonly height: number; + /** 图内全部节点，键为节点索引 */ + readonly nodes: ReadonlyMap; +} + +export interface IPathfindingGraphBuilder { + /** + * 绑定地图状态对象，用于解析图层所属楼层 id + * @param maps 地图状态对象 + */ + useMapState(maps: IMapState | null): void; + + /** + * 绑定构建有向图所用的地图图层 + * @param layer 地图图层对象 + */ + useMapLayer(layer: IMapLayer | null): void; + + /** + * 设置构建图时使用的损失函数，未注入时每格损失 1 + * @param cost 损失函数 + */ + useCostFunction(cost: PathCostFunction | null): void; + + /** + * 注入判定边可行性的通行性谓词 + * @param predicate 通行性谓词 + */ + usePassPredicate(predicate: IPassPredicate | null): void; + + /** + * 设置邻域使用的方向组 + * @param group 朝向组 + */ + useDirGroup(group: number): void; + + /** + * 以起始位置为中心构建有向图：沿可通行有向边 BFS 扩展， + * 仅包含从起始位置可达的节点。图层未绑定或起始位置越界时告警并返回空图 + * @param start BFS 起始位置 + */ + build(start: ITileLocator): IPathGraph; +} /** * 将方向描述器的坐标增量解析为对应的朝向 diff --git a/packages-user/data-system/src/path/system.ts b/packages-user/data-system/src/path/system.ts index a418fc7..4bc5c5e 100644 --- a/packages-user/data-system/src/path/system.ts +++ b/packages-user/data-system/src/path/system.ts @@ -17,6 +17,8 @@ export class PathfindingSystem implements IPathfindingSystem { /** 绑定的移动器对象 */ private mover: IObjectMover | null = null; + /** 绑定的移动对象，用于保留用户契约的对象绑定入口 */ + private movable: IObjectMovable | null = null; /** 注入的瞬移回退策略，未注入时必定回退为逐步寻路 */ private policy: PathFallbackPolicy | null = null; /** 最近一次寻路移动的控制器包装 */ @@ -26,8 +28,13 @@ export class PathfindingSystem implements IPathfindingSystem { this.finder = new PathfindingFinder(state); } + useMovable(movable: IObjectMovable | null): void { + this.movable = movable; + } + useMover(mover: IObjectMover | null): void { this.mover = mover; + this.movable = mover ? mover.tile : null; } useFallbackPolicy(policy: PathFallbackPolicy | null): void { @@ -36,11 +43,13 @@ export class PathfindingSystem implements IPathfindingSystem { getPath(target: ITileLocator): IPathfindingStep[] { const mover = this.mover; - if (isNil(mover)) { + const movable = this.movable; + if (isNil(mover) && isNil(movable)) { logger.warn(173); return []; } - const tile = mover.tile; + const tile = mover ? mover.tile : movable; + if (!tile) return []; return this.finder.find({ x: tile.x, y: tile.y }, target); } diff --git a/packages-user/data-system/src/path/types.ts b/packages-user/data-system/src/path/types.ts index 50e4363..c663e3d 100644 --- a/packages-user/data-system/src/path/types.ts +++ b/packages-user/data-system/src/path/types.ts @@ -9,12 +9,9 @@ import { import { FaceDirection, IMoverController, - IObjectMovable, - IObjectMover + IObjectMovable } from '@user/data-common'; -//#region 寻路系统 - export interface IPathfindingStep { /** 移动方向 */ readonly dir: FaceDirection; @@ -88,9 +85,9 @@ export interface IPathfindingSystem extends IDataBaseExtended { /** * 绑定寻路移动对象，可绑定勇士位置或任意 `IObjectMovable`，如动态图块 - * @param mover 移动对象 + * @param movable 移动对象 */ - useMover(mover: IObjectMover | null): void; + useMovable(movable: IObjectMovable | null): void; /** * 设置瞬移回退策略，默认必定回退为逐步寻路 @@ -107,12 +104,14 @@ export interface IPathfindingSystem extends IDataBaseExtended { /** * 逐步寻路至目标位置，触发途经事件 * @param target 目标坐标 + * @returns 移动控制器。无法寻路、无路径或已有移动进行中时返回 `null` */ moveTo(target: ITileLocator): IPathfindingController | null; /** * 瞬移至目标位置。瞬移前经回退策略判定，判定需要回退则自动退为逐步寻路 * @param target 目标坐标 + * @returns 移动控制器；无法寻路、无路径或已有移动进行中时返回 `null` */ teleportTo(target: ITileLocator): IPathfindingController | null; @@ -121,81 +120,3 @@ export interface IPathfindingSystem extends IDataBaseExtended { */ interrupt(): Promise; } - -//#endregion - -//#region 路径图 - -export interface IPathGraphEdge { - /** 本条边对应的移动方向 */ - readonly dir: FaceDirection; - /** 边指向的节点索引，值为 y * width + x */ - readonly to: number; -} - -export interface IPathGraphNode { - /** 节点索引，值为 y * width + x */ - readonly index: number; - /** 节点横坐标 */ - readonly x: number; - /** 节点纵坐标 */ - readonly y: number; - /** 节点对应的位置信息 */ - readonly block: ILayerLocation; - /** 进入该节点的损失，构建图时由损失函数计算 */ - readonly cost: number; - /** 该节点是否仅可作为路径终点，不可作为中间节点 */ - readonly terminal: boolean; - /** 该节点的全部出边 */ - readonly edges: readonly IPathGraphEdge[]; -} - -export interface IPathGraph { - /** 图宽度 */ - readonly width: number; - /** 图高度 */ - readonly height: number; - /** 图内全部节点，键为节点索引 */ - readonly nodes: ReadonlyMap; -} - -export interface IPathfindingGraphBuilder { - /** - * 绑定地图状态对象，用于解析图层所属楼层 id - * @param maps 地图状态对象 - */ - useMapState(maps: IMapState | null): void; - - /** - * 绑定构建有向图所用的地图图层 - * @param layer 地图图层对象 - */ - useMapLayer(layer: IMapLayer | null): void; - - /** - * 设置构建图时使用的损失函数，未注入时每格损失 1 - * @param cost 损失函数 - */ - useCostFunction(cost: PathCostFunction | null): void; - - /** - * 注入判定边可行性的通行性谓词 - * @param predicate 通行性谓词 - */ - usePassPredicate(predicate: IPassPredicate | null): void; - - /** - * 设置邻域使用的方向组 - * @param group 朝向组 - */ - useDirGroup(group: number): void; - - /** - * 以起始位置为中心构建有向图：沿可通行有向边 BFS 扩展， - * 仅包含从起始位置可达的节点。图层未绑定或起始位置越界时告警并返回空图 - * @param start BFS 起始位置 - */ - build(start: ITileLocator): IPathGraph; -} - -//#endregion