384400's Blog - 分享网络技术、UE开发、Unity 开发、AI 技术应用

UE5 Gameplay Ability System (GAS) 完全指南

Mon, 30 Mar 2026 17:59:00 GMT

前言

Gameplay Ability System（GAS）是Epic官方推出的强大技能系统框架，被《堡垒之夜》等顶级游戏采用。它提供了一套完整的技能、buff、冷却管理的解决方案。

本文带你从零理解GAS的设计思想，并手把手实现一个简单的技能系统。

什么是GAS？

GAS是Unreal Engine的核心技能/属性系统框架，核心特点是：

特性	说明
ASC架构	Ability System Component驱动
属性委托	GameplayAttribute系统
技能标签	Tag驱动的权限控制
预测系统	客户端预测支持
技能委托	完整的生命周期事件

简单来说：GAS让你能优雅地实现技能、buff、属性、冷却一套完整的战斗系统。

GAS核心概念

1. ASC（Ability System Component）

挂在Actor上的核心组件，负责管理所有技能：

UPROPERTY()
UAbilitySystemComponent* AbilitySystemComponent;

2. AttributeSet（属性集）

存储角色的数值属性（生命值、魔法值、攻击力等）：

UCLASS()
class UMyAttributeSet : public UAttributeSet
{
    GENERATED_BODY()

public:
    UPROPERTY()
    float Health = 100.f;

    UPROPERTY()
    float MaxHealth = 100.f;

    UPROPERTY()
    float Mana = 50.f;

    UPROPERTY()
    float MaxMana = 50.f;

    UPROPERTY()
    float AttackPower = 10.f;
};

3. GameplayAbility（技能）

具体的技能逻辑：

UCLASS()
class UMyGameplayAbility : public UGameplayAbility
{
    GENERATED_BODY()

public:
    // 技能激活时调用
    virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle, 
                                FGameplayAbilityActorInfo* ActorInfo,
                                const FGameplayAbilityActivationInfo& ActivationInfo,
                                FOnGameplayAbilityEnded::FDelegate* OnEnded) override;

    // 技能结束时调用
    virtual void EndAbility(const FGameplayAbilitySpecHandle Handle,
                           FGameplayAbilityActorInfo* ActorInfo,
                           FGameplayAbilityActivationInfo ActivationInfo,
                           bool bReplicateEndAbility,
                           bool bWasCancelled) override;
};

4. GameplayEffect（效果）

用于修改属性（buff/debuff）：

// 瞬间生效的效果（回血、掉血）
TSubclassOf<UGameplayEffect> InstantEffect;

// 持续效果（持续回血、dot）
TSubclassOf<UGameplayEffect> DurationEffect;

// 无限持续效果（buff）
TSubclassOf<UGameplayEffect> InfiniteEffect;

5. GameplayTags（标签）

用于权限控制和技能识别：

// 在ProjectSettings中定义Tag
// Ability.Book.Fire
// Ability.Book.Ice
// Buff.Shield
// Debuff.Slow

项目配置

启用GAS插件

在 Edit > Plugins 中启用：

GameplayAbilities — 核心GAS插件

创建AttributeSet

// MyAttributeSet.h
#pragma once
#include "CoreMinimal.h"
#include "AttributeSet.h"
#include "MyAttributeSet.generated.h"

UCLASS()
class UMyAttributeSet : public UAttributeSet
{
    GENERATED_BODY()

public:
    // 生命值
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attributes")
    FGameplayAttributeData Health;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attributes")
    FGameplayAttributeData MaxHealth;

    // 魔法值
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attributes")
    FGameplayAttributeData Mana;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attributes")
    FGameplayAttributeData MaxMana;

    // 攻击力
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Attributes")
    FGameplayAttributeData AttackPower;

    // 回调：当属性被修改时触发
    virtual void PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data) override;
};

// MyAttributeSet.cpp
#include "MyAttributeSet.h"
#include "GameplayEffect.h"
#include "GameplayEffectExtension.h"

void UMyAttributeSet::PostGameplayEffectExecute(const FGameplayEffectModCallbackData& Data)
{
    if (Data.EvaluatedData.Attribute == GetHealthAttribute())
    {
        SetHealth(FMath::Clamp(GetHealth(), 0.f, GetMaxHealth()));
    }
    else if (Data.EvaluatedData.Attribute == GetManaAttribute())
    {
        SetMana(FMath::Clamp(GetMana(), 0.f, GetMaxMana()));
    }
}

绑定ASC到Character

// MyCharacter.h
UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Abilities")
    TObjectPtr<UAbilitySystemComponent> AbilitySystemComponent;

    UPROPERTY()
    TObjectPtr<UMyAttributeSet> AttributeSet;

    virtual void PossessedBy(AController* NewController) override;
    virtual void OnRep_PlayerState() override;
};

// MyCharacter.cpp
#include "MyCharacter.h"
#include "MyAttributeSet.h"

void AMyCharacter::PossessedBy(AController* NewController)
{
    Super::PossessedBy(NewController);

    if (AbilitySystemComponent)
    {
        AbilitySystemComponent->InitAbilityActorInfo(this, this);
        
        // 给ASC注册AttributeSet
        AbilitySystemComponent->AddAttributeSetSubobject(AttributeSet);
        
        // 赋予初始技能
        GiveDefaultAbilities();
    }
}

void AMyCharacter::OnRep_PlayerState()
{
    Super::OnRep_PlayerState();

    if (AbilitySystemComponent)
    {
        AbilitySystemComponent->InitAbilityActorInfo(this, this);
    }
}

void AMyCharacter::GiveDefaultAbilities()
{
    // 在这里赋予角色的默认技能
    // 使用GrantAbility或通过DataAsset配置
}

实战：创建Fireball技能

步骤1：创建技能蓝图

创建GameplayAbility子类蓝图 BP_FireballAbility
在蓝图编辑器中设置：
- Ability Tags：添加 Damage.Fire
- Cooldown：设置冷却时间
- Cost：设置消耗（魔法值）

步骤2：实现技能逻辑

// FireballAbility.h
UCLASS()
class UFireballAbility : public UGameplayAbility
{
    GENERATED_BODY()

public:
    // 发射火球
    virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle,
                                FGameplayAbilityActorInfo* ActorInfo,
                                const FGameplayAbilityActivationInfo& ActivationInfo,
                                FOnGameplayAbilityEnded::FDelegate* OnEnded) override;

    // 激活技能的输入事件
    UFUNCTION(BlueprintCallable, Category = "Ability")
    void InputPressed(const FGameplayAbilitySpecHandle Handle,
                     const FGameplayAbilityActorInfo* ActorInfo,
                     const FGameplayAbilityActivationInfo& ActivationInfo);
};

// FireballAbility.cpp
#include "FireballAbility.h"
#include "Abilities/GameplayAbilityTargetActor_SingleLineTrace.h"
#include "Abilities/GameplayAbilityTypes.h"

void UFireballAbility::ActivateAbility(const FGameplayAbilitySpecHandle Handle,
                                       FGameplayAbilityActorInfo* ActorInfo,
                                       const FGameplayAbilityActivationInfo& ActivationInfo,
                                       FOnGameplayAbilityEnded::FDelegate* OnEnded)
{
    // 检查技能是否有效
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, false);
        return;
    }

    // 获取技能所有者
    AActor* Owner = ActorInfo->OwnerActor.Get();

    // 生成火球逻辑...
    // 这里可以Spawn一个Actor或播放特效

    UE_LOG(LogTemp, Warning, TEXT("Fireball Activated!"));

    // 结束技能
    EndAbility(Handle, ActorInfo, ActivationInfo, false, false);
}

void UFireballAbility::InputPressed(const FGameplayAbilitySpecHandle Handle,
                                    const FGameplayAbilityActorInfo* ActorInfo,
                                    const FGameplayAbilityActivationInfo& ActivationInfo)
{
    TryActivateAbility(Handle);
}

步骤3：赋予技能

// 在Character的GiveDefaultAbilities中
void AMyCharacter::GiveDefaultAbilities()
{
    if (!AbilitySystemComponent) return;

    // 创建技能Spec
    FGameplayAbilitySpec Spec;
    Spec.Ability = NewObject<UFireballAbility>();
    Spec.Level = 1;

    // 赋予技能
    AbilitySystemComponent->GiveAbility(Spec);
}

冷却系统

设置Cooldown GameplayEffect

// 定义冷却GE
TSubclassOf<UGameplayEffect> CooldownGE = StaticLoadClass(
    UGameplayEffect::StaticClass(),
    nullptr,
    TEXT("GameplayEffect'/Game/Effects/GE_Cooldown.GE_Cooldown_C'")
);

// 检查是否在冷却中
bool AMyCharacter::IsAbilityOnCooldown(FGameplayTag AbilityTag)
{
    FGameplayTagContainer OwnedTags;
    AbilitySystemComponent->GetOwnedGameplayTags(OwnedTags);
    return OwnedTags.HasTag(AbilityTag);
}

常见问题

Q: GAS和普通函数调用的区别？

A: GAS提供了完整的生命周期管理、预测系统、网络同步、冷却/消耗验证。普通函数调用没有这些。

Q: AttributeSet为什么要用FGameplayAttributeData而不是float？

A: FGameplayAttributeData支持元属性（MaxHealth）和Clamp设置，能正确处理属性比例修改。

Q: 如何调试GAS？

A: 使用ASC->Debug命令可以在屏幕上显示所有技能和属性的详细信息。

总结

GAS是UE5最强大的技能系统框架，核心组成：

ASC — 技能系统核心组件
AttributeSet — 管理角色属性
GameplayAbility — 定义技能逻辑
GameplayEffect — 实现buff/debuff
GameplayTags — 权限控制和识别

建议从官方示例项目入手，熟悉后再自定义实现复杂系统。

参考资源

UE5 Mass集群系统详解 — 大规模人群模拟解决方案

Mon, 30 Mar 2026 12:31:00 GMT

前言

在游戏开发中，渲染大量独立个体（如城市人群、动物群体、昆虫群落）一直是性能优化的难题。传统方式下，每个AI角色都是独立的Actor，大规模场景下Draw Call和物理计算会成为灾难。

UE5给出的答案是——Mass。

Mass是Epic官方推出的Entity Component System (ECS) 架构的人群模拟框架，专为大规模集群设计。本文带你从零理解Mass的设计思想，并手把手实现一个简单的集群效果。

什么是Mass？

Mass是UE5内置的大规模实体模拟框架，核心特点是：

特性	说明
ECS架构	数据与逻辑分离，缓存友好
GPU Driven	支持GPU实例化渲染
可扩展	自定义Fragment处理复杂行为
高性能	单帧可处理数万个实体

简单来说：Mass让你能渲染数万个同时运行的AI单位，而且帧率稳定。

Mass核心概念

1. Entity（实体）

一个唯一的ID，标识一个集群单位。不存储任何数据，只是一个Handle。

2. Fragment（片段）

存储实体的数据，比如：

FTransformFragment — 位置、旋转、缩放
FStaticMeshHashMeshVISet — 渲染数据
自定义Fragment存储AI状态

3. Trait（特征）

给Entity附加的行为逻辑，比如：

移动行为
状态机
渲染表现

4. Processing（处理）

每个系统（System）处理特定的Fragment数据，按阶段顺序执行。

项目配置

启用Mass插件

在 Edit > Plugins 中启用：

MassEntity — 核心框架
MassSmartObject — 智能物体交互
MassCrowd — 人群可视化（可选）

重启编辑器后生效。

创建Mass处理器的模块

Mass处理器需要在C++模块中注册。如果你的项目没有Gameplay框架，需要先创建：

// .uproject 添加依赖
"MassEntity": { "Enabled": true },
"MassCrowd": { "Enabled": true }

实战：创建一个简单的集群效果

步骤1：定义Fragment

// MyMassFragments.h
#pragma once
#include "CoreMinimal.h"
#include "MassEntityTypes.h"
#include "MyMassFragments.generated.h"

// 位置和移动数据
USTRUCT()
struct FMyMovementFragment : public FMassFragment
{
    GENERATED_BODY()

    FVector Velocity = FVector::ZeroVector;
    float Speed = 100.f;
};

// 外观数据
USTRUCT()
struct FMyVisualFragment : public FMassFragment
{
    GENERATED_BODY()

    UStaticMesh* Mesh = nullptr;
    FLinearColor Color = FLinearColor::White;
};

步骤2：创建System

// MyMassSystem.h
#pragma once
#include "CoreMinimal.h"
#include "MassEntityTypes.h"
#include "MassProcessor.h"
#include "MyMassSystem.generated.h"

// 移动处理系统
UCLASS()
class UMyMovementSystem : public UMassProcessor
{
    GENERATED_BODY()

public:
    UMyMovementSystem();

protected:
    virtual void ConfigureQueries() override;
    virtual void Execute(UMassEntitySubsystem& EntitySubsystem, FMassExecutionContext& Context) override;

    FMassEntityQuery EntityQuery;
};

// MyMassSystem.cpp
#include "MyMassSystem.h"
#include "MyMassFragments.h"

UMyMovementSystem::UMyMovementSystem()
{
    ExecutionOrder.ExecuteInGroup = EMassFragmentAccessAlgorithm::Linear;
    EntityQuery.AddRequirement<FMyMovementFragment>(EMassFragmentAccess::ReadWrite);
}

void UMyMovementSystem::ConfigureQueries()
{
    EntityQuery.AddTagRequirement<FMyMovementFragment>(EMassFragmentPresence::All);
}

void UMyMovementSystem::Execute(UMassEntitySubsystem& EntitySubsystem, FMassExecutionContext& Context)
{
    EntityQuery.ForEachEntityChunk(EntitySubsystem, Context, [this](FMassExecutionContext& Context)
    {
        TArrayView<FMyMovementFragment> MovementList = Context.GetMutableFragments<FMyMovementFragment>();

        for (int32 i = 0; i < MovementList.Num(); ++i)
        {
            FMyMovementFragment& Movement = MovementList[i];
            
            // 简单示例：让实体向前移动
            FVector Direction = FVector(1.f, 0.f, 0.f);
            Movement.Velocity = Direction * Movement.Speed;
        }
    });
}

步骤3：Spawn实体

// 在GameInstance或Actor中
void USpawnerComponent::SpawnCluster()
{
    UWorld* World = GetWorld();
    UMassEntitySubsystem* MassSystem = UWorld::GetSubsystem<UMassEntitySubsystem>(World);
    
    const int32 ClusterCount = 1000;
    FMassEntityManager& EntityManager = MassSystem->GetEntityManager();
    
    for (int32 i = 0; i < ClusterCount; ++i)
    {
        FMassEntityHandle Entity = EntityManager.CreateEntity();
        
        FMyMovementFragment Movement;
        Movement.Speed = 100.f + FMath::Rand() % 50.f;
        
        EntityManager.SetFragmentData(Entity, Movement);
    }
}

Mass与渲染

使用InstancedStaticMesh

最常见的渲染方式是配合 InstancedStaticMeshComponent：

// 渲染系统示例
void UMyRenderSystem::Execute(UMassEntitySubsystem& EntitySubsystem, FMassExecutionContext& Context)
{
    TArray<FMatrix> InstanceMatrices;
    // ... 填充矩阵数据
    
    if (InstancedMesh)
    {
        InstancedMesh->SetStaticMesh(YourMesh);
        InstancedMesh->BuildRuntimeMeshIfNeeded();
        
        for (int32 i = 0; i < InstanceMatrices.Num(); ++i)
        {
            InstancedMesh->SetMatrixAtIndex(i, InstanceMatrices[i]);
        }
        InstancedMesh->MarkRenderStateDirty();
    }
}

MassCrowd插件

如果你只需要简单的人群渲染，可以启用 MassCrowd 插件，它提供了开箱即用的：

基础移动AI
状态机（行走、站立、奔跑）
动画绑定

集群算法：Reynolds' Boids

要让集群行为自然，通常使用Boids算法，三条核心规则：

1. 分离（Separation）

避免碰撞，保持个体间距：

FVector Separation(const FMyMovementFragment& Self, const TArray<FMyMovementFragment>& Neighbors)
{
    FVector Force = FVector::ZeroVector;
    for (const auto& Other : Neighbors)
    {
        float Distance = FVector::Dist(Self.Position, Other.Position);
        if (Distance < MinSeparationDistance && Distance > 0)
        {
            FVector Away = (Self.Position - Other.Position).GetSafeNormal();
            Force += Away / Distance;
        }
    }
    return Force;
}

2. 对齐（Alignment）

与邻居速度方向一致：

FVector Alignment(const FMyMovementFragment& Self, const TArray<FMyMovementFragment>& Neighbors)
{
    FVector AverageVelocity = FVector::ZeroVector;
    int32 Count = 0;
    for (const auto& Other : Neighbors)
    {
        if (FVector::Dist(Self.Position, Other.Position) < NeightborRadius)
        {
            AverageVelocity += Other.Velocity;
            ++Count;
        }
    }
    return Count > 0 ? (AverageVelocity / Count).GetSafeNormal() : FVector::ZeroVector;
}

3. 内聚（Cohesion）

向邻居中心移动：

FVector Cohesion(const FMyMovementFragment& Self, const TArray<FMyMovementFragment>& Neighbors)
{
    FVector Center = FVector::ZeroVector;
    int32 Count = 0;
    for (const auto& Other : Neighbors)
    {
        if (FVector::Dist(Self.Position, Other.Position) < NeightborRadius)
        {
            Center += Other.Position;
            ++Count;
        }
    }
    return Count > 0 ? ((Center / Count) - Self.Position).GetSafeNormal() : FVector::ZeroVector;
}

性能优化建议

优化项	方法
空间分区	使用Grid或Octree减少邻居搜索范围
LOD	远处实体用简化模型或2D sprite
批处理	Fragment数据布局连续，利于缓存命中
Job System	Mass内部已用TaskGraph，可并行处理
GPU计算	对于简单逻辑，考虑使用GPU Buffer

常见问题

Q: Mass和Niagara有什么区别？

A: Niagara是粒子特效系统，适合数千个简单粒子。Mass是通用ECS框架，适合需要独立AI逻辑的实体。

Q: 支持动画吗？

A: 支持！可以用 MassAnimationInstance 配合 Animation Blueprint，或者使用 MassCrowd 的内置动画。

Q: 如何调试？

A: 启用 MassVisualizer 插件，可以在Editor中可视化实体位置、速度等信息。

总结

Mass是UE5解决大规模集群问题的利器。核心思想：

ECS架构 — 数据与逻辑分离，利于并行
Fragment自定义 — 灵活扩展，满足各种需求
批量处理 — 利用TaskGraph最大化性能

建议从官方 MassCrowd 插件开始体验，熟悉后再深入自定义System和Fragment。

参考资源

