Skip to content

Epic: Hand Runner (符咒) - 功能分析与实现计划

1. 核心理念与概述 (Rationale & Overview)

Hand Runner (符咒) 引入了一种低技术门槛、即时消耗型的代码运行器，专为应对不需要太复杂逻辑的场景而设计，主要提供一些实用工具和提升游戏体验 (QoL) 的功能。相比于运行成本高、设置复杂的 Block Runner (方块运行器)，Hand Runner 在设计上略微昂贵，但功能被严格限制。它的主要目的是提供一些轻量级的早期“魔法”体验，降低修改代码和运行模组的难度。

当玩家右键使用符咒时，会消耗一个物品并生成一个实体 (Entity) 来运行代码。符咒会处于燃烧状态 (如同真实的符被点燃一样)，并在一定时间后消失。

2. 用户故事 (User Stories)

US-01: Hand Runner 物品的使用

作为一个 玩家， 我希望 能够手持并右键点击一个 Hand Runner (符咒) 物品， 以便于 我可以简单直接地触发一次短时间的魔法效果，并伴随着冷却时间（类似末影珍珠或雪球）。

US-02: 代码模块的绑定 (合成)

作为一个 玩家， 我希望 可以在工作台中将编写了代码的模块 (Module) 附加到空白的符咒上， 以便于 定制该符咒在消耗时所触发的特定功能。

US-03: 实体生命周期与视觉反馈

作为一个 玩家， 我希望 根据设定的时间限制，符咒在运行一段时间后自动消失，并且在运行期间实体会显示着火的特效， 以便于 我能直观地看到符咒魔法的时效性和燃烧使用方式。

US-04: 模块函数的调用与消耗

作为一个 玩家， 我希望 符咒内部附带的模块在其被调用的函数执行完毕后会被消耗， 以便于 平衡一些强大的一次性功能的使用频率。

US-05: 方便入门的示例

作为一个 玩家， 我希望 能在创造模式物品栏、村民交易或搜刮战利品箱时，找到预先写好基础代码的符咒示例， 以便于 我能够快速上手并理解这些代码是如何运行的。

3. 验收标准 (Acceptance Criteria)

针对 US-01 (物品使用):

  • 游戏中新增 HandRunnerItemVB (符咒) 物品，带有 VB 后缀以防冲突。
  • 右键点击该物品时，精准消耗 1 个物品，并生成一个用于执行代码的 HandRunnerEntityVB。
  • 物品设定有使用冷却时间 (Cooldown)。

针对 US-02 (代码模块的绑定):

  • 开发一个新的接口 (Interface) 使合成台能够接收多个不同的类并在符咒上写入代码。
  • 代码可以安全地绑定到 HandRunnerItemVB 上。

针对 US-03 (实体生命周期与视觉反馈):

  • 重写 HandRunnerEntityVB 的 tick 函数，实现在每个 tick 中递减生命值 (life)。
  • 当该实体的 life 降为 0 时，正确删除或销毁自身。
  • 实体在生存期间渲染着火 (on fire) 状态。

针对 US-04 (模块函数的调用与消耗):

  • 实体的上下文 (Context) 能够获取运行信息。
  • 如果调用的是附近方块中的函数，可以安全模拟并在方块的 tick 中调用。
  • 如果调用的是实体背包 (Inventory) 中的内置代码：
  • 代码的包装请求必须实现消耗功能：在执行后从实体背包中删除对应的符模块。
  • 再次调用时，若背包中已无该符，能够安全终止并报错。

针对 US-05 (方便入门的示例):

  • 构建良好的示例组件 (Components)，并以原版物品栈的形式作为预制符咒发放。
  • 示例可以从创造模式物品栏稳定获取。

4. 技术实现计划与约束 (Implementation Plan & Constraints)

重要约束 (Critical Constraints): 所有新物品和实体必须以 VB 结尾 (如 HandRunnerItemVB, HandRunnerEntityVB)。所有新功能不得与现有代码冲突。可以且应该尽可能复用、调用现有代码（如 Block Runner 的逻辑）。除非绝对必要，否则尽量避免直接修改现有代码。

第 1 阶段：物品层级与实体基础 (Items & Entities)

  1. 物品功能实现 (Item Functionality): 创建继承自基础物品的 HandRunnerItemVB，重写右击事件以生成对应的 HandRunnerEntityVB，保留原版的冷却时间逻辑。
  2. 实体生命周期实现 (Entity Lifecycle): 创建 HandRunnerEntityVB，继承自适用的实体基础类。实现其内部的 tick 逻辑（生命值递减机制及生命归零时的自毁）。
  3. 视觉效果: 为 HandRunnerEntityVB 添加着火的视觉效果。

第 2 阶段：能力系统与数据载体封装 (Capabilities & Inv Module)

  1. 接口设计: 设计并创建一个新的接口 (扩展自 IWenyanDevice 或类似接口)。
  2. 能力系统注入 (Capability): 创建一种新的 Capability 类型。从 ItemStack 的 capability 中获取设备的名称 (由组建持有) 以及原始的执行包 (由物品持有)。
  3. 共享逻辑提取: 提取并创建一个静态辅助函数 (Static Utility)，用于统一处理 Block 和 Item 两者的模块执行逻辑，避免代码冗余。

第 3 阶段：模块解析与消耗机制 (Module Function Impl)

  1. 模块寻找: 实现基于实体坐标搜索目标的功能，使符能够通过自身的背包或是根据坐标在一定范围内的方块中寻找需要引入 (import) 的模块。
  2. 安全调用方块代码: 对于已经存在于代码块中的函数，伪装成代码块自身的 tick 执行方式，直接安全调用。
  3. 消耗机制: 实现请求包装器 (Wrapper Request)，确保附着在内部背包中的符咒在调用之后被精确删除，并在二次请求时添加防御性验证。

第 4 阶段：合成与游戏内容扩充

  1. 合成逻辑: 在合成台中实现多类兼容的读写能力，用于代码刻录。
  2. 游戏内容分发: 配置创造模式选项卡 (Creative Tab) 和相应的交易及战利品表注入系统，以提供可用的预制使用样例。