Auto-sync: 2026-04-26 12:02

wiki/concepts/Actor-Replication.md

@@ -0,0 +1,46 @@
+---
+title: "Actor Replication"
+type: concept
+tags: []
+sources: [unreal-multiplayer-architect]
+last_updated: 2026-04-26
+---
+
+## Definition
+Actor 复制是 UE5 多人游戏网络同步的基础机制，允许 Actor 的属性和状态在服务器与所有客户端之间自动同步。通过 `UPROPERTY(Replicated)` 和 `GetLifetimeReplicatedProps()` 实现。
+
+## Core Mechanisms
+- `UPROPERTY(Replicated)` — 将属性标记为需要复制到所有客户端
+- `UPROPERTY(ReplicatedUsing=OnRep_X)` — 带通知函数的复制，客户端可在属性变化时执行逻辑
+- `DOREPLIFETIME_CONDITION` — 条件复制，如 `COND_OwnerOnly`、`COND_SimulatedOnly`
+- `GetNetPriority()` — 控制 Actor 的复制优先级
+- `SetNetUpdateFrequency()` — 控制 Actor 的复制频率
+
+## Key Implementation
+```cpp
+void AMyNetworkedActor::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
+{
+    Super::GetLifetimeReplicatedProps(OutLifetimeProps);
+    DOREPLIFETIME(AMyNetworkedActor, Health);
+    DOREPLIFETIME_CONDITION(AMyNetworkedActor, PrivateInventoryCount, COND_OwnerOnly);
+}
+```
+
+## Best Practices
+- 仅复制所有客户端都需要的状态
+- 使用 `COND_OwnerOnly` 减少私有状态的带宽消耗
+- 按 Actor 类型设置合适的 `NetUpdateFrequency`（大多数 20–30Hz）
+- 使用 `ReplicatedUsing` 让客户端能响应属性变化
+
+## Connection to Other Concepts
+- [[Server-Authoritative Model]] — Actor Replication 是实现服务器权威的技术基础
+- [[Network Prediction]] — 客户端利用复制的状态进行预测和调和
+- [[Replication Graph]] — 空间分区优化复制性能
+
+## Relationship to Agent
+[[UnrealMultiplayerArchitect]] 强调 Actor 复制的正确实现是 UE5 多人游戏开发的第一步，必须从一开始就用 `DOREPLIFETIME_CONDITION` 进行带宽优化。
+
+## Aliases
+- UE5 Replication
+- Property Replication
+- State Synchronization