GPT-SoVITS 本地语音合成完整教程

Tue, 24 Mar 2026 20:40:00 GMT

前言

GPT-SoVITS是一款强大的本地语音合成项目，支持零样本声音克隆和少样本训练。本文记录完整的本地部署流程，帮你快速上手AI语音合成技术。

环境要求

硬件

显卡：NVIDIA GPU（建议6GB以上显存）
内存：16GB RAM
硬盘：30GB可用空间

软件

Python 3.10+
CUDA 11.8 或 12.1
cuDNN

安装依赖

创建虚拟环境

conda create -n gptsovits python=3.10
conda activate gptsovits

安装PyTorch

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

克隆项目

git clone https://github.com/RVC-Boss/GPT-SoVITS.git
cd GPT-SoVITS

安装依赖

pip install -r requirements.txt

预训练模型下载

需要下载的模型

模型	说明	大小
GPT-SoVITS模型	主模型	~1.5GB
HuggingFace模型	底模	~4GB
训练语料（可选）	参考音色	几百MB

下载地址

模型存放

GPT-SoVITS/
├── GPT_SoVITS/
│   └── pretrained_models/
│       ├── GPT-SoVITS/
│       └── huqubert/
└── SoVITS/
    └── pretrained_models/

推理使用

启动WebUI

python webui.py --port 9876 --colab

浏览器访问

打开 http://localhost:9876

推理参数

参数	说明	建议值
参考音频	克隆音色的源	5-30秒
文本内容	要合成的文字	避免超长
语速	合成语速	1.0正常
音调	音高调整	0正常

API服务

启动API服务

python API.py --port 9880

HTTP调用示例

import requests

# 合成语音
url = "http://127.0.0.1:9880/tts"

data = {
    "text": "你好，欢迎使用GPT-SoVITS语音合成",
    "text_lang": "zh",
    "ref_audio_path": "path/to/reference.wav",
    "prompt_lang": "zh",
    "prompt_text": "这是一段参考音频的文字内容"
}

response = requests.post(url, json=data)

# 保存音频
with open("output.wav", "wb") as f:
    f.write(response.content)

返回格式

{
  "code": 200,
  "message": "success",
  "data": {
    "audio": "base64编码的音频数据",
    "duration": 3.5
  }
}

训练自定义音色

数据准备

收集目标音色的音频（5-30分钟）
音频格式：16bit WAV，16kHz，单声道
命名规范：speaker_name_001.wav

音频预处理

python 3_applyforcevocab.py \
  --input_path ./raw/ \
  --output_path ./processed/

启动训练

# 训练SoVITS
python train_sovits.py \
  --data_path ./processed/ \
  --model_path ./output/sovits/

# 训练GPT
python train_gpt.py \
  --data_path ./processed/ \
  --model_path ./output/gpt/

训练参数

参数	说明	建议值
batch_size	批量大小	显存允许尽量大
learning_rate	学习率	1e-4
epochs	训练轮数	10-20

与项目集成

Python集成

import subprocess
import base64
import os

class GPTSoVITSClient:
    def __init__(self, api_url="http://127.0.0.1:9880"):
        self.api_url = api_url

    def generate(self, text, ref_audio, ref_text):
        import requests
        with open(ref_audio, "rb") as f:
            ref_audio_b64 = base64.b64encode(f.read()).decode()

        data = {
            "text": text,
            "text_lang": "zh",
            "ref_audio_path": ref_audio,
            "prompt_lang": "zh",
            "prompt_text": ref_text
        }

        response = requests.post(self.api_url + "/tts", json=data)
        result = response.json()

        if result["code"] == 200:
            audio_b64 = result["data"]["audio"]
            audio_data = base64.b64decode(audio_b64)

            output_path = "temp_output.wav"
            with open(output_path, "wb") as f:
                f.write(audio_data)
            return output_path
        return None

游戏引擎集成

在UE5中使用：

// 在OpenClaw或其他项目中调用API
void USoVITSManager::GenerateVoice(const FString& Text, const FString& RefAudio)
{
    TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest();
    Request->SetURL("http://127.0.0.1:9880/tts");
    Request->SetVerb("POST");
    Request->SetHeader("Content-Type", "application/json");

    TArray<TSharedPtr<FJsonValue>> JsonArray;
    // ... 构建JSON
    Request->SetContentAsString(JsonString);

    Request->OnProcessRequestComplete().BindUObject(this, &USoVITSManager::OnResponse);
    Request->ProcessRequest();
}

常见问题

Q: 显存不足？

A: 降低batch_size，或使用量化模型。

Q: 合成声音不自然？

A: 提供更清晰、时长适中的参考音频（10-20秒为佳）。

Q: 中文发音错误？

A: 使用拼音或带声调的拼音输入。

Q: 如何提升推理速度？

A: 使用TensorRT加速，或降低推理精度。

总结

GPT-SoVITS核心要点：

本地部署 — 无需云服务，保护隐私
零样本克隆 — 5秒音频即可克隆
少样本训练 — 5-30分钟数据定制音色
API服务 — 方便项目集成
游戏应用 — NPC对话、语音播报

本地语音合成让AI应用更灵活可控。

参考资源

🎉 恭喜！ 现在你掌握了GPT-SoVITS本地部署与使用！

OpenClaw 部署完整指南

Mon, 23 Mar 2026 20:34:00 GMT

前言

OpenClaw是一个强大的AI助手框架，支持多种聊天平台（Telegram、Discord、Signal等）。本文记录完整的OpenClaw部署流程，帮助你快速搭建自己的AI助手。

环境要求

硬件

内存：4GB RAM以上
硬盘：10GB可用空间
网络：稳定的互联网连接

软件

Node.js 18+
npm 或 pnpm
Git

安装Node.js

Windows

访问 Node.js官网
下载LTS版本（18.x或更高）
运行安装程序
验证安装：

node --version
npm --version

Linux (Ubuntu/Debian)

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

安装OpenClaw

全局安装CLI

npm install -g openclaw

创建新项目

openclaw create my-bot
cd my-bot

目录结构

my-bot/
├── config.yaml          # 主配置文件
├── skills/             # 技能文件夹
├── memory/             # 记忆存储
├── workspace/          # 工作区
└── package.json

配置文件详解

config.yaml

# 机器人名称
name: "My Bot"

# 运行端口
port: 18789

# Telegram配置
telegram:
  enabled: true
  botToken: "你的BotToken"
  allowedUsers:
    - 用户ID1
    - 用户ID2

# AI模型配置
models:
  default: "minimax/MiniMax-M2.7"
  providers:
    minimax:
      apiKey: "你的API密钥"
      baseUrl: "https://api.minimax.chat"

# 日志配置
logging:
  level: "info"
  file: "openclaw.log"

获取Telegram Bot Token

在Telegram搜索 @BotFather
发送 /newbot
输入机器人名称
获取Token

获取用户ID

在Telegram搜索 @userinfobot
发送任意消息
获取数字ID

启动机器人

开发模式

npm run dev

生产模式

npm run build
npm start

系统服务（Linux）

创建systemd服务文件：

[Unit]
Description=OpenClaw Bot
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/my-bot
ExecStart=/usr/bin/npm start
Restart=on-failure

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

技能系统

安装技能

openclaw skill install <skill-name>

常用技能

技能	说明
clawhub	技能市场
github	GitHub集成
weather	天气查询
summarize	内容总结

常用命令

命令	说明
`/help`	显示帮助信息
`/status`	显示状态
`/skills`	列出已安装技能
`/reload`	重载配置

Docker部署

Dockerfile

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 18789

CMD ["npm", "start"]

docker-compose.yml

version: '3.8'
services:
  openclaw:
    build: .
    container_name: openclaw-bot
    restart: unless-stopped
    ports:
      - "18789:18789"
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./data:/app/data

启动：

docker-compose up -d

Nginx反向代理

配置SSL证书

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

重启Nginx：

sudo systemctl restart nginx

常见问题

Q: 启动失败，提示端口被占用？

A: 检查端口是否被其他程序占用：

lsof -i :18789
netstat -tlnp | grep 18789

Q: Telegram无法连接？

A: 检查：

Bot Token是否正确
网络能否访问Telegram API
allowedUsers是否包含你的ID

Q: AI模型调用失败？

A: 检查：

API Key是否有效
API额度是否充足
网络是否能访问模型API

Q: 如何更新OpenClaw？

npm update -g openclaw

总结

OpenClaw部署要点：

环境准备 — Node.js 18+
安装启动 — npm install -g openclaw
配置 — config.yaml填写正确信息
启动 — npm start 或 Docker
代理 — Nginx配置SSL

祝你部署成功！

参考资源

🎉 恭喜！ 你的OpenClaw机器人已准备就绪！

UE5 StateTree状态树完全指南

Sun, 15 Mar 2026 20:24:00 GMT

前言

StateTree是UE5引入的全新AI行为逻辑框架，旨在替代传统的Behavior Tree。它结合了有限状态机（FSM）和行为树的优点，提供更直观、更模块化的AI逻辑设计方式。

本文系统讲解StateTree的用法，帮你快速上手这一强大的AI工具。

为什么用StateTree？

特性	Behavior Tree	StateTree
状态切换	需要自定义逻辑	内置状态转换
模块化	有限	高度模块化
并行任务	支持但复杂	原生支持
学习曲线	较陡	平缓

核心概念

State（状态）

// State是StateTree的基本单元
// 每个State包含：Enter、Tick、Exit三个阶段

Transition（转换）

// 状态之间的转换条件
// 支持事件触发和条件判断

Event（事件）

// 事件驱动状态切换
// 可在代码或蓝图中发送事件

节点类型

1. State Nodes（状态节点）

节点	说明
State	普通状态，执行子节点
Linked State	链接到另一个StateTree
Operator State	并行执行多个任务

2. Task Nodes（任务节点）

// 执行具体行为
// 如：移动、攻击、等待

3. Condition Nodes（条件节点）

// 判断是否满足某个条件
// 用于Transition中

4. Event Nodes（事件节点）

// 等待特定事件触发
// 收到事件后切换状态

创建StateTree

1. 创建Asset

内容浏览器右键
AI → StateTree
命名如 STT_EnemyAI

2. 基本结构

Root
├── Idle State
│   └── Tasks: Wait, LookAround
├── Chase State
│   └── Tasks: MoveToTarget, FollowPath
└── Attack State
    └── Tasks: FaceTarget, ExecuteAttack

3. 配置Transition

Idle → Chase
├── Condition: TargetDetected == true
└── Event: OnTargetFound

Chase → Attack
├── Condition: DistanceToTarget < MeleeRange
└── Event: OnInRange

Attack → Chase
├── Condition: DistanceToTarget > MeleeRange
└── Event: OnOutOfRange

代码集成

发送事件

// 从代码发送StateTree事件
UStateTreeComponent* StateTree = Player->FindComponentByClass<UStateTreeComponent>();
if (StateTree)
{
    FStateTreeEvent Event;
    Event.Tag = FGameplayTag::RequestGameplayTag("Event.EnemyAlert");
    Event.Payload.SetValue<FVector>(TargetLocation);
    StateTree->SendEvent(FStateTreeEvent("Alert", Event));
}

绑定数据

// StateTree需要的数据定义在Schema中
USTRUCT()
struct FEnemyStateTreeContext : public FStateTreeOwnerContext
{
    GENERATED_BODY()

    UPROPERTY()
    TObjectPtr<AAIController> Controller;

    UPROPERTY()
    TObjectPtr<UAIPerceptionComponent> Perception;
};

实战：敌人AI

需求分析

Idle（待机）
  ↓ 发现目标
Chase（追击）
  ↓ 进入攻击范围
Attack（攻击）
  ↓ 目标逃离
Chase（追击）

创建Tasks

MoveToTarget Task

USTRUCT()
struct FMoveToTargetTask : public FStateTreeTask
{
    GENERATED_BODY()

    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransition& Transition) const override
    {
        // 获取Context中的数据
        FEnemyStateTreeContext EnemyContext;
        if (!Context.GetContext(EnemyContext)) return EStateTreeRunStatus::Failed;

        AAIController* Controller = EnemyContext.Controller;
        if (!Controller) return EStateTreeRunStatus::Failed;

        // 执行移动
        Controller->MoveToActor(EnemyContext.TargetActor);
        return EStateTreeRunStatus::Running;
    }

    virtual EStateTreeRunStatus Tick(FStateTreeExecutionContext& Context, const float DeltaTime) const override
    {
        // 检查是否到达
        AAIController* Controller = EnemyContext.Controller;
        if (Controller->GetMoveStatus() == EPathFollowingStatus::Type::AtGoal)
        {
            return EStateTreeRunStatus::Succeeded;
        }
        return EStateTreeRunStatus::Running;
    }
};

Attack Task

USTRUCT()
struct FAttackTask : public FStateTreeTask
{
    GENERATED_BODY()

    float AttackCooldown = 1.0f;
    float LastAttackTime = 0.f;

    virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransition& Transition) const override
    {
        FEnemyStateTreeContext EnemyContext;
        if (!Context.GetContext(EnemyContext)) return EStateTreeRunStatus::Failed;

        // 执行攻击
        if (GetWorld()->TimeSeconds - LastAttackTime > AttackCooldown)
        {
            Attack(EnemyContext.Controller);
            LastAttackTime = GetWorld()->TimeSeconds;
        }

        return EStateTreeRunStatus::Succeeded;
    }
};

调试StateTree

编辑器内调试

在StateTree编辑器中打开Debug面板
Play In Editor
观察状态高亮和变量值

日志输出

UE_VLOG_UELOG(StateTreeComponent->GetOwner(), LogStateTree, Log, TEXT("Entering State: %s"), *StateName);

可视化工具

StateTree Debugger — 查看当前状态和转换
AI Perception Visualizer — 查看AI感知范围
Behavior Tree Visualizer — 配合使用

常见问题

Q: StateTree和Behavior Tree哪个好？

A: 新项目推荐StateTree，更易维护。Behavior Tree适合复杂行为树已有项目。

Q: 如何处理并发状态？

A: 使用 Operator State 节点，可以同时执行多个任务。

Q: 可以和Behavior Tree混用吗？

A: 可以。通过 Linked State 节点引用Behavior Tree。

Q: 性能如何？

A: 比传统Behavior Tree略优，尤其在高频状态切换场景。

总结

StateTree核心要点：

模块化 — 状态和任务独立，可复用
事件驱动 — 灵活的状态切换
并行执行 — Operator State支持
易调试 — 内置调试工具
代码集成 — 可扩展Task和Condition

StateTree是UE5 AI开发的首选框架。

参考资源

🎉 恭喜！ 现在你掌握了UE5 StateTree的用法！

游戏开发常用设计模式完全指南

Mon, 02 Mar 2026 20:00:00 GMT

前言

设计模式是解决特定问题的最佳实践，是经过大量项目验证的代码组织方式。在游戏开发中，合理运用设计模式能让代码更清晰、更易维护、更易扩展。本文系统讲解游戏开发中最常用的设计模式。

1. 单例模式（Singleton）

概念

确保一个类只有一个实例，并提供全局访问点。

游戏开发中的应用

场景	说明
GameManager	游戏状态管理，全局唯一
AudioManager	音频管理，统一控制背景音乐、音效
UIManager	UI 管理，协调所有界面
DataManager	数据管理，保存/加载游戏数据

Unity 实现

public class GameManager : MonoBehaviour
{
    public static GameManager Instance { get; private set; }

    private void Awake()
    {
        if (Instance != null && Instance != this)
        {
            Destroy(gameObject);
            return;
        }
        Instance = this;
        DontDestroyOnLoad(gameObject);
    }
}

注意事项

避免滥用单例，导致耦合度过高
考虑使用 ScriptableObject 替代部分单例
线程安全问题在 Unity 中较少出现，但需注意

2. 观察者模式（Observer）

概念

定义对象间的一种一对多依赖关系，当一个对象状态改变时，所有依赖它的对象都会收到通知。

游戏开发中的应用

场景	说明
事件系统	玩家受伤通知、得分变化、任务完成
UI 更新	血量变化时自动更新血条
成就系统	达成条件时触发成就奖励

实现方式

// 事件参数
public class PlayerHealthChangedEvent
{
    public int CurrentHealth;
    public int MaxHealth;
}

// 事件管理器
public class EventManager
{
    public static EventManager Instance { get; private set; }

    private Dictionary<string, List<System.Action<object>>> _listeners = new();

    public void Subscribe(string eventName, System.Action<object> callback)
    {
        if (!_listeners.ContainsKey(eventName))
            _listeners[eventName] = new List<System.Action<object>>();
        _listeners[eventName].Add(callback);
    }

    public void Publish(string eventName, object data = null)
    {
        if (_listeners.ContainsKey(eventName))
        {
            foreach (var callback in _listeners[eventName])
            {
                callback?.Invoke(data);
            }
        }
    }
}

// 使用
public class HealthBar : MonoBehaviour
{
    private void Start()
    {
        EventManager.Instance.Subscribe("PlayerHealthChanged", OnHealthChanged);
    }

    private void OnHealthChanged(object data)
    {
        if (data is PlayerHealthChangedEvent e)
        {
            UpdateHealthBar(e.CurrentHealth, e.MaxHealth);
        }
    }
}

3. 状态机模式（State Machine）

概念

允许对象在内部状态改变时改变其行为，看起来好像修改了它的类。

游戏开发中的应用

场景	说明
角色状态	待机、行走、跑步、跳跃、攻击
AI 行为	巡逻、追击、攻击、逃跑
游戏流程	开始菜单、游戏中、暂停、游戏结束

简单实现

public interface IState
{
    void Enter();
    void Update();
    void Exit();
}

public class StateMachine
{
    private IState _currentState;

    public void TransitionTo(IState newState)
    {
        _currentState?.Exit();
        _currentState = newState;
        _currentState.Enter();
    }

    public void Update()
    {
        _currentState?.Update();
    }
}

Unity 角色状态机示例

// 待机状态
public class IdleState : IState
{
    private PlayerController _player;

    public IdleState(PlayerController player)
    {
        _player = player;
    }

    public void Enter()
    {
        _player.Animator.SetBool("IsWalking", false);
    }

    public void Update()
    {
        float h = Input.GetAxisRaw("Horizontal");
        if (Mathf.Abs(h) > 0.1f)
        {
            _player.StateMachine.TransitionTo(new WalkState(_player));
        }
    }

    public void Exit() { }
}

// 行走状态
public class WalkState : IState
{
    private PlayerController _player;

    public WalkState(PlayerController player)
    {
        _player = player;
    }

    public void Enter()
    {
        _player.Animator.SetBool("IsWalking", true);
    }

