From 2a745f5e85d6336dbb9af7c0807cbd04c2c16aae Mon Sep 17 00:00:00 2001
From: ud18010 <ud18010@xworld.ren>
Date: Thu, 30 Jul 2026 12:18:07 +0800
Subject: [PATCH] docs: translate actor behavior design to chinese

---
 ...2026-07-30-actor-behavior-system-design.md | 392 +++++++++---------
 1 file changed, 196 insertions(+), 196 deletions(-)

diff --git a/docs/superpowers/specs/2026-07-30-actor-behavior-system-design.md b/docs/superpowers/specs/2026-07-30-actor-behavior-system-design.md
index 438ceb8f..f8f9446b 100644
--- a/docs/superpowers/specs/2026-07-30-actor-behavior-system-design.md
+++ b/docs/superpowers/specs/2026-07-30-actor-behavior-system-design.md
@@ -1,91 +1,91 @@
-# Actor Behavior System Design
+# 角色行为（技能）系统设计
 
-## Goal
+## 目标
 
-Build a reusable actor behavior system for lobby actors and mini games. Behaviors are configured from JSON and can describe skills, actions, visual effects, projectiles, buffs, and logic effects. Client and server load the same JSON files; the server runs only authoritative logic, while the client consumes presentation events and synchronized authoritative results.
+实现一套大厅角色和小游戏都能复用的角色行为系统。行为通过 JSON 配置，可描述技能、动作、特效、飞行物、Buff 和逻辑效果。客户端和服务端加载同一套 JSON 文件；服务端只运行权威逻辑，客户端消费表现事件以及服务端同步来的权威结果。
 
-The first implementation scope is the shared core, example configuration, and automated tests. It does not directly integrate the lobby actor controller or any mini game UI yet.
+第一版范围是共享核心、示例配置和自动化测试，不直接接入大厅角色控制器，也不直接接入某个小游戏 UI。
 
-## Current Project Context
+## 当前项目背景
 
-- Unity client shared framework code lives in `Client/Assets/Framework/Shared`.
-- `Server/Framework.Shared/Framework.Shared.csproj` compiles the same shared source files from the client tree.
-- Mini game Core code follows the same pattern: a `scripts~` source directory is compiled by both client and server projects.
-- The existing virtual HUD input work intentionally stops at raw joystick and action button events. This behavior system sits after that input layer and turns input into behavior requests.
-- Existing character JSON uses `Client/Assets/Resources/Config`, while the server needs direct file/string loading for the same JSON content.
+- Unity 客户端共享框架代码位于 `Client/Assets/Framework/Shared`。
+- `Server/Framework.Shared/Framework.Shared.csproj` 会从客户端共享目录编译同一份源码。
+- 小游戏 Core 代码也使用同源模式：`scripts~` 目录同时被客户端和服务端项目编译。
+- 已有虚拟 HUD 输入系统只负责输出摇杆和按钮事件，不负责技能协议或技能执行。角色行为系统位于输入层之后，把输入转换为行为请求。
+- 客户端已有 `Client/Assets/Resources/Config` 配置目录先例；服务端需要通过文件或字符串读取同一套 JSON 内容。
 
-## Recommended Approach
+## 推荐方案
 
-Add a pure C# shared module under:
+新增一个纯 C# 共享模块：
 
 ```text
 Client/Assets/Framework/Shared/ActorBehavior/
 ```
 
-The module namespace is:
+命名空间：
 
 ```csharp
 XWorld.Framework.ActorBehavior
 ```
 
-The shared core does not reference Unity. It owns configuration models, deterministic runtime state, timeline triggering, projectile movement, buff ticking, logic effect target selection, and structured event output.
+共享核心不引用 Unity。它负责配置模型、确定性的运行时状态、时间线触发、飞行物移动、Buff tick、逻辑效果目标选择和结构化事件输出。
 
