新增文档

2026-06-30 22:12:46 +08:00
parent ae3fcab777
commit bc0c85771c
79 changed files with 12558 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 灵灯技能实现计划
+
+## 现有系统分析
+
+- **光照系统**: `LightSource` 组件注册到 `LightMaskSystem`，由 `DarknessOverlay` shader 在遮罩层挖洞实现光照效果
+- **伤害系统**: `HealthSystem.Damage(int)` 通用扣血，敌人碰到的标准伤害接口
+- **技能参考**: `EchoSystem` (E键摇铃) 是现有最接近的技能模板，有冷却、按键触发的成熟模式
+- **命名空间**: 新脚本放在 `IndianOceanAssets.Engine2_5D` 命名空间，与现有 2.5D 引擎脚本一致
+
+## Task 1: 创建 SpiritLanternSystem.cs（玩家技能管理组件）
+
+**文件**: `Assets/eco/SpiritLanternSystem.cs`
+
+挂载到玩家物体上，负责：
+- 管理灵灯数量（初始 5 个，`[SerializeField] private int maxLanterns = 5`）
+- 按键 U 触发放置（`[SerializeField] private KeyCode lanternKey = KeyCode.U`）
+- 冷却时间控制（`[SerializeField] private float cooldown = 3f`）
+- 放置时实例化灵灯 Prefab 到玩家当前位置
+- 跟踪所有已放置的灵灯，回收时增加可用数量
+- 提供 `public int RemainingLanterns` 属性供 UI 使用
+
+核心逻辑：
+```csharp
+// 按 U 且 CD 就绪 且 还有灵灯 → 放置
+if (Input.GetKeyDown(lanternKey) && remainingLanterns > 0 && Time.time > lastPlaceTime + cooldown)
+{
+    PlaceLantern();
+}
+```
+
+放置时：
+1. 实例化 `lanternPrefab` 在玩家位置
+2. `remainingLanterns--`，记录 `lastPlaceTime`
+3. 订阅灵灯的 `OnLanternRecalled` 事件（回收时 `remainingLanterns++`）
+
+## Task 2: 创建 SpiritLantern.cs（灵灯行为组件）
+
+**文件**: `Assets/eco/SpiritLantern.cs`
+
+挂在灵灯 Prefab 上，负责单个灵灯的行为：
+- **存在时间**: `[SerializeField] private float lifetime = 10f`，倒计时结束触发回收
+- **碰撞检测**: 使用 `CircleCollider2D` (trigger) 检测怪物接触
+  - `OnTriggerEnter2D` → 调用 `HealthSystem.Damage(1)` 扣怪物 1 血 → 灵灯消失 → 通知 `SpiritLanternSystem` 回收
+- **光照**: 挂载 `LightSource` 组件（复用现有光照系统，与主角遮罩效果一致）
+- **回收事件**: `public event Action OnLanternRecalled`，供 `SpiritLanternSystem` 订阅
+- **Layer**: 灵灯 Prefab 需放在 `whatIsEnemy` 能检测到的层，或使用独立的碰撞检测方式
+
+碰撞逻辑：
+```csharp
+private void OnTriggerEnter2D(Collider2D other)
+{
+    var health = other.GetComponent<HealthSystem>();
+    if (health != null && !other.isPlayer) // 排除玩家
+    {
+        health.Damage(1);
+        Recalled(); // 灵灯消失 + 通知回收
+    }
+}
+```
+
+超时回收：
+```csharp
+private void Update()
+{
+    lifetime -= Time.deltaTime;
+    if (lifetime <= 0)
+        Recalled();
+}
+```
+
+## Task 3: 创建灵灯 Prefab
+
+**文件**: `Assets/eco/Prefabs/SpiritLantern.prefab`
+
+Prefab 组成：
+- 空 GameObject（或灯笼 Sprite）
+- `SpriteRenderer` — 灯笼外观（需要美术资源，可先用临时 Sprite）
+- `LightSource` 组件 — 配置光照半径和强度（复用现有光照系统）
+- `SpiritLantern` 脚本 — 管理生命周期和碰撞
+- `CircleCollider2D` (isTrigger = true) — 检测怪物接触
+- `Rigidbody2D` (isKinematic = true) — Collider 需要 Rigidbody 才能触发
+
+## Task 4: 配置与集成
+
+1. 在 `PlayerController` 的 `[RequireComponent]` 中添加 `SpiritLanternSystem`（可选，也可以手动挂载）
+2. 在 Inspector 中配置：
+   - `SpiritLanternSystem` 的 `lanternPrefab` 引用
+   - `LightSource` 的光照半径/强度
+   - 冷却时间、灵灯数量、存在时间等参数
+3. 确保灵灯 Prefab 的 Layer 不与玩家/敌人碰撞冲突
+
+## 数据流总结
+
+```
+按 U 键
+  → SpiritLanternSystem.PlaceLantern()
+    → 实例化 SpiritLantern Prefab（带 LightSource）
+    → LightSource 自动注册到 LightMaskSystem → 遮罩挖洞（照亮区域）
+    → 怪物碰触 → HealthSystem.Damage(1) → 灵灯 Recalled() → remainingLanterns++
+    → 超时 → Recalled() → Destroy → remainingLanterns++
+```
+
+## 可配置参数汇总
+
+| 参数 | 默认值 | 所在脚本 |
+|------|--------|----------|
+| maxLanterns | 5 | SpiritLanternSystem |
+| cooldown | 3s | SpiritLanternSystem |
+| lanternKey | U | SpiritLanternSystem |
+| lifetime | 10s | SpiritLantern |
+| lightRadius | 4f | LightSource (Prefab上) |
+| lightIntensity | 1f | LightSource (Prefab上) |