    public void Update()
    {
        float h = Input.GetAxisRaw("Horizontal");
        _player.transform.Translate(Vector3.right * h * _player.Speed * Time.deltaTime);

        if (Mathf.Abs(h) < 0.1f)
        {
            _player.StateMachine.TransitionTo(new IdleState(_player));
        }
    }

    public void Exit() { }
}

4. 对象池模式（Object Pool）

概念

避免频繁的对象创建和销毁，复用已创建的对象。

游戏开发中的应用

场景	说明
子弹/炮弹	射击游戏中的大量子弹
粒子特效	爆炸、火花等频繁创建的特效
敌人	波次生成的敌人
UI 元素	伤害数字、道具图标

实现

public class ObjectPool<T> where T : class, new()
{
    private Stack<T> _pool = new();
    private System.Func<T> _createFunc;

    public ObjectPool(System.Func<T> createFunc)
    {
        _createFunc = createFunc;
    }

    public T Get()
    {
        return _pool.Count > 0 ? _pool.Pop() : _createFunc();
    }

    public void Return(T obj)
    {
        _pool.Push(obj);
    }
}

// Unity 中的对象池
public class BulletPool : MonoBehaviour
{
    public GameObject bulletPrefab;
    private ObjectPool<GameObject> _pool;

    private void Start()
    {
        _pool = new ObjectPool<GameObject>(() =>
        {
            return Instantiate(bulletPrefab);
        });
    }

    public GameObject GetBullet()
    {
        var bullet = _pool.Get();
        bullet.SetActive(true);
        return bullet;
    }

    public void ReturnBullet(GameObject bullet)
    {
        bullet.SetActive(false);
        _pool.Return(bullet);
    }
}

注意事项

设置合理的池子容量上限
对象回收时注意重置状态
考虑线程安全问题

5. 命令模式（Command）

概念

将请求封装成对象，从而允许参数化和排队执行请求。

游戏开发中的应用

场景	说明
输入处理	键盘按键映射为具体命令
撤销/重做	记录操作历史，支持撤销重做
AI 命令	给 AI 单位下达移动、攻击等命令
回放系统	录制操作命令并回放

实现

// 命令接口
public interface ICommand
{
    void Execute();
    void Undo();
}

// 移动命令
public class MoveCommand : ICommand
{
    private Transform _target;
    private Vector3 _direction;
    private Vector3 _previousPosition;

    public MoveCommand(Transform target, Vector3 direction)
    {
        _target = target;
        _direction = direction;
    }

    public void Execute()
    {
        _previousPosition = _target.position;
        _target.position += _direction;
    }

    public void Undo()
    {
        _target.position = _previousPosition;
    }
}

// 命令管理器
public class CommandManager
{
    private Stack<ICommand> _history = new();
    private Stack<ICommand> _redoStack = new();

    public void ExecuteCommand(ICommand command)
    {
        command.Execute();
        _history.Push(command);
        _redoStack.Clear();
    }

    public void Undo()
    {
        if (_history.Count > 0)
        {
            var cmd = _history.Pop();
            cmd.Undo();
            _redoStack.Push(cmd);
        }
    }

    public void Redo()
    {
        if (_redoStack.Count > 0)
        {
            var cmd = _redoStack.Pop();
            cmd.Execute();
            _history.Push(cmd);
        }
    }
}

6. 工厂模式（Factory）

概念

定义创建对象的接口，让子类决定实例化哪个类。

游戏开发中的应用

场景	说明
敌人生成	根据波次生成不同类型敌人
道具生成	随机掉落不同道具
技能释放	创建不同的技能实例
UI 生成	动态创建不同类型的界面

实现

// 抽象工厂
public abstract class EnemyFactory
{
    public abstract Enemy CreateEnemy(EnemyType type);
}

// 具体工厂
public class UnityEnemyFactory : EnemyFactory
{
    public override Enemy CreateEnemy(EnemyType type)
    {
        Enemy enemy = type switch
        {
            EnemyType.Slime => Resources.Load<Slime>("Prefabs/Enemies/Slime"),
            EnemyType.Goblin => Resources.Load<Goblin>("Prefabs/Enemies/Goblin"),
            EnemyType.Dragon => Resources.Load<Dragon>("Prefabs/Enemies/Dragon"),
            _ => throw new ArgumentException("Unknown enemy type")
        };

        return Instantiate(enemy);
    }
}

// 使用
public class WaveManager : MonoBehaviour
{
    private EnemyFactory _factory = new UnityEnemyFactory();

    public void SpawnWave(WaveConfig config)
    {
        foreach (var enemyType in config.Enemies)
        {
            var enemy = _factory.CreateEnemy(enemyType);
            enemy.transform.position = GetSpawnPoint();
        }
    }
}

7. 外观模式（Facade）

概念

为复杂的子系统提供一个统一的高层接口，简化子系统使用。

游戏开发中的应用

场景	说明
音频系统	统一管理背景乐、音效、语音
存档系统	统一管理存档、读档、自动存档
战斗系统	整合伤害计算、Buff 管理、战斗结算

实现

// 子系统
public class AudioSubsystem { }
public class SaveSubsystem { }
public class NetworkSubsystem { }

// 外观类
public class GameFacade
{
    public AudioSubsystem Audio { get; }
    public SaveSubsystem Save { get; }
    public NetworkSubsystem Network { get; }

    public GameFacade()
    {
        Audio = new AudioSubsystem();
        Save = new SaveSubsystem();
        Network = new NetworkSubsystem();
    }

    public void Initialize()
    {
        Audio.Init();
        Save.Init();
        Network.Connect();
    }
}

// 使用方不需要了解子系统细节
public class GameManager : MonoBehaviour
{
    private GameFacade _facade;

    private void Start()
    {
        _facade = new GameFacade();
        _facade.Initialize();
    }
}

8. 策略模式（Strategy）

概念

定义一系列算法，把它们一个个封装起来，使它们可以相互替换。

游戏开发中的应用

场景	说明
移动方式	走路、跑步、蹲行、翻滚
攻击方式	近战、远程、法术
AI 寻路	A*、Dijkstra、导航网格
难度设置	简单、普通、困难

实现

// 策略接口
public interface IMoveStrategy
{
    void Move(Transform transform, float speed);
}

// 行走策略
public class WalkStrategy : IMoveStrategy
{
    public void Move(Transform transform, float speed)
    {
        float h = Input.GetAxis("Horizontal");
        float v = Input.GetAxis("Vertical");
        Vector3 dir = new Vector3(h, 0, v).normalized;
        transform.position += dir * speed * Time.deltaTime;
    }
}

// 翻滚策略
public class RollStrategy : IMoveStrategy
{
    public void Move(Transform transform, float speed)
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            // 执行翻滚
        }
    }
}

// 使用
public class PlayerController : MonoBehaviour
{
    public IMoveStrategy MoveStrategy { get; set; }

    private void Update()
    {
        MoveStrategy?.Move(transform, Speed);
    }
}

9. 装饰器模式（Decorator）

概念

动态地给对象添加额外的职责，比继承更灵活。

游戏开发中的应用

场景	说明
Buff 系统	给角色添加各种增益/减益效果
装备强化	武器附加元素伤害、属性强化
技能强化	基础技能加强化效果

实现

// 基础攻击
public class AttackComponent
{
    public virtual int CalculateDamage()
    {
        return 10;
    }
}

// 装饰器基类
public abstract class AttackDecorator : AttackComponent
{
    protected AttackComponent _baseAttack;

    public AttackDecorator(AttackComponent baseAttack)
    {
        _baseAttack = baseAttack;
    }

    public override int CalculateDamage()
    {
        return _baseAttack.CalculateDamage();
    }
}

// 火焰附魔
public class FireEnchantment : AttackDecorator
{
    public FireEnchantment(AttackComponent baseAttack) : base(baseAttack) { }

    public override int CalculateDamage()
    {
        int baseDamage = base.CalculateDamage();
        int fireDamage = 5;
        Debug.Log($"造成 {baseDamage} 物理伤害 + {fireDamage} 火焰伤害");
        return baseDamage + fireDamage;
    }
}

// 冰霜附魔
public class IceEnchantment : AttackDecorator
{
    public IceEnchantment(AttackComponent baseAttack) : base(baseAttack) { }

    public override int CalculateDamage()
    {
        int baseDamage = base.CalculateDamage();
        int iceDamage = 3;
        Debug.Log($"造成 {baseDamage} 物理伤害 + {iceDamage} 冰霜伤害 + 减速效果");
        return baseDamage + iceDamage;
    }
}

10. MVC 与 MVVM 架构

MVC（Model-View-Controller）

Model（模型）     ←→     View（视图）
       ↑                    ↑
       └──── Controller ────┘

部分	职责	游戏开发应用
Model	数据和业务逻辑	角色数据、道具数据
View	UI 显示	血条、伤害数字
Controller	处理输入，协调 Model 和 View	输入控制、UI 事件响应

MVVM（Model-View-ViewModel）

适用于复杂 UI 系统：

Model：数据
View：界面（不直接操作数据）
ViewModel：界面逻辑，数据绑定

// ViewModel 示例
public class HealthBarViewModel : MonoBehaviour
{
    public Observable<int> CurrentHealth { get; } = new();
    public Observable<int> MaxHealth { get; } = new();

    private void Start()
    {
        // 绑定到 View
        CurrentHealth.OnChanged += UpdateHealthBar;
    }

    public void TakeDamage(int damage)
    {
        CurrentHealth.Value = Mathf.Max(0, CurrentHealth.Value - damage);
    }

    private void UpdateHealthBar(int health)
    {
        healthBarImage.fillAmount = (float)health / MaxHealth.Value;
    }
}

设计模式选用指南

按场景选择

场景	推荐模式
全局唯一对象	单例模式
事件通知系统	观察者模式
角色/AI 状态	状态机模式
频繁创建销毁的对象	对象池模式
输入处理/撤销重做	命令模式
对象创建	工厂模式
复杂系统整合	外观模式
算法替换	策略模式
Buff/装备强化	装饰器模式
UI 系统	MVC/MVVM

避免过度设计

不要为了用模式而用模式
简单问题简单解决
代码可读性优先
后续维护成本考虑

总结

设计模式是工具，不是目的。掌握核心模式，理解其适用场景：

模式	核心价值
单例	全局访问点
观察者	解耦事件通知
状态机	清晰的状态管理
对象池	性能优化
命令	封装请求/撤销
工厂	封装创建逻辑
外观	简化复杂系统
策略	算法可替换
装饰器	动态扩展功能

实践建议：从简单模式开始，在实际项目中体会模式的威力。遇到问题时思考"这个问题是否有成熟的解决方案"，而非强行套用模式。

参考资源

《设计模式：可复用面向对象软件的基础》
《游戏编程模式》- Robert Nystrom
Unity 官方设计模式教程

本文结合游戏开发实战经验，系统整理了常用设计模式及其 Unity 实现方式。

Unity+Cursor AI IDE开发实战指南

Sun, 01 Mar 2026 20:00:00 GMT

前言

AI 代码编辑器正在改变开发者的编码方式。Cursor 是一款基于 VS Code 的 AI IDE，完美兼容 Unity 开发环境。本文详细讲解如何将 Cursor 与 Unity 结合，实现高效智能开发。

Cursor 简介

什么是 Cursor

Cursor 是一款内置 AI 能力的代码编辑器（AI IDE），基于 Visual Studio Code 设计，完全兼容 VS Code 的插件生态系统和快捷键。

核心特点

特点	说明
智能代码生成	根据自然语言或代码上下文自动生成代码片段、函数、类
内置 AI 聊天	直接在编辑器内与 AI 对话，询问代码解释、获取优化建议
代码库理解	分析整个项目结构，提供跨文件的精准建议
错误检测修复	自动识别逻辑错误、语法问题、性能瓶颈
多模型支持	支持 GPT、Claude、Gemini 等多种模型

下载地址：https://cursor.com/download（Windows 可选 System 版本）

AI IDE vs 网页问答式 AI

对比

维度	AI IDE	网页问答式 AI
项目理解	直接理解整个工程	需要手动复制上传代码
上下文	完整不丢失	复制不全易缺失
代码修改	一键应用	手动粘贴回文件
新建脚本	AI 自动创建	需手动创建文件再粘贴
批量修改	支持多文件	单文件操作

重构项目示例

网页 AI 流程：

复制代码 → 复制报错 → 粘贴修改 → 来回切换网页 → 上下文丢失 → 容易理解错误

AI IDE 流程：

打开项目 → 直接问 → 一键应用修改 → 逐步优化 → 不用离开编辑器

关联 Unity 编辑器

配置步骤

Unity 菜单栏 Edit > Preferences > External Tools
External Script Editor 点击 Browse
找到 Cursor 安装路径，点击 Cursor.exe
External Script Editor 切换为 Cursor

让 Cursor 理解项目架构

方法一：手动打开项目文件夹

在 Cursor 中点击 Open Folder，定位到 Unity 工程文件夹（有 Assets 文件级的层级）。

不推荐：每次打开脚本都要重新设置。

方法二：配置 External Script Editor Args（推荐）

在 Unity 的 Preferences > External Tools > External Script Editor Args 输入：

-r -g "$(File):$(Line):$(Column)" "$(ProjectPath)"

参数作用：

$(File) — 文件路径
$(Line) — 行号
$(Column) — 列号
$(ProjectPath) — 项目根目录路径

效果：

双击 Console 报错能定位到具体行
Cursor 自动识别项目根目录
所有工程通用

方法三：导入第三方包（实现代码智能提示）

Git 导入：

安装 Git：https://git-scm.com/
Unity Package Manager > + > Install package from git URL
填入：https://github.com/boxqkrtm/com.unity.ide.cursor
安装完成后在 Preferences > External Tools 会发现界面变化

本地导入：

下载 Zip：Code > Download Zip
Package Manager > + > Install package from disk
选择 package.json

生成 .csproj 文件

如果只生成了 .sln，需要：

Preferences > External Tools 勾选相关选项
点击 Regenerate Project files

注：.sln 和 .csproj 只是让编辑器理解项目结构，不参与编译，删掉不影响运行。

安装代码智能插件

插件	作用
.NET SDK	C# 开发环境，必须安装
C#	C# 语言支持
Unity Code Snippets	快速调用 Unity 生命周期函数

安装步骤

View > Extensions（或 Ctrl+Shift+X）
搜索并安装插件（注意供应商名称一致）
.NET SDK 会自动安装，如失败手动安装：https://dotnet.microsoft.com/zh-cn/download/dotnet

Cursor AI 提示词设置

Rules 全局规则

点击 设置按钮 > Rules, Skills, Subagents > Rules，可设置全局提示词规则。

Unity 开发提示词模板

- 请用中文回复
- 节约 Token，简洁明了
- 禁止在项目中乱写新脚本
- 如需新建脚本，请先确认脚本名称和位置

两种 Rule 类型：

类型	作用域
User Rule	账户全局，换电脑也生效
Project Rule	仅当前项目生效

添加 Unity API 参考

在 Settings > Indexing & Docs > Add Doc：

URL：https://docs.unity3d.com/ScriptReference/
提问时输入 @Unity Doc 获取官方 API 答案

.cursorignore 配置

作用

提升 AI 响应速度（跳过无关文件）
提高建议准确性（避免无效上下文）
保护敏感信息
减少干扰，上下文更干净

Unity 开发配置模板

# Unity 生成文件
Library/
Temp/
Obj/
Build/
Logs/

# IDE
.vs/
.vscode/
.idea/

# 版本控制
.git/
.svn/

# 依赖
Packages/

协作模式详解

四种模式

模式	定位	使用场景
Plan	项目蓝图规划师	大型功能启动初期，理清思路
Agent	自主执行代理	多文件复杂任务，自动创建/修改代码
Ask	技术咨询顾问	解答疑问、解释代码，不修改文件
Edit	精准编辑助手	对选中代码块进行精准修改

Plan 示例

输入：/plan 为游戏设计一个包含任务接取、追踪与奖励的完整任务系统

AI 会生成详细规划文档，列出需要创建/修改的脚本、关键步骤、技术思路。

Agent 示例

输入：/agent 请实现一个完整的金币收集系统

AI 自动创建脚本、处理文件引用关系、运行相关命令。

Ask 示例

选中代码："请解释一下这段状态机是如何实现状态切换的？"
直接提问："Unity 中的协程（Coroutine）主要用来解决什么问题？"

Edit 示例

选中移动代码，输入：将这段基于 Transform 的移动改为基于物理引擎（Rigidbody）驱动，并添加重力影响

工作流建议

Plan（理清思路）→ Ask（解决疑问）→ Agent（核心实现）→ Edit（细节微调）

模型切换

付费版功能

在聊天框点击 Auto 可切换不同模型。

模型	说明
Auto	免费版默认，随机选择
Claude Opus	需要付费订阅
GPT Codex	需要付费订阅

注意：中国大陆 IP 无法使用 Claude 模型，需要 VPN + TUN 模式。

添加自定义模型

Settings > Models：

Override OpenAI Base URL 填写 Base URL
OpenAI API Key 填写 API Key
+ Add Custom Model 添加自定义模型

总结

Cursor + Unity 高效开发要点：

关联 Unity：External Script Editor 配置 Cursor.exe
理解项目：配置 Args 参数 + 导入第三方包
智能提示：安装 .NET SDK 和 C# 插件
设置规则：编写 Unity 开发提示词模板
配置 .cursorignore：提升 AI 效率
灵活使用四种模式：Plan > Agent > Ask > Edit

核心优势：AI IDE 能直接理解整个项目架构，支持多文件批量修改，一键应用代码，远超网页问答式 AI 的开发体验。

参考资源

本文整理自 Unity XR 训练营学习资料，结合 Cursor AI IDE 实战经验。

UE5 智能指针完全指南

Thu, 26 Feb 2026 20:22:00 GMT

前言

智能指针是现代C++开发的重要工具，UE5提供了自己的智能指针实现——TSmartPointer系列（TSharedPtr、TWeakPtr、TSharedRef）。

本文系统讲解UE5智能指针的用法，帮你写出更安全的内存管理代码。

为什么使用智能指针？

传统指针	智能指针
手动new/delete	自动内存管理
容易内存泄漏	RAII原则
悬空指针难排查	引用计数安全
所有权不明确	所有权清晰

基础类型

TSharedPtr 共享指针

#include "CoreMinimal.h"

// 创建共享指针
TSharedPtr<FVector> Position = MakeShared<FVector>();

// 使用默认构造
TSharedPtr<FVector> Direction = nullptr;

// 从原始指针创建
FVector* RawPtr = new FVector(1, 0, 0);
TSharedPtr<FVector> Speed = TSharedPtr<FVector>(RawPtr);

// 访问内容
float X = Position->X;
float Y = (*Direction).Y;

TSharedRef 共享引用

// 不可为空的共享指针
TSharedRef<FVector> Ref = MakeShared<FVector>();
Ref->X = 100.f;

