ggj26_heron/Docs/HeronGlideAbility使用说明.md

夜鹭滑翔能力使用说明

概述

UHeronGlideAbility 是一个为夜鹭角色设计的滑翔能力组件，允许角色在空中滑翔，并在撞到墙壁（TileMap）时停止滑翔并掉落。

功能特性

• ✨ 空中滑翔：角色在跳跃后可以开始滑翔
• 🧱 墙壁检测：自动检测TileMap墙壁和其他静态物体的碰撞
• 📉 撞墙掉落：撞到墙壁后立即停止滑翔，恢复正常重力
• ⚙️ 可调参数：重力缩放、滑翔速度、下落速度等均可在编辑器中调整

如何使用

1. 在蓝图中添加能力组件

在HeronPlayer蓝图中：

1. 打开 BP_HeronPlayer (或你的角色蓝图)
2. 点击 "Add Component"
3. 搜索并添加 HeronGlideAbility
4. 在BeginPlay事件中，将该组件赋值给 CurrentAbility 变量

蓝图示例：

BeginPlay
  ├─> Get Component by Class (HeronGlideAbility)
  └─> Set CurrentAbility

2. C++中使用

在 HeronPlayer.cpp 的 BeginPlay() 中添加：

void AHeronPlayer::BeginPlay() {
    Super::BeginPlay();
    
    // 查找并设置滑翔能力
    CurrentAbility = FindComponentByClass<UHeronGlideAbility>();
    
    if (CurrentAbility) {
        CurrentAbility->OnEnterAbility();
    }
}

3. 调整参数

在编辑器中选中 HeronGlideAbility 组件，可以调整以下参数：

参数名	默认值	说明
GlideGravityScale	0.3	滑翔时的重力缩放（越小浮空越明显）
GlideSpeed	400.0	滑翔时的水平速度
GlideFallSpeed	100.0	滑翔时的最大下落速度
NormalGravityScale	1.0	正常状态的重力缩放

控制说明

空格键操作

• 在地面按空格：跳跃
• 在空中按空格：开始滑翔
• 滑翔时按空格：停止滑翔（手动取消）
• 撞到墙壁：自动停止滑翔并掉落
• 落地：自动停止滑翔

💡 操作提示：滑翔是切换模式，不需要一直按住空格！一个空格键实现跳跃和滑翔的所有操作。

实现细节

墙壁检测机制

• 使用球形射线追踪（Sphere Sweep）检测前方障碍物
• 检测距离：50单位
• 检测半径：20单位
• 能识别：
  • ✅ TileMap组件
  • ✅ 静态网格体
  • ❌ 动态物体（不会触发停止滑翔）

物理效果

滑翔时：

• 重力缩放降低到 GlideGravityScale
• 下落速度被限制在 GlideFallSpeed 以内
• 水平速度保持在 GlideSpeed

停止滑翔时：

• 重力缩放恢复到 NormalGravityScale
• 速度恢复正常物理模拟

调试日志

能力在运行时会输出以下日志信息：

• "夜鹭滑翔能力已激活" - 能力被激活
• "夜鹭滑翔能力已停用" - 能力被停用
• "开始滑翔" - 角色开始滑翔
• "停止滑翔" - 角色停止滑翔
• "滑翔时撞到TileMap墙壁！" - 检测到TileMap碰撞
• "滑翔时撞到墙壁！" - 检测到其他墙壁碰撞

扩展建议

添加滑翔动画

在 StartGlide() 和 StopGlide() 中调用PaperZD动画：

void UHeronGlideAbility::StartGlide() {
    // ...existing code...
    
    // 播放滑翔动画
    if (APaperZDCharacter* Character = Cast<APaperZDCharacter>(GetOwner())) {
        // Character->GetAnimInstance()->PlayAnimationOverride(GlideAnimation);
    }
}

添加粒子效果

在滑翔时生成风的粒子效果：

UPROPERTY(EditAnywhere, Category = "Glide Settings")
UParticleSystem* GlideParticle;

UParticleSystemComponent* GlideParticleComponent;

添加音效

UPROPERTY(EditAnywhere, Category = "Glide Settings")
USoundBase* GlideStartSound;

UPROPERTY(EditAnywhere, Category = "Glide Settings")
USoundBase* GlideLoopSound;

常见问题

Q: 为什么角色无法开始滑翔？ A: 确保：

1. CurrentAbility 已正确设置
2. 角色处于空中（不在地面上）
3. 已正确绑定动作输入

Q: 撞墙后没有停止滑翔？ A: 检查：

1. 墙壁是否为静态物体（Mobility = Static）
2. 墙壁是否有碰撞体积
3. 调整检测距离 TraceDistance 和半径 SphereRadius

Q: 滑翔感觉太快/太慢？ A: 调整以下参数：

• GlideGravityScale - 控制浮空程度
• GlideFallSpeed - 控制下落速度
• GlideSpeed - 控制前进速度

文件结构

Source/ggj26_heron/Ability/
├── BirdAbilityBase.h          # 能力基类头文件
├── BirdAbilityBase.cpp        # 能力基类实现
├── HeronGlideAbility.h        # 滑翔能力头文件
└── HeronGlideAbility.cpp      # 滑翔能力实现

版本历史

• v1.0 (2026-01-31): 初始版本
  • 基础滑翔功能
  • TileMap墙壁检测
  • 可调参数