-Unity-specific work is kept outside the core. Client code will later adapt `TimelineAnimation`, `TimelineEffect`, and projectile presentation events to `Animator`, prefab loading, and visual effects. Server code will later adapt authoritative logic events to real game attributes, snapshots, and network broadcasts.
+Unity 相关逻辑放在核心之外。客户端后续用适配层把 `TimelineAnimation`、`TimelineEffect`、飞行物表现事件接到 `Animator`、资源加载和特效预设。服务端后续用适配层把权威逻辑事件接到真实游戏属性、快照和网络广播。
 
-## Alternatives Considered
+## 备选方案
 
-### Shared Core First
+### 共享核心优先
 
-This is the selected approach. It matches the existing shared framework design, keeps client and server behavior rules in one place, and lets lobby and mini games adopt the same API later.
+这是选定方案。它符合当前项目的共享框架设计，保证客户端和服务端使用同一套行为规则，也方便大厅和小游戏后续同时接入。
 
-Trade-off: the first version proves the system through tests and example configuration, not through a visible lobby skill.
+取舍：第一版通过测试和示例配置证明系统可用，不会先做一个可见的大厅技能效果。
 
-### Per Mini Game Behavior Core
+### 每个小游戏各自实现行为 Core
 
-Each mini game could package its own behavior runtime.
+每个小游戏都可以打包自己的行为运行时。
 
-This isolates game modules, but it duplicates fighter/mage style character configuration and makes lobby reuse weak.
+优点是小游戏隔离更强；缺点是 fighter、mage 等通用人物配置会被复制多份，大厅也难以复用。
 
-### Unity Client First
+### Unity 客户端优先
 
-The client could implement skills directly with Unity animation, prefab, and collision APIs, then the server could be added later.
+也可以先在客户端用 Unity 动画、Prefab、碰撞 API 直接实现技能，再补服务端。
 
-This would show visuals quickly, but it would bind rules to Unity object lifetimes and make server authority hard to add cleanly.
+优点是能较快看到视觉效果；缺点是规则会绑定 Unity 对象生命周期，后续补服务端权威逻辑会变得很难。
 
-## Core Components
+## 核心组件
 
 ### BehaviorConfigCatalog
 
-Owns one actor type configuration set, such as `fighter`.
+表示一种角色类型的一整套配置，例如 `fighter`。
 
-Inputs:
+输入文件：
 
 - `fighter_skill.json`
 - `fighter_flyobj.json`
 - `fighter_buff.json`
 
-Responsibilities:
+职责：
 
-- Parse JSON strings.
-- Validate duplicate ids, missing references, invalid durations, invalid shape parameters, and unsupported enum values.
-- Expose behavior, projectile, buff, and logic effect definitions by id.
+- 解析 JSON 字符串。
+- 校验重复 id、缺失引用、非法时长、非法形状参数和不支持的枚举值。
+- 按 id 提供行为、飞行物、Buff 和逻辑效果定义。
 
 ### BehaviorWorld
 
-Owns runtime simulation for many actors and projectiles.
+管理多个角色和飞行物的运行时模拟。
 
-Responsibilities:
+职责：
 
-- Register multiple `BehaviorConfigCatalog` instances.
-- Add, remove, and update actor runtime state.
-- Switch an actor's active catalog by actor type.
-- Start and stop behaviors.
-- Tick active behavior timelines.
-- Tick projectile movement and collision.
-- Tick buffs by duration, interval, and repeat count.
-- Drain generated `BehaviorEvent` instances.
+- 注册多套 `BehaviorConfigCatalog`。
+- 添加、移除、更新角色运行时状态。
+- 按角色类型切换角色当前使用的配置。
+- 开始和停止行为。
+- Tick 当前行为时间线。
+- Tick 飞行物移动和碰撞。
+- Tick Buff 持续时间、起效间隔和重复次数。
+- 输出并清空本帧产生的 `BehaviorEvent`。
 