// TSharedRef 可以安全转换为 TSharedPtr
TSharedPtr<FVector> Ptr = Ref;

TWeakPtr 弱指针

// 不增加引用计数的观察者
TWeakPtr<FVector> WeakPosition;

// 从SharedPtr创建
TSharedPtr<FVector> Shared = MakeShared<FVector>();
TWeakPtr<FVector> Weak = Shared;

// 检查有效性
if (Weak.IsValid())
{
    // 安全使用
    TSharedPtr<FVector> Locked = Weak.Pin();
    if (Locked)
    {
        UE_LOG(LogTemp, Warning, TEXT("X: %f"), Locked->X);
    }
}

引用计数

引用计数原理

TSharedPtr<FVector> Ptr1 = MakeShared<FVector>();
// 引用计数 = 1

TSharedPtr<FVector> Ptr2 = Ptr1;
// 引用计数 = 2

{
    TSharedPtr<FVector> Ptr3 = Ptr1;
    // 引用计数 = 3
}
// Ptr3 销毁，引用计数 = 2

Ptr1.Reset();
// 引用计数 = 1

Ptr2.Reset();
// 引用计数 = 0，对象自动销毁

手动引用计数

// 共享引用计数对象
TSharedRef<int32> CountRef = MakeShared<int32>();
*CountRef = 0;

TWeakPtr<int32> Weak = CountRef;

// 在需要的地方增加引用
{
    TSharedPtr<int32> Temp = CountRef;
    (*CountRef)++;
} // Temp 销毁但不影响原引用

线程安全

线程安全版本

// TSharedPtr 默认非线程安全
TSharedPtr<FVector> ThreadUnsafe;

// 线程安全版本
TSharedPtr<FVector, ESPMode::ThreadSafe> ThreadSafe;

// 在多线程环境中使用
void WorkerThread()
{
    TSharedPtr<FVector, ESPMode::ThreadSafe> LocalCopy = GlobalPtr;
    if (LocalCopy)
    {
        // 安全访问
    }
}

实战用法

缓存管理

class UCachedDataManager : public UObject
{
public:
    // 缓存计算结果
    TSharedPtr<FVector> GetCachedDirection(FName Key)
    {
        if (Cache.Contains(Key))
        {
            return Cache[Key];
        }

        TSharedPtr<FVector> NewData = ComputeDirection(Key);
        Cache.Add(Key, NewData);
        return NewData;
    }

private:
    TMap<FName, TSharedPtr<FVector>> Cache;
};

观察者模式

class FObserverManager
{
public:
    void Register(TWeakPtr<FSubject> Observer)
    {
        Observers.Add(Observer);
    }

    void Notify()
    {
        // 只通知有效且存在的观察者
        for (auto It = Observers.CreateIterator(); It; ++It)
        {
            if (It->IsValid())
            {
                if (TSharedPtr<FSubject> Observer = It->Pin())
                {
                    Observer->OnNotify();
                }
            }
            else
            {
                It.RemoveCurrent();
            }
        }
    }

private:
    TArray<TWeakPtr<FSubject>> Observers;
};

异步加载

TSharedPtr<FAsyncLoadTask> LoadAssetAsync(const FSoftObjectPath& Path)
{
    return TSharedPtr<FAsyncLoadTask>(new FAsyncLoadTask(Path));
}

void OnAssetLoaded(TSharedPtr<FAssetData> Asset)
{
    if (Asset.IsValid())
    {
        // 使用加载的资产
        ProcessAsset(Asset);
    }
}

与UObject的关系

重要限制

// ⚠️ 智能指针不能指向UObject（因为UObject有自己的垃圾回收）
// 错误用法
TSharedPtr<AActor> Actor = MakeShared<AActor>(); // 编译错误！

// ✅ 正确做法：使用UObject的垃圾回收
TWeakObjectPtr<AActor> ActorPtr;

// 或使用TScriptInterface
TScriptInterface<IActorInterface> ActorInterface;

TWeakObjectPtr

// 用于引用UObject而不影响GC
TWeakObjectPtr<AActor> CachedActor;

// 存储
CachedActor = MyActor;

// 检查有效性
if (CachedActor.IsValid())
{
    AActor* Actor = CachedActor.Get();
    // 安全使用
}

// 或使用Pin
if (TSharedPtr<AActor> Pinned = CachedActor.Pin())
{
    // 使用Pinned
}

常见问题

Q: 和标准库智能指针的区别？

A: UE5的TSmartPointer不依赖标准库，更轻量，且与UE的内存管理系统集成。

Q: 什么时候用TWeakPtr？

A: 观察者、缓存、避免循环引用时。

Q: 可以用在蓝图吗？

A: 智能指针是纯C++特性，蓝图无法直接使用。蓝图中用Object指针和接口。

Q: 性能如何？

A: 略有开销（引用计数），但比手动管理安全。游戏关键路径注意测试。

总结

UE5智能指针核心要点：

TSharedPtr — 共享所有权，自动释放
TSharedRef — 不可为空的共享指针
TWeakPtr — 观察者，不增加引用计数
TWeakObjectPtr — UObject专用弱引用
ESPMode::ThreadSafe — 多线程版本

智能指针是编写安全、优雅C++代码的利器。

参考资源

🎉 恭喜！ 现在你掌握了UE5智能指针的用法！

UE5 PicoVR开发环境配置与基础教程

Wed, 25 Feb 2026 20:13:00 GMT

前言

Pico是国内领先的VR设备厂商，其Pico Neo系列和Pico 4系列支持Unreal Engine开发。本文记录UE5配置PicoVR开发环境的完整流程，帮你快速上手VR开发。

环境要求

硬件

Pico Neo 3 / Neo 4 / Pico 4 企业版
PC VR模式：RTX 1060及以上显卡
USB数据线（支持数据传输）

软件

Unreal Engine 5.0 - 5.4
Pico VR SDK for Unreal
Android Studio（用于配置Android SDK）

步骤一：下载Pico VR SDK

访问 Pico开发者中心
注册/登录开发者账号
下载最新的 Pico XR Unreal SDK
解压得到 PicoVR_UE我要刷屏SDK_v2.x.x 文件夹

步骤二：安装Pico插件

方法一：编辑器内安装

打开UE5编辑器
编辑 → 插件 → 搜索 "Pico"
找到 PicoXR 插件，启用
重启编辑器

方法二：手动安装

将SDK中的 PicoVR 文件夹复制到项目 Plugins 目录下
右键 .uproject 文件 → Generate Visual Studio project files
用VS重新生成项目

步骤三：配置Android SDK

Pico VR需要配置Android SDK环境：

1. 安装Android Studio

下载 Android Studio，安装时勾选：

Android SDK
Android SDK Platform-Tools
Android SDK Build-Tools

2. 配置环境变量

ANDROID_HOME = C:\Users\你的用户名\AppData\Local\Android\Sdk
ANDROID_SDK_ROOT = %ANDROID_HOME%

3. 下载Pico专有SDK

在Pico开发者中心下载 Pico Mobile SDK，解压后包含：

pico_vr_unity_aar — AAR库
pico_vr_unity_libs — SO库

步骤四：配置项目

修改 `DefaultEngine.ini`

[/Script/EngineSettings.GameMapsSettings]
GameDefaultMap=/Game/Maps/VRTemplate_P ICO Map

[/Script/Engine.Engine]
+ActiveGameNameRedirects=(OldGameName="/Script/VRBasePI CO",NewGameName="/Script/你的项目名")
+ActiveGameNameRedirects=(OldGameName="/Script/VRBoilerplate",NewGameName="/Script/你的项目名")

配置Build.cs

// 你的项目.Build.cs
ExtraModuleNames.AddRange(new string[] { "PicoVR" });

步骤五：配置VR Pawn

创建VR Pawn

创建新的 Blueprint Class，父类选择 Pawn
命名 BP_VRPawn

添加组件

组件	说明
Camera	绑定到VR相机
MotionControllerComponent	左右手柄追踪
PicoVRMotionControllerComponent	Pico专用手柄组件
SceneComponent	VR追踪根节点

相机设置

// 在Pawn的BeginPlay中
UCameraComponent* Camera = Cast<UCameraComponent>(GetComponentByClass(UCameraComponent::StaticClass()));
if (Camera)
{
    Camera->bLockToHmd = true;
    Camera->bUsePawnControlRotation = false;
}

步骤六：配置手柄交互

Pico手势追踪

// 获取手部骨骼数据
UPicoXRHandComponent* LeftHand = FindComponentByClass<UPicoXRHandComponent>();
if (LeftHand)
{
    FVector PalmPosition = LeftHand->GetPalmPosition();
    FRotator PalmRotation = LeftHand->GetPalmRotation();
}

抓取物体

// 实现抓取逻辑
void AVRPawn::GrabObject(USceneComponent* Interactable)
{
    if (Interactable && !bIsGrabbing)
    {
        bIsGrabbing = true;
        GrabbedComponent = Interactable;
        
        // 附加到手柄
        AttachToComponent(MotionControllerRight, FAttachmentTransformRules::SnapToTargetIncludingScale);
    }
}

void AVRPawn::ReleaseObject()
{
    if (bIsGrabbing && GrabbedComponent)
    {
        bIsGrabbing = false;
        GrabbedComponent->DetachFromComponent(FDetachmentTransformRules::KeepWorldTransform);
        GrabbedComponent = nullptr;
    }
}

步骤七：真机调试

1. 启用开发者模式

在Pico头显中：

设置 → 通用 → 开发者模式 → 开启

2. 连接设备

通过USB连接PC，头显中确认"允许USB调试"

3. 打包项目

文件 → 打包项目 → Android → Android (ASTC)
选择输出目录
等待打包完成

4. 安装APK

adb install -r 你的项目.apk

5. 启动

在头显中找到你的应用，点击运行

常见问题

Q: 打包失败，提示SDK版本不对？

A: 检查 Project Settings → Platforms → Android SDK，确保Android SDK路径正确，且NDK版本为21以上。

Q: 手柄不显示？

A: 确保Pico XR Plugin已正确启用，且项目使用的Pawn正确继承了VR模板。

Q: 画面撕裂/延迟高？

A: 开启VR内固定的注视点渲染（Fixed Foveated Rendering），并确保使用单通道立体渲染。

Q: 如何调参优化性能？

A: 在 PicoXRGeneralSettings 中调整：

Foveation Level（注视点渲染等级）
Spawn Priority（生成优先级）
Pixel Density（像素密度）

总结

Pico VR开发流程总结：

下载SDK → Pico开发者中心获取
安装插件 → 编辑器内或手动安装
配置Android → SDK环境变量
配置Pawn → VR相机+手柄组件
真机调试 → 开发者模式+ADB安装

Pico的生态在国内VR开发中较为成熟，适合快速验证VR游戏原型。

参考资源

🎉 恭喜！ 现在你可以开始PicoVR开发之旅了！

UE5 委托与代理完全指南

Sat, 21 Feb 2026 20:20:00 GMT

前言

委托（Delegate）是UE5中实现事件驱动编程的核心机制。它允许你在一个对象上绑定函数回调，并在特定事件发生时触发调用。

本文系统讲解UE5委托的各种用法，帮你掌握这一重要的C++技能。

委托基础

为什么使用委托？

传统回调	委托优势
函数指针	类型安全
接口回调	声明简洁
消息中心	解耦设计

声明委托

单播委托

// 声明一个返回bool、接受int参数的委托
DECLARE_DELEGATE_RetVal_OneParam(bool, FOnPlayerAction, int32)

// 或者使用宏自动生成
DECLARE_MULTICAST_DELEGATE_OneParam(FOnDamageDelegate, float)

参数规则

// 无参数
DECLARE_DELEGATE(FSimpleDelegate)

// 单参数（最多8个）
DECLARE_DELEGATE_OneParam(FOneParamDelegate, int32)
DECLARE_DELEGATE_TwoParams(FTwoParamDelegate, int32, FString)
DECLARE_DELEGATE_ThreeParams(FThreeParamDelegate, AActor*, float, FVector)

// 返回值
DECLARE_DELEGATE_RetVal(bool, FReturnBoolDelegate)
DECLARE_DELEGATE_RetVal_OneParam(int32, FReturnIntDelegate, float)

绑定函数

绑定普通成员函数

class AMyActor : public AActor
{
    UFUNCTION()
    void HandleDamage(float Damage);

    void BindDelegate();
};

void AMyActor::BindDelegate()
{
    // 假设有一个委托对象
    FOnDamageDelegate OnDamage;

    // 绑定到成员函数
    OnDamage.AddDynamic(this, &AMyActor::HandleDamage);
}

绑定静态函数

void MyStaticFunction(float Damage)
{
    UE_LOG(LogTemp, Warning, TEXT("Static handler: %f"), Damage);
}

void AMyActor::BindStatic()
{
    FOnDamageDelegate OnDamage;
    OnDamage.AddStatic(&MyStaticFunction);
}

绑定Lambda

void AMyActor::BindLambda()
{
    FOnDamageDelegate OnDamage;

    // C++14+ 支持Lambda
    int32 Count = 0;
    OnDamage.AddLambda([this, Count](float Damage) {
        UE_LOG(LogTemp, Warning, TEXT("Lambda: %f, Count: %d"), Damage, Count);
    });
}

多播代理

声明与使用

// 声明多播委托
DECLARE_MULTICAST_DELEGATE_TwoParams(FOnHealthChanged, float /*OldHealth*/, float /*NewHealth*/);

// 在类中定义
UPROPERTY()
FOnHealthChanged OnHealthChangedDelegate;

// 广播（调用所有绑定的函数）
void AMyCharacter::TakeDamage(float Damage)
{
    float OldHealth = Health;
    Health -= Damage;
    OnHealthChangedDelegate.Broadcast(OldHealth, Health);
}

添加/移除监听

void AMyActor::RegisterCallbacks(AMyCharacter* Character)
{
    if (Character)
    {
        // 添加监听
        Character->OnHealthChangedDelegate.AddDynamic(this, &AMyActor::OnHealthChanged);

        // 移除监听
        Character->OnHealthChangedDelegate.RemoveDynamic(this, &AMyActor::OnHealthChanged);
    }
}

void AMyActor::OnHealthChanged(float OldHealth, float NewHealth)
{
    UE_LOG(LogTemp, Warning, TEXT("Health: %f -> %f"), OldHealth, NewHealth);
}

清空所有绑定

// 清空所有监听
OnHealthChangedDelegate.Clear();

动态委托

动态多播代理

// 用于蓝图支持的动态委托
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnSpellCast, FVector, Location, float, Damage);

// 实现
UPROPERTY(BlueprintAssignable)
FOnSpellCast OnSpellCastDelegate;

// 在Blueprint中绑定

生成函数签名

宏	生成函数
`AddDynamic`	`AddUFunction`
`RemoveDynamic`	`RemoveUFunction`
`IsBound`	`IsBoundToGameInstance`

实战：事件系统

定义事件管理器

// UGameInstanceSubsystem 实现全局事件
UCLASS()
class UEventManager : public UGameInstanceSubsystem, public FTickableGameObject
{
    GENERATED_BODY()

public:
    // 玩家相关事件
    FDelegateHandle OnPlayerDamagedHandle;
    FDelegateHandle OnPlayerDiedHandle;

    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
    virtual void Deinitialize() override;

    // 事件广播
    void BroadcastPlayerDamaged(AActor* Player, float Damage);
    void BroadcastPlayerDied(AActor* Player);

    // 事件监听
    void ListenPlayerDamaged(UObject* Listener, FName FunctionName);
};

实现

void UEventManager::Initialize(FSubsystemCollectionBase& Collection)
{
    Super::Initialize(Collection);
}

void UEventManager::BroadcastPlayerDamaged(AActor* Player, float Damage)
{
    // 广播到所有监听者
    OnPlayerDamaged.Broadcast(Player, Damage);
}

void UEventManager::ListenPlayerDamaged(UObject* Listener, FName FunctionName)
{
    if (Listener && !FunctionName.IsNone())
    {
        FScriptDelegate Delegate;
        Delegate.BindUFunction(Listener, FunctionName);
        OnPlayerDamaged.Add(Delegate);
    }
}

常见问题

Q: AddDynamic报错？

A: 确保目标函数声明为 UFUNCTION()，且接受正确参数。

Q: 内存泄漏？

A: 确保在 EndPlay 或 Deinitialize 中调用 RemoveDynamic 或 Clear。

Q: 委托与接口怎么选？

A: 简单1对1回调用委托，多对多用多播代理，需要蓝图支持用动态委托。

Q: 如何调试委托绑定？

A: 使用 IsBound() 检查，或在Broadcast前加日志。

总结

UE5委托核心要点：

单播委托 — 一对一回调
多播代理 — 一对多广播
动态委托 — 蓝图支持
生命周期 — 记得解绑防止泄漏

委托是实现解耦和事件驱动编程的利器。

参考资源

🎉 恭喜！ 现在你掌握了UE5委托的核心用法！

UE5 网络同步完全指南

Tue, 17 Feb 2026 20:17:00 GMT

前言

网络同步是多人游戏开发的核心技术栈。UE5提供了强大且灵活的网络框架，封装了底层的Socket和序列化管理，让开发者能专注于游戏逻辑而非网络细节。

本文系统讲解UE5的网络同步机制，帮你从零构建多人游戏。

核心概念

服务器-客户端架构

角色	说明
Server	游戏权威来源，负责验证所有操作
Client	接收服务器数据，本地预测执行
Listen Server	玩家充当服务器（常见于P2P）
Dedicated Server	专用服务器，无图形渲染

复制模式

模式	说明
Actor Replicate	自动同步Actor状态
RPC	远程过程调用，触发特定函数
Variable Replicate	变量值同步

Actor复制基础

启用复制

// 在Actor类的构造函数中启用
AActor::AActor()
{
    bReplicates = true;  // 启用复制
    NetUpdateFrequency = 10.f;  // 更新频率
}

设置复制距离

// 默认10米内复制，可通过SetReplicateMovement自定义
SetReplicateMovement(true);

// 或使用NetCullDistanceSquared
NetCullDistanceSquared = 100000000.f;  // 10000米平方

属性同步

声明复制属性

// 在Actor的头文件中
UCLASS()
class AMyCharacter : public ACharacter
{
    GENERATED_BODY()

public:
    // 同步生命值
    UPROPERTY(Replicated, BlueprintReadWrite, Category = "Attributes")
    float Health = 100.f;

    // 仅服务器可修改
    UPROPERTY(ReplicatedUsing = OnRep_Score, BlueprintReadOnly, Category = "Game")
    int32 Score = 0;

protected:
    UFUNCTION()
    void OnRep_Score(int32 OldScore);
};

实现GetLifetimeReplicatedProps

