# 梦魇绝镇

**Repository Path**: zzu886/nightmare-town

## Basic Information

- **Project Name**: 梦魇绝镇
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-25
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CharacterControl

当前项目是一个 **Godot 4.6** 的第一人称角色控制原型。


编码标准：
如果是AI编码请务必保证每次新增GD代码不要超过80行，否则就认为是危险代码，要按照阶段拆分；


现阶段代码目标很明确：
- 先把 **组件系统** 跑通
- 先把 **状态机系统** 跑通
- 先把 **玩家角色原型** 跑通
- 暂时不引入怪物、武器、剧情流程等更高层玩法

当前项目已经补充了较完整的脚本说明文档：
- 组件说明： [docs/components](docs/components)
- 状态说明： [docs/states](docs/states)
- 玩家系统重构计划： [docs/player_system_refactor_plan.md](docs/player_system_refactor_plan.md)
- 玩家组件总览： [docs/player_components_overview.md](docs/player_components_overview.md)
- 导航障碍插件说明： [docs/navigation_obstacle_helper_plugin.md](docs/navigation_obstacle_helper_plugin.md)
- 敌人导航接入方案： [docs/enemy_navigation_integration_plan.md](docs/enemy_navigation_integration_plan.md)

另外，项目已新增文档同步规则：
- [skills/docs_sync_rule.md](skills/docs_sync_rule.md)

后续凡是修改组件或状态脚本，都必须同步更新 `docs/` 下对应说明文档。

---

## 当前推荐的目录结构

### 核心框架
- [scripts/core/components/component_blackboard.gd](scripts/core/components/component_blackboard.gd)
- [scripts/core/components/component_config_resource.gd](scripts/core/components/component_config_resource.gd)
- [scripts/core/components/component_host.gd](scripts/core/components/component_host.gd)
- [scripts/core/components/interactable_component.gd](scripts/core/components/interactable_component.gd)
- [scripts/core/components/pickup_interactable_component.gd](scripts/core/components/pickup_interactable_component.gd)
- [scripts/core/navigation/navigation_manager.gd](scripts/core/navigation/navigation_manager.gd)
- [scripts/core/state_machine/state.gd](scripts/core/state_machine/state.gd)
- [scripts/core/state_machine/state_machine.gd](scripts/core/state_machine/state_machine.gd)

### 玩家逻辑
- [scripts/player/player_controller.gd](scripts/player/player_controller.gd)
- [scripts/player/components/input_component.gd](scripts/player/components/input_component.gd)
- [scripts/player/components/move_component.gd](scripts/player/components/move_component.gd)
- [scripts/player/components/jump_component.gd](scripts/player/components/jump_component.gd)
- [scripts/player/components/locomotion_component.gd](scripts/player/components/locomotion_component.gd)
- [scripts/player/components/look_component.gd](scripts/player/components/look_component.gd)
- [scripts/player/components/interaction_component.gd](scripts/player/components/interaction_component.gd)
- [scripts/player/components/inventory_component.gd](scripts/player/components/inventory_component.gd)
- [scripts/player/components/hand_equipment_component.gd](scripts/player/components/hand_equipment_component.gd)
- [scripts/player/components/inventory_blackboard_sync_component.gd](scripts/player/components/inventory_blackboard_sync_component.gd)
- [scripts/player/components/equipment_blackboard_sync_component.gd](scripts/player/components/equipment_blackboard_sync_component.gd)
- [scripts/player/components/head_bob_component.gd](scripts/player/components/head_bob_component.gd)
- [scripts/player/components/breath_sway_component.gd](scripts/player/components/breath_sway_component.gd)
- [scripts/player/states/idle_state.gd](scripts/player/states/idle_state.gd)
- [scripts/player/states/move_state.gd](scripts/player/states/move_state.gd)
- [scripts/player/states/jump_state.gd](scripts/player/states/jump_state.gd)

