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

@@ -21,12 +21,16 @@ interface IEventState extends IStateBase {
 const EVENT_INSERT_MAX_DEPTH = 32;
 const eventInsertDepth: WeakMap<IBlockEventEnv, number> = 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

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<T extends IObjectMovable>(
     mover: IObjectMover<T>,
     steps: readonly ObjectMoveStep[]
@@ -89,7 +95,9 @@ export function appendMoveSteps<T extends IObjectMovable>(
     }
 }
 
-/** 启动勇士移动并等待其完整结束 */
+/**
+ * 启动勇士移动并等待其完整结束
+ */
 async function startHeroMove(
     mover: IHeroMover<IHeroLocation>,
     steps: readonly ObjectMoveStep[]
@@ -101,14 +109,18 @@ async function startHeroMove(
     await controller.onEnd;
 }
 
-/** 获取可以执行移动的勇士移动器 */
+/**
+ * 获取可以执行移动的勇士移动器
+ */
 function getHeroMover(env: IBlockEventEnv): IHeroMover<IHeroLocation> | 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<IBlockEventEnv['layer']>,
@@ -205,7 +221,9 @@ function collectInvocations(
     return invocations;
 }
 
-/** 触发勇士正面的 onTouch 事件 */
+/**
+ * 触发勇士正面的 onTouch 事件
+ */
 export async function eventTouchFront(
     _param: ITouchFrontEventParam,
     env: IBlockEventEnv

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

packages-user/data-state/src/event/registrations.ts

@@ -14,7 +14,9 @@ import {
     InsertEventsEventRegistration
 } from './event';
 
-/** 创建地图控制事件的内建函数注册项 */
+/**
+ * 创建地图控制事件的内建函数注册项
+ */
 export function createMapEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunction> {
     return [
         new SetBlockEventRegistration(),
@@ -23,7 +25,9 @@ export function createMapEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunct
     ];
 }
 
-/** 创建勇士控制事件的内建函数注册项 */
+/**
+ * 创建勇士控制事件的内建函数注册项
+ */
 export function createHeroEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunction> {
     return [
         new MoveHeroEventRegistration(),
@@ -32,7 +36,9 @@ export function createHeroEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunc
     ];
 }
 
-/** 创建事件控制事件的内建函数注册项 */
+/**
+ * 创建事件控制事件的内建函数注册项
+ */
 export function createControlEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunction> {
     return [
         new InsertEventsEventRegistration(),
@@ -40,7 +46,9 @@ export function createControlEventBuiltinRegistrations(): ReadonlyArray<BuiltInF
     ];
 }
 
-/** 组装八个批准事件 built-in 的稳定注册项 */
+/**
+ * 组装八个批准事件 built-in 的稳定注册项
+ */
 export function createEventBuiltinRegistrations(): ReadonlyArray<BuiltInFunction> {
     return [
         ...createMapEventBuiltinRegistrations(),