void AMyCharacter::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

    DOREPLIFETIME(AMyCharacter, Health);
    DOREPLIFETIME(AMyCharacter, Score);
}

void AMyCharacter::OnRep_Score(int32 OldScore)
{
    // 分数变化时调用（客户端）
    UE_LOG(LogTemp, Warning, TEXT("Score changed: %d -> %d"), OldScore, Score);
}

RPC远程调用

服务器调用客户端

// 在头文件中声明
UFUNCTION(Server, Reliable)
void ServerTakeDamage(float DamageAmount, AController* InstigatorController);

UFUNCTION(Client, Reliable)
void ClientShowDamageNumber(float Damage, FVector Location);

// 实现
void AMyCharacter::ServerTakeDamage_Implementation(float DamageAmount, AController* InstigatorController)
{
    // 服务器验证并应用伤害
    Health -= DamageAmount;
    OnRep_Health();

    // 通知所有客户端显示伤害数字
    ClientShowDamageNumber(DamageAmount, GetActorLocation());
}

void AMyCharacter::ClientShowDamageNumber_Implementation(float Damage, FVector Location)
{
    // 客户端播放伤害数字特效
    ShowFloatingDamageText(Damage, Location);
}

客户端调用服务器

UFUNCTION(Server, Reliable, WithValidation)
void ServerPurchaseItem(int32 ItemID);

void AMyCharacter::ServerPurchaseItem_Implementation(int32 ItemID)
{
    // 服务器验证并处理购买逻辑
    if (CanAfford(ItemID))
    {
        GiveItem(ItemID);
        DeductGold(ItemID);
    }
}

bool AMyCharacter::ServerPurchaseItem_Validate(int32 ItemID)
{
    // 安全检查
    return ItemID >= 0 && ItemID < MaxItems;
}

角色移动同步

角色移动组件配置

void AMyCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);

    // 确认网络配置
    GetCharacterMovement()->bReplicateInputs = true;
    GetCharacterMovement()->bServerAcceptClientAuthoritativePosition = true;
}

预测性移动

// 在PlayerController中启用预测
void AMyPlayerController::BeginPlay()
{
    Super::BeginPlay();

    // 启用客户端预测
    if (IsLocalPlayerController())
    {
        Player = Cast<AUnrealPlayer>(GetPawn());
        if (Player)
        {
            Player->SetReplicateMovement(true);
        }
    }
}

网络更新频率

优化NetUpdateFrequency

// 高频更新（如玩家）
NetUpdateFrequency = 30.f;  // 每秒30次

// 低频更新（如NPC）
NPC->NetUpdateFrequency = 10.f;  // 每秒10次

// 静态物体
StaticMeshActor->NetUpdateFrequency = 1.f;  // 每秒1次

条件复制

// 仅在值变化时复制
DOREPLIFETIME_CONDITION(AMyCharacter, Health, COND_OwnerOnly);

// 条件枚举
// COND_None - 无条件复制
// COND_OwnerOnly - 仅所有者
// COND_InitialOnly - 仅初始化时
// COND_SkipOwner - 跳过所有者

连接状态检测

心跳检测

// 在PlayerController中
void AMyPlayerController::Tick(float DeltaSeconds)
{
    Super::Tick(DeltaSeconds);

    // 检查连接状态
    if (IsLocalController())
    {
        UNetConnection* Connection = Player->GetNetConnection();
        if (Connection)
        {
            float RoundTripTime = Connection->GetRoundTripTime();
            UE_LOG(LogTemp, Warning, TEXT("RTT: %.2f ms"), RoundTripTime * 1000.f);
        }
    }
}

断开检测

void AMyGameMode::NotifyLogout(AController* Exiting)
{
    // 清理玩家数据
    AMyPlayerState* PS = Exiting->GetPlayerState<AMyPlayerState>();
    if (PS)
    {
        SavePlayerData(PS);
        RemoveFromLeaderboard(PS);
    }
}

常见问题

Q: 客户端移动不流畅？

A: 启用客户端预测和服务器校准。在 DefaultEngine.ini 中：

[/Script/EngineSettings]
n.VerifyPeer=false  // 避免服务器校准延迟

Q: RPC调用失败？

A: 检查：

函数是否声明为 UFUNCTION(Server/Client)
函数签名是否一致
bReplicates是否启用

Q: 大量Actor同步卡顿？

A: 使用 Relevancy 规则或 NetDriveDistance 限制复制范围。优先同步玩家关心的Actor。

Q: 如何调试网络？

A: 使用控制台命令：

net. 1 - 显示网络debug信息
net.ShowReps - 显示复制详情
p.NetSmoothingMode - 网络平滑模式

总结

UE5网络同步核心要点：

Actor复制 — bReplicates + NetUpdateFrequency
属性同步 — DOREPLIFETIME + OnRep回调
RPC调用 — UFUNCTION(Server/Client) + _Validate
移动同步 — 客户端预测 + 服务器校准
频率优化 — 动静分离，按需更新

多人游戏开发的关键是理解服务器权威和客户端预测的配合。

参考资源

🎉 恭喜！ 现在你掌握了UE5网络同步的核心技术！

Unity XR性能优化核心知识完全指南

Sun, 15 Feb 2026 20:00:00 GMT

前言

XR（VR/AR/MR）应用对性能要求极为严苛——需要同时保证高帧率渲染、物理计算、交互系统稳定运行。稍有卡顿就会严重影响用户体验。

渲染批次基础

Draw Call 与 SetPass

理解渲染批次，先要搞清楚 Draw Call 和 SetPass 的区别。

概念	说明
Draw Call	CPU 向 GPU 发送的一条命令，告诉 GPU "画这个网格（Mesh）"
SetPass Call	统计 GPU 准备渲染状态（切换 Shader、贴图、Blend 模式等）的次数

简单比喻：

SetPass = 工厂里工人为下一个生产任务更换工具、调整机器设置、准备好原材料
Draw Call = 工人开始用这套设置实际组装产品

一个 SetPass Call 可以为一次或多次 Draw Call 服务，只要这些 Draw Call 使用完全相同的渲染状态。这就是合批（Batching）的基础。

四大批次技术

动态批次（Dynamic Batching）

Unity 在运行时由 CPU 自动合并满足限制条件的多个动态物体网格，合成一个大网格一次性提交给 GPU。

// 动态批次自动生效，无需手动开启
// 适用场景：大量小型相同材质物体（如场景草地、碎石）

重要：动态批次是 内置渲染管线（Build-in） 的重要优化手段。在 SRP（URP/HDRP）管线中主要采用 SRP Batcher，URP 渲染管线可以使用动态批次。

静态批次（Static Batching）

对不移动的物体标记 Batching Static，Unity 在构建时合并相同材质的物体。

// 在 Inspector 中勾选 Batching Static
// 或使用 API 强制合并
StaticBatchingUtility.Combine(gameObject);

静态批次规则：

必须勾选 Batching Static
必须相同材质、相同渲染状态（Blend/ZTest/Pass）
每批次最多 64,000 个顶点
运行时不能改变 Transform（位置、旋转、缩放）
物体不能改变网格数据

内存警告：静态批次会占用额外内存，因为合并后的网格是唯一存在的。合并物体越多，顶点越多，内存越大。

释放静态批次内存：

// 对象不再使用时，手动释放
Resources.UnloadAsset(meshData);
AssetBundle.Unload(true);

GPU Instancing

GPU Instancing 允许 CPU 一次 Draw Call 通知 GPU 渲染 N 个相同网格但不同变换/颜色的物体。

原理对比：

技术	CPU 端	GPU 端
动态/静态批次	合并网格，有计算和内存开销	收到一个大网格
GPU Instancing	只传递数据，开销小	承担更多矩阵运算

// Shader 中添加支持
#pragma multi_compile_instancing

// 材质球上勾选 Enable GPU Instancing

适用场景：

大量相同物体（树木、森林、岩石、子弹等）
实例之间只有 Transform、颜色、UV 偏移等微小变化
动态物体，但网格和材质固定，性能瓶颈在 CPU 时

不适用场景：

每个物体材质/贴图不同
实例数量很少（几十个以内，开销可能反而更大）
大量独立网格和材质
SkinnedMeshRenderer（不支持）

SRP Batcher

SRP Batcher 是 SRP（URP/HDRP） 下的 CPU 优化技术，通过将物体和材质数据缓存到 GPU，减少计算和上传开销。

核心特点：

不直接减少 Draw Call 数量，但减少 CPU 到 GPU 的数据传输
让同一 Shader 的不同材质对象共用已缓存的 GPU 常量缓冲
Draw Call 数量不变，但 CPU 渲染线程时间显著下降

注意：Frame Debugger 中显示的是 SRP Batch，而不是每个物体的单独 Draw Call。实际上 GPU 仍在分别绘制，CPU 端提交被优化了。

SRP Batcher 使用要求：

Shader 必须声明 UnityPerDraw 和 UnityPerMaterial 的 Constant Buffer
对象不能使用 MaterialPropertyBlocks
对象需要是 MeshRenderer 或 SkinnedMeshRenderer

四种技术优先级

渲染管线	优先级顺序
内置渲染管线	静态批次 > GPU Instancing > 动态批次 > 单独绘制
SRP 管线	静态批次 > SRP Batcher > GPU Instancing > 单独绘制

注意：静态批次执行后就不会再执行 GPU Instancing，但会执行 SRP Batcher。

GPU 性能优化

Overdraw（过度绘制）

Overdraw 指同一像素在一帧中被重复绘制多次，上一次计算结果会被覆盖或叠加。

优化思路一：针对不透明物体

1. 从前向后渲染

Unity 内部处理不透明物体已采用这种方式
使用 Early-Z（提前深度测试）在片元着色器运行之前丢弃被遮挡的片元

2. 遮挡剔除（Occlusion Culling）

// Window > Rendering > Occlusion Culling
// 避免完全不可见的物体进入渲染

优化思路二：针对半透明物体

1. 减少透明层数

UI 背景、HUD 尽量合并图层，少用大面积透明混合

2. Alpha Test 替代 Alpha Blend

树叶、栅栏等使用 Alpha Test（Clip）替代 Alpha Blend，让深度测试能提前丢弃片元

3. 排序优化

透明物体按从远到近绘制，减少不必要的重复混合

4. 特殊替代方案

粒子系统远处改用广告牌效果，降低粒子数量和透明叠加

优化思路三：针对 UI 系统

1. 图集 + 批次 — 减少 Draw Call，但避免大图集带来过多 Overdraw

2. 减少叠层 — UI 设计时避免多层全屏半透明面板

3. RectMask2D 替代 Mask

普通 Mask 相当于多了一层全屏绘制，浪费填充率
RectMask2D 是更轻量级的矩形裁剪，不会产生额外的全屏 OverDraw

4. Stencil 遮罩

复杂形状裁剪使用 Stencil（模板缓冲），需要在自定义 Shader 中实现

5. UI Renderer 独立渲染

避免与 3D 场景互相叠加 OverDraw

内存带宽优化

内存带宽 = 单位时间内，显存（VRAM）和 GPU 内部之间能传输的数据量。

GPU 架构比喻：

ALU = 只做加减乘除、逻辑运算的工人
Shader Core = 负责跑一条着色器指令的一组工人
SM（流式多处理器）= 一个小工厂，内有成百上千个工人
显存 = 存储原料的大仓库
内存带宽 = 从大仓库运原料到小工厂的输送带

优化思路：减少显存读写量，让 GPU 少搬运，多干活

1. 减少分辨率和像素相关开销

降低渲染分辨率（动态分辨率、注视点渲染）
降低抗锯齿采样
减少 OverDraw

2. 优化纹理相关开销

使用 Mipmap：远处物体采样低分辨率贴图，减少带宽浪费
压缩纹理格式：ASTC/ETC2 等压缩格式显著减少带宽占用
贴图合并：把粗糙度、金属度纹理合并，减少采样次数
合理分辨率：角色贴图、UI 纹理尽量使用满足需求的最小分辨率

3. 提高缓存利用率

避免 Shader 中随机纹理采样，尽量连续访问
减少冗余读取，能一次采样合并的就合并
前向渲染排序让 Early-Z 提前丢掉被挡片元

4. 减少不必要的数据存储

避免冗余拷贝（同一贴图拷贝到多个 RT）
利用 GPU 共享内存缓存重复计算的数据
压缩 G-Buffer（延迟渲染阶段存储几何信息的缓冲区）

5. 优化 RenderTarget

使用低精度格式
屏幕后处理效果用 1/2 或 1/4 分辨率处理后放大
多个后处理效果合并到一个 Pass，避免重复拷贝

网格优化

顶点与片元基础

顶点 = 3D 模型的"钢筋骨架"，决定模型形状
片元 = 光栅化阶段产生的候选像素点，决定屏幕上每个像素的最终颜色

GPU 渲染流程：先有骨架（顶点），再填满砖块（片元），最后变成完整画面。

顶点优化思路

从本质上减少顶点以及顶点相关的计算

降低顶点数量
- LOD（Level of Detail）
- 网格简化
- 使用 Impostor（公告牌替代品）优化远距离物体
Billboard（广告牌）
- 多角度烘焙到球面或半球面纹理图集
- Octahedral Impostor 优化
蒙皮优化
- 减少骨骼数量、减少顶点权重、合并骨骼等
顶点动画优化
- 把复杂的程序形变改为 VAT（顶点动画纹理）
顶点着色器优化
- 减少 v2f 里插值数量（TEXCOORD 通道）
- 移动端着色器中数值类型尽量用 half
- 避免大量 sin/cos/pow，用 x*x 替代 pow(x,2.0)
- 预计算复杂函数结果到纹理
合批处理
剔除先于变化 — 使用遮挡剔除、视锥剔除

片元优化思路

从本质上减少片元以及片元相关的计算

降低分辨率（动态分辨率）
减少全屏 Pass
避免 Early-Z 失效（透明物体会导致失效）
Shader 中避免 if/else 分支，用 step/lerp 替代

内存堆栈优化

常见内存分配问题与解决方案

// ❌ 错误：每帧分配字符串
void Update() {
    string name = gameObject.name; // 每次都分配新字符串
}

// ✅ 正确：使用 String.Empty 或缓存
private string tempName = String.Empty;

优化建议清单：

序号	优化项	说明
1	定期清理资源	Resources.UnloadUnusedAssets()
2	字符串拼接	使用 StringBuilder
3	配置数据	使用 Scriptable Object
4	标签比较	使用 Gameobject.CompareTag
5	协程缓存	避免 new WaitForSeconds
6	LINQ	避免使用 LINQ 和正则表达式
7	分帧执行	Update 逻辑改为每 N 帧执行一次
8	禁用调试日志	正式发布时关闭 Debug.Log
9	删除空函数	删除空的 Update/Start 等
10	缓存组件	不要在 Update 里 GetComponent
11	字符串	使用 String.Empty 替代 ""
12	数据结构	单纯传递数据用 struct 而非 class
13	对象池	频繁创建对象时用缓存池

分帧执行示例

private int interval = 3;

void Update()
{
    if (Time.frameCount % interval == 0)
    {
        ExampleExpensiveFunction();
    }
}

禁用调试日志

public class GameLog : MonoBehaviour
{
    [SerializeField] private bool logEnable = true;

    private void Awake()
    {
        Debug.unityLogger.logEnabled = logEnable;
    }
}

Shader 参数优化

// ❌ 一般做法
material.SetFloat("_DissolveAmount", 1);

// ✅ 优化做法：使用 PropertyToID
private int dissolveAmountProperty = Shader.PropertyToID("_DissolveAmount");
private MaterialPropertyBlock propertyBlock;

void Update()
{
    targetRenderer.GetPropertyBlock(propertyBlock);
    propertyBlock.SetFloat(dissolveAmountProperty, 1);
    targetRenderer.SetPropertyBlock(propertyBlock);
}

CPU-Slicing

将一些脚本的 Update 逻辑放在一个统一的 Update 管理器，分帧执行：

// 第一帧执行 A 脚本 Update
// 第二帧执行 B 脚本 Update
// ...

贴图与物理优化

贴图优化

XR 一体机建议贴图 Max Size 设为 1024

Mipmap 设置

参数	推荐值	说明
MipMap	ON	远处使用低分辨率
Filter Mode	Trilinear	在 mip 级别间平滑过渡
MipMap Filter	Kaiser	过滤更清晰
Aniso Level	4~8	各项异性，角度越大越清晰
Wrap Mode	Repeat	重复模式

VR 头显推荐配置：

MipMap: ON
Filter Mode: Trilinear
MipMap Filter: Kaiser
Aniso Level: 4~8
Wrap Mode: Repeat

UI 贴图设置：Clamp + 不需要 MipMap

注意：开启 Mipmap 的贴图会多占用 33% 显存。

物理优化

优化项	说明
减少 MeshCollider	少用复杂网格碰撞体
删除无用碰撞体	删除没用的碰撞器和刚体
Prebake Collision Meshes	Player > Optimation 勾选
Reuse Collision Callbacks	Project Settings > Physics 勾选
关闭可读写	模型导入设置中关闭 Read/Write

UI 优化深度解析

Canvas 重建机制

Canvas 的本质作用：

收集子节点的 UI 元素（Graphic）信息
处理渲染顺序（Sorting、Camera、RenderMode）
管理重建，监听子物体的变动
批量生成 UI 顶点网格、更新材质信息
最终在渲染阶段合批并提交给 GPU

核心问题：一个 Canvas 统一管理它下面所有子 UI 元素，若更新其中一个子元素会让整个 Canvas 重建。

导致 Canvas 重建的操作：

修改 RectTransform（位置、尺寸、角度）
动态布局变化（LayoutGroup、ContentSizeFitter）
频繁改变父子关系
透明度变化
修改材质
脚本修改 Shader

动静分离策略

方案	效果
大 Canvas	500 个 UI + 血条 + 按钮... → 血条变化 → 重建 500 个 UI
分离 Canvas	450 个静态 UI + 小 Canvas(50 个动态血条) → 血条变化只重建 50 个

注意：Canvas 不是越大越好，合并后可能产生更多 DrawCall。

UI 优化清单

不需要交互的取消勾选 Raycast target
移除默认的 Graphic caster
手动指定 Canvas 的 event camera
少用自适应布局组件
使用 SpriteAtlas 图集
用 canvas.enabled = false 替代 SetActive（避免 UI 重建）
避免用 Animator 控制 UI，优先使用：
- DoTween 插件做缓动效果
- 协程或 Lerp 实现插值动画
- Shader 实现动态效果（进度条流光、动态血条等）

音频优化

音频加载类型选择

Load Type	说明	适用场景
Decompress On Load	加载即解压，占用内存多	短音效
Compressed In Memory	内存中压缩，占 CPU	中等长度音效
Streaming	边读边播，占用内存最少	BGM 等长音频