### 敌人逻辑
- [scripts/enemy/enemy_peanut_controller.gd](scripts/enemy/enemy_peanut_controller.gd)
- [scripts/enemy/components/enemy_target_component.gd](scripts/enemy/components/enemy_target_component.gd)
- [scripts/enemy/components/enemy_observation_component.gd](scripts/enemy/components/enemy_observation_component.gd)
- [scripts/enemy/components/enemy_move_component.gd](scripts/enemy/components/enemy_move_component.gd)
- [scripts/enemy/components/enemy_navigation_component.gd](scripts/enemy/components/enemy_navigation_component.gd)
- [scripts/enemy/states/enemy_frozen_state.gd](scripts/enemy/states/enemy_frozen_state.gd)
- [scripts/enemy/states/enemy_chase_state.gd](scripts/enemy/states/enemy_chase_state.gd)

当前敌人导航方案推荐额外引入：

- 单例 `NavigationManager`
  - 作为统一导航入口
  - 通过分组收集当前关卡中的 `NavigationRegion3D`
  - 向敌人和后续 AI 单位暴露统一的 `navigation_map`

### 可交互物
- [scripts/interactable/holdable_interactable_component.gd](scripts/interactable/holdable_interactable_component.gd)
- [scripts/interactable/drawer_controller.gd](scripts/interactable/drawer_controller.gd)
- [scripts/interactable/drawer_interactable_component.gd](scripts/interactable/drawer_interactable_component.gd)

### 文档
- [docs/components](docs/components)
- [docs/states](docs/states)
- [docs/navigation_obstacle_helper_plugin.md](docs/navigation_obstacle_helper_plugin.md)
- [docs/enemy_navigation_integration_plan.md](docs/enemy_navigation_integration_plan.md)
- [docs/navigation_manager.md](docs/navigation_manager.md)
- [skills/docs_sync_rule.md](skills/docs_sync_rule.md)

### 编辑器工具
- [addons/navigation_obstacle_helper/plugin.gd](addons/navigation_obstacle_helper/plugin.gd)
- [addons/navigation_obstacle_helper/mesh_replacement_rules.gd](addons/navigation_obstacle_helper/mesh_replacement_rules.gd)

### 视角表现
- [scripts/camera/head_bob_camera.gd](scripts/camera/head_bob_camera.gd)

### 场景
- [scenes/player/player_character.tscn](scenes/player/player_character.tscn)
- [scenes/enemy/enemy_peanut.tscn](scenes/enemy/enemy_peanut.tscn)
- [scenes/interactables/drawer/drawer.tscn](scenes/interactables/drawer/drawer.tscn)
- [scenes/Test.tscn](scenes/Test.tscn)
- [scenes/Test2.tscn](scenes/Test2.tscn)

---

## 文件夹分类说明

### `scripts/core/`
这里放**与具体玩法无关**的基础能力。

这部分代码后续不只是玩家能用，怪物、可交互物、武器宿主、UI 控制宿主也都可能复用。

#### `scripts/core/components/`
这里放组件系统的基础设施。

- `ComponentBlackboard`
  - 运行时共享数据容器
  - 目前只负责通用键值存取
  - 不负责组件构建
  - 不负责强类型玩法配置

- `ComponentConfigResource`
  - 单个组件的配置资源
  - 用于描述：
    - 组件名
    - 组件脚本
    - 是否每帧处理
    - 初始化参数
  - 由 `ComponentHost` 读取并构建组件

- `ComponentHost`
  - 组件宿主节点
  - 是当前组件系统里唯一必须存在的 `Node`
  - 职责：
    - 持有黑板
    - 持有组件配置数组
    - 根据配置创建组件
    - 注册/注销组件
    - 提供组件查询
    - 调度每帧组件更新

- `InteractableComponent`
  - 基础交互物组件
  - 负责交互提示与基础显示刷新

- `PickupInteractableComponent`
  - 可拾取交互物组件
  - 负责把配置好的物品加入玩家背包

### `scripts/interactable/`
这里放**具体可交互物或异常物**的脚本实现。

- `HoldableInteractableComponent`
  - 在普通拾取逻辑上增加“直接持拿世界物”的分支

- `DrawerController`
  - 抽屉场景根节点控制器
  - 负责记录抽屉是否开启、是否关闭、是否正在动画中
  - 使用 Tween 在关闭位置和拉开位置之间移动抽屉根节点

