做UE项目的人基本都踩过同一个坑想在UI里显示当前关卡名跑去GetGameMode拿结果客户端崩了想在换关卡后保留玩家的金币数随手丢进 GameMode 的变量里一切关卡数据就蒸发了想同步血量给其他玩家看注释写了replicated结果只有服务器看得见。这些问题的根子都指向同一件事——没搞清楚 GameInstance、GameMode、GameState、PlayerState、PlayerController 这五个类各自活多久、住在哪、管什么。它们不是五个随便挑的角色而是一套职责边界相当清晰的分工体系理解它们的生命周期和存在范围比背一百个 API 都管用。这篇把我自己在项目里踩过的坑、验证过的写法、以及排查问题时最常用的思路整理出来适合刚接触 UE4 网络架构的同学也适合已经写了半年但总觉得状态管理玄学的开发者对照检查。1. 五个核心类到底各自管什么在 UE4 里这五个类经常被混着用因为它们在单机小项目里表现得很随和——乱放数据好像也能跑。但一旦你把项目改成多人联机或者加了关卡切换乱放的东西就开始出问题。想理清楚最好先别想代码先想一个现实场景一个网吧网吧本身、这局开黑的规则、门口的战绩公告栏、每个玩家的会员卡、每个玩家手里的键盘鼠标这五样东西恰好能对应上这五个类。1.1 GameInstance贯穿整个进程的常驻管家GameInstance 是我个人认为最容易被低估的一个类。它的生命周期从游戏进程启动开始一直到进程退出才结束中间不管切换多少次关卡、返回多少次主菜单它都只有一个实例而且不会被销毁。这个特性决定了它天生适合放跨关卡存活的数据比如玩家的账号信息、设置选项、已解锁的成就、需要通过多个关卡累计的统计值。它最容易被误用的地方是有人把它当成全局变量垃圾桶什么数据都往里塞。这里要提醒一句GameInstance 在单机环境下确实方便但在联机环境下它有个很重要的限制GameInstance 本身不参与网络复制。也就是说客户端上的 GameInstance 和服务器上的 GameInstance 是两份独立的数据你在服务器上改了MyGameInstance-Coins 100客户端并不会自动同步。所以它只适合放每个端各自需要知道的信息比如本地音量设置、本地语言偏好如果是需要全网统一的玩家数据还是得老老实实走 PlayerState 或 GameState 的复制通道。获取方式也很简单任意有 World 的 Actor 都能通过GetGameInstance()拿到或者用GetWorld()-GetGameInstance()。要注意的是在极早期的初始化阶段比如 Actor 构造函数里GameInstance 可能还没准备好这时候强行取会拿到空指针后面会专门讲这个坑。1.2 GameMode只活在服务器上的规则制定者GameMode 是这五个类里最霸道的一个因为它只在服务器上存在。客户端上你GetGameMode()拿到的永远是空指针——不是没初始化是压根就没这个对象。这一点很多人第一次遇到会懵觉得引擎是不是出 bug 了。GameMode 管的是这一局怎么玩的规则。玩家怎么出生、能不能中途加入、胜负条件怎么判定、死掉之后是重生还是观战这类规则性的逻辑都归它。它也是唯一有权决定玩家加入时创建什么 Pawn、什么 PlayerController的地方。你可以把它理解成裁判裁判只在比赛现场服务器坐着观众席客户端是看不到裁判的。正因为它是规则制定者所以它同时也是一个关卡级的对象。每次加载新关卡GameMode 都会被销毁重建。这意味着你绝不能把跨关卡数据放里面。我曾经在一个项目里把玩家的持久经验值放在 GameMode本机测试一切正常直到策划要求做一个打完这关进下一关继承经验的流程数据全丢排查了半天才反应过来是 GameMode 被重建了。另外通过 GameMode 可以拿到GameState、当前所有PlayerController它是服务器的总控台。写服务器逻辑时GameMode 往往是入口。1.3 GameState给所有人看的战况公告栏GameState 的存在意义就是让所有端看到同一份战况。它由服务器创建然后自动复制到所有客户端。它存放的是那些跟具体某个玩家无关、但所有人都需要知道的数据比如当前剩余时间、当前比分、当前游戏阶段等待开始/战斗中/结算中、队伍的总分。和 GameMode 一样GameState 也是关卡级的切关卡就重建。区别在于GameMode 只在服务器存在GameState 在所有端都存在。所以当你想在客户端 UI 上显示当前比分 3:2时正确的做法是读 GameState而不是读 GameMode。这是新手最常犯的错误之一。GameState 的复制是自动的只要属性标记为Replicated并且你在服务器上通过 Set 函数修改客户端就能收到。但要注意它适合放少量、低频变化的全局数据。别拿它当高频同步的通道比如每帧变化的位置信息那会拖垮网络带宽。1.4 PlayerState每个玩家的公开档案PlayerState 是每个玩家一份的对象服务器为每个加入的玩家创建一份然后复制给所有客户端。也就是说每个客户端上都能看到所有玩家的 PlayerState。这个特性非常关键它决定了 PlayerState 适合放别人需要知道的、关于某个玩家的公开信息比如玩家昵称、当前得分、 ping、队伍编号、生命值如果设计上希望别人能看到。这里要和 GameState 做个区分GameState 是一份全局公告PlayerState 是每个玩家的个人档案。公告栏上写的是比分 3:2会员卡上写的是张三得分 12红队。想清楚某条数据是全局的还是属于某个玩家的你就知道该放哪了。PlayerState 同样是关卡级的切换关卡时会重建。而且它有个生命周期上的细节玩家加入时PlayerController 先创建然后才创建 PlayerState或由 Controller 触发初始化。所以任何依赖 PlayerState 的初始化逻辑都不能放在 Controller 的构造函数里得等 PlayerState 就绪比如在PostInitializeComponents或者监听相应的初始化时机。1.5 PlayerController玩家的代理人加操作手柄PlayerController 是玩家意志在游戏世界里的代表。玩家的输入先到这里再由它驱动 Pawn 移动、开火。每个玩家在服务器上有一份对于本地控制的玩家在客户端上也有一份。它是唯一能接收玩家输入的对象。它管的事情很杂输入绑定、摄像机管理、UI 显示HUD、鼠标光标、以及一部分这个玩家自己知道的状态。它和 PlayerState 的分工是PlayerController 负责操作和本地表现PlayerState 负责公开数据。举个例子玩家的移动速度这种瞬时状态放 Controller玩家的得分这种要给别人看的数据放 PlayerState。PlayerController 也是关卡级的切关卡重建。而且它在客户端和服务器上都有所以判断我是不是本地玩家就显得很重要——写逻辑时经常要IsLocalController()来区分。这个判断写错会导致逻辑在服务器和客户端重复执行或者该执行的地方没执行。2. 生命周期与存在范围谁生谁死谁在谁不在光知道管什么还不够真正让新手翻车的是什么时候有、什么时候没有。我把这几个类的关键属性整理成一张表再逐个拆开讲。类生命周期服务器客户端数量跨关卡存活GameInstance进程启动到退出有有1是GameMode关卡加载到卸载有无1否GameState关卡加载到卸载有有复制1否PlayerState玩家加入到离开有有复制每玩家 1否PlayerController玩家加入到离开有本地玩家有每玩家 1否2.1 从进程启动到玩家加入的顺序理解顺序最关键。我按实际流程走一遍游戏进程启动引擎初始化GameInstance 被创建。此时还没有任何关卡没有世界。加载第一个关卡World 被创建。在世界初始化阶段服务器上创建 GameMode紧接着创建 GameState。玩家登录本地玩家或网络玩家服务器上创建 PlayerController。PlayerController 初始化过程中服务器上创建 PlayerState并把它关联到 Controller。这些对象通过复制机制在客户端上建立对应的镜像。这个顺序解释了很多现象。比如为什么在 Controller 的构造函数里取 PlayerState 会拿到空——因为那时候 PlayerState 还没生出来。为什么在 GameInstance 里取 World 会拿到空——因为 GameInstance 比 World 先存在。我见过一个同学在 GameInstance 的Init里想访问当前关卡的名字结果崩溃就是没意识到这个先后关系。2.2 为什么 GameMode 客户端没有这可能是被问得最多的问题。原因其实很直接GameMode 里装的是规则和服务器专属逻辑这些逻辑不需要、也不应该在客户端执行。引擎干脆就不在客户端创建它避免误用。你如果确实有需要服务器和客户端都要执行的逻辑应该放 GameState 或者一个普通的复制 Actor而不是 GameMode。那么客户端怎么知道游戏规则相关的状态呢通过 GameState。服务器在 GameMode 里判定规则把结果写进 GameStateGameState 复制给客户端客户端读 GameState 做表现。这个服务器算GameState 传客户端显示的模式是 UE 网络架构里最核心的一条链路。2.3 关卡切换时到底发生了什么切关卡是数据丢失的高发区。流程是这样的旧世界被销毁GameMode、GameState、所有 PlayerState、所有 PlayerController 全部被销毁然后加载新世界重新创建一套。唯一活下来的是 GameInstance。所以如果你需要跨关卡保留数据只有两条路要么放 GameInstance要么在切关卡前把数据搬到 GameInstance 或存到本地/服务器存档新关卡再读回来。我通常的做法是在 GameInstance 里维护一个玩家持久数据结构体切关卡前由 GameMode 或 PlayerController 把当前数据写回 GameInstance新关卡开始时再由新的 PlayerController 从 GameInstance 读出来初始化 PlayerState。这套存和取的时机把握是跨关卡系统的核心。3. 数据该放哪一套判断流程和几个典型误用前面讲了原理这一节讲怎么用。我给自己总结了一套判断流程遇到这个数据放哪的问题时按顺序问三个问题基本不会错。3.1 三步判断法第一步问这个数据要跨关卡吗。如果要放 GameInstance如果不要继续问第二步。第二步问这个数据是服务器专属的规则还是所有人要看的。如果只是服务器内部用、客户端完全不需要知道放 GameMode如果所有端都要看继续问第三步。第三步问这个数据是全局一份还是每个玩家一份。全局一份放 GameState每个玩家一份放 PlayerState。而如果是某个玩家自己的操作状态、本地表现放 PlayerController。这套流程我用了很久绝大多数情况都能快速定位。举几个具体例子验证一下当前关卡倒计时不跨关卡、所有人要看、全局一份 → GameState。每个玩家的击杀数不跨关卡、所有人要看、每玩家一份 → PlayerState。玩家的账号 ID跨关卡 → GameInstance。玩家能否在战斗中重生服务器规则、客户端不需要 → GameMode。玩家当前按住的移动键本地操作状态 → PlayerController。3.2 一个高频误用的真实例子我见过最多的误用是在客户端 UI 里读 GameMode 显示关卡信息。代码大概是这样// 错误示范客户端会因为 GameMode 为空而崩溃 void UMyHUD::ShowLevelInfo() { AGameModeBase* GM GetWorld()-GetAuthGameMode(); if (GM) { FString LevelName GM-GetLevelName(); // 更新 UI ... } }GetAuthGameMode()在客户端返回空所以客户端这份 UI 直接不显示或者崩溃。正确写法是读 GameState或者更简单——直接读 World 的名字// 正确示范之一读当前世界名称所有端都有 void UMyHUD::ShowLevelInfo() { if (UWorld* World GetWorld()) { FString LevelName World-GetMapName(); LevelName.RemoveFromStart(World-StreamingLevelsPrefix); // 更新 UI ... } }再比如想在客户端显示比分很多人第一反应去 GameMode 拿正确做法是在 GameState 里定义Replicated的比分变量服务器改客户端读。这个思路转换过来之后很多为什么客户端显示不对的问题就迎刃而解了。3.3 复制属性的选择要点既然涉及复制这里补充几个实操要点。想让一个变量从服务器同步到客户端需要三件事属性标记Replicated、在GetLifetimeReplicatedProps里注册、用带OnRep的 Set 函数修改。// PlayerState 里定义一个复制的得分 UPROPERTY(ReplicatedUsing OnRep_Score) int32 Score 0; void AMyPlayerState::GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const { Super::GetLifetimeReplicatedProps(OutLifetimeProps); DOREPLIFETIME(AMyPlayerState, Score); } void AMyPlayerState::SetScore(int32 NewScore) { if (HasAuthority()) // 只有服务器有权修改 { Score NewScore; OnRep_Score(); // 服务器自己也要手动调一次 } } void AMyPlayerState::OnRep_Score() { // 客户端收到更新后的表现逻辑比如刷新 UI }有两个新手常忽略的点一是OnRep函数在服务器上不会自动触发服务器自己改了值得手动调用一次否则会造成服务器和客户端表现不一致的错觉二是所有复制变量的写操作都必须加HasAuthority()判断否则客户端本地改值会在下一次服务器同步时被覆盖表现为改了但没用。注意复制变量的修改一定要走服务器客户端改本地值只是临时假象下一个同步包就会把你的修改抹掉。这个坑我在调试为什么分数加了又弹回去时踩过。4. 动手做一个跨关卡的经验值系统光讲理论容易晕我们做一个具体的小需求玩家在一局游戏中击杀敌人获得经验关卡结束后经验要保留进入下一个关卡继续累计并且在结算 UI 里显示。这个需求正好串起五个类。4.1 需求拆解与职责分配先把需求拆成数据流。经验值的累计是跨关卡的所以真身要放 GameInstance单局内的击杀计数、临时经验属于当前玩家要给别人看的话放 PlayerState关卡结束的处理和结算逻辑服务器主导放 GameMode结算状态是否进入结算是全局的、所有人要看放 GameState玩家的输入触发击杀上报走 PlayerController。这么一分配每个类的活都明确了。下面逐个写关键部分。4.2 用 GameInstance 存持久数据UCLASS() class UMyGameInstance : public UGameInstance { GENERATED_BODY() public: // 跨关卡保留的玩家经验 UPROPERTY(BlueprintReadWrite) int32 PersistentExp 0; // 记录玩家选的角色切换关卡后要用 UPROPERTY(BlueprintReadWrite) FName SelectedCharacterId; };GameInstance 里的这些数据不会被关卡切换清掉是可靠的数据容器。要注意别在 GameInstance 里直接持有 Actor 指针因为 Actor 会在切关卡时销毁留着就是悬空指针。存 ID、数值、结构体这些纯数据是安全的存对象引用要非常小心。4.3 用 PlayerState 承载单局数据UCLASS() class AMyPlayerState : public APlayerState { GENERATED_BODY() public: UPROPERTY(ReplicatedUsing OnRep_SessionExp) int32 SessionExp 0; virtual void GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const override; void AddExp(int32 Amount) { if (HasAuthority()) { SessionExp Amount; OnRep_SessionExp(); } } UFUNCTION() void OnRep_SessionExp(); }; void AMyPlayerState::GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const { Super::GetLifetimeReplicatedProps(OutLifetimeProps); DOREPLIFETIME(AMyPlayerState, SessionExp); }SessionExp 是本局内的经验标记为复制所有人都能看到。这样别的玩家也能在排行榜里看到你的贡献。AddExp 里加了权限判断保证只有服务器能加分。4.4 关卡切换时的数据搬运关键在切关口。我在 GameMode 里处理关卡结束void AMyGameMode::EndLevel() { if (!HasAuthority()) return; // 把每个玩家的本局经验累加进 GameInstance UMyGameInstance* GI GetGameInstanceUMyGameInstance(); if (GI) { for (FConstPlayerControllerIterator It GetWorld()-GetPlayerControllerIterator(); It; It) { APlayerController* PC It-Get(); if (APlayerController* ValidPC CastAPlayerController(PC)) { if (AMyPlayerState* PS ValidPC-GetPlayerStateAMyPlayerState()) { GI-PersistentExp PS-SessionExp; } } } } // 通知 GameState 进入结算 if (AMyGameState* GS GetGameStateAMyGameState()) { GS-SetPhase(EGamePhase::Settling); } }这里有个细节要特别注意遍历 PlayerController 时服务器上每个玩家都有 Controller都能拿到对应的 PlayerState累加逻辑是完整的。但如果直接在客户端做这件事客户端只有本地玩家的 Controller累加会漏人。所以这种汇总逻辑必须在服务器上跑。4.5 关卡开始时回填数据新关卡开始时先把 GameInstance 里的持久经验读回来。这个时机要选在 PlayerState 已经创建之后void AMyPlayerController::BeginPlay() { Super::BeginPlay(); if (IsLocalController()) { // 本地玩家的表现逻辑比如刷新 HUD if (UMyGameInstance* GI GetGameInstanceUMyGameInstance()) { UpdateHUDExp(GI-PersistentExp); } } // 服务器上把持久经验回填到 PlayerState if (HasAuthority()) { if (AMyPlayerState* PS GetPlayerStateAMyPlayerState()) { // PlayerState 此时应已就绪 } } }这里我特意把本地表现和服务器数据回填分开。IsLocalController()判断很重要不加的话这段逻辑在服务器和客户端都会跑容易出重复执行的问题。回填 PlayerState 的时机如果拿不准可以监听 PlayerState 的初始化或覆写 Controller 的相关回调确保拿到的是已初始化的对象。5. 常见问题速查与排查思路理论讲完最后是我觉得最有价值的部分——这几年实际排查过的典型问题。我按现象、原因、解决整理成速查表再挑几个展开讲。现象可能原因排查方向客户端读 GameMode 为空GameMode 只在服务器存在改用 GameState 或 World换关卡后数据丢失数据放在了关卡级对象里移到 GameInstance客户端改了值又恢复客户端无权限被同步覆盖加 HasAuthority 判断OnRep 在服务器不触发服务器不会自动触发 OnRep服务器手动调用一次构造函数里取对象为空对象还没初始化换到 BeginPlay 或初始化回调UI 显示 nil/空指针没做空指针检查加 if 判断处理未就绪5.1 空指针排查的标准流程拿到空指针首先别急着改代码先确认三件事现在跑的是服务器还是客户端当前处于生命周期的哪个阶段这个对象在这个阶段、这个端是否应该存在我常用一个小技巧在怀疑的地方加日志UE_LOG(LogTemp, Warning, TEXT([Check] NetMode%d, HasGM%d, HasGS%d, HasPS%d), (int32)GetWorld()-GetNetMode(), GetWorld()-GetAuthGameMode() ! nullptr, GetGameStateAGameStateBase() ! nullptr, GetPlayerStateAPlayerState() ! nullptr);把NetMode、各个对象的存在性打出来一眼就能判断是这个端本来就没有还是初始化时机不对。NM_Standalone是单机NM_DedicatedServer是服务器NM_Client是客户端。这个日志模板我几乎每个项目都会留一份排查效率提升非常明显。5.2 数据不同步的排查顺序遇到别人看不到我的数据或者客户端显示和服务器不一致按这个顺序查第一属性有没有标Replicated第二有没有在GetLifetimeReplicatedProps里注册第三修改是不是在服务器上、有没有走 Set 函数第四OnRep有没有正确绑定。这四步覆盖了九成以上的复制问题。还有一个隐蔽的坑是对象本身没被复制。如果 PlayerState 都没有从服务器传到客户端那它里面的属性自然也传不过去。判断方法是先看那个对象本身在客户端是否存在再去查它的属性。5.3 关于时机的实操心得我个人最大的体会是这五个类的所有疑难杂症八成都出在时机上。同一个函数在 BeginPlay 里调用和在构造函数里调用结果完全不同在服务器调用和在客户端调用结果也完全不同。写这类代码时养成两个习惯能省下大量调试时间一是每个可能为空的地方都做空指针检查并打日志二是任何涉及服务器权威的逻辑第一行先写if (!HasAuthority()) return;。这两条看着简单但真正贯彻到项目里的开发者不多。我见过太多人把本机能跑当成逻辑正确一到联机测试就全面崩盘。骨架梳理清楚之后你会发现 UE 的这套设计其实非常自洽每个类都有明确的存活范围每个数据都有它该待的地方乱放只是在给未来的自己埋雷。最后分享一个我自己的项目约定在团队里维护一份数据归属表任何新增的同步数据都必须在表里写明它属于哪个类、是否复制、由谁修改。这份表看着像文档负担但它让新人快速上手也让我在 review 代码时一眼看出这个数据放错地方了。很多联机 bug其实在写代码之前就能避免。
UE4五大核心类生命周期与网络复制数据归属
做UE项目的人基本都踩过同一个坑想在UI里显示当前关卡名跑去GetGameMode拿结果客户端崩了想在换关卡后保留玩家的金币数随手丢进 GameMode 的变量里一切关卡数据就蒸发了想同步血量给其他玩家看注释写了replicated结果只有服务器看得见。这些问题的根子都指向同一件事——没搞清楚 GameInstance、GameMode、GameState、PlayerState、PlayerController 这五个类各自活多久、住在哪、管什么。它们不是五个随便挑的角色而是一套职责边界相当清晰的分工体系理解它们的生命周期和存在范围比背一百个 API 都管用。这篇把我自己在项目里踩过的坑、验证过的写法、以及排查问题时最常用的思路整理出来适合刚接触 UE4 网络架构的同学也适合已经写了半年但总觉得状态管理玄学的开发者对照检查。1. 五个核心类到底各自管什么在 UE4 里这五个类经常被混着用因为它们在单机小项目里表现得很随和——乱放数据好像也能跑。但一旦你把项目改成多人联机或者加了关卡切换乱放的东西就开始出问题。想理清楚最好先别想代码先想一个现实场景一个网吧网吧本身、这局开黑的规则、门口的战绩公告栏、每个玩家的会员卡、每个玩家手里的键盘鼠标这五样东西恰好能对应上这五个类。1.1 GameInstance贯穿整个进程的常驻管家GameInstance 是我个人认为最容易被低估的一个类。它的生命周期从游戏进程启动开始一直到进程退出才结束中间不管切换多少次关卡、返回多少次主菜单它都只有一个实例而且不会被销毁。这个特性决定了它天生适合放跨关卡存活的数据比如玩家的账号信息、设置选项、已解锁的成就、需要通过多个关卡累计的统计值。它最容易被误用的地方是有人把它当成全局变量垃圾桶什么数据都往里塞。这里要提醒一句GameInstance 在单机环境下确实方便但在联机环境下它有个很重要的限制GameInstance 本身不参与网络复制。也就是说客户端上的 GameInstance 和服务器上的 GameInstance 是两份独立的数据你在服务器上改了MyGameInstance-Coins 100客户端并不会自动同步。所以它只适合放每个端各自需要知道的信息比如本地音量设置、本地语言偏好如果是需要全网统一的玩家数据还是得老老实实走 PlayerState 或 GameState 的复制通道。获取方式也很简单任意有 World 的 Actor 都能通过GetGameInstance()拿到或者用GetWorld()-GetGameInstance()。要注意的是在极早期的初始化阶段比如 Actor 构造函数里GameInstance 可能还没准备好这时候强行取会拿到空指针后面会专门讲这个坑。1.2 GameMode只活在服务器上的规则制定者GameMode 是这五个类里最霸道的一个因为它只在服务器上存在。客户端上你GetGameMode()拿到的永远是空指针——不是没初始化是压根就没这个对象。这一点很多人第一次遇到会懵觉得引擎是不是出 bug 了。GameMode 管的是这一局怎么玩的规则。玩家怎么出生、能不能中途加入、胜负条件怎么判定、死掉之后是重生还是观战这类规则性的逻辑都归它。它也是唯一有权决定玩家加入时创建什么 Pawn、什么 PlayerController的地方。你可以把它理解成裁判裁判只在比赛现场服务器坐着观众席客户端是看不到裁判的。正因为它是规则制定者所以它同时也是一个关卡级的对象。每次加载新关卡GameMode 都会被销毁重建。这意味着你绝不能把跨关卡数据放里面。我曾经在一个项目里把玩家的持久经验值放在 GameMode本机测试一切正常直到策划要求做一个打完这关进下一关继承经验的流程数据全丢排查了半天才反应过来是 GameMode 被重建了。另外通过 GameMode 可以拿到GameState、当前所有PlayerController它是服务器的总控台。写服务器逻辑时GameMode 往往是入口。1.3 GameState给所有人看的战况公告栏GameState 的存在意义就是让所有端看到同一份战况。它由服务器创建然后自动复制到所有客户端。它存放的是那些跟具体某个玩家无关、但所有人都需要知道的数据比如当前剩余时间、当前比分、当前游戏阶段等待开始/战斗中/结算中、队伍的总分。和 GameMode 一样GameState 也是关卡级的切关卡就重建。区别在于GameMode 只在服务器存在GameState 在所有端都存在。所以当你想在客户端 UI 上显示当前比分 3:2时正确的做法是读 GameState而不是读 GameMode。这是新手最常犯的错误之一。GameState 的复制是自动的只要属性标记为Replicated并且你在服务器上通过 Set 函数修改客户端就能收到。但要注意它适合放少量、低频变化的全局数据。别拿它当高频同步的通道比如每帧变化的位置信息那会拖垮网络带宽。1.4 PlayerState每个玩家的公开档案PlayerState 是每个玩家一份的对象服务器为每个加入的玩家创建一份然后复制给所有客户端。也就是说每个客户端上都能看到所有玩家的 PlayerState。这个特性非常关键它决定了 PlayerState 适合放别人需要知道的、关于某个玩家的公开信息比如玩家昵称、当前得分、 ping、队伍编号、生命值如果设计上希望别人能看到。这里要和 GameState 做个区分GameState 是一份全局公告PlayerState 是每个玩家的个人档案。公告栏上写的是比分 3:2会员卡上写的是张三得分 12红队。想清楚某条数据是全局的还是属于某个玩家的你就知道该放哪了。PlayerState 同样是关卡级的切换关卡时会重建。而且它有个生命周期上的细节玩家加入时PlayerController 先创建然后才创建 PlayerState或由 Controller 触发初始化。所以任何依赖 PlayerState 的初始化逻辑都不能放在 Controller 的构造函数里得等 PlayerState 就绪比如在PostInitializeComponents或者监听相应的初始化时机。1.5 PlayerController玩家的代理人加操作手柄PlayerController 是玩家意志在游戏世界里的代表。玩家的输入先到这里再由它驱动 Pawn 移动、开火。每个玩家在服务器上有一份对于本地控制的玩家在客户端上也有一份。它是唯一能接收玩家输入的对象。它管的事情很杂输入绑定、摄像机管理、UI 显示HUD、鼠标光标、以及一部分这个玩家自己知道的状态。它和 PlayerState 的分工是PlayerController 负责操作和本地表现PlayerState 负责公开数据。举个例子玩家的移动速度这种瞬时状态放 Controller玩家的得分这种要给别人看的数据放 PlayerState。PlayerController 也是关卡级的切关卡重建。而且它在客户端和服务器上都有所以判断我是不是本地玩家就显得很重要——写逻辑时经常要IsLocalController()来区分。这个判断写错会导致逻辑在服务器和客户端重复执行或者该执行的地方没执行。2. 生命周期与存在范围谁生谁死谁在谁不在光知道管什么还不够真正让新手翻车的是什么时候有、什么时候没有。我把这几个类的关键属性整理成一张表再逐个拆开讲。类生命周期服务器客户端数量跨关卡存活GameInstance进程启动到退出有有1是GameMode关卡加载到卸载有无1否GameState关卡加载到卸载有有复制1否PlayerState玩家加入到离开有有复制每玩家 1否PlayerController玩家加入到离开有本地玩家有每玩家 1否2.1 从进程启动到玩家加入的顺序理解顺序最关键。我按实际流程走一遍游戏进程启动引擎初始化GameInstance 被创建。此时还没有任何关卡没有世界。加载第一个关卡World 被创建。在世界初始化阶段服务器上创建 GameMode紧接着创建 GameState。玩家登录本地玩家或网络玩家服务器上创建 PlayerController。PlayerController 初始化过程中服务器上创建 PlayerState并把它关联到 Controller。这些对象通过复制机制在客户端上建立对应的镜像。这个顺序解释了很多现象。比如为什么在 Controller 的构造函数里取 PlayerState 会拿到空——因为那时候 PlayerState 还没生出来。为什么在 GameInstance 里取 World 会拿到空——因为 GameInstance 比 World 先存在。我见过一个同学在 GameInstance 的Init里想访问当前关卡的名字结果崩溃就是没意识到这个先后关系。2.2 为什么 GameMode 客户端没有这可能是被问得最多的问题。原因其实很直接GameMode 里装的是规则和服务器专属逻辑这些逻辑不需要、也不应该在客户端执行。引擎干脆就不在客户端创建它避免误用。你如果确实有需要服务器和客户端都要执行的逻辑应该放 GameState 或者一个普通的复制 Actor而不是 GameMode。那么客户端怎么知道游戏规则相关的状态呢通过 GameState。服务器在 GameMode 里判定规则把结果写进 GameStateGameState 复制给客户端客户端读 GameState 做表现。这个服务器算GameState 传客户端显示的模式是 UE 网络架构里最核心的一条链路。2.3 关卡切换时到底发生了什么切关卡是数据丢失的高发区。流程是这样的旧世界被销毁GameMode、GameState、所有 PlayerState、所有 PlayerController 全部被销毁然后加载新世界重新创建一套。唯一活下来的是 GameInstance。所以如果你需要跨关卡保留数据只有两条路要么放 GameInstance要么在切关卡前把数据搬到 GameInstance 或存到本地/服务器存档新关卡再读回来。我通常的做法是在 GameInstance 里维护一个玩家持久数据结构体切关卡前由 GameMode 或 PlayerController 把当前数据写回 GameInstance新关卡开始时再由新的 PlayerController 从 GameInstance 读出来初始化 PlayerState。这套存和取的时机把握是跨关卡系统的核心。3. 数据该放哪一套判断流程和几个典型误用前面讲了原理这一节讲怎么用。我给自己总结了一套判断流程遇到这个数据放哪的问题时按顺序问三个问题基本不会错。3.1 三步判断法第一步问这个数据要跨关卡吗。如果要放 GameInstance如果不要继续问第二步。第二步问这个数据是服务器专属的规则还是所有人要看的。如果只是服务器内部用、客户端完全不需要知道放 GameMode如果所有端都要看继续问第三步。第三步问这个数据是全局一份还是每个玩家一份。全局一份放 GameState每个玩家一份放 PlayerState。而如果是某个玩家自己的操作状态、本地表现放 PlayerController。这套流程我用了很久绝大多数情况都能快速定位。举几个具体例子验证一下当前关卡倒计时不跨关卡、所有人要看、全局一份 → GameState。每个玩家的击杀数不跨关卡、所有人要看、每玩家一份 → PlayerState。玩家的账号 ID跨关卡 → GameInstance。玩家能否在战斗中重生服务器规则、客户端不需要 → GameMode。玩家当前按住的移动键本地操作状态 → PlayerController。3.2 一个高频误用的真实例子我见过最多的误用是在客户端 UI 里读 GameMode 显示关卡信息。代码大概是这样// 错误示范客户端会因为 GameMode 为空而崩溃 void UMyHUD::ShowLevelInfo() { AGameModeBase* GM GetWorld()-GetAuthGameMode(); if (GM) { FString LevelName GM-GetLevelName(); // 更新 UI ... } }GetAuthGameMode()在客户端返回空所以客户端这份 UI 直接不显示或者崩溃。正确写法是读 GameState或者更简单——直接读 World 的名字// 正确示范之一读当前世界名称所有端都有 void UMyHUD::ShowLevelInfo() { if (UWorld* World GetWorld()) { FString LevelName World-GetMapName(); LevelName.RemoveFromStart(World-StreamingLevelsPrefix); // 更新 UI ... } }再比如想在客户端显示比分很多人第一反应去 GameMode 拿正确做法是在 GameState 里定义Replicated的比分变量服务器改客户端读。这个思路转换过来之后很多为什么客户端显示不对的问题就迎刃而解了。3.3 复制属性的选择要点既然涉及复制这里补充几个实操要点。想让一个变量从服务器同步到客户端需要三件事属性标记Replicated、在GetLifetimeReplicatedProps里注册、用带OnRep的 Set 函数修改。// PlayerState 里定义一个复制的得分 UPROPERTY(ReplicatedUsing OnRep_Score) int32 Score 0; void AMyPlayerState::GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const { Super::GetLifetimeReplicatedProps(OutLifetimeProps); DOREPLIFETIME(AMyPlayerState, Score); } void AMyPlayerState::SetScore(int32 NewScore) { if (HasAuthority()) // 只有服务器有权修改 { Score NewScore; OnRep_Score(); // 服务器自己也要手动调一次 } } void AMyPlayerState::OnRep_Score() { // 客户端收到更新后的表现逻辑比如刷新 UI }有两个新手常忽略的点一是OnRep函数在服务器上不会自动触发服务器自己改了值得手动调用一次否则会造成服务器和客户端表现不一致的错觉二是所有复制变量的写操作都必须加HasAuthority()判断否则客户端本地改值会在下一次服务器同步时被覆盖表现为改了但没用。注意复制变量的修改一定要走服务器客户端改本地值只是临时假象下一个同步包就会把你的修改抹掉。这个坑我在调试为什么分数加了又弹回去时踩过。4. 动手做一个跨关卡的经验值系统光讲理论容易晕我们做一个具体的小需求玩家在一局游戏中击杀敌人获得经验关卡结束后经验要保留进入下一个关卡继续累计并且在结算 UI 里显示。这个需求正好串起五个类。4.1 需求拆解与职责分配先把需求拆成数据流。经验值的累计是跨关卡的所以真身要放 GameInstance单局内的击杀计数、临时经验属于当前玩家要给别人看的话放 PlayerState关卡结束的处理和结算逻辑服务器主导放 GameMode结算状态是否进入结算是全局的、所有人要看放 GameState玩家的输入触发击杀上报走 PlayerController。这么一分配每个类的活都明确了。下面逐个写关键部分。4.2 用 GameInstance 存持久数据UCLASS() class UMyGameInstance : public UGameInstance { GENERATED_BODY() public: // 跨关卡保留的玩家经验 UPROPERTY(BlueprintReadWrite) int32 PersistentExp 0; // 记录玩家选的角色切换关卡后要用 UPROPERTY(BlueprintReadWrite) FName SelectedCharacterId; };GameInstance 里的这些数据不会被关卡切换清掉是可靠的数据容器。要注意别在 GameInstance 里直接持有 Actor 指针因为 Actor 会在切关卡时销毁留着就是悬空指针。存 ID、数值、结构体这些纯数据是安全的存对象引用要非常小心。4.3 用 PlayerState 承载单局数据UCLASS() class AMyPlayerState : public APlayerState { GENERATED_BODY() public: UPROPERTY(ReplicatedUsing OnRep_SessionExp) int32 SessionExp 0; virtual void GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const override; void AddExp(int32 Amount) { if (HasAuthority()) { SessionExp Amount; OnRep_SessionExp(); } } UFUNCTION() void OnRep_SessionExp(); }; void AMyPlayerState::GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const { Super::GetLifetimeReplicatedProps(OutLifetimeProps); DOREPLIFETIME(AMyPlayerState, SessionExp); }SessionExp 是本局内的经验标记为复制所有人都能看到。这样别的玩家也能在排行榜里看到你的贡献。AddExp 里加了权限判断保证只有服务器能加分。4.4 关卡切换时的数据搬运关键在切关口。我在 GameMode 里处理关卡结束void AMyGameMode::EndLevel() { if (!HasAuthority()) return; // 把每个玩家的本局经验累加进 GameInstance UMyGameInstance* GI GetGameInstanceUMyGameInstance(); if (GI) { for (FConstPlayerControllerIterator It GetWorld()-GetPlayerControllerIterator(); It; It) { APlayerController* PC It-Get(); if (APlayerController* ValidPC CastAPlayerController(PC)) { if (AMyPlayerState* PS ValidPC-GetPlayerStateAMyPlayerState()) { GI-PersistentExp PS-SessionExp; } } } } // 通知 GameState 进入结算 if (AMyGameState* GS GetGameStateAMyGameState()) { GS-SetPhase(EGamePhase::Settling); } }这里有个细节要特别注意遍历 PlayerController 时服务器上每个玩家都有 Controller都能拿到对应的 PlayerState累加逻辑是完整的。但如果直接在客户端做这件事客户端只有本地玩家的 Controller累加会漏人。所以这种汇总逻辑必须在服务器上跑。4.5 关卡开始时回填数据新关卡开始时先把 GameInstance 里的持久经验读回来。这个时机要选在 PlayerState 已经创建之后void AMyPlayerController::BeginPlay() { Super::BeginPlay(); if (IsLocalController()) { // 本地玩家的表现逻辑比如刷新 HUD if (UMyGameInstance* GI GetGameInstanceUMyGameInstance()) { UpdateHUDExp(GI-PersistentExp); } } // 服务器上把持久经验回填到 PlayerState if (HasAuthority()) { if (AMyPlayerState* PS GetPlayerStateAMyPlayerState()) { // PlayerState 此时应已就绪 } } }这里我特意把本地表现和服务器数据回填分开。IsLocalController()判断很重要不加的话这段逻辑在服务器和客户端都会跑容易出重复执行的问题。回填 PlayerState 的时机如果拿不准可以监听 PlayerState 的初始化或覆写 Controller 的相关回调确保拿到的是已初始化的对象。5. 常见问题速查与排查思路理论讲完最后是我觉得最有价值的部分——这几年实际排查过的典型问题。我按现象、原因、解决整理成速查表再挑几个展开讲。现象可能原因排查方向客户端读 GameMode 为空GameMode 只在服务器存在改用 GameState 或 World换关卡后数据丢失数据放在了关卡级对象里移到 GameInstance客户端改了值又恢复客户端无权限被同步覆盖加 HasAuthority 判断OnRep 在服务器不触发服务器不会自动触发 OnRep服务器手动调用一次构造函数里取对象为空对象还没初始化换到 BeginPlay 或初始化回调UI 显示 nil/空指针没做空指针检查加 if 判断处理未就绪5.1 空指针排查的标准流程拿到空指针首先别急着改代码先确认三件事现在跑的是服务器还是客户端当前处于生命周期的哪个阶段这个对象在这个阶段、这个端是否应该存在我常用一个小技巧在怀疑的地方加日志UE_LOG(LogTemp, Warning, TEXT([Check] NetMode%d, HasGM%d, HasGS%d, HasPS%d), (int32)GetWorld()-GetNetMode(), GetWorld()-GetAuthGameMode() ! nullptr, GetGameStateAGameStateBase() ! nullptr, GetPlayerStateAPlayerState() ! nullptr);把NetMode、各个对象的存在性打出来一眼就能判断是这个端本来就没有还是初始化时机不对。NM_Standalone是单机NM_DedicatedServer是服务器NM_Client是客户端。这个日志模板我几乎每个项目都会留一份排查效率提升非常明显。5.2 数据不同步的排查顺序遇到别人看不到我的数据或者客户端显示和服务器不一致按这个顺序查第一属性有没有标Replicated第二有没有在GetLifetimeReplicatedProps里注册第三修改是不是在服务器上、有没有走 Set 函数第四OnRep有没有正确绑定。这四步覆盖了九成以上的复制问题。还有一个隐蔽的坑是对象本身没被复制。如果 PlayerState 都没有从服务器传到客户端那它里面的属性自然也传不过去。判断方法是先看那个对象本身在客户端是否存在再去查它的属性。5.3 关于时机的实操心得我个人最大的体会是这五个类的所有疑难杂症八成都出在时机上。同一个函数在 BeginPlay 里调用和在构造函数里调用结果完全不同在服务器调用和在客户端调用结果也完全不同。写这类代码时养成两个习惯能省下大量调试时间一是每个可能为空的地方都做空指针检查并打日志二是任何涉及服务器权威的逻辑第一行先写if (!HasAuthority()) return;。这两条看着简单但真正贯彻到项目里的开发者不多。我见过太多人把本机能跑当成逻辑正确一到联机测试就全面崩盘。骨架梳理清楚之后你会发现 UE 的这套设计其实非常自洽每个类都有明确的存活范围每个数据都有它该待的地方乱放只是在给未来的自己埋雷。最后分享一个我自己的项目约定在团队里维护一份数据归属表任何新增的同步数据都必须在表里写明它属于哪个类、是否复制、由谁修改。这份表看着像文档负担但它让新人快速上手也让我在 review 代码时一眼看出这个数据放错地方了。很多联机 bug其实在写代码之前就能避免。