音频优化建议

Preload Audio Data：短音效勾选，长音效关闭
使用 WAV 格式（未压缩，解码快）
推荐压缩格式：OGG/MP3
音频压缩可节省存储空间

总结：性能优化检查清单

优化领域	核心要点
渲染批次	减少 Draw Call，根据管线选择合适的批次技术
GPU 优化	减少 Overdraw，使用遮挡剔除，优化 Shader
内存带宽	使用 Mipmap，压缩纹理格式，减少不必要的数据传输
网格优化	LOD，减少三角面，使用合适的公告牌技术
内存堆栈	减少堆分配，缓存组件，使用对象池，分帧执行
UI 优化	动静分离，避免 Canvas 重建，使用图集
音频优化	选择合适的 Load Type，使用压缩格式
贴图优化	合理分辨率，启用 Mipmap，选择压缩格式
物理优化	简化碰撞体，启用回调复用

工具建议：使用 Unity Profiler 和 Frame Debugger 定期检查性能瓶颈，针对性优化。

参考资源

本文整合自 Unity XR 训练营学习资料，结合 PDF 与 Word 两份文档编写。如有疑问欢迎交流！

Unity XR 多人联机注意事项与故障排查

Tue, 10 Feb 2026 20:00:00 GMT

前言

XR 多人联机开发比普通 PC 多人联机更复杂，涉及网络配置、安卓打包、权限设置等问题。本文基于 Unity XR 训练营资料，总结 XR 多人联机开发的注意事项与故障排查方法。

IP 地址配置

注意事项

重要：复制 IP 地址时检查前面和后面有没有多复制了空格，特别是后面不能带有空格。

查看电脑 IP

Windows 系统：Win + R → 输入 cmd → 输入 ipconfig

本地网络测试

检查项	说明
Unity Transport Address	替换为电脑的 IP 地址
Allow Remote Connections	必须勾选（容易遗漏）

Wifi 设置

使用本地网络测试时，最好把 Wifi 设为专用网络。公用网络有时候容易连不上。

手机作为服务端

网络知识

网络类型	IP 特点
Wi-Fi 私有网络	通常是 192.x.x.x 私有 IP 地址
移动数据（4G/5G）	公共 IP 地址

手机开热点注意事项

手机（移动数据）→ 开启热点 → 电脑连接

电脑获得的 192.x.x.x IP 是电脑的私有 IP，不是手机的
手机作为服务端时，需要在手机的 Wi-Fi 设置里查看路由器为手机分配的 IP 地址
两个设备的 IP 可能不同，但都在同一个局域网内

XR 安卓打包设置

降低 Android API Level

问题：Quest 开发需要 Android 12（API Level 32），但某些手机（如华为 P30 Pro）打包会报错"解析包时出现错误"。

解决：把 Minimum API Level 调低。

关闭 XR 插件

在 XR Plug-in Management 的安卓端取消勾选 XR 的底层插件。

安卓端网络权限设置

AndroidManifest 配置

在 Assets/Plugins/Android/AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Project Settings 配置

Edit > Project Settings > Player > Android：

Internet Access 设为 Require

本地测试关闭防火墙

测试本地联机时，关闭电脑防火墙或添加防火墙例外规则。

故障排查手册

1. 服务端 IP 地址是否正确

检查 Windows 的 ipconfig 查询到的 IP 是否正确配置在 Unity Transport 的 Address 中。

2. Quest 头显网络是否已连接

确保头显已连接 Wi-Fi 并且与电脑在同一局域网内。

3. 打包程序是否误设为 Server/Host

如果电脑作为服务端，打包的程序需要启动 Client。

4. 是否勾选允许远程连接

在 Unity Transport 脚本：

Address 填入电脑 IP（无多余空格）
Allow Remote Connections 必须勾选

5. Wi-Fi 是否设为专用网络

公用网络可能阻止局域网连接。

6. 安卓端网络权限

检查清单：

[ ] AndroidManifest 添加 INTERNET 权限
[ ] AndroidManifest 添加 ACCESS_NETWORK_STATE 权限
[ ] Project Settings 的 Internet Access 设为 Require

7. 防火墙是否关闭

尝试关闭防火墙进行测试。

常见错误与解决方案

问题	解决方案
无法连接	检查 IP 是否正确、防火墙是否关闭
打包安装失败	降低 Minimum API Level
权限弹窗没出现	检查 OVRManager 的 Permission Request On Startup
画面不同步	检查 NetworkVariable 的 Server 写权限
延迟高	使用有线网络而非 Wi-Fi

MR 多人联机特殊注意

空间对齐

MR 多人联机需要空间对齐，确保多个玩家的虚拟坐标系与现实空间对应。

权威判定

所有影响游戏结果的逻辑必须在 Server 端 执行，Client 只负责申请和显示。

输入同步

XR 输入（头显位置、手柄控制器）是实时流，需要持续同步到远端 Player。

总结

XR 多人联机注意事项：

IP 配置：Address 无空格、勾选 Allow Remote Connections
网络设置：专用 Wi-Fi、同一局域网、防火墙关闭
安卓打包：降低 API Level、关闭 XR 插件、配置网络权限
故障排查：按清单逐项检查（IP → 网络 → 权限 → 防火墙）

调试建议：先用 PC 双开测试，确认功能正常后再打包到安卓设备。

本文整理自 Unity XR 训练营学习资料。

Unity MR二维码识别开发实战指南

Mon, 09 Feb 2026 20:00:00 GMT

前言

二维码识别是 MR 开发中的重要技术，可以用于室内导航、物体定位、多人协作等场景。本文基于 Unity XR 训练营资料，详细讲解如何在 Meta Quest 设备上实现二维码识别与追踪功能。

摄像头 API 基础

前置要求

要求	说明
Quest 系统版本	v74 及以上（推荐 v81+）
设备	Quest 3 或 Quest 3s
分辨率	最大 1280x1280（v83+）
图像延迟	40-60 ms

注意：从 v76 开始，使用摄像头 API 的应用已支持上架 Quest 商店。

限制：

目前不适合处理移动对象
不适合识别小的或远的图像和文本
SDK 目前无法在串流模式下生效，需要打包到头显测试

官方样例工程

PassthroughCameraApiSamples

CameraViewer：将摄像头画面渲染到 RawImage
CameraToWorld：相机坐标转世界坐标
BrightnessEstimation：环境亮度估计
MultiObjectDetection：AI 语义物体识别（Unity Sentis）
ShaderSample：虚拟水面倒影特效

Quest Vision Kit

Color Picker：吸取现实颜色转虚拟画笔
Object Detection：AI 语义识别
QR Code Tracking：二维码识别追踪（ZXing）
Shader Samples：毛玻璃特效
OpenAI Vision：基于 GPT 的视觉助手
WebRTC Streaming：网络串流摄像头画面

核心脚本：PassthroughCameraAccess

Meta XR SDK V81+ 将摄像头 API 集成到了 MRUK 开发包中，使用统一的 PassthroughCameraAccess 脚本。

配置步骤

步骤一：添加脚本

通过 Building Block 快速添加：

菜单栏 Meta > Tools > Building Blocks
点击 Passthrough 标签
拖入 Passthrough Camera Access 模块

会自动添加：

[BuildingBlock] Passthrough Camera Access — 核心脚本
[BuildingBlock] Passthrough Camera Visualizer — 摄像画面渲染 Quad

步骤二：添加透视模块（可选）

透视场景下使用摄像头 API 是常见场景，但纯 VR 场景也可以使用，根据项目需求决定是否添加。

步骤三：环境修复

Meta XR Tools > Project Setup Tool：

在安卓端和 PC 端点击 Fix All 和 Apply All
主要消除红色警告

步骤四：检查 OVRManager

在玩家物体（Camera Rig）的 OVRManager 脚本中，确保 Enable Passthrough Camera Access 已勾选。

步骤五：请求摄像头权限

重要：第一次打开程序会弹出权限请求，用户必须点击允许。

方法一：勾选权限自动请求

在 OVRManager 的 Permission Request On Startup 下勾选：

Passthrough Camera Access — 摄像头访问权限
Scene — 空间数据权限（二维码定位需要）

注意：如果点击拒绝，后续不会再次弹窗且无法获取画面。

方法二：代码调用

using UnityEngine;
using Meta.XR.MRUK;

public class RequestCameraPermissions : MonoBehaviour
{
    private void Awake()
    {
        OVRPermissionsRequester.Request(new[]
        {
            OVRPermissionsRequester.Permission.Scene,
            OVRPermissionsRequester.Permission.PassthroughCameraAccess
        });
    }
}

步骤六：检查 AndroidManifest

确保 Assets/Plugins/Android/AndroidManifest.xml 中包含：

<uses-permission android:name="com.oculus.permission.HEADSET_CAMERA" />

如没有，运行 Meta > Tools > Update AndroidManifest.xml 自动更新。

二维码识别样例

官方工程

Quest Vision Kit：https://github.com/xrdevrob/QuestCameraKit

配置步骤

1. 下载工程并打开

克隆或下载 GitHub 工程，用 Unity 打开。

2. 解决报错

首次打开可能报错，选择 Ignore 忽略。

3. 下载 ZXing 插件

下载：https://github.com/micjahn/ZXing.Net/releases/tag/v0.16.10.0
解压后找到 unity/zxing.unity.dll
复制到 Assets/Plugins/ 文件夹

4. 配置 ZXingDefineSymbolChecker

打开脚本，修改 HasZXingDLL 方法：

private static bool HasZXingDLL()
{
    var files = Directory.GetFiles(Application.dataPath, "*ZXing.dll", SearchOption.AllDirectories)
                         .Concat(Directory.GetFiles(Application.dataPath, "*zxing.dll", SearchOption.AllDirectories))
                         .Concat(Directory.GetFiles(Application.dataPath, "*zxing.unity.dll", SearchOption.AllDirectories));
    Debug.Log($"Has ZxingDLL:{files.Any()}");
    return files.Any();
}

保存后等待编译完成，自动生成 ZXING_ENABLED 符号。

如未自动生成，手动在 Edit > Project Settings > Player > Other Settings > Scripting Define Symbols 中添加。

5. 配置权限

在 OVRManager 的 Permission Requests On Startup 下勾选 Passthrough Camera Access。

6. 打包测试

确保头显系统版本为 v81+，打包测试。

移植到自己的项目

Unity 6 之前的版本

XR Plug-in Management 安卓端勾选 Oculus

Unity 6 及以上

XR Plug-in Management 安卓端勾选 OpenXR
导入包：com.unity.xr.meta-openxr

移植文件

zxing.unity.dll → Assets/Plugins/
Assets/Samples/QRCodeTracking → 自己的项目
Assets/Samples/Common → 自己的项目

检查项

[ ] ZXING_ENABLED 符号已配置
[ ] OVRManager 的 Passthrough Camera Access 已勾选

二维码稳定识别框架

样例工程的缺陷：识别位置稳定，但旋转角度不稳定。

解决思路：多次采样位姿数据，进行平均滤波。

框架集成包

核心物体：

物体	说明
QrCodeStasticDisplayManager	稳定识别核心算法
CustomQRCodeMarkerSpawner	指定二维码和生成的物体
ResetStableController	处理重定位后重新扫码

次要物体（空间锚点相关）：

脚本	说明
QRCodeTrackEvent	提供事件，OnImageStabilized 为稳定后调用
CustomQRCodeMarkerControllerBase	继承并重写 ShowObjByGivenPose

实际项目需求

指定二维码识别：只识别特定二维码
多二维码分组：场地内多个二维码，同组只识别一个
重定位恢复：重定位后重新扫码恢复定位
空间锚点保存：借助空间锚点固定虚拟场景
关闭扫码节省性能：识别成功后关闭扫码功能

二维码坐标轴朝向

MR 大空间扫码通常是：

竖直码：贴在墙上，Z 轴垂直于二维码平面
水平码：贴在桌上，Y 轴朝上

配置规则：

竖直码：虚拟场景 Z 轴与二维码法线朝向一致
水平码：虚拟场景 Z 轴与二维码 Y 轴一致

常见问题

权限弹窗没出现

检查 OVRManager 的 Permission Request On Startup 是否勾选
使用代码手动请求权限
在头显 设置 > 隐私与安全 > 应用权限 > 头戴设备摄像头 手动开启

摄像头画面显示白色

检查 AndroidManifest 是否有摄像头权限
运行 Project Setup Tool 的 Fix All
检查 OVRManager 的 Enable Passthrough Camera Access 是否勾选

二维码识别不稳定

使用稳定识别框架，进行多次采样滤波。

空间锚点保存失败

需要设备账号开启双重身份认证
手机 APP 需要开启开发者模式
代激活/租的设备可能无法使用空间锚点

总结

二维码识别 MR 开发流程：

环境配置：安装 MRUK → 配置 PassthroughCameraAccess → 请求权限
集成 ZXing：下载插件 → 配置符号 → 打包测试
稳定识别：使用滤波框架 → 处理重定位 → 空间锚点辅助
性能优化：识别成功后关闭扫码

核心建议：从官方样例工程开始学习，逐步移植到自己的项目。二维码识别涉及坐标转换、位姿滤波等多个环节，需要多调试理解原理。

参考资源

本文整理自 Unity XR 训练营学习资料，结合 Meta 官方样例与稳定识别框架实战经验。

Unity MR大空间部署与同步系统开发指南

Sun, 01 Feb 2026 20:00:00 GMT

前言

MR 大空间部署是 XR 开发中的高级课题，需要解决空间对齐、角色对齐、跨设备同步等问题。本文基于 Unity XR 训练营资料，详细讲解 MR 大空间部署的核心技术与 Quest-PC 同步系统。

空间对齐基础

什么是空间对齐？

空间对齐：让所有人看到的虚拟世界在现实中的同一个位置。

为什么需要空间对齐？

假设同一个现实空间有两个玩家，如果不对齐坐标系：

玩家 A 在自己的 (0, 0, 1) 发射子弹
同步到玩家 B 的世界后，子弹位置会跑偏
导致 A 和 B 看到的虚拟物体在实际位置上对不上

核心思想

先在现实世界建立"统一的空间坐标系"，再在这个坐标系里做联机同步。

场景结构

现实世界（二维码）
   ↓
Root（所有虚拟世界的根节点）
   ├── RootHead
   ├── RootLeftHand
   ├── RootRightHand
   ├── NetworkPlayerRoot（网络玩家的父物体）
   └── 所有虚拟物体

第一步：空间对齐

原理

不管戴上头显时的初始站位在哪，识别到二维码后都会将 Root 重置到二维码的位置和朝向。

相当于把虚拟世界转换到了一个以二维码为原点的"现实坐标系"下。

效果

所有人扫同个二维码，就会把所有人的 Root 对齐到固定不动的现实坐标系
因为虚拟世界会作为 Root 的子物体，所以每个人眼中的虚拟世界在现实当中位于同个位置

可替代方案

二维码可以替换为其他能被头显追踪到的固定物体：

空间锚点
Marker
任何能被头显获取到坐标的物体

第二步：角色对齐

目的

对齐网络空间。让每个玩家的网络虚拟化身对齐到现实的身体上。

表面上

虚拟头和现实头进行对齐
虚拟手和现实手进行对齐

实际上

对齐网络空间，确保多人联机时每个玩家看到的位置一致。

LocalInput（本地输入映射）

负责把头显的真实追踪数据映射到 Root 坐标系下。

二维码对齐的是 Root
头和手只是往这个 Root 里填数据

NetworkPlayer（网络玩家物体）

让所有网络玩家物体生活在同一个 Root 空间中：

设置为 Root 子物体
代码中在 Root 下新建 NetworkPlayerRoot
把网络玩家物体的原点重置到 Root 空间的原点（与二维码原点一致）
之后网络玩家物体的坐标就是相对于 Root 的

注意：Netcode 中想把一个网络物体作为另一个物体的子物体，另一个物体也必须是网络物体（有 NetworkObject），且需要先通过网络加载出来才能作为其他网络物体的父物体。

同步原理

因为之前记录过现实头显位置的 RootHead 等物体也作为了 Root 的子物体，和重置过的网络玩家在同一个空间下，所以直接通过相对于 Root 的本地坐标来将网络玩家物体匹配到现实中的玩家身体上。

开发注意事项

写代码前考虑两点

这件事是不是由服务端说了算？
这段代码是不是我这个客户端能控制的？

Quest-PC 物体同步系统

问题背景

识别二维码成功后，需要在头显里调整虚拟物体的位置让虚拟物体和现实空间产生匹配。但是：

这个调整后的位置没法同步到 Unity 编辑器里
只有 Unity 编辑器的位置调整过了，下次打包扫码得到的位置才是正确的

传统方式

头显端调完后不要关闭程序，手动记录 Immersive Debugger 调试窗口的 Inspector 面板记录的调整后模型的 localPosition、localRotation、localScale，再手动在 Unity 编辑器里一个个修改。

同步系统方案

通过网络进行同步：

电脑编辑器（Server）
        ↓ 连接
头显（Client）
        ↓
把头显中修改的物体 Transform 数据传回电脑
        ↓
数据保存在本地
        ↓
退出运行后，把数据应用回编辑器中的物体

系统使用

样例场景配置

"Quest PC调试同步系统" 物体为核心物体：

运行设备	Quest 物体	PC 物体
头显	激活	隐藏
电脑编辑器	隐藏	激活

Unity 编辑器拓展面板

Windows > Tools > Quest 同步变换工具

在服务器配置处引用场景中的 PC 物体
运行 Unity 编辑器启动同步服务
手动指定根物体会自动引用 PC 物体上引用的根物体
连接成功后 Quest 和头显都会显示已连接的相关信息

同步流程

头显端：调好位置后，在面板上点击"手动保存当前变换"
将调整的数据（根物体所有嵌套子物体的 Transform）保存到本地
退出运行模式
点击"加载变换数据"，把之前同步的数据加载到根物体的所有嵌套子物体上

提示：加载变换后记得"停止同步服务"。

二维码空间定位系统

核心组件

组件	说明
Root	虚拟世界根节点，与二维码位置对齐
LocalInput	本地输入映射到 Root 坐标系
NetworkPlayerRoot	网络玩家父物体
QRCodeStasticDisplayManager	稳定二维码识别

同步流程

二维码识别成功
   ↓
Root 位置和朝向与二维码一致
   ↓
LocalInput 将头显追踪数据映射到 Root 坐标系
   ↓
NetworkPlayer 同步到所有客户端
   ↓
所有玩家看到相同的虚拟世界

常见问题

二维码识别不稳定

使用稳定识别框架，进行多次采样滤波。

网络物体无法作为子物体

确保父物体有 NetworkObject 组件，且先通过网络加载完成。

位置同步有偏差

检查 LocalInput 的映射是否正确，确保所有物体都在 Root 坐标系下。