- `DrawerInteractableComponent`
  - 抽屉专用交互组件
  - 接入现有交互系统
  - 根据抽屉状态返回“拉开 / 关闭 / 移动中”提示
  - 玩家按下交互键后调用 `DrawerController.toggle()`

### `scenes/interactables/`
这里放可复用的交互场景模板。

- `drawer/drawer.tscn`
  - 当前第一版抽屉交互模板
  - 已接入 `ComponentHost`
  - 交互检测使用 `Area3D`
  - Tween 直接驱动抽屉根节点位移

### `addons/navigation_obstacle_helper/`
当前插件除了生成 `NavigationObstacle3D` 之外，还额外承担白盒 Mesh 到交互场景模板的替换工作。

- `plugin.gd`
  - 提供 Tools 菜单入口
  - 支持按规则替换选中节点及其子树中的 `MeshInstance3D`

- `mesh_replacement_rules.gd`
  - 统一维护 Mesh 替换规则
  - 支持关键字匹配和自定义匹配函数
  - 单个 Mesh 命中第一个 case 后即停止继续匹配

#### `scripts/core/state_machine/`
这里放状态机基础设施。

- `State`
  - 状态基类
  - 是 `RefCounted`
  - 不进入场景树
  - 持有：
    - `actor`
    - `components_host`
    - `machine`

- `StateMachine`
  - 状态机宿主节点
  - 是状态系统里唯一必须存在的 `Node`
  - 职责：
    - 接收状态定义
    - 构建状态对象
    - 维护当前状态
    - 进行切换
    - 分发 `update` / `physics_update`

#### `scripts/core/navigation/`
这里放导航访问基础设施。

- `NavigationManager`
  - AutoLoad 单例
  - 负责收集当前场景中加入 `level_navigation_region` 分组的 `NavigationRegion3D`
  - 对敌人和后续 AI 单位暴露统一的 `navigation_map`

---

## 玩家代码说明

### `scripts/player/player_controller.gd`
玩家宿主。

它是一个 `CharacterBody3D`，当前职责非常克制：
- 获取 `ComponentHost`
- 获取 `StateMachine`
- 获取相机节点
- 从宿主中拿玩家组件引用
- 初始化状态机
- 转发鼠标输入给视角组件
- 提供 `get_move_direction()` 给状态使用
- 提供 `get_view_camera()` 给敌人观察或其他系统使用

它**不直接承担**移动、跳跃、视角计算细节。

### `scripts/player/components/`
这里放当前玩家专用组件。

- `InputComponent`
  - 采集统一输入动作
  - 维护移动、交互、跳跃、主副行为、槽位切换等输入请求

- `MoveComponent`
  - 处理水平移动速度
  - 负责地面/空中的加减速参数

- `JumpComponent`
  - 处理重力与起跳速度

- `LocomotionComponent`
  - 汇总移动与跳跃公共逻辑
  - 负责跳跃缓冲与土狼时间入口

- `LookComponent`
  - 处理鼠标视角
  - 处理 yaw / pitch
  - 捕获鼠标输入

- `InteractionComponent`
  - 处理射线交互目标检测
  - 负责交互提示与交互触发

- `InventoryComponent`
  - 玩家背包核心数据组件
  - 负责槽位、堆叠、增删查

- `HandEquipmentComponent`
  - 当前手持物管理组件
  - 负责装备、卸下、世界物生成与使用委托

- `InventoryBlackboardSyncComponent`
  - 把背包摘要同步到黑板

- `EquipmentBlackboardSyncComponent`
  - 把当前装备状态同步到黑板

- `HeadBobComponent`
  - 生成步行动效偏移

- `BreathSwayComponent`
  - 生成呼吸与轻微镜头摆动偏移

### `scripts/player/states/`
这里放当前玩家状态。

- `IdleState`
- `MoveState`
- `JumpState`

这三个状态目前只服务于玩家移动原型。

后续如果要扩展：
- 蹲伏
- 冲刺
- 受惊
- 交互锁定

建议继续放在这一层中逐步拆分，而不是一开始做过度复杂的层级状态机。

### `scripts/enemy/`
这里放当前敌人原型。

当前已新增一个“木头人 / 小花生规则”敌人原型：