-Primary API shape:
+主要 API 形态：
 
 ```csharp
 var catalog = BehaviorConfigCatalog.LoadFromJson(type, skillJson, flyObjJson, buffJson);
@@ -99,17 +99,17 @@ IReadOnlyList<BehaviorEvent> events = world.DrainEvents();
 
 ### ActorBehaviorController
 
-Represents behavior state for one actor inside `BehaviorWorld`.
+表示 `BehaviorWorld` 内某一个角色的行为状态。
 
-Responsibilities:
+职责：
 
-- Track the actor's active catalog type.
-- Track the current active behavior and elapsed time.
-- Enforce that only one active behavior runs at a time.
-- Allow explicit special interruption when the current behavior permits interruption.
-- Own active buffs for that actor.
+- 记录角色当前使用的配置类型。
+- 记录当前主动行为和行为已运行时间。
+- 保证同一角色同一时刻只能运行一个主动行为。
+- 当前行为允许中断时，支持外部特殊逻辑显式打断。
+- 管理附加在该角色身上的 Buff。
 
-Behavior control:
+行为控制示例：
 
 ```csharp
 world.TryStartBehavior(actorId, "slash", BehaviorInput.FromDirection(1f, 0f));
@@ -117,69 +117,69 @@ world.StopBehavior(actorId, BehaviorStopReason.Stunned);
 world.TryStartBehavior(actorId, "stun_fall", BehaviorInput.None);
 ```
 
-### Projectile Runtime
+### 飞行物运行时
 
-Projectiles are independent runtime objects configured by id.
+飞行物是按 id 配置、独立存在的运行时对象。
 
-Responsibilities:
+职责：
 
-- Spawn from behavior timelines or logic effects.
-- Update position by configured movement mode.
-- Check collision through configured collision shapes.
-- Run projectile-owned timelines.
-- Trigger logic effects on collision or on configured times.
+- 由行为时间线或逻辑效果生成。
+- 按配置的位移方式更新位置。
+- 按配置的碰撞形状检测命中。
+- 运行飞行物自己的时间线。
+- 在碰撞或配置时间点触发逻辑效果。
 
-First version movement modes:
+第一版位移方式：
 
-- `Line`
-- `Parabola`
-- `Homing`
+- `Line`：直线飞行。
+- `Parabola`：抛物线物理飞行。
+- `Homing`：追踪目标。
 
-First version collision mode:
+第一版碰撞方式：
 
-- Sphere collision with radius and hit limit.
+- 球形碰撞，包含半径和命中次数上限。
 
-### Buff Runtime
+### Buff 运行时
 
-Buffs are special attached effects.
+Buff 是附加在角色上的特殊效果。
 
-Responsibilities:
+职责：
 
-- Track duration.
-- Tick at configured intervals.
-- Respect repeat count.
-- Apply stacking behavior.
-- Trigger configured logic effects on add, tick, or remove.
+- 记录持续时间。
+- 按起效间隔 tick。
+- 支持重复次数。
+- 支持堆叠规则。
+- 在添加、tick 或移除时触发配置的逻辑效果。
 
-First version stacking modes:
+第一版堆叠规则：
 
-- `RefreshDuration`
-- `IgnoreIfExists`
-- `StackIndependent`
+- `RefreshDuration`：已有同 id Buff 时刷新持续时间。
+- `IgnoreIfExists`：已有同 id Buff 时忽略新 Buff。
+- `StackIndependent`：同 id Buff 独立叠加。
 
-### Logic Effect Runtime
+### 逻辑效果运行时
 
-Logic effects select targets by shape and request one or more business effects.
+逻辑效果负责按形状选取目标，并请求一个或多个业务效果。
 
-First version shapes:
+第一版形状：
 
-- `Sector`
-- `Sphere`
-- `Ring`
-- `Line`
-- `Locked`
+- `Sector`：扇形。
+- `Sphere`：球形。
+- `Ring`：环形。
+- `Line`：直线或胶囊范围。
+- `Locked`：锁定目标。
 
-First version effect operations:
+第一版效果操作：
 
-- `Attribute`: request an attribute delta, such as `hp = -30`.
-- `Buff`: request applying a configured buff id.
-- `Projectile`: request spawning a configured projectile id.
+- `Attribute`：请求属性变化，例如 `hp = -30`。
+- `Buff`：请求添加某个 Buff。
+- `Projectile`：请求生成某个飞行物。
 
-The core does not own the real business attribute table. It emits structured events or calls an adapter so lobby and mini games can decide how `hp`, `moveSpeed`, `score`, or custom attributes are applied.
+核心系统不维护真实业务属性表。它输出结构化事件，或通过适配器回调，让大厅或小游戏自行决定如何处理 `hp`、`moveSpeed`、`score` 或自定义属性。
 
-## JSON Configuration
+## JSON 配置
 
-Each actor type owns three files. File names use the actor type prefix:
+每种角色类型有三份配置文件，文件名前缀使用角色类型名：
 
 ```text
 fighter_skill.json