同步数据丢失

确保保存后不要提前退出运行模式，按顺序操作：保存 → 退出运行 → 加载数据。

总结

MR 大空间部署核心要点：

步骤	内容
空间对齐	扫二维码将 Root 对齐到现实坐标系
角色对齐	LocalInput 映射 + NetworkPlayer 在同一 Root 空间
同步系统	Quest-PC 网络同步变换数据

核心原则：先建立统一现实坐标系，再做联机同步。所有物体都在 Root 坐标系下工作。

参考资源

本文整理自 Unity XR 训练营学习资料，结合大空间部署与同步系统实战经验。

Unity Netcode for GameObjects 多人联机开发基础

Sun, 25 Jan 2026 20:00:00 GMT

前言

多人联机是 XR 开发中的重要方向，可以让多个用户在同一个 MR 空间中协作。本文基于 Unity XR 训练营资料，系统讲解 Unity 多人联机开发的核心概念与 Netcode for GameObjects 的使用方法。

核心概念：空间对齐与权威

空间对齐

为什么需要对齐？

假设同一个现实空间有两个玩家，玩家在 Unity 中的初始坐标都是 (0, 0, 0)。但玩家戴上头显时，头显在现实中的初始位置和朝向决定了玩家的 Unity 原点位置和朝向。

问题	后果
玩家 A 在自己的 (0, 0, 1) 发射子弹	如果同步到玩家 B 的世界，B 看到的子弹在实际位置上对不上
需要统一的坐标系	才能保证 A 和 B 看到的东西在现实中一致

权威（Authority）

概念	说明
权威	谁拥有最终决定权
服务端	就是权威，最终由它说了算
权威同步	同步权威判定后的结果

Client、Server、Host 区别

角色	说明
Client（客户端）	玩家本人，作为当事人操作
Server（服务端）	规则本身，作为裁判判定结果
Host	Server + Client 在同一台设备，一边当玩家一边当裁判

Host 写逻辑需要区分 Server/Client

权威规则示例

错误做法：

Client 自己改血量、位置、状态 ✗
Client 自己判定命中 ✗

正确流程：

Client（玩家）发射子弹
↓
Server 判断子弹有没有命中
↓
得出结果：命中/未命中
↓
把结果同步给所有人

子弹生成流程：

Client 扣下扳机
↓
Client 向 Server 申请开枪
↓
Server 验证：冷却时间？弹药？状态？
↓
Server 实例化子弹物体
↓
Server 把子弹同步给 Client

核心原则：写代码前想好这段代码是在当玩家，还是当裁判。凡是能够影响别人结果的，都是由 Server 进行生成和判定。

联机框架选择

框架	费用	特点
Unity Netcode for Gameobjects（NGO）	免费	Unity 官方维护，学习资料多，可自建服务器或使用云服务器
Mirror	免费，开源	写法与 NGO 相似，教程少，只能自建服务器
Photon	商业	免费版最大 20 人同时在线，只能用官方云服务

Netcode for GameObjects 安装配置

安装

在 Unity Package Manager 的 Unity Registry 搜索 Netcode for Gameobjects，进行安装。

基础配置

在场景中新增一个空物体（如 Network Manager）
在物体上添加 NetworkManager 脚本
一个场景只能有一个 NetworkManager 脚本
在 NetworkManager 的 Network Transport 处选择 Unity Transport 作为网络传输层

多实例调试工具 ParrelSync

下载：https://github.com/VeriorPies/ParrelSync

下载 unitypackage 并导入 Unity
点击菜单栏 ParrelSync > Clone Manager 克隆 Unity 工程
Open In New Editor 打开
可在多个相同工程里模拟不同客户端/服务端
主工程修改后克隆的工程会同步修改

常用组件

NetworkManager

整个联机世界的开关，负责：

启动 Server / Client / Host
管理玩家连接
管理 Player Prefab
管理网络生命周期

Player Prefab

每个客户端玩家在联机世界中代表自己的游戏对象，相当于自己在联机世界的化身。

在 NetworkManager 组件的 Player Prefab 字段中进行指定。

NetworkObject

联机世界的身份证，允许物体进入联机世界。

NetworkBehaviour

类	说明
MonoBehaviour	单机逻辑
NetworkBehaviour	联机逻辑

继承自 NetworkBehaviour 的脚本能够处理联机逻辑。

NetworkVariable

特点

特点	说明
用途	用于同步状态，无法同步行为
可同步	血量、子弹数量、是否死亡
不可同步	开枪动作、播放动画

工作机制

自动同步：值改变后，NGO 自动处理网络通信（只有值变化后才同步，不是每帧同步）
状态同步：中途加入的客户端会自动同步服务器的当前状态
变更回调：提供 OnValueChanged 事件，可在值改变时执行自定义逻辑

代码写法

// 权威规则
// Server 写（只能服务端修改数值，修改后所有客户端会自动同步）
// Client 读

public class HealthSystem : NetworkBehaviour
{
    public NetworkVariable<int> health = new NetworkVariable<int>(100);

    // Server 端修改
    public void TakeDamage(int damage)
    {
        health.Value -= damage; // 只有 Server 有权限
    }
}

常见错误

错误一：Client 直接改 NetworkVariable

// ❌ 错误：客户端自己执行
health.Value -= 100;

// 后果：客户端没有权利判定结果

错误二：用 NetworkVariable 同步瞬时事件

// ❌ 错误：开枪是瞬时事件，不是长期状态
isShooting.Value = true;

// 后果：玩家一直维持开枪状态

错误三：每帧修改 NetworkVariable

// ❌ 错误：Update 里不断改血量
void Update()
{
    health.Value = currentHealth;
}

// 后果：性能消耗大

XR 输入同步例外：XR 中需要实时同步头显、手柄输入到远端 Player，这是输入流需要持续更新。

IsOwner 含义

我有没有资格发请求。当前生成的 Player 是不是由我这个客户端控制的。

例如：客户端 A 先加入，然后客户端 B 加入。A 的世界里生成了代表 B 的 Player，但 A 客户端的这个 B 不归 A 管，所以不会触发 Move。而 B 世界里生成的 B 归自己管，所以一生成就调用 Move。

IsOwner 和 IsLocalPlayer 区别

参数	说明
IsOwner	当前客户端是否拥有这个 NetworkObject
IsLocalPlayer	是否是本地玩家

RPC（Remote Procedure Call）

RPC 是联机世界的对话方式，一般用于瞬时的动作或事件（玩家开枪、播放音效、触发爆炸）。

ServerRPC（Client → Server）

客户端向服务端发起请求，执行的代码在服务端执行。

[ServerRpc]
void ShootServerRpc()
{
    // 执行在服务端
    Debug.Log("Server 处理开枪逻辑");
}

ClientRPC（Server → Client）

服务端向客户端发起通知。

[ClientRpc]
void ExplodeClientRpc()
{
    // 执行在所有客户端
    PlayExplosionEffect();
}

官方新手入门样例

HelloWorldPlayer 与 HelloWorldManager

执行流程：

Client 按按钮
↓
ServerRpc
↓
Server 决定位置
↓
NetworkVariable 同步结果
↓
所有 Client 更新显示

总结

概念	核心要点
空间对齐	MR 多人联机需要统一坐标系
权威	Server 说了算，Client 只负责申请和显示
NetworkVariable	同步状态，Server 写 Client 读
RPC	瞬时动作/事件，ServerRpc/ClientRPC

核心原则：写代码前想好是在当玩家还是当裁判。影响别人结果的逻辑，必须由 Server 执行。

参考资源

本文整理自 Unity XR 训练营学习资料。

Unity MR透视与传送门开发指南

Thu, 15 Jan 2026 20:00:00 GMT

前言

MR（混合现实）透视技术让虚拟物体与现实环境融为一体，是当前 XR 开发的热点方向。本文基于 Unity XR 训练营资料，详细讲解 MR 透视开发的核心技术，包括基础配置、深度测试原理、以及 MR 传送门的实现方案。

透视基础配置

1. 添加 Passthrough 模块

在 Building Blocks 中找到 Passthrough 模块，拖到场景中。

2. 配置 Camera Rig

在玩家物体（CameraRig）上的 OVRManager 脚本中进行配置。

3. 配置相机背景

在玩家物体的相机（CenterEyeAnchor）中：

Camera 组件的 Background Type 设为 Solid Color
Background 颜色 RGB 设为 0，透明度（A）设为 0

4. 关闭 MR 安全边界

方法一：在 AndroidManifest 中配置

在 Assets/Plugins/Android/AndroidManifest.xml 中添加：

<uses-feature android:name="com.oculus.feature.BOUNDARYLESS_APP" android:required="true"/>

方法二：彻底关闭 Quest 安全边界

在头显中：设置 > 开发者 > 实际空间功能

注意：关闭后头显录屏里的现实环境是黑的。

透视材质

创建透视材质

新建一个 Material 材质
Shader 参数设为 Oculus/SelectivePassthrough

Render Queue 规则

透视材质的 Render Queue 一般需要 大于 2000。

规则	说明
Unity 不透明物体默认 Render Queue	2000
透视物体在后方时	需要先渲染不透明物体，再渲染透视物体
Render Queue 越大	越后渲染

天空盒设置

打开 Window > Rendering > Lighting，将 Environment 下的 skybox material 设为 None。

这样才能看到正确的透视物体和不透明物体的前后遮挡关系。

深度与渲染队列基础

深度（Depth）

深度 = 物体离摄像机的远近，决定谁在前、谁在后，是实现正确遮挡关系的基础。

深度测试（Depth Test）

"谁近谁赢"的淘汰规则：

当一个像素想被画到屏幕上时
它将自己的深度值与深度缓冲区中当前存储的值进行比较
如果它"更近"，通过测试，颜色显示并更新深度缓冲区
如果它"更远"，被淘汰，颜色不绘制

Render Queue

Render Queue = 渲染队列，决定物体渲染顺序。值越大，越后渲染。

MR 传送门：方法一 Depth Only Shader

核心原理

Shader 类型	作用
Depth Only Shader	只写入深度，不渲染颜色
透视材质	显示现实环境

渲染流程示例：MR 虚拟门窗

假设深度缓冲区比较规则是"小等于"：

第一步：虚拟场景先渲染，往深度缓冲区写入深度信息

第二步：渲染门

门材质为 Depth Only Shader
门深度 < 虚拟场景（门在虚拟场景前面）
通过深度测试，深度缓冲区更新为门的深度值
门本身不渲染颜色，所以重叠区域仍显示虚拟场景

第三步：渲染墙（透视材质）

墙深度 > 门（墙在门后面）
未通过深度测试，墙与门重叠部分不显示
墙深度 < 虚拟场景（墙在虚拟场景前面）
通过深度测试，墙与虚拟场景重叠部分渲染出墙的颜色

注意事项

重要：需要用透视材质物体把人从 6 个面包裹起来，挡住外侧的虚拟场景。

如果是室内空间：

让透视材质物体与现实中的墙壁、天花板、地面贴合
相当于造一个和现实空间结构一样的虚拟室内空间

MR 传送门：方法二模板测试（Stencil Test）

模板缓冲区（Stencil Buffer）

模板缓冲区可以为屏幕上的每一个像素点保存一个值。

模板测试流程

在渲染过程中，用模板缓冲区中保存的值与预设的参考值（Reference Value） 作比较
根据比较结果决定是否更新相应像素点的颜色值

比较规则示例

设置参考值为 1，只保留值为 1 的部分：

条件	结果
模板缓冲区值 = 参考值	通过测试，显示颜色
否则	不显示

Unity 中实现步骤

第一步：添加 Stencil Shader

给传送门区域添加 Stencil Shader，作用：

不显示颜色
不参与深度测试
只在模板缓冲区中把值设为设定的 ID（如 1）

应用此材质的物体在屏幕上显示区域的模板缓冲区值就被设为了 1。

第二步：设置虚拟世界 Layer

随便取一个 Layer 名字，方便辨识即可（如 StencilMask1）。

第三步：配置 URP 过滤器

找到项目中使用的 URP 配置文件（Universal Renderer Data）：

在 Filtering > Layer Mask 中，取消勾选刚才为虚拟世界设置的 Layer
这样场景中就看不到虚拟世界了

第四步：添加 Renderer Feature

在 URP 配置文件中添加 Renderer Feature：

点击 Add Renderer Feature
选择 Render Objects

配置参数：

参数	值	说明
Layer Mask	虚拟世界的 Layer	控制哪些物体
Stencil Value	与 Stencil Shader 一致（如 1）	参考值
Compare Function	Equal	只渲染Stencil值为1的部分
其他值	Keep	保持原值

核心原理

在 Layer 为 StencilMask1 的物体中，只渲染 Stencil 值为 1 的部分。

什么部分 Stencil 值为 1？ = 传送门区域与虚拟世界在屏幕上重合的部分

因为传送门区域的材质为 Stencil Shader，限定了该显示区域的 Stencil 值为 1。

两种方法对比

方法	优点	缺点
Depth Only Shader	简单直接	需要物体把人 6 面包裹
Stencil Test	灵活，可做任意形状	配置较复杂

常见问题

透视物体不透明

检查 Render Queue 是否 > 2000
检查天空盒是否已关闭（设为 None）
检查 Camera 的 Background Type 是否为 Solid Color

安全边界弹窗

在 AndroidManifest 中添加 BOUNDARYLESS_APP 配置
或在头显设置中彻底关闭

深度测试不工作

检查 Camera 的 Depth Texture 是否开启
检查各物体的 Render Queue 设置
确保渲染顺序正确（先不透明物体，再透视物体）

总结

MR 透视开发要点：

基础配置：Building Blocks Passthrough → OVRManager → 相机背景 → 关闭安全边界
透视材质：Oculus/SelectivePassthrough，Render Queue > 2000
Depth Only Shader：只写深度不写颜色，实现虚拟物体与现实环境遮挡
Stencil Test：更灵活，可以实现任意形状的传送门效果

选择建议：

简单场景用 Depth Only Shader
复杂形状（如圆形、异形传送门）用 Stencil Test

参考资源

本文整理自 Unity XR 训练营学习资料，结合 MR 透视与传送门开发实战经验。

Unity物理碰撞系统完全指南

Fri, 09 Jan 2026 20:00:00 GMT

前言

物理碰撞是 Unity 游戏开发中的核心系统之一，正确理解和使用物理碰撞能让游戏交互更加真实自然。本文基于 Unity XR 训练营资料，系统讲解 Unity 物理碰撞系统的核心概念与实际应用。

核心概念：刚体与碰撞体

刚体（Rigidbody）

让游戏对象受物理引擎驱动，模拟质量、重力、受力运动。

碰撞体（Collider）

定义游戏物体的物理形状和边界，用于碰撞检测，是几何上的碰撞体积。

协同工作

组件	作用
刚体	提供动力
碰撞体	提供可碰撞的形体

两者协同工作：刚体提供物理驱动力，碰撞体提供可碰撞的形状。

刚体重要属性

1. 质量（Mass）

决定物体的惯性。质量越大的物体：

越难被推动
碰撞时产生的动量越大

注意：应根据物体大小合理设置质量比例，避免失衡。

2. 阻力与角阻力（Drag / Angular Drag）

属性	作用
Drag	影响物体直线移动时的阻力
Angular Drag	影响物体旋转时的阻力

数值越大，物体运动衰减越快。

3. 使用重力（Use Gravity）

勾选后，对象会受到持续向下的重力影响。

4. 是否运动学（Is Kinematic）

关键属性

启用后：

刚体不再受物理力（重力、碰撞力）的影响
只能通过直接设置 Transform（位置、旋转）来移动

适用场景：

移动平台
开关门
由动画或脚本精确控制的物体

5. 碰撞检测模式（Collision Detection）

模式	说明	性能
Discrete（离散）	默认模式，可能导致高速物体"穿模"	低
Continuous（连续）	适合高速物体	中
Continuous Dynamic	动态物体使用连续检测	高

建议：对于高速移动的物体（如子弹），使用 Continuous 或 Continuous Dynamic 以确保碰撞准确。

6. 约束（Constraints）

可以"冻结"对象在特定方向上的移动或旋转。

示例：2D 游戏角色

冻结 Z 轴移动（防止前后移动）
冻结 X、Y 轴旋转（防止倾斜）

碰撞体重要属性

Is Trigger

勾选后碰撞体成为触发器：

不再具有物理阻挡作用
其他物体可以穿过它
会触发特定事件

事件函数：

OnTriggerEnter — 进入触发器时
OnTriggerStay — 停留在触发器时
OnTriggerExit — 离开触发器时

适用场景：

收集物品
检测玩家进入特定区域（检查点、陷阱）
触发区域事件

Mesh Collider（网格碰撞体）

工作原理

Mesh Collider 根据模型的网格信息生成对应形状的碰撞体：

Mesh 参数引用的是模型的网格
与 Mesh Filter 中的 Mesh 参数相同
模型网格由许多三角面组成
Mesh Collider 给每个三角面添加碰撞体

特点

优点	缺点
碰撞体更精确表示模型形状	性能消耗增大

Convex 参数

如果带有 Mesh Collider 的物体身上有刚体，需要勾选 Convex 参数才能让刚体拥有物理效果。

Convex = 凸体：

会填充模型网格凹进去的部分
最多支持 255 个三角面
模型面数太大不适合用 Mesh Collider

碰撞发生的条件

碰撞 vs 触发器

类型	效果	应用
碰撞（Collision）	产生阻挡，可传递力	物理碰撞、弹跳、阻挡
触发器（Trigger）	无阻挡，触发事件	收集物品、区域检测

碰撞的条件

两个物体都要有 Collider
至少一个物体有 Rigidbody
物体间有相对运动（或其中一个受重力影响）

触发器的条件

条件	说明
两个物体都有 Collider	碰撞体存在
至少一个物体有 Rigidbody	提供物理引擎驱动
至少一个 Collider 勾选 Is Trigger	触发器模式

代码示例

碰撞检测

public class CollisionExample : MonoBehaviour
{
    void OnCollisionEnter(Collision collision)
    {
        Debug.Log($"碰撞到: {collision.gameObject.name}");
    }

    void OnCollisionStay(Collision collision)
    {
        Debug.Log($"持续碰撞中: {collision.gameObject.name}");
    }

    void OnCollisionExit(Collision collision)
    {
        Debug.Log($"碰撞结束: {collision.gameObject.name}");
    }
}

触发器检测

public class TriggerExample : MonoBehaviour
{
    void OnTriggerEnter(Collider other)
    {
        Debug.Log($"触发器进入: {other.gameObject.name}");
    }

    void OnTriggerStay(Collider other)
    {
        Debug.Log($"触发器停留中: {other.gameObject.name}");
    }