- `EnemyPeanutController`
  - 敌人宿主
  - 是一个 `CharacterBody3D`
  - 负责装配敌人组件与状态机

#### `scripts/enemy/components/`

- `EnemyTargetComponent`
  - 负责解析当前目标玩家与目标相机

- `EnemyObservationComponent`
  - 负责判断敌人是否被玩家有效观察
  - 采用“屏幕范围粗筛 + 多观察点射线精判 + 防抖”方案

- `EnemyMoveComponent`
  - 负责基础追击移动、重力与转向

- `EnemyNavigationComponent`
  - 负责把敌人接入 `NavigationAgent3D`
  - 通过单例 `NavigationManager` 获取当前关卡导航图
  - 为追击状态提供下一路径点

#### `scripts/enemy/states/`

- `EnemyFrozenState`
  - 被玩家观察时冻结

- `EnemyChaseState`
  - 脱离玩家观察时追击
  - 优先沿导航路径点追击，导航不可用时回退为直线追击

---

## 当前基类与核心约定

### 1. 宿主是 `Node`，组件和状态尽量是 `RefCounted`
当前设计约定：
- `ComponentHost` 是组件宿主 `Node`
- `StateMachine` 是状态机宿主 `Node`
- 普通组件尽量使用 `RefCounted`
- 普通状态尽量使用 `RefCounted`

这样做的好处是：
- 场景树更干净
- 逻辑对象更轻量
- 可组合性更强

### 2. 组件初始化约定
当前组件可选实现的接口有：
- `attach_host(host)`
- `configure(config)`
- `frame_tick(delta)`
- `teardown()`

其中：
- `attach_host()` 用于注入 `ComponentHost`
- `configure()` 用于接收配置资源
- `frame_tick()` 只给被标记为每帧处理的组件调用
- `teardown()` 用于卸载清理

### 3. 状态初始化约定
状态统一使用：
- `setup(actor, components_host, machine)`
- `enter(msg)`
- `exit()`
- `update(delta)`
- `physics_update(delta)`

---

## 当前角色场景说明

### 玩家角色场景
- [scenes/player/player_character.tscn](scenes/player/player_character.tscn)

这个场景目前只包含：
- 玩家根节点 `CharacterBody3D`
- 碰撞体
- 相机
- `ComponentHost`
- `StateMachine`
- 手持挂点 `HandAnchor`

**不包含：**
- 地形
- 怪物
- 武器
- UI

它是一个干净的“角色预制体起点”。

---

## 当前建议的扩展方向

后续如果要继续扩展，建议按这个方向走：

### 怪物
当前已落地最小敌人原型：

- `scripts/enemy/`
- `scripts/enemy/components/`
- `scripts/enemy/states/`
- [scenes/enemy/enemy_peanut.tscn](scenes/enemy/enemy_peanut.tscn)

当前敌人同样复用：
- `ComponentHost`
- `StateMachine`
- `State`
- `ComponentConfigResource`
- `ComponentBlackboard`

当前版本先验证“小花生规则”机制：
- 在玩家有效视野中时冻结
- 不在玩家有效视野中时追击
- 先不引入复杂导航与攻击系统

### 武器
未来可以新增：
- `scripts/weapon/`
- `scripts/weapon/components/`
- `scripts/weapon/states/`

但当前阶段不建议提前实现。

---

## 当前项目状态

目前项目更像一个 **玩家控制原型**，不是完整游戏框架。

也就是说：
- 基础结构已经开始成型
- 组件系统和状态机系统已经有了最小可运行骨架
- 已新增一个最小敌人原型用于验证“观察冻结 / 脱离观察追击”机制
- 但目录里仍有一些历史文件可后续继续清理

当前推荐优先使用的是：
- `scripts/core/`
- `scripts/player/`
- `scripts/enemy/`
- `scenes/player/player_character.tscn`
- `scenes/enemy/enemy_peanut.tscn`
- `docs/components/`
- `docs/states/`

如果后续继续整理，建议下一步做：
1. 清理旧的平铺脚本文件
2. 给玩家补一个独立的配置资源目录
3. 把测试场景和正式角色场景彻底分开