From 521413fea4bbcff0a068891ea720958b51eb95e0 Mon Sep 17 00:00:00 2001 From: unanmed <1319491857@qq.com> Date: Sat, 12 Sep 2026 13:26:13 +0800 Subject: [PATCH] style(03-19): normalize touched event JSDoc to multiline - Convert map, hero, event, and registration-assembly function JSDoc into multiline form for every touched declaration - Preserve export-only barrels, class-owned registration order, direct Statement[] insertion, hero front-touch ownership, and Chinese event test comments --- packages-user/data-state/src/event/event.ts | 20 ++++++++--- packages-user/data-state/src/event/hero.ts | 36 ++++++++++++++----- packages-user/data-state/src/event/map.ts | 11 ++++-- .../data-state/src/event/registrations.ts | 16 ++++++--- 4 files changed, 63 insertions(+), 20 deletions(-) diff --git a/packages-user/data-state/src/event/event.ts b/packages-user/data-state/src/event/event.ts index 5d2a7a9..21af0d8 100644 --- a/packages-user/data-state/src/event/event.ts +++ b/packages-user/data-state/src/event/event.ts @@ -21,12 +21,16 @@ interface IEventState extends IStateBase { const EVENT_INSERT_MAX_DEPTH = 32; const eventInsertDepth: WeakMap = new WeakMap(); -/** 判断状态是否包含事件执行器 */ +/** + * 判断状态是否包含事件执行器 + */ function hasEventSystem(state: IStateBase): state is IEventState { return 'eventSystem' in state; } -/** 从环境获取事件执行器和事件存储器 */ +/** + * 从环境获取事件执行器和事件存储器 + */ export function getEventRuntime(env: IBlockEventEnv): { readonly executor: IGameEventExecutor; readonly store: IGameEventStore; @@ -40,7 +44,9 @@ export function getEventRuntime(env: IBlockEventEnv): { }; } -/** 过滤存在的事件 id 并构造临时事件调用 */ +/** + * 过滤存在的事件 id 并构造临时事件调用 + */ function collectEventInvocations( ids: readonly string[], env: IBlockEventEnv, @@ -59,7 +65,9 @@ function collectEventInvocations( return invocations; } -/** 临时按顺序执行指定事件 */ +/** + * 临时按顺序执行指定事件 + */ export async function eventInsertEvents( param: IInsertEventsEventParam, env: IBlockEventEnv @@ -79,7 +87,9 @@ export async function eventInsertEvents( } } -/** 临时直接执行一段事件语句 */ +/** + * 临时直接执行一段事件语句 + */ export async function eventInsertEvent( param: IInsertEventEventParam, env: IBlockEventEnv diff --git a/packages-user/data-state/src/event/hero.ts b/packages-user/data-state/src/event/hero.ts index e8571b6..cb7be2f 100644 --- a/packages-user/data-state/src/event/hero.ts +++ b/packages-user/data-state/src/event/hero.ts @@ -29,7 +29,9 @@ import { } from './types'; import { getEventRuntime } from './event'; -/** 通过环境参量获取可能的地图对象 */ +/** + * 通过环境参量获取可能的地图对象 + */ export function getPossibleMap(env: IBlockEventEnv): IGameMap | null { if (env.map) return env.map; if (env.layer) return env.layer.map; @@ -40,7 +42,9 @@ export function getPossibleMap(env: IBlockEventEnv): IGameMap | null { return null; } -/** 通过环境参量获取可能的事件图层 */ +/** + * 通过环境参量获取可能的事件图层 + */ export function getPossibleLayer(env: IBlockEventEnv): IMapLayer | null { if (env.layer) return env.layer; @@ -50,7 +54,9 @@ export function getPossibleLayer(env: IBlockEventEnv): IMapLayer | null { return null; } -/** 启动勇士移动并等待其完整结束 */ +/** + * 将移动步骤按顺序追加到移动器，不启动移动 + */ export function appendMoveSteps( mover: IObjectMover, steps: readonly ObjectMoveStep[] @@ -89,7 +95,9 @@ export function appendMoveSteps( } } -/** 启动勇士移动并等待其完整结束 */ +/** + * 启动勇士移动并等待其完整结束 + */ async function startHeroMove( mover: IHeroMover, steps: readonly ObjectMoveStep[] @@ -101,14 +109,18 @@ async function startHeroMove( await controller.onEnd; } -/** 获取可以执行移动的勇士移动器 */ +/** + * 获取可以执行移动的勇士移动器 + */ function getHeroMover(env: IBlockEventEnv): IHeroMover | null { const hero = env.state.hero; if (!hero) return null; return hero.location.mover; } -/** 按指定移动序列移动勇士 */ +/** + * 按指定移动序列移动勇士 + */ export async function eventMoveHero( param: IMoveHeroEventParam, env: IBlockEventEnv @@ -118,7 +130,9 @@ export async function eventMoveHero( await startHeroMove(mover, param.steps); } -/** 让勇士沿当前朝向移动一步 */ +/** + * 让勇士沿当前朝向移动一步 + */ export async function eventMoveHeroStep( _param: IMoveHeroStepEventParam, env: IBlockEventEnv @@ -139,7 +153,9 @@ interface IEventSource { readonly tile: IReadonlyMapTileBase | null; } -/** 按坐标收集事件来源并保留其触发环境 */ +/** + * 按坐标收集事件来源并保留其触发环境 + */ function collectInvocations( env: IBlockEventEnv, layer: NonNullable, @@ -205,7 +221,9 @@ function collectInvocations( return invocations; } -/** 触发勇士正面的 onTouch 事件 */ +/** + * 触发勇士正面的 onTouch 事件 + */ export async function eventTouchFront( _param: ITouchFrontEventParam, env: IBlockEventEnv diff --git a/packages-user/data-state/src/event/map.ts b/packages-user/data-state/src/event/map.ts index 352e1e2..fc9eff7 100644 --- a/packages-user/data-state/src/event/map.ts +++ b/packages-user/data-state/src/event/map.ts @@ -10,6 +10,9 @@ import { isNil } from 'lodash-es'; import { logger } from '@motajs/common'; import { appendMoveSteps, getPossibleLayer } from './hero'; +/** + * 在解析出的目标图层设置静态图块，目标或图块缺失时安全返回 + */ export function eventSetBlock( param: ISetBlockEventParam, env: IBlockEventEnv @@ -28,7 +31,9 @@ export function eventSetBlock( layer.setBlock(num, param.x, param.y); } -/** 将动态图块移动完成后还原为静态图块 */ +/** + * 将动态图块移动完成后还原为静态图块 + */ export async function eventMoveBlock( param: IMoveBlockEventParam, env: IBlockEventEnv @@ -53,7 +58,9 @@ export async function eventMoveBlock( } } -/** 删除目标坐标的静态图块和动态图块 */ +/** + * 删除目标坐标的静态图块和动态图块 + */ export async function eventDeleteBlock( param: IDeleteBlockEventParam, env: IBlockEventEnv diff --git a/packages-user/data-state/src/event/registrations.ts b/packages-user/data-state/src/event/registrations.ts index 67c2321..0eb49df 100644 --- a/packages-user/data-state/src/event/registrations.ts +++ b/packages-user/data-state/src/event/registrations.ts @@ -14,7 +14,9 @@ import { InsertEventsEventRegistration } from './event'; -/** 创建地图控制事件的内建函数注册项 */ +/** + * 创建地图控制事件的内建函数注册项 + */ export function createMapEventBuiltinRegistrations(): ReadonlyArray { return [ new SetBlockEventRegistration(), @@ -23,7 +25,9 @@ export function createMapEventBuiltinRegistrations(): ReadonlyArray { return [ new MoveHeroEventRegistration(), @@ -32,7 +36,9 @@ export function createHeroEventBuiltinRegistrations(): ReadonlyArray { return [ new InsertEventsEventRegistration(), @@ -40,7 +46,9 @@ export function createControlEventBuiltinRegistrations(): ReadonlyArray { return [ ...createMapEventBuiltinRegistrations(),