F2RopeLine2/AGENTS.md

F2RopeLine2

项目定位

• 本项目是测试项目。
• 目标是用于测试钓鱼鱼线相关的逻辑编写与功能测试。

编写原则

• 保持精简，优先直接可验证的实现。
• 避免过度设计，不提前抽象不存在的需求。
• 在保证后续可扩展的前提下，尽量简化结构与实现。
• 新增逻辑应优先服务测试目的，避免引入与当前目标无关的复杂度。

开发流程

• 在项目开始阶段，或后续出现结构性修改时，必须先沟通并确认设计结构。
• 结构设计未确认前，不进入大段代码填充。
• 设计结构确认后，再进入具体实现与代码补全。
• 如果需求变更会影响节点结构、连接关系、渲染流程或交互挂接方式，应重新对齐设计后再修改代码。

实现默认策略

• 首次设计确认时，默认只输出 3 到 6 个核心脚本或模块，不主动展开完整分层架构，除非用户明确要求。
• 未经确认，不引入 Builder、Runtime、Config、Interaction Framework 等扩展层。
• 测试阶段优先使用最少脚本、最少运行时对象、最少中间抽象的实现。
• 新增方案优先选择容易验证、容易回退、容易观察结果的写法。

当前需求

• 鱼线由多节点组成，节点分为逻辑节点和虚拟节点。
• 逻辑节点用于表达真实业务结构，数量和类型会随钓鱼场景变化。
• 虚拟节点用于补足线段表现与计算，不应替代逻辑节点语义。

逻辑节点示例

• 路亚钓可为 2 个逻辑节点：起点、末尾点。
• 路亚钓也可为 3 个逻辑节点：起点、配重点、末尾点。
• 浮子钓可为 4 个逻辑节点：起点、浮漂点、配重点、末尾点。
• 浮子钓需要双钩时，可在浮漂点后存在 2 个末尾点。
• 设计上应允许不同钓法组合出不同逻辑节点结构，但不要为未确认场景预先做复杂抽象。

节点交互

• 逻辑节点可以挂接额外的交互逻辑。
• 交互逻辑可由节点类型决定，也可由同类型下的具体产品决定。
• 浮漂节点可根据需要挂接半物理的浮漂交互脚本。
• 末尾点可根据路亚饵类型挂接不同的交互脚本。
• 设计上应支持节点与交互逻辑解耦，避免把所有交互直接写死在单一节点实现中。
• 同时仍需保持实现精简，只支持当前明确需要的交互扩展，不预建过大的脚本体系。

节点连接

• 逻辑节点与逻辑节点之间使用 ConfigurableJoint 连接。
• 起点节点需要固定锚定到指定的 Transform。
• 该 Transform 表示鱼竿上的固定挂点。
• 起点节点应作为整条鱼线的固定起始约束点。

鱼线渲染

• 各节点之间的鱼线渲染使用 Verlet 算法实现。
• 渲染结果需要平滑过渡，避免明显抖动。
• Verlet 渲染出的鱼线长度应与 Joint 约束链的实际长度保持一致。
• 不允许因平滑处理导致视觉上的鱼线长度明显长于物理长度。
• 渲染层应服务于物理结果表现，不能脱离节点链和约束长度单独扩张。
• 任何平滑、插值、样条、圆角化处理，都不得使任一局部段长或整条视觉长度超过约束链长度。
• 若无法低成本严格保证长度不超限，则默认不启用该类视觉平滑。

虚拟节点规则

• 第一段为动态段，即起点到第一个逻辑节点之间的线段。
• 第一段需要支持放线和收线，因此虚拟节点数量必须可动态增减。
• 除第一段外，其他段的虚拟节点数量可以固定，只需满足当前测试需求。
• 第一段中，起点到第一个虚拟节点的距离也必须是动态的。
• 当按固定步长切分第一段时，不能整除的余量应落在起点到第一个虚拟节点之间。
• 例如基础步长为 0.1 米、第一段总长度为 1.12 米时，离起点最近的第一个虚拟节点距离应为 0.02 米，后续节点再按 0.1 米递进。

虚拟节点默认策略

• 虚拟节点默认使用纯数据结构，不创建运行时 GameObject。
• 只有在明确需要场景交互、挂载组件、独立调试对象时，才将虚拟节点提升为实体对象。
• 长线场景下应优先避免大量 Transform 或 GameObject 带来的层级与性能开销。
• 第一段动态虚拟节点在增减时，应尽量保持已有节点身份与历史状态稳定，避免链路重排导致明显抽动。

水面与地面处理

• 水面或地面表现优先采用轻量规则修正，如高度约束、投影贴附。
• 不默认引入额外碰撞采样器、完整碰撞链或新增物理节点。
• 应支持排除头尾若干节点不参与表面修正，以保留杆梢入水、浮漂黑漂等表现自由度。
• 若仅为钓鱼表现需求，优先使用固定水面高度或简单表面规则，不优先构建完整环境碰撞解。

调试规则

• 调试默认优先使用 Scene Gizmos、必要日志和可开关的调试绘制。
• 不默认添加 GUI 面板、屏幕按钮、大段调试文字，除非用户明确要求。
• 虚拟节点即使为纯数据，也应支持 Gizmos 可视化，便于在 Scene 中观察。
• 调试功能应尽量不影响运行时结构与性能，不为调试方便引入长期保留的重对象方案。

后续补充

• 具体功能边界、数据结构、更新方式、测试用例在后续阶段继续补充。