init

2026-06-04 21:37:53 +08:00
parent b0d2a0e2e7
commit 29a3f77908
63 changed files with 4068 additions and 1 deletions
--- a/Source/lonese/ACameraPawn.md
+++ b/Source/lonese/ACameraPawn.md
@@ -0,0 +1,60 @@
+# ACameraPawn
+
+## 基本信息
+- **类型**: UCLASS
+- **父类**: APawn
+- **源文件**: Source/lonese/CameraPawn.h
+- **模块**: lonese
+
+## 功能概述
+ACameraPawn 是使用 SpringArmComponent + CameraComponent 构建的摄像机 Pawn，挂接到 FollowTarget 的 Actor 上。支持缩放（臂长范围 300-3000）、旋转（绕目标 Yaw 旋转）、平移（相对偏移，限制在 ±800 范围内）和重置（恢复初始状态）。BeginPlay 将玩家控制器的视图切换至自身并挂接到目标。
+
+## 设计用意
+将所有摄像机行为封装在独立 Pawn 中，与角色类完全解耦，实现独立创作、独立测试和灵活替换。FollowTarget + AttachToActor 机制使其可复用于任意 Actor。AMyCharacter 上的 TSubclassOf 属性允许在蓝图中注入自定义摄像机类型。
+
+## 职责范围
+摄像机变换管理，包括缩放、旋转、平移和重置操作，以及视口目标设置。不处理角色移动，也不直接绑定输入（输入由 AMyCharacter 转发）。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| SpringArmComponent.h | #include（在 .cpp 中） | Engine |
+| CameraComponent.h | #include（在 .cpp 中） | Engine |
+
+## 对外接口
+**C++ / Blueprint（UFUNCTION，全部 BlueprintCallable）**
+- `CameraZoom(FInputActionValue)` — 缩放控制。通过调整 SpringArmComponent 的 TargetArmLength 在 MinArmLength(300) 到 MaxArmLength(3000) 之间缩放，速度由 ZoomSpeed(10.0) 控制。
+- `CameraRotate(FInputActionValue)` — 旋转控制。通过修改 SpringArmComponent 绕 FollowTarget 的相对 Yaw 旋转实现绕目标旋转，速度由 RotateSpeed(2.0) 控制。
+- `CameraMove(FInputActionValue)` — 平移控制。通过修改 SpringArmComponent 的 SocketOffset 实现摄像机偏移，限制在 ±CameraMoveClamp(800.0) 范围内，速度由 MoveSpeed(10.0) 控制。
+- `CameraReset(FInputActionValue)` — 重置摄像机。将 SpringArmComponent 的 TargetArmLength 和 SocketOffset 恢复至初始值 (InitialArmLength, 零偏移)，旋转恢复至 InitialRotation。
+
+**C++ / Blueprint（UPROPERTY，全部 BlueprintReadOnly）**
+- `SpringArmComponent` (USpringArmComponent*) — 弹簧臂组件，控制摄像机臂长和延迟。
+- `CameraComponent` (UCameraComponent*) — 摄像机组件。
+- `FollowTarget` (APawn*, VisibleInstanceOnly) — 跟随目标 Pawn，Tick 中更新 SpringArm 位置跟踪。
+- `InitialRotation` (FRotator, EditDefaultsOnly) — 初始旋转，默认 (-60, 0, 0)。
+- `InitialArmLength` (float, EditDefaultsOnly) — 初始臂长，默认 1200。
+- `RotateSpeed` / `ZoomSpeed` / `MoveSpeed` (float, EditDefaultsOnly) — 旋转/缩放/平移速度。
+- `MaxArmLength` / `MinArmLength` (float, EditDefaultsOnly) — 最大/最小臂长，默认 3000/300。
+- `CameraMoveClamp` (double, EditDefaultsOnly) — 平移限制范围，默认 800。
+
+## 使用方法
+- 类声明：`Source/lonese/CameraPawn.h:10-62`
+- 构造函数：`Source/lonese/CameraPawn.cpp:58-73` — 创建 SpringArmComponent 和 CameraComponent，配置臂长、延迟、旋转等默认值。
+- BeginPlay：`Source/lonese/CameraPawn.cpp:76-96` — 将控制器视图切换至自身，若 FollowTarget 已设置则 AttachToActor。
+- Tick：`Source/lonese/CameraPawn.cpp:99-103` — 调用 Super，无额外逻辑。
+- CameraZoom 实现：`Source/lonese/CameraPawn.cpp:10-14`
+- CameraRotate 实现：`Source/lonese/CameraPawn.cpp:17-28`
+- CameraMove 实现：`Source/lonese/CameraPawn.cpp:31-40`
+- CameraReset 实现：`Source/lonese/CameraPawn.cpp:43-49`
+- 由 AMyCharacter 生成并配置 FollowTarget：`Source/lonese/MyCharacter.cpp:111-132`
+
+## 用例
+- **BP_CameraPawn** — 项目摄像机蓝图，继承自 ACameraPawn，在蓝图层配置摄像机默认参数。
+  - `Document/Content/Blueprints/BP_CameraPawn.md:5`（父类为 ACameraPawn）
+  - `Document/Content/Blueprints/_relationships.md:9`
+- **BP_TestChar** — 通过 AMyCharacter 的 CameraActorClass 属性生成 ACameraPawn 实例。
+  - `Document/Content/Blueprints/BP_TestChar.md:22`（间接依赖 ACameraPawn）
+  - `Document/Content/Blueprints/_relationships.md:27`（CameraActorClass = BP_CameraPawn → ACameraPawn）
+- **BP_ControllerComp** — 摄像机控制端点组件，通过指令系统调用 ACameraPawn 的 SpringArm 变换能力。
+  - `Document/Content/Blueprints/BP_ControllerComp.md:13,16`（依赖 ACameraPawn 的摄像机变换能力）
--- a/Source/lonese/AMyActor.md
+++ b/Source/lonese/AMyActor.md
@@ -0,0 +1,35 @@
+# AMyActor
+
+## 基本信息
+- **类型**: UCLASS
+- **父类**: AActor
+- **源文件**: Source/lonese/MyActor.h
+- **模块**: lonese
+
+## 功能概述
+AMyActor 是项目中的基础占位 Actor 类，仅包含标准生命周期函数（BeginPlay/Tick），无任何自定义逻辑。构造函数设置 bCanEverTick 为 true，两个覆写函数均仅调用 Super。
+
+## 设计用意
+由 UE 类向导生成的样板起步类，作为骨架 Actor 准备后续自定义。当前阶段尚未解决具体的游戏性问题，仅作为新 Actor 类型的可扩展基类存在。
+
+## 职责范围
+提供 BeginPlay 和 Tick 生命周期钩子，不含自定义逻辑。可作为新 Actor 类型的扩展基类使用。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+|（无）| — | 不依赖任何项目内类，仅引用引擎头文件 |
+
+## 对外接口
+AMyActor 未定义任何 UFUNCTION 或 UPROPERTY，对外暴露的能力全部来自 AActor 基类。构造函数将 bCanEverTick 设为 true。由于不包含自定义逻辑，C++ 和 Blueprint 调用者无法通过该类调用任何项目特定的方法。
+
+## 使用方法
+作为新 Actor 类型的 C++ 基类或 Blueprint 父类使用。因其仅包含空覆写的 BeginPlay/Tick 且无自定义成员，适合用作任意新 Actor 的起点。
+
+- 类声明：`Source/lonese/MyActor.h:10-26` — 继承自 AActor，无自定义 UFUNCTION/UPROPERTY。
+- 构造函数：`Source/lonese/MyActor.cpp:7-12` — 设置 `bCanEverTick = true`。
+- BeginPlay 覆写：`Source/lonese/MyActor.cpp:15-19` — 仅调用 `Super::BeginPlay()`。
+- Tick 覆写：`Source/lonese/MyActor.cpp:22-25` — 仅调用 `Super::Tick(DeltaTime)`。
+
+## 用例
+项目中无实际调用方。AMyActor 未被任何项目 C++ 类或 Blueprint 继承或引用（Plugins/UnrealClaude 中的引用为文档示例，非项目代码）。
--- a/Source/lonese/AMyCharacter.md
+++ b/Source/lonese/AMyCharacter.md
@@ -0,0 +1,57 @@
+# AMyCharacter
+
+## 基本信息
+- **类型**: UCLASS
+- **父类**: ACharacter
+- **源文件**: Source/lonese/MyCharacter.h
+- **模块**: lonese
+
+## 功能概述
+AMyCharacter 是玩家可控的主角类，通过 Enhanced Input 支持 WASD 移动（世界空间坐标）、走/跑切换（600/1200 速度）、蹲下切换，并将摄像机控制委托给 ACameraPawn。SetupPlayerInputComponent 添加输入映射上下文并绑定 8 个输入动作。摄像机输入转发至 BeginPlay 中生成的 CameraActor 子对象。
+
+## 设计用意
+作为项目主玩家角色，采用关注点分离策略：将摄像机逻辑委托给独立的 ACameraPawn，自身专注于角色移动和输入绑定。使用 Enhanced Input 实现现代化的输入处理。通过状态查询方法将角色状态暴露给蓝图。
+
+## 职责范围
+角色移动控制（走、跑、蹲）、输入动作绑定、摄像机 Pawn 的生成与所有权管理。在 BeginPlay 中生成并持有 CameraActor，将摄像机相关输入转发给该 Actor。不处理摄像机变换逻辑（委托给 ACameraPawn）。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| ACameraPawn | 创建/引用（UPROPERTY 成员，BeginPlay 中 Spawn） | Source/lonese/CameraPawn.h |
+| EnhancedInputSubsystems.h | #include（在 .cpp 中） | Engine |
+| EnhancedInputComponent.h | #include（在 .cpp 中） | Engine |
+
+## 对外接口
+**C++ / Blueprint（UFUNCTION，全部 BlueprintCallable）**
+- `Move(FInputActionValue)` — 接收移动输入（世界空间坐标），根据走/跑状态设置速度为 600 或 1200。
+- `BeginRun(FInputActionValue)` / `StopRun(FInputActionValue)` — 开始/停止跑步状态。跑步时 MaxWalkSpeed 设为 1200，走路为 600。
+- `BeginCrouch(FInputActionValue)` / `StopCrouch(FInputActionValue)` — 开始/停止蹲下，调用 ACharacter 的 Crouch/UnCrouch。
+- `IsRunning() -> bool` — 查询当前是否处于跑步状态。
+- `IsCrouching() -> bool` — 查询当前是否处于蹲下状态。
+
+**C++ / Blueprint（UPROPERTY，EditAnywhere/BlueprintReadOnly）**
+- `DefaultMapping` (UInputMappingContext*) — 默认输入映射上下文。
+- `MoveAction` / `RunAction` / `CrouchAction` (UInputAction*) — 角色移动相关输入动作。
+- `CameraMoveAction` / `CameraZoomAction` / `CameraResetAction` / `CameraRotateAction` (UInputAction*) — 摄像机相关输入动作（转发至 CameraActor）。
+- `CameraActorClass` (TSubclassOf<ACameraPawn>) — 摄像机 Pawn 类，BeginPlay 中以此类生成 CameraActor。
+
+**C++（private，供内部输入绑定使用）**
+- `CameraZoom` / `CameraRotate` / `CameraMove` / `CameraReset` — 将输入值转发给当前 CameraActor 的对应方法。
+
+## 使用方法
+- 类声明：`Source/lonese/MyCharacter.h:10-74`
+- 构造函数：`Source/lonese/MyCharacter.cpp:92-103` — 设置初始移动速度等默认属性。
+- BeginPlay：`Source/lonese/MyCharacter.cpp:106-133` — 生成 CameraActor（通过 CameraActorClass 或默认 ACameraPawn 类），挂接到自身。
+- SetupPlayerInputComponent：`Source/lonese/MyCharacter.cpp:143-196` — 添加 DefaultMapping 到 Enhanced Input 子系统，绑定全部 8 个输入动作到对应方法。
+- Tick：`Source/lonese/MyCharacter.cpp:136-140` — 仅调用 Super。
+- Move 实现：`Source/lonese/MyCharacter.cpp:12-29`
+- BeginRun/StopRun 实现：`Source/lonese/MyCharacter.cpp:32-41`
+- BeginCrouch/StopCrouch 实现：`Source/lonese/MyCharacter.cpp:43-56`
+- 摄像机输入转发：`Source/lonese/MyCharacter.cpp:59-89`
+
+## 用例
+- **BP_TestChar** — 项目主角色蓝图，继承自 AMyCharacter。在 BeginPlay 中添加 CharacterControl 插件组件（UCommandRouterComponent 及各端点组件）。配置 CameraActorClass 指向 BP_CameraPawn。
+  - 声明：`Document/Content/Blueprints/BP_TestChar.md:5`（父类为 AMyCharacter）
+  - 关系：`Document/Content/Blueprints/_relationships.md:7`
+- 蓝图继承类通过编辑 CameraActorClass 属性替换摄像机实现，通过配置 Input 类别下的 8 个 UInputAction 属性定制键位绑定。
--- a/Source/lonese/AMyPlayerController.md
+++ b/Source/lonese/AMyPlayerController.md
@@ -0,0 +1,45 @@
+# AMyPlayerController
+
+## 基本信息
+- **类型**: UCLASS
+- **父类**: APlayerController
+- **源文件**: Source/lonese/MyPlayerController.h
+- **模块**: lonese
+
+## 功能概述
+AMyPlayerController 是自定义 PlayerController，提供三种行为：GetOwnedPawn（GetPawn 的蓝图包装）、CalcCamera 覆写（调用 AActor::CalcCamera 以禁用内置视口目标混合）、AcknowledgePossession 覆写（触发 OnClientPossessFinished BlueprintImplementableEvent，供蓝图实现 Possess 后逻辑）。
+
+## 设计用意
+作为 C++ 与蓝图之间的桥梁。CalcCamera 覆写阻止默认摄像机系统干扰 ACameraPawn 的工作。OnClientPossessFinished 提供蓝图钩子，满足 Possess 后初始化（如 UI 设置、游戏性逻辑）的常见需求。
+
+## 职责范围
+PlayerController 的自定义层：禁用默认摄像机混合计算、提供蓝图 Possess 事件通知。不实现摄像机逻辑（委托给 ACameraPawn 通过视口目标机制处理）。
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+|（无）| — | 不依赖任何项目内类，仅引用引擎头文件 |
+
+## 对外接口
+**C++ / Blueprint（UFUNCTION）**
+- `GetOwnedPawn() -> APawn*` (BlueprintCallable) — 返回当前控制的 Pawn。对 APlayerController::GetPawn() 的蓝图友好包装。
+
+**Blueprint（UFUNCTION，BlueprintImplementableEvent）**
+- `OnClientPossessFinished(APawn* P)` — 当 Possess 完成时由 C++ 层触发的蓝图事件。在 AcknowledgePossession 中调用，参数为被 Possess 的 Pawn。蓝图可覆写此事件实现 Possess 后初始化逻辑（如 UI 设置、状态重置）。
+
+**C++（覆写基类）**
+- `CalcCamera(float DeltaTime, FMinimalViewInfo& OutResult)` — 覆写 APlayerController::CalcCamera，调用 `AActor::CalcCamera` 以禁用内置视口目标混合（viewport blending），确保 ACameraPawn 的视口目标设置不被干扰。
+- `AcknowledgePossession(APawn* P)` — 覆写 APlayerController::AcknowledgePossession，在调用 Super 后触发 OnClientPossessFinished 蓝图事件。
+
+## 使用方法
+- 类声明：`Source/lonese/MyPlayerController.h:13-29`
+- GetOwnedPawn 实现：`Source/lonese/MyPlayerController.cpp:6-8` — 调用并返回 `GetPawn()`。
+- BeginPlay 实现：`Source/lonese/MyPlayerController.cpp:11-13` — 仅调用 Super。
+- CalcCamera 覆写：`Source/lonese/MyPlayerController.cpp:16-18` — 调用 `AActor::CalcCamera` 禁用摄像机混合。
+- AcknowledgePossession 覆写：`Source/lonese/MyPlayerController.cpp:21-24` — Super 后触发 OnClientPossessFinished。
+
+## 用例
+- **BP_TestCtl** — 项目玩家控制器蓝图，继承自 AMyPlayerController，在蓝图中实现 OnClientPossessFinished 事件处理 Possess 完成后逻辑，并定义 SetupControllingPawn 自定义函数处理控制权切换。
+  - `Document/Content/Blueprints/BP_TestCtl.md:5`（父类为 AMyPlayerController）
+  - `Document/Content/Blueprints/BP_TestCtl.md:10,13`（实现 OnClientPossessFinished，利用禁用摄像机计算特性）
+  - `Document/Content/Blueprints/_relationships.md:8,38`（输入管线中的角色）
--- a/Source/lonese/_relationships.md
+++ b/Source/lonese/_relationships.md
@@ -0,0 +1,29 @@
+# lonese 模块依赖关系
+
+## 文件间引用关系
+
+| 源文件 | 引用方式 | 目标文件 | 目标单位 |
+|--------|---------|---------|---------|
+| MyCharacter.h | #include | GameFramework/Character.h | ACharacter |
+| MyCharacter.h | forward-declare | -- | UInputMappingContext |
+| MyCharacter.h | forward-declare | -- | UInputAction |
+| MyCharacter.h | forward-declare | -- | ACameraPawn |
+| MyCharacter.cpp | #include | MyCharacter.h | AMyCharacter |
+| MyCharacter.cpp | #include | CameraPawn.h | ACameraPawn |
+| MyCharacter.cpp | #include | EnhancedInputSubsystems.h | UEnhancedInputLocalPlayerSubsystem |
+| MyCharacter.cpp | #include | EnhancedInputComponent.h | UEnhancedInputComponent |
+| MyCharacter.cpp | #include | GameFramework/CharacterMovementComponent.h | UCharacterMovementComponent |
+| CameraPawn.cpp | #include | CameraPawn.h | ACameraPawn |
+| CameraPawn.cpp | #include | GameFramework/SpringArmComponent.h | USpringArmComponent |
+| CameraPawn.cpp | #include | Camera/CameraComponent.h | UCameraComponent |
+| CameraPawn.cpp | #include | InputActionValue.h | FInputActionValue |
+| MyPlayerController.cpp | #include | MyPlayerController.h | AMyPlayerController |
+| MyActor.cpp | #include | MyActor.h | AMyActor |
+
+## 关键依赖链
+
+1. Character Movement: Enhanced Input -> AMyCharacter::SetupPlayerInputComponent -> binds Move/Run/Crouch actions -> AMyCharacter::Move/BeginRun/StopRun/BeginCrouch/StopCrouch
+2. Camera Control: Enhanced Input -> AMyCharacter -> CameraMove/CameraZoom/CameraRotate/CameraReset -> forwards to ACameraPawn methods
+3. Camera View: AMyCharacter::BeginPlay -> spawns ACameraPawn (deferred) -> ACameraPawn::BeginPlay -> SetViewTarget(self) on PlayerController + AttachToActor(FollowTarget)
+4. Camera Override: AMyPlayerController::CalcCamera -> calls AActor::CalcCamera (bypassing default view target blending) -> camera driven by ACameraPawn transform
+5. Possession: AMyPlayerController::AcknowledgePossession -> Super + OnClientPossessFinished (BlueprintImplementableEvent in BP_TestCtl)