    void OnTriggerExit(Collider other)
    {
        Debug.Log($"触发器离开: {other.gameObject.name}");
    }
}

XR 开发中的物理碰撞

Quest 中的注意事项

碰撞检测模式：XR 交互物体多为中低速，Discrete 足够
Mesh Collider 慎用：MR 场景复杂，Mesh Collider 性能开销大
使用 Compound Collider：多个简单碰撞体组合代替复杂网格碰撞体
关闭不必要的物理：静态物体不启用刚体

XR 交互建议

交互类型	碰撞体建议
抓取物体	使用 Capsule Collider 或 Box Collider
手柄射线检测	使用 Raycast 或 Sphere Collider
区域触发	使用 Trigger Collider

常见问题

物体穿模

使用 Continuous 碰撞检测
或降低物体移动速度
增加碰撞体大小

碰撞不触发

检查两个物体是否都有 Collider
检查至少一个物体是否有 Rigidbody
确保不是两个都是 Kinematic

Trigger 不触发

检查 Collider 是否勾选 Is Trigger
确保至少一个物体有 Rigidbody

Mesh Collider 不生效

如果有 Rigidbody，必须勾选 Convex
检查模型面数是否超过 255

总结

概念	要点
刚体	提供物理驱动力，控制重力、受力运动
碰撞体	定义碰撞形状，决定碰撞检测范围
Is Kinematic	运动学刚体不受物理力影响
Is Trigger	触发器模式，触发事件但不阻挡
Mesh Collider	精确但性能开销大，注意 Convex 限制
碰撞检测模式	高速物体用 Continuous

核心原则：刚体提供动力，碰撞体提供形状。合理搭配使用，平衡性能与真实性。

参考资源

本文整理自 Unity XR 训练营学习资料。

Unity XR开发实战指南

Thu, 08 Jan 2026 20:00:00 GMT

前言

XR（VR/AR/MR）开发正在快速发展，Meta Quest、PICO、Apple Vision Pro 等设备引领着空间计算时代的到来。本文基于 Unity XR 训练营资料，系统讲解 Unity XR 开发的核心流程与实战技巧。

开发环境搭建

1. 创建 URP 工程

首先在 Unity Hub 中创建一个使用 URP（Universal Render Pipeline） 的工程。URP 是 Meta 推荐使用的渲染管线，提供更好的性能表现。

2. 切换安卓平台

菜单栏 File > Build Profile，点击 Android，点击 Switch Platform。

为什么需要切换平台？Quest 和 PICO 头显都是基于安卓系统，想要把程序打包发布到这些设备上运行，必须打包出能在安卓系统运行的 APK 文件。

3. 配置 XR Plugin Management

打开 Edit > Project Settings > XR Plugin Management
点击 Install XR Plugin Management
在安卓端和 PC 端都勾选 OpenXR

4. 导入 Meta XR SDK

打开 Window > Package Management > Package Manager
在 Unity Asset Store 添加以下三个 SDK：
- Meta XR Core SDK — 核心功能
- Meta XR Interaction SDK — 交互系统
- Meta MR Utility Kit — MR 工具包

提示：安装可能需要科学上网，如果失败请尝试重新安装。

5. 环境修复

找到 Meta XR Tools > Project Setup Tool
在安卓端和 PC 端都点击 Fix All 和 Apply All
重点消除 Fix All 下的红色警告（未消除会导致程序无法运行）
点击 XR Plug-in Management > Project Validation，在安卓端和 PC 端点击 Fix All

6. 最终检查

检查项	说明
OpenXR 安卓端 Render Mode	设为 Single Pass Instanced 或 Multi-view（性能更好）
Enable Interaction Profiles	应有 Oculus Touch Controller Profile
OpenXR Feature Groups	勾选 Meta XR

交互系统开发

玩家物体

Meta 提供了功能齐全的玩家物体（Building Block），可以快速搭建基础交互功能。

抓取交互

近距离抓取

在需要添加抓取交互的物体上鼠标右键
选择 Interaction SDK > Add Grab Interaction
点击 Fix All 后再点击 Create
Unity 会自动添加抓取交互所需的脚本和组件

限制抓取物体的移动、旋转、双手缩放

在有 Grabbable 脚本的物体上添加 Grab Free Transformer 脚本：

// 配置步骤
1. 把 GrabFreeTransformer 添加到 Grabbable 的 One Grab Transformer 参数
2. 如果需要双手抓取，添加到 Two Grab Transformer 参数
3. 取消勾选 Grabbable 的 Transfer On Second Selection 参数

双手缩放

将 GrabFreeTransformer 脚本上 Scale Constraints 三个轴的 Constrain 取消勾选，双手就能自由缩放物体大小。

限制抓取范围

GrabFreeTransformer 脚本上的 Position/Rotation/Scale Constrains 分别控制位置、旋转和缩放的允许范围：

// 配置参数说明
Constrain：勾选后启用该轴的限制
Min / Max：限制的最小值和最大值
Constraints Are Relative：是否相对于本地坐标

Constraints Are Relative 示例（以缩放为例）：

假设物体原缩放为 (0.8, 0.8, 0.8)，X/Y/Z 缩放最小值 0.3，最大值 2：

模式	最小缩放	最大缩放
勾选 Relative	(0.24, 0.24, 0.24)	(1.6, 1.6, 1.6)
不勾选	(0.3, 0.3, 0.3)	(2, 2, 2)

录制抓取手势

Meta 提供了便捷的抓取手势录制工具。

录制步骤

第一步：准备工作

菜单栏点击 Meta > Interaction > Hand Grab Pose Recorder
引用有 Hand 脚本的右手物体
需要录制手势的物体需有 Rigidbody 刚体组件

第二步：运行录制

运行程序，做出抓取手势
在 Recorder 面板空白处双击
按空格键或点击 Record HandGrabPose 按钮开始录制

第三步：保存手势

点击 Save To Collection

第四步：加载手势

退出运行模式
点击 Load From Collection
保留一个有 HandGrabPose 子物体的 HandGrabInteractable，删除其他的

生成镜像手势

找到物体身上的 HandGrabInteractable 脚本，点击 Create Mirrored HandGrabInteractable 即可快速生成另一只手的镜像手势。

远距离抓取

添加远距离抓取

选中物体，鼠标右键 > Interaction SDK > Add Distance Grab Interaction

三种抓取类型

类型	说明	特点
Grab Relative To Hand	物体和手同步移动	像手和物体之间连成一条线
Pull Interactable To Hand	物体飞向手	最常用，一把物体抓到手上
Manipulate In Place	远距离操控物体	像有只无形的"幽灵手"直接抓住物体

推荐：Pull Interactable To Hand，用户体验最自然。

Time out Snap Zone

当选择 Pull Interactable To Hand 类型时：

在 Optional Components 下找到 Time out Snap Zone
点击 Fix 再点击 Create
增加功能：松开手后等待一定秒数，物体自动回到初始位置

控制返回时间：设置 Snap Interactor 中的 Time out 参数。

触碰物体交互

配置步骤

添加近距离抓取交互组件后，删除物体原先的 Grabbable 脚本
在 ISDK_HandGrabInteraction 子物体上添加 InteractableUnityEventWrapper 脚本
将 HandGrabInteractable 引用到 Interactable View 参数上

应用场景

可以配置 WhenHover 事件获取物体被手触碰的时机，用于：

触发高亮效果
播放音效
启动某些交互逻辑

性能优化要点

渲染批次优化

技术	适用场景
动态批次	大量小型相同材质物体
静态批次	不移动的物体
GPU Instancing	大量相同网格物体（树木、石头等）
SRP Batcher	URP/HDRP 管线优化

贴图优化

XR 一体机建议贴图 Max Size 设为 1024
启用 Mipmap 减少带宽浪费
使用压缩格式（ASTC/ETC2）

内存优化

定期调用 Resources.UnloadUnusedAssets()
使用 StringBuilder 拼接字符串
避免在 Update 中使用 LINQ
禁用正式版本的 Debug.Log

常见问题与解决

SDK 导入报错

如果导入 Meta XR Core SDK 报错：

Library\PackageCache\com.meta.xr.sdk.core@xxx\Editor\MetaXRSimulator\XRSimInstallationDetector.cs(87,29):

解决方案：打开 Package Manager，在 In Project 中找到 Unity Version Control，点击 Version History，选择带有 Recommended 的版本，点击 Update。

项目验证失败

如果 Project Validation 有红色警告：

使用 Project Setup Tool 的 Fix All 功能
检查 XR Plug-in Management 配置
确保所有平台（安卓/PC）都已正确配置

交互不工作

检查物体是否有正确的 Rigidbody 组件
确认 Layer 设置正确（需要包含在交互系统的 Layer 配置中）
查看 Frame Debugger 检查渲染事件

总结

Unity XR 开发主要流程：

环境搭建：创建 URP 项目 → 切换安卓平台 → 配置 XR Plugin → 导入 SDK → 环境修复
交互开发：添加玩家物体 → 配置抓取交互 → 录制手势 → 远距离抓取
性能优化：批次处理 → 贴图优化 → 内存管理

核心建议：使用 Meta 提供的 Building Block 快速原型开发，深入理解 Interaction SDK 的组件架构，遇到问题多查看官方文档和 Frame Debugger。

参考资源

本文整理自 Unity XR 训练营学习资料，结合 Meta XR SDK 与 Interaction SDK 实战经验。如有疑问欢迎交流！

Unity脚本生命周期函数详解

Wed, 07 Jan 2026 20:00:00 GMT

前言

Unity脚本是驱动游戏逻辑和行为的核心组件。理解脚本的核心概念和生命周期函数的执行顺序，是编写高效、可维护代码的基础。本文将从实际开发角度，详细讲解Unity脚本的关键知识点。

Unity脚本核心概念

1. 脚本基础：继承 MonoBehaviour

所有控制游戏对象（GameObject）行为的脚本都必须直接或间接继承自 MonoBehaviour 类。

using UnityEngine;

public class MyScript : MonoBehaviour
{
    // 脚本逻辑
}

提示：MonoBehaviour 是 Unity 脚本的基类，它提供了与引擎交互的接口。

2. 组件交互：GetComponent<T>

获取组件引用是与引擎交互的最主要方式。

public class ComponentExample : MonoBehaviour
{
    private Rigidbody rb;
    private Renderer meshRenderer;

    void Awake()
    {
        // 获取组件引用
        rb = GetComponent<Rigidbody>();
        meshRenderer = GetComponent<Renderer>();
    }
}

注意：GetComponent 会有一定开销，避免在 Update 中频繁调用。

3. 变量与 Inspector 面板

使用 public 或 [SerializeField] 属性将变量暴露给 Inspector：

public class InspectorExample : MonoBehaviour
{
    // 公开变量，直接在Inspector中显示和修改
    public float moveSpeed = 5f;
    public GameObject targetObject;

    // 私有变量但仍显示在Inspector
    [SerializeField] private float rotationSpeed = 90f;
    [SerializeField] private bool isActive = true;
}

生命周期函数详解

脚本生命周期定义了脚本从创建到销毁的整个过程中，各个函数被调用的顺序和规则。

执行顺序图

┌─────────────────────────────────────────────────────────────┐
│                      脚本实例创建                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Awake()         — 脚本实例被创建时立即调用（最早执行）      │
│                     即使脚本未启用也会调用，整个生命周期只执行一次│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  OnEnable()      — 每次脚本被启用时调用                      │
│                     （组件被勾选 或 所在对象被激活）            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Start()         — 首次启用后，Update之前调用               │
│                     只执行一次                                 │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────────┐
│  FixedUpdate()          │     │  Update()                   │
│  固定时间间隔调用        │     │  每帧调用，频率不固定         │
│  默认0.02秒             │     │                             │
│  用于物理计算            │     │  用于非物理逻辑：             │
│                         │     │  - 输入检测                  │
│                         │     │  - 角色状态                  │
│                         │     │  - 游戏逻辑                  │
└─────────────────────────┘     └─────────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  LateUpdate()      — 所有Update执行完毕后调用               │
│                      常用于摄像机跟随等需要后处理的逻辑          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  OnDisable()       — 脚本被禁用时调用                        │
│                      取消事件监听、停止协程、清理资源           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  OnDestroy()       — 脚本被销毁时调用（对象销毁或场景切换）   │
│                      进行最终的清理工作                        │
└─────────────────────────────────────────────────────────────┘

各生命周期函数详解

Awake()

void Awake()
{
    // 初始化变量、获取组件引用
    // 整个生命周期内只执行一次，执行顺序最早
    rb = GetComponent<Rigidbody>();
    health = maxHealth;
}

特性	说明
调用时机	脚本实例被创建时立即调用
是否需要启用	否，即使脚本禁用也会调用
执行次数	整个生命周期只执行一次
执行顺序	所有生命周期函数中最早

典型用途：初始化变量、获取组件引用。用于设置脚本运行所需的基础状态。

OnEnable()

void OnEnable()
{
    // 注册事件监听、启动协程
    GameEvents.OnEnemyKilled += HandleEnemyKilled;
    StartCoroutine(UpdateHealthBar());
}

典型用途：注册事件监听、启动脚本激活时需要立即执行的操作。

Start()

void Start()
{
    // 进行依赖于其他组件已初始化完成的逻辑
    // 或者游戏开始前的最终设置
    target = GameObject.FindWithTag("Player").transform;
    animator = GetComponent<Animator>();
}

特性	说明
调用时机	脚本首次启用后，在第一次 Update 之前
是否需要启用	是
执行次数	只执行一次

典型用途：进行依赖于其他组件已初始化完成的逻辑，或游戏开始前的最终设置。

Update()

void Update()
{
    // 处理非物理相关的实时游戏逻辑
    float horizontal = Input.GetAxis("Horizontal");
    float vertical = Input.GetAxis("Vertical");

    transform.Translate(horizontal * moveSpeed * Time.deltaTime, 0,
                        vertical * moveSpeed * Time.deltaTime);
}

特性	说明
调用时机	每一帧调用一次
调用频率	与设备性能和当前帧渲染量相关，不固定
适用场景	输入检测、角色状态、游戏逻辑

性能注意：Update 每一帧都会执行，避免在其中进行高开销操作，如 GetComponent、字符串拼接、内存分配。

FixedUpdate()

void FixedUpdate()
{
    // 执行与物理计算相关的操作
    // 固定时间间隔调用（默认0.02秒），不受渲染帧率影响
    rb.AddForce(physicsInput * thrustForce);
}

特性	说明
调用时机	固定时间间隔（默认 0.02 秒）
调用频率	固定，不受渲染帧率影响
适用场景	物理计算、刚体施力

为什么物理计算用 FixedUpdate：物理引擎需要稳定的时间步长，如果用 Update，帧率波动会导致物理模拟不稳定。

LateUpdate()

void LateUpdate()
{
    // 常用语摄像机跟随，确保在目标对象移动完成后再更新
    targetPosition = target.position + offset;
    transform.position = Vector3.SmoothDamp(transform.position,
                                           targetPosition,
                                           ref velocity,
                                           smoothTime);
}

典型用途：摄像机跟随、动画后处理等需要在所有 Update 执行完毕后再处理的逻辑。

OnDisable()

void OnDisable()
{
    // 取消事件监听、停止协程、清理资源
    GameEvents.OnEnemyKilled -= HandleEnemyKilled;
    StopAllCoroutines();
}

重要：防止脚本禁用后仍执行不必要的操作，造成难以排查的 bug。

OnDestroy()

void OnDestroy()
{
    // 进行最终的清理工作
    Debug.Log($"{gameObject.name} 已被销毁");
}

典型用途：保存数据、释放资源、记录日志。

实用代码模板

using UnityEngine;

public class LifecycleExample : MonoBehaviour
{
    // Inspector 面板可编辑
    public float moveSpeed = 5f;
    public float rotationSpeed = 90f;

    // 私有变量
    private Rigidbody rb;
    private Vector3 startPosition;

    void Awake()
    {
        // 最早执行，用于初始化
        rb = GetComponent<Rigidbody>();
        startPosition = transform.position;
        Debug.Log("Awake called");
    }

    void OnEnable()
    {
        // 每次启用时调用
        Debug.Log("OnEnable called");
    }

    void Start()
    {
        // 初始化依赖
        Debug.Log("Start called");
    }

    void FixedUpdate()
    {
        // 物理更新（固定频率）
        rb.AddForce(Vector3.forward * moveSpeed);
    }

    void Update()
    {
        // 游戏逻辑更新（每帧）
        float h = Input.GetAxis("Horizontal");
        float v = Input.GetAxis("Vertical");

        transform.Rotate(0, h * rotationSpeed * Time.deltaTime, 0);
    }

    void LateUpdate()
    {
        // 摄像机跟随等后处理
    }

    void OnDisable()
    {
        // 清理工作
        Debug.Log("OnDisable called");
    }

    void OnDestroy()
    {
        // 最终清理
        Debug.Log("OnDestroy called");
    }
}

常见问题与最佳实践

1. Awake vs Start

函数	特点
Awake	脚本实例创建时就调用，无需启用，用于基础初始化
Start	首次启用后才调用，用于需要其他组件已就绪的初始化

经验：基础初始化放 Awake，依赖其他组件的初始化放 Start。

2. Update vs FixedUpdate

函数	特点	适用场景
Update	每帧调用，频率不固定	输入检测、角色控制、游戏逻辑
FixedUpdate	固定间隔，频率固定	物理计算、刚体操作

3. 性能优化建议

public class BadExample : MonoBehaviour
{
    void Update()
    {
        // ❌ 每帧都GetComponent，开销大
        Rigidbody rb = GetComponent<Rigidbody>();
        rb.AddForce(Vector3.forward);
    }
}

public class GoodExample : MonoBehaviour
{
    private Rigidbody rb;

    void Awake()
    {
        // ✅ 缓存引用，只获取一次
        rb = GetComponent<Rigidbody>();
    }

    void Update()
    {
        // ✅ 使用缓存的引用
        rb.AddForce(Vector3.forward);
    }
}

总结

理解 Unity 脚本的生命周期函数是开发的基础：

Awake — 最先执行，用于基础初始化
OnEnable — 每次启用时调用
Start — 首次启用后执行，用于依赖初始化
FixedUpdate — 固定频率，用于物理计算
Update — 每帧调用，用于游戏逻辑
LateUpdate — 所有 Update 后调用，用于后处理
OnDisable — 禁用时清理资源
OnDestroy — 销毁时最终清理

核心理念：在合适的生命周期函数中做合适的事。基础初始化用 Awake，物理计算用 FixedUpdate，游戏逻辑用 Update，摄像机跟随用 LateUpdate。

参考资源

[Unity 官方文档：脚本生命周期](https://docs.unity3d.com/cn/current/Manual Execution Order.html)
MonoBehaviour 官方文档

如果你有任何问题，欢迎在评论区交流！