@@ -187,12 +187,12 @@ fighter_flyobj.json
 fighter_buff.json
 ```
 
-All files include:
+所有文件都包含：
 
-- `type`: actor type name, such as `fighter`.
-- `version`: integer config version.
+- `type`：角色类型名，例如 `fighter`。
+- `version`：整数配置版本。
 
-### Behavior JSON
+### 行为配置
 
 ```json
 {
@@ -227,7 +227,7 @@ All files include:
 }
 ```
 
-### Projectile JSON
+### 飞行物配置
 
 ```json
 {
@@ -259,7 +259,7 @@ All files include:
 }
 ```
 
-### Buff JSON
+### Buff 配置
 
 ```json
 {
@@ -287,60 +287,60 @@ All files include:
 }
 ```
 
-## Input Model
+## 输入模型
 
-`BehaviorInput` supports:
+`BehaviorInput` 支持：
 
-- `None`
-- `Direction`
-- `TargetPosition`
-- `TargetActor`
+- `None`：无输入。
+- `Direction`：方向输入。
+- `TargetPosition`：目标位置。
+- `TargetActor`：锁定目标角色。
 
-The existing virtual joystick and action pad can later map raw input events to this input model.
+已有虚拟摇杆和动作按钮后续可把原始输入事件映射到这个输入模型。
 
-Examples:
+示例：
 
-- Joystick direction plus attack button maps to `Direction`.
-- Drag-release skill maps to `Direction` or `TargetPosition`.
-- Target lock skill maps to `TargetActor`.
+- 摇杆方向加普攻按钮映射为 `Direction`。
+- 拖拽释放技能映射为 `Direction` 或 `TargetPosition`。
+- 锁定目标技能映射为 `TargetActor`。
 
-## Run Modes
+## 运行模式
 
 ### ServerLogic
 
-The server mode runs authoritative logic:
+服务端模式运行权威逻辑：
 
-- Behavior start and stop.
-- Timeline logic events.
-- Projectile movement and collision.
-- Buff add, tick, and remove.
-- Logic effect target selection.
-- Attribute, buff, and projectile requests.
+- 行为开始和停止。
+- 时间线逻辑事件。
+- 飞行物移动和碰撞。
+- Buff 添加、tick 和移除。
+- 逻辑效果目标选择。
+- 属性、Buff 和飞行物请求。
 
-It does not execute animation or effect presentation. It may still emit presentation events for logging or optional network relay, but these are not authoritative.
+该模式不执行动画和特效表现。它可以产出表现事件用于日志或可选网络转发，但这些事件本身不作为权威判定。
 
 ### ClientPresentation
 
-The client presentation mode consumes behavior state and events for visuals:
+客户端表现模式消费行为状态和事件，用于播放表现：
 
-- Animation timeline events.
-- Effect timeline events.
-- Projectile presentation spawn and movement.
-- Buff visual add/remove markers.
+- 动画时间线事件。
+- 特效时间线事件。
+- 飞行物表现生成和移动。
+- Buff 表现添加和移除标记。
 
-It does not perform authoritative target selection or attribute application.
+该模式不执行权威目标选择，也不执行属性结算。
 
 ### ClientPredict
 
-Client prediction may be added after the core is stable. It can run the same timeline and movement logic locally, then reconcile against server events or snapshots.
+客户端预测可在核心稳定后继续扩展。它可以本地运行同一套时间线和移动逻辑，再根据服务端事件或快照校正。
 
-The first version can define the enum value but does not need full reconciliation.
+第一版可以定义这个枚举值，但不需要实现完整校正流程。
 
-## Event Model
+## 事件模型
 
-The core emits `BehaviorEvent` values. Events are deterministic data records, not callbacks into Unity.
+核心系统输出 `BehaviorEvent`。事件是确定性数据记录，不是对 Unity 的回调。
 
-First version event kinds:
+第一版事件类型：
 
 - `BehaviorStarted`
 - `BehaviorStopped`
@@ -355,88 +355,88 @@ First version event kinds:
 - `LogicEffectApplied`
 - `AttributeEffectRequested`
 
-Server and client consume the same event stream differently:
+服务端和客户端消费同一事件流，但职责不同：
 
-- Client consumes `TimelineAnimation`, `TimelineEffect`, and projectile presentation events.
-- Server consumes `LogicEffectApplied`, `AttributeEffectRequested`, buff events, and projectile spawn/hit events.
-- Network integration will later broadcast authoritative events and snapshots from the server to clients.
+- 客户端消费 `TimelineAnimation`、`TimelineEffect` 和飞行物表现事件。
+- 服务端消费 `LogicEffectApplied`、`AttributeEffectRequested`、Buff 事件和飞行物生成/命中事件。
+- 网络接入后，服务端会把权威事件和必要快照广播给客户端。
 
-## Targeting And Filtering
+## 目标选择与过滤
 
-Actors tracked by the core have minimal deterministic state:
+核心系统记录角色的最小确定性状态：
 
-- Actor id.
-- Catalog type.
-- Position.
-- Forward direction.
-- Team or faction id.
-- Alive/enabled flag.
-- Optional radius for collision and target selection.
+- 角色 id。
+- 配置类型。
+- 位置。
+- 朝向。
+- 队伍或阵营 id。
+- 是否存活或启用。
+- 可选半径，用于碰撞和目标选择。
 
-Logic effect target filters:
+逻辑效果目标过滤：
 
-- `Self`
-- `Ally`
-- `Enemy`
-- `All`
-- `Owner`
-- `HitActor`
+- `Self`：自己。
+- `Ally`：友方。
+- `Enemy`：敌方。
+- `All`：全部。
+- `Owner`：效果拥有者。
+- `HitActor`：被飞行物命中的角色。
 
-The first version keeps filtering simple and deterministic. Complex gameplay rules can be added through adapter decisions later.
+第一版过滤规则保持简单、确定、可测试。更复杂的玩法规则后续通过适配器决定。
 
-## Error Handling
+## 错误处理
 
-Configuration loading fails with clear validation messages for:
+配置加载遇到以下问题时失败，并返回清晰的校验信息：
 
-- Missing `type`.
-- Mismatched type across skill, projectile, and buff JSON.
-- Duplicate behavior, projectile, buff, or logic effect ids.
-- Timeline entries with negative time.
-- Timelines referencing missing logic effect ids.
-- Behaviors referencing missing projectile ids.
-- Logic operations referencing missing projectile or buff ids.
-- Unsupported enum strings.
-- Invalid shape parameters, such as negative radius or sector angle outside `(0, 360]`.
+- 缺少 `type`。
+- skill、flyobj、buff 三份 JSON 的 `type` 不一致。
+- 行为、飞行物、Buff 或逻辑效果 id 重复。
+- 时间线条目时间为负数。
+- 时间线引用不存在的逻辑效果 id。
+- 行为引用不存在的飞行物 id。
+- 逻辑操作引用不存在的飞行物或 Buff id。
+- 不支持的枚举字符串。
+- 非法形状参数，例如半径为负数，或扇形角度不在 `(0, 360]`。
 
-Runtime behavior:
+运行时行为：
 
-- Starting an unknown behavior returns failure and emits no events.
-- Starting a second behavior while one is active returns failure unless the current behavior was explicitly stopped or interrupted.
-- Non-interruptible behaviors ignore special stop requests except terminal reasons like `Death`.
-- Projectiles expire when duration ends or hit limit is reached.
-- Buffs expire when duration ends or repeat count is reached.
+- 开始未知行为会返回失败，不产生事件。
+- 当前已有主动行为时，开始第二个行为会失败，除非当前行为已被显式停止或中断。
+- 不可中断行为会忽略特殊停止请求，但 `Death` 这类终止原因例外。
+- 飞行物在持续时间结束或达到命中上限时过期。
+- Buff 在持续时间结束或达到重复次数时过期。
 
-## Tests
+## 测试
 
-Add xUnit tests in `Server/Framework.Shared.Tests`.
+在 `Server/Framework.Shared.Tests` 添加 xUnit 测试。
 
-Required coverage:
+必须覆盖：
 
-- Loads a complete fighter config from three JSON strings.
-- Rejects mismatched config type names.
-- Rejects duplicate ids and missing references.
-- Allows only one active behavior per actor.
-- Allows special stop and behavior switch when the current behavior is interruptible.
-- Triggers timeline animation, effect, logic effect, and projectile entries at configured times.
-- Selects targets for sector, sphere, ring, line, and locked shapes.
-- Updates line, parabola, and homing projectile movement.
-- Triggers projectile sphere collision and hit-limited expiry.
-- Ticks buffs by duration, interval, and repeat count.
-- Emits logic effect requests for attribute, buff, and projectile operations.
-- In `ServerLogic`, authoritative logic events are produced and presentation execution is skipped.
-- In `ClientPresentation`, presentation events are produced and authoritative attribute requests are skipped.
+- 能从三段 JSON 字符串加载完整 `fighter` 配置。
+- 拒绝三份配置 `type` 不一致。
+- 拒绝重复 id 和缺失引用。
+- 同一角色同一时刻只能运行一个主动行为。
+- 当前行为可中断时，允许特殊停止并切换到另一个行为。
+- 时间线能按配置时间触发动画、特效、逻辑效果和飞行物条目。
+- 扇形、球形、环形、直线、锁定形状能正确选择目标。
+- 直线、抛物线、追踪飞行物能更新位置。
+- 飞行物球形碰撞能触发命中，并在达到命中上限后过期。
+- Buff 能按持续时间、起效间隔和重复次数 tick。
+- 逻辑效果能产出属性、Buff、飞行物请求。
+- `ServerLogic` 模式会产出权威逻辑事件，并跳过表现执行。
+- `ClientPresentation` 模式会产出表现事件，并跳过权威属性请求。
 
-## Acceptance Criteria
+## 验收标准
 
-- A caller can load a `fighter` behavior catalog from `fighter_skill.json`, `fighter_flyobj.json`, and `fighter_buff.json`.
-- A `BehaviorWorld` can register multiple actor type catalogs.
-- Each actor can switch its active behavior catalog by type name.
-- A caller can start a behavior by actor id and behavior id with direction or target input.
-- One actor cannot run two active behaviors at the same time.
-- Special logic can stop or interrupt behavior and then start another behavior when rules allow it.
-- Behavior timelines can emit animation, effect, projectile, buff, and logic events.
-- Projectiles can move independently and trigger logic on collision.
-- Buffs can attach to actors, tick repeatedly, and expire.
-- Logic effects support sector, sphere, ring, line, and locked target selection.
-- Server logic can run without Unity animation, prefab, or effect dependencies.
-- Client code can consume the same event stream later for animation, prefab, and effect playback.
+- 调用方能从 `fighter_skill.json`、`fighter_flyobj.json`、`fighter_buff.json` 加载一套 `fighter` 行为配置。
+- `BehaviorWorld` 能注册多套角色类型配置。
+- 每个角色能按类型名切换当前行为配置。
+- 调用方能通过角色 id、行为 id 和方向或目标输入开始行为。
+- 同一角色不能同时运行两个主动行为。
+- 外部特殊逻辑能在规则允许时停止或中断行为，并切换到其他行为。
+- 行为时间线能产出动画、特效、飞行物、Buff 和逻辑事件。
+- 飞行物能独立移动，并在碰撞时触发逻辑。
+- Buff 能附加到角色、重复 tick 并过期。
+- 逻辑效果支持扇形、球形、环形、直线和锁定目标选择。
+- 服务端逻辑运行不依赖 Unity 动画、Prefab 或特效。
+- 客户端后续能消费同一事件流，用于播放动画、加载预设和表现飞行物。