F2RopeLine/AGENTS.md

AGENTS.md

项目定位

这是一个专门用于编写、验证、迭代 Unity 钓鱼鱼线系统 的实验项目。

当前仓库目标很单一：

• 验证鱼线脚本方案是否稳定、可控、可扩展
• 快速测试不同钓组节点组合
• 为后续正式项目沉淀可复用的线系统原型

当前不把它当成完整钓鱼游戏项目处理。除非用户明确提出，否则不要主动扩展为完整玩法框架、完整 UI、完整鱼系统、完整多人框架。

---

核心目标

本项目优先级固定为：

1. 稳定
2. 可控
3. 可调试
4. 可配置
5. 表现可信

不以“绝对真实物理”作为目标。游戏性、设计可控性优先于真实感。

---

核心技术路线

鱼线系统应采用 自写节点链 + 半物理求解 的方案，而不是依赖 Unity Joint 串联整条链路。

推荐方向：

• 主链使用自写节点系统
• 更新方式优先考虑 Verlet / PBD / 自定义积分
• 用规则、状态和限幅控制结果
• 允许保留重力、阻尼、水阻、浮力等物理感
• 允许结果“看起来对”，不要求完全真实

明确结论：

• Joint 不是主方案
• Rigidbody 不是主方案
• 通用物理只可作为局部辅助，不可夺走主控制权

---

节点模型

鱼线由一组 逻辑节点 和若干 虚拟节点 组成。

逻辑节点

逻辑节点用于表达钓组结构和特殊行为。至少应支持以下概念：

• Start
• Float
• Sinker
• Hook
• Lure
• Weight
• Normal

逻辑节点规则：

• 第一个节点通常锚定某个 Transform
• 最后一个节点通常是尾端节点
• 逻辑节点之间的总间距应可配置
• 一个逻辑节点可以挂一个或多个显示物体
• Hook 节点允许挂多个钩模型，用于双钩/多钩配置

虚拟节点

虚拟节点只用于：

• 线形态求解
• 平滑弯曲
• 长度约束
• 张力传递近似

虚拟节点不是玩法语义节点。

---

典型钓组

系统应优先支持通过配置生成以下结构：

路亚

• Start -> Lure
• Start -> Weight -> Lure

浮漂钓

• Start -> Float -> Sinker -> Hook

双钩浮漂钓

• Start -> Float -> Sinker -> HookNode

其中 HookNode 可挂多个钩对象。

不要把钓组逻辑写死在脚本流程里，优先抽成可配置数据。

---

设计原则

1. 控制权统一

参与主链求解的节点，只能由一套主系统更新。

禁止出现以下混控：

• 自写求解器更新位置
• 同时又被 Rigidbody 推动
• 同时又被 Transform 直接改位
• 同时又被动画系统强控

2. 只拉不推

鱼线本质是软约束，不是刚性杆件。

求解应优先满足：

• 松弛时不过度传力
• 拉直后再逐步传张力
• 有限幅和平滑
• 允许视觉弯曲

3. 特殊节点是线系统的一部分

Float、Lure、Sinker、Hook 都应作为线系统中的特殊节点处理，而不是外部通过 Joint 硬串在线上。

4. 表现层不反向劫持求解层

渲染、模型跟随、浮漂姿态、杆弯曲等展示逻辑，默认只能读取主链结果，不应直接反向改写主链节点结果。

5. 规则驱动优先于通用物理自然涌现

以下内容默认视为规则/状态系统问题，而不是纯物理问题：

• 漂相
• 鱼口反馈
• 收线手感
• 路亚拖拽表现
• 挂底反馈

---

当前阶段建议分层

Line Solver

负责：

• 节点数据管理
• 积分更新
• 长度约束
• 松弛/拉紧判断
• 张力近似计算
• 关键节点输出

Special Node

负责：

• Float 特殊行为
• Lure 特殊行为
• Sinker / Weight 特殊行为
• Hook 挂载规则

Presentation

负责：

• LineRenderer 或其他线渲染
• 节点挂载物跟随
• 浮漂显示姿态
• 路亚显示姿态
• 调试可视化

Gameplay / Test Harness

负责：

• 钓组切换
• 收线 / 放线测试
• 参数调试
• 场景内验证入口

---

当前实现优先级

当 agent 在本项目中编码时，优先做这些事：

1. 先做最小可运行闭环
2. 先保证 Inspector 可调参数清晰
3. 先保证场景中可视化和调试信息完整
4. 先支持多种节点配置
5. 先验证结构稳定，再补真实感

第一阶段最小目标：

• 起点锚定
• 逻辑节点配置
• 虚拟节点自动生成
• 基础长度约束
• 线渲染
• 挂载物跟随
• 基础调试输出

除非用户明确要求，否则当前阶段不要优先投入：

• 复杂碰撞
• 缠绕
• 完整鱼 AI
• 完整多人同步
• 大量演出系统

---

对 Agent 的明确要求

做实现时

• 优先做原型，但结构不要明显走向错误架构
• 优先保留可替换空间，不要把节点类型和钓组写死
• 优先写便于调试的代码和可视化
• 允许先单文件原型，再按模块拆分

做方案时

• 默认从“可控性”角度评估，而不是从“最真实”角度评估
• 若某方案依赖 Unity Joint/Rigidbody 成为主链核心，应明确反对并给出替代方案
• 若某方案会导致多套系统抢控制权，应明确指出风险

做新增功能时

• 优先确认它属于 Solver、Special Node、Presentation 还是 Gameplay/Test Harness
• 若新增功能会破坏主链控制权统一，应先调整设计再实现

---

明确不要走的方向

• 不要把 Fish / Float / Lure / Rope 再做成 Joint 串联主架构
• 不要让主链节点同时受多套系统控制
• 不要期待钓鱼手感完全靠 Unity 通用物理自然产生
• 不要在项目早期优先做复杂真实碰撞和缠绕
• 不要为了“真实”牺牲调试性和可控性

---

推荐代码组织

文件组织可逐步靠近以下结构：

• FishingLineSolver.cs
• FishingLineNode.cs
• FishingLineConfig.cs
• FishingRigDefinition.cs
• FishingLineRendererBinder.cs
• FishingTensionModel.cs
• FishingSpecialNode_Float.cs
• FishingSpecialNode_Lure.cs
• FishingSpecialNode_Sinker.cs
• FishingGameplayController.cs

如果当前只是验证原型，允许先合并实现，但后续应能平滑拆分。

---

一句话总结

本项目不是在追求“最真实的鱼线物理”，而是在做一套 面向钓鱼玩法、以可控性为核心的半物理鱼线系统原型。