🎮 日常类比：餐厅服务质量

想象你经营一家餐厅，顾客抱怨"上菜太慢"：

❓ 问题可能出在哪里？
┌────────────────────────────────────────────────────────────────────────┐
│                                                                        │
│   🍳 厨房问题？          🏃 服务员问题？         📝 点单系统问题？        │
│   ├── 厨师太少           ├── 人手不足            ├── 系统卡顿            │
│   ├── 食材准备慢         ├── 路线不合理          ├── 订单丢失            │
│   └── 设备故障           └── 托盘太小            └── 优先级混乱          │
│                                                                        │
│   🎯 没有诊断工具，你只能瞎猜！                                          │
│   ✅ 有了监控系统，问题一目了然！                                        │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

网络复制也是如此：
- 🍳 厨房 = 服务器（生成数据）- 🏃 服务员 = 网络（传输数据）- 📝 点单系统 = Iris（管理复制）- 👨‍🍳 顾客 = 客户端（接收数据）

🎮 日常类比：飞机黑匣子

飞机上有两个黑匣子：
📦 飞行数据记录器（FDR）：记录飞机的各种参数
🎙️ 驾驶舱语音记录器（CVR）：记录飞行员的对话

当飞机出事时，黑匣子能告诉调查员发生了什么。

Iris 日志系统 = 网络复制的"黑匣子"
- 📝 记录复制事件- ⚠️ 记录错误警告- 🔍 事后分析排查

🎯 出问题时，日志是你最好的朋友！

// IrisLog.h（节选）IRISCORE_API DECLARE_LOG_CATEGORY_EXTERN(LogIris, Log, All);
IRISCORE_API DECLARE_LOG_CATEGORY_EXTERN(LogIrisFiltering, Log, All);

// IrisLog.cpp（节选）DEFINE_LOG_CATEGORY(LogIris);
DEFINE_LOG_CATEGORY(LogIrisFiltering);

// ReplicationBridge.h（节选）IRISCORE_API DECLARE_LOG_CATEGORY_EXTERN(LogIrisBridge, Log, All);

// ReplicationBridge.cpp（节选）DEFINE_LOG_CATEGORY(LogIrisBridge)

// ObjectReplicationBridge.h（节选）DECLARE_LOG_CATEGORY_EXTERN(LogIrisFilterConfig, Log, All);

// ObjectReplicationBridge.cpp（节选）DEFINE_LOG_CATEGORY(LogIrisFilterConfig)

🎮 日常类比：消息通知设置

想象你手机的通知设置：
📵 静音：什么都不通知
🔔 重要：只通知重要消息
🔔🔔 全部：所有消息都通知

; 方式 1：在 DefaultEngine.ini 中配置[Core.Log]LogIris=Verbose                    ; Iris 主日志设为详细LogIrisFiltering=Warning           ; 过滤系统只显示警告以上

// 方式 2：通过控制台命令// Log LogIris Verbose// Log LogIrisFiltering Warning

📋 问题：玩家报告"敌人突然消失"

🔍 第一步：开启过滤日志
控制台输入：Log LogIrisFiltering Verbose

🔍 第二步：复现问题，查看日志
[LogIrisFiltering] Object filtered out: BP_Enemy_C_0 by GridFilter
[LogIrisFiltering] GridFilter: Object outside view range
[LogIrisFiltering]   ObjectPos=(5000, 3000, 0)
[LogIrisFiltering]   ViewPos=(0, 0, 0)
[LogIrisFiltering]   Distance=5831, MaxDistance=5000

🎯 第三步：定位问题
原因：敌人距离玩家 5831 单位，超过了 GridFilter 的 5000 单位限制

✅ 第四步：解决方案
• 增加 GridFilter 的裁剪距离
• 或者为重要敌人设置更高的优先级

🎮 日常类比：游戏里的“作弊码菜单”（仅开发环境）

- 你想“锁血/透视”不是为了正式玩，而是为了定位 bug 更快。
- `IrisDebugging` 也是这个定位：让你在关键时刻一脚刹车（断点），或者直接把内部状态吐出来。

// IrisDebugging.h（节选）namespace UE::Net::IrisDebugHelper
{
    IRISCORE_API bool BreakOnObjectName(UObject* Object);
    IRISCORE_API bool BreakOnNetRefHandle(FNetRefHandle NetRefHandle);
    IRISCORE_API bool BreakOnRPCName(FName RPCName);

    extern "C" IRISCORE_API void DebugOutputNetObjectState(uint64 NetRefHandleId, uint32 ReplicationSystemId);
    extern "C" IRISCORE_API const TCHAR* DebugNetObjectStateToString(uint32 NetRefHandleId, uint32 ReplicationSystemId);
}

// IrisDebugging.cpp（节选）FAutoConsoleVariableRef NetIrisDebugName(
    TEXT("Net.Iris.DebugName"),
    GIrisDebugName,
    TEXT("Set a class name or object name to break on."),
    ECVF_Default);

static FAutoConsoleCommand NetIrisDebugNetRefHandle(
    TEXT("Net.Iris.DebugNetRefHandle"),
    TEXT("Specify a NetRefHandle ID that we will break on (or none to turn off)."),
    FConsoleCommandWithArgsDelegate::CreateLambda([](const TArray<FString>& Args){ /*...*/ }));

// ObjectReplicationBridgeDebugging.cpp（节选）FAutoConsoleCommand ObjectBridgePrintReplicatedObjects(
    TEXT("Net.Iris.PrintReplicatedObjects"),
    TEXT("Prints the list of replicated objects registered for replication in Iris"),
    FConsoleCommandWithArgsDelegate::CreateLambda([](const TArray<FString>& Args)
{
    // ... FindReplicationSystemFromArg(Args) 支持 RepSystemId=
    // ... FindPrintTraitsFromArgs(Args) 支持 WithSubObjects/SortBy...
    // ... ObjectBridge->PrintReplicatedObjects(...)
}));

═══════════════════════════════════════════════════════════════════Object Replication Info: BP_PlayerCharacter_C_0═══════════════════════════════════════════════════════════════════

📌 Basic Info:├── NetRefHandle: 0x00010042├── Class: BP_PlayerCharacter_C├── Owner: PlayerController_0└── NetRole: ROLE_Authority

📊 Replication State:├── IsReplicating: Yes├── IsDirty: No├── LastReplicatedFrame: 12345└── PollPeriod: 0 (every frame)

🎯 Filter Status:├── GridFilter: Passed ✅├── ConnectionFilter: Passed ✅└── GroupFilter: Passed ✅

⭐ Priority Info:├── StaticPriority: 1.0├── Prioritizer: SphereNetObjectPrioritizer└── CurrentPriority: 0.85

🔗 Connections Relevancy:├── Connection 1: Relevant ✅ (Owner)├── Connection 2: Relevant ✅ (Distance: 500)└── Connection 3: Not Relevant ❌ (Distance: 8000)

🎮 日常类比：汽车仪表盘

开车时，仪表盘能让你一眼看到：
⛽ 油量、🌡️ 水温、🏎️ 速度、📍 导航

Iris 可视化调试 = 网络复制的"仪表盘"

> ⚠️ 源码事实：在 UE5.5 的 `Runtime/Experimental/Iris` 目录里，我没有找到 `Net.Iris.Draw...` 之类的“场景内画线/画圈”命令注册；**Iris 更偏向用 `Net.Iris.Print...` 系列打印 + Insights 时间线来“可视化”**。下面这张图是帮你快速建立直觉的示意图，真正排查还是以 15.3.2/15.4 为准。

┌────────────────────────────────────────────────────────────────────────┐
│                    🎨 可视化调试效果图解                                 │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│                        游戏场景俯视图                                   │
│   ┌──────────────────────────────────────────────────────────────┐    │
│   │                                                              │    │
│   │     🟢 = 正常复制的对象                                       │    │
│   │     🔴 = 脏对象（需要同步）                                    │    │
│   │     ⚪ = 被过滤的对象                                         │    │
│   │     🔵 = 玩家视图范围                                         │    │
│   │                                                              │    │
│   │              ⚪ ⚪                                            │    │
│   │           ⚪      ⚪                                          │    │
│   │        ⚪    ┌────────┐    ⚪                                 │    │
│   │             │  🔵    │                                       │    │
│   │      ⚪     │ 🟢 🔴  │     ⚪                                 │    │
│   │             │  🟢 🟢 │                                       │    │
│   │        ⚪   │   👤   │   ⚪                                   │    │
│   │             └────────┘                                       │    │
│   │           ⚪      ⚪                                          │    │
│   └──────────────────────────────────────────────────────────────┘    │
│                                                                        │
│   💡 通过颜色可以快速判断对象复制状态和过滤效果                          │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

🎮 日常类比：体检报告

每年体检，医生会给你一份详细的报告：
📊 血压：120/80 ✅ 正常
📊 血糖：5.6 ✅ 正常
📊 胆固醇：6.2 ⚠️ 偏高
📊 尿酸：480 ❌ 超标

有了这份报告，你就知道该关注什么、改善什么。

性能分析 = 给网络复制系统做"体检"

┌────────────────────────────────────────────────────────────────────────┐
│                    📊 Iris 关键性能指标                                  │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   ⏱️ 时间指标（越小越好）                                               │
│   ├── NetUpdateTime       │ < 2ms ✅  │ 2-5ms ⚠️  │ > 5ms ❌           │
│   ├── FilteringTime       │ < 0.5ms   │ 0.5-1ms   │ > 1ms              │
│   ├── PrioritizationTime  │ < 0.3ms   │ 0.3-0.8ms │ > 0.8ms            │
│   └── SerializationTime   │ < 1ms     │ 1-3ms     │ > 3ms              │
│                                                                        │
│   📦 数量指标                                                           │
│   ├── ReplicatedObjects   │ < 1000 建议 │ 每连接复制的对象数            │
│   ├── DirtyObjects        │ < 100 建议  │ 每帧脏对象数                  │
│   └── FilteredObjects     │ 越多越好    │ 被过滤掉的对象数              │
│                                                                        │
│   📡 带宽指标                                                           │
│   ├── BandwidthUsage      │ < 80% limit │ 带宽使用率                   │
│   ├── AvgPacketSize       │ 500-1200    │ 平均包大小(字节)             │
│   └── PacketsPerSecond    │ 30-60       │ 每秒数据包数                 │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

// IrisProfiler.h（节选）#ifndef IRIS_PROFILER_ENABLE#	if (UE_BUILD_SHIPPING)#		define IRIS_PROFILER_ENABLE 0#	else#		define IRIS_PROFILER_ENABLE 1#	endif#endif

#if IRIS_PROFILER_ENABLE#	include "ProfilingDebugging/CpuProfilerTrace.h"#	define IRIS_PROFILER_SCOPE(x) TRACE_CPUPROFILER_EVENT_SCOPE(x)#	define IRIS_PROFILER_SCOPE_TEXT(X) TRACE_CPUPROFILER_EVENT_SCOPE_TEXT(X)#else#	define IRIS_PROFILER_SCOPE(x)#	define IRIS_PROFILER_SCOPE_TEXT(X)#endif

// IrisCsv.h（节选）CSV_DECLARE_CATEGORY_EXTERN(Iris);

#if UE_NET_IRIS_CSV_STATS#	define IRIS_CSV_PROFILER_SCOPE(CsvCategory, x) \
		CSV_SCOPED_TIMING_STAT(CsvCategory, x); \
		IRIS_PROFILER_SCOPE(x)#else#	define IRIS_CSV_PROFILER_SCOPE(CsvCategory, x) IRIS_PROFILER_SCOPE(x)#endif

// IrisProfiler.cpp（节选）static FAutoConsoleVariableRef CVarEnableDetailedClientProfilerRef(
    TEXT("net.Iris.EnableDetailedClientProfiler"),
    bEnableDetailedClientProfiler,
    TEXT("Generates detailed CSV Iris stats (client only)."),
    ECVF_Default);

// 命令行参数（推荐：最稳）
-trace=cpu,net

// 或控制台命令（运行时开启）
Trace.Start cpu,net
...复现问题...
Trace.Stop

┌────────────────────────────────────────────────────────────────────────┐
│                    📊 Unreal Insights 时间线视图（示意）                │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   Frame 1234                                                           │
│   │                                                                    │
│   │ GameThread ═══════════════════════════════════════════════════    │
│   │ ├─ Tick ──────────────────────────────────────────────────────    │
│   │ │  ├─ Physics ████                                                │
│   │ │  ├─ Animation ██████                                            │
│   │ │  └─ Iris_* ████████████████████                                 │
│   │ │     ├─ ...（Filtering / Poll / Quantize / Write 等）             │
│   │ │     └─ ...                                                      │
│   │                                                                    │
│   │ 0ms        5ms        10ms       15ms       16.67ms (60fps)       │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

// NetStats.cpp（节选）static FAutoConsoleVariableRef CShouldIncludeSubObjectWithRoot(
    TEXT("net.Iris.Stats.ShouldIncludeSubObjectWithRoot"),
    bCVARShouldIncludeSubObjectWithRoot,
    TEXT("If enabled SubObjects will reports stats with RootObject..."));

CSV_DEFINE_CATEGORY(IrisPreUpdateMS, WITH_SERVER_CODE);
CSV_DEFINE_CATEGORY(IrisPollMS, WITH_SERVER_CODE);
CSV_DEFINE_CATEGORY(IrisQuantizeMS, WITH_SERVER_CODE);
CSV_DEFINE_CATEGORY(IrisWriteMS, WITH_SERVER_CODE);
CSV_DEFINE_CATEGORY(IrisWriteKBytes, WITH_SERVER_CODE);

// NetStats.cpp（节选）CSV_CUSTOM_STAT(Iris, ReplicatingConnectionCount, Stats.ReplicatingConnectionCount, ECsvCustomStatOp::Set);
CSV_CUSTOM_STAT(Iris, HugeObjectWaitingForAckTimeInSeconds, Stats.HugeObjectWaitingForAckTimeInSeconds, ECsvCustomStatOp::Set);

Frame,IrisPreUpdateMS,IrisPollMS,IrisQuantizeMS,IrisWriteMS,IrisWriteKBytes
1,0.18,0.42,0.31,0.55,32.4
2,0.20,0.47,0.28,0.62,35.1
3,0.19,0.40,0.29,0.50,29.8

// NetStats.h（节选）/**
 * Send stats for Iris replication reported to the CSV profiler.
 * ... intended use is to do thread local tracking ... and then use Accumulate ...
 */class FNetSendStats
{
public:
	IRISCORE_API void Accumulate(const FNetSendStats& Stats);
	IRISCORE_API void Reset();
	IRISCORE_API void ReportCsvStats();
	// ... AddNumberOfReplicatedObjects / AddHugeObjectWaitingTime 等
};

// NetStatsContext.h（节选）struct FNetTypeStatsData
{
	enum EStatsIndex : unsigned { PreUpdate, Poll, PollWaste, Quantize, Write, WriteWaste, WriteCreationInfo, WriteExports, Count };
	struct FStatsValue { uint64 Time = 0; uint32 Bits = 0; uint32 Count = 0; };
	FStatsValue Values[EStatsIndex::Count];
};

#if UE_NET_IRIS_CSV_STATS#	define UE_NET_IRIS_STATS_TIMER(TimerName, NetStatsContext) UE::Net::Private::FNetStatsTimer TimerName(NetStatsContext);#	define UE_NET_IRIS_STATS_ADD_TIME_AND_COUNT_FOR_OBJECT(Timer, StatName, ObjectIndex) /*...*/#	define UE_NET_IRIS_STATS_ADD_BITS_WRITTEN_AND_COUNT_FOR_OBJECT(NetStatsContext, BitCount, StatName, ObjectIndex) /*...*/#endif

// ObjectReplicationBridge.cpp（节选）static FAutoConsoleVariableRef CVarUseVerboseCsvStats(
	TEXT("net.Iris.UseVerboseIrisCsvStats"),
	bUseVerboseIrisCsvStats,
	TEXT("Whether to use verbose per-class csv stats. Default is false in Shipping, otherwise True.")
);

🎮 日常类比：家庭开支记账

不记账：💸 "钱都花哪去了？"
记账后：📊 一目了然！

内存追踪 = 告诉你内存都被谁占用了

LLM (示意)
- NetworkingSummary
  - Iris
    - State
    - Initialization
    - Connection

// IrisMemoryTracker.h（节选）LLM_DECLARE_TAG_API(Iris, IRISCORE_API);
LLM_DECLARE_TAG_API(IrisState, IRISCORE_API);
LLM_DECLARE_TAG_API(IrisInitialization, IRISCORE_API);
LLM_DECLARE_TAG_API(IrisConnection, IRISCORE_API);

// IrisMemoryTracker.cpp（节选）LLM_DEFINE_TAG(Iris, NAME_None, NAME_None, GET_STATFNAME(STAT_IrisLLM), GET_STATFNAME(STAT_NetworkingSummaryLLM));
LLM_DEFINE_TAG(IrisState, "State", "Iris", GET_STATFNAME(STAT_IrisStateLLM), GET_STATFNAME(STAT_NetworkingSummaryLLM));
LLM_DEFINE_TAG(IrisInitialization, "Initialization", "Iris", GET_STATFNAME(STAT_IrisInitializationLLM), GET_STATFNAME(STAT_NetworkingSummaryLLM));
LLM_DEFINE_TAG(IrisConnection, "Connection", "Iris", GET_STATFNAME(STAT_IrisConnectionLLM), GET_STATFNAME(STAT_NetworkingSummaryLLM));

🎮 日常类比：中医看病的四诊法

👀 望：观察日志、统计数据
👂 闻：监听网络流量、事件
💬 问：了解问题发生的场景
✋ 切：使用调试工具深入分析

Step 1: 先确认“对象到底有没有注册进 Iris”
Net.Iris.PrintReplicatedObjects RepSystemId=0
→ 在输出里搜对象名（或类名）
→ 如果根本找不到：问题通常在“注册/桥接层/生命周期”

Step 2: 再确认“对象是不是被过滤/不相关了”
Net.Iris.PrintRelevantObjectsToConnection RepSystemId=0 ConnectionId=1 WithFilter
→ 这个命令会在输出里附带过滤信息（WithFilter）
→ 如果对象在 ReplicatedObjects 里，但不在 RelevantObjects 里：优先查过滤/裁剪距离

Step 3: 快速验证“是不是距离裁剪导致消失”
Net.Iris.PrintNetCullDistances RepSystemId=0 NumClasses=20
→ 看你关心的类，MostCommon NetCullDistance 是多少

Step 4: 只要你怀疑“某个对象一处理就出错”，直接在案发点断下来
Net.Iris.DebugName=MyBoss   （或用 Net.Iris.DebugNetRefHandle 指定句柄）
→ 命中就 UE_DEBUG_BREAK()，你能直接看调用栈

Step 5: 回到基础：属性是否真的可复制
✅ UPROPERTY(Replicated)
✅ GetLifetimeReplicatedProps 里注册
✅（如果是 Push Model）修改后记得“标脏”（告诉系统它变了）

Step 1: 先确认“对象这条链路是通的”
Net.Iris.PrintReplicatedObjects RepSystemId=0
Net.Iris.PrintRelevantObjectsToConnection RepSystemId=0 ConnectionId=1 WithFilter
→ 对象必须“已注册 + 对该连接相关”，否则你盯着属性看是白费劲

Step 2: 再看“是不是复制条件把你挡在门外了”
常见条件（在 Gameplay 代码里配）：
- COND_OwnerOnly / COND_SkipOwner
- COND_InitialOnly
→ 现象：服务器改了，客户端永远收不到（其实是条件没满足）

Step 3: 用 Iris 自带命令确认 PushBased 状态（源码真实存在✅）
Net.Iris.PrintPushBasedStatuses
→ 它会打印哪些类是 fully push-based，并列出“不是 push-based 的属性路径”
→ 如果你改的属性属于 push-based：必须在 Gameplay 层做“标脏”（否则 Iris 认为“没变过”）

Step 4: 还不对？考虑“你看到的是量化后的值”
现象：服务器 100.123456，客户端 100.12
→ 这不是不同步，而是量化精度导致的“正常舍入”
→ 线索通常在具体序列化器的 Quantize/Dequantize（可回看第七部分）

Step 1: 先用 Unreal Insights 录“录像”（看时间线）
命令行：-trace=cpu,net
或控制台：Trace.Start cpu,net
复现后：Trace.Stop

Step 2: 如果想要“表格化记账”，用 CSV Profiler（Iris 会上报 Iris* 类别）
- Iris 在源码里用 CSV_DEFINE_CATEGORY/CSV_CUSTOM_STAT 上报（见 15.4.5）- 想要更细：检查 net.Iris.UseVerboseIrisCsvStats / net.Iris.EnableDetailedClientProfiler

Step 3: 用 Iris 自带的“对象维度”命令快速判断规模是否异常
Net.Iris.PrintRelevantObjects RepSystemId=0
Net.Iris.PrintReplicatedObjects RepSystemId=0 WithSubObjects

Step 4: 对症下药（把锅甩给正确的人😉）
- IrisPollMS 高：降低轮询压力（例如更合理的 PollPeriod / Dormancy / 过滤）- IrisWriteKBytes 高：过滤/条件/量化/增量压缩有没有真正生效- 大量 SubObject 计入 Root：尝试切换 net.Iris.Stats.ShouldIncludeSubObjectWithRoot

┌────────────────────────────────────────────────────────────────────────┐│                    📋 第十五部分知识点总结                               │├────────────────────────────────────────────────────────────────────────┤│                                                                        ││   📝 日志系统                                                           ││   ├── LogIris 主日志类别及子类别                                        ││   ├── 7 个日志级别（Fatal → VeryVerbose）                              ││   └── 配置文件 / 代码 / 控制台 三种配置方式                              ││                                                                        ││   🔧 调试工具                                                           ││   ├── IrisDebugHelper：断点条件/调试输出（Watch/Immediate Window 友好）  ││   ├── 控制台命令：Net.Iris.PrintReplicatedObjects / PrintRelevant...     ││   └── “可视化”主要靠：日志打印 + Unreal Insights 时间线                 ││                                                                        ││   📈 性能分析                                                           ││   ├── IrisProfiler：时间统计、计数器                                    ││   ├── Unreal Insights：详细时间线分析                                   ││   └── IrisCsv：CSV 数据导出                                            ││                                                                        ││   💾 内存追踪                                                           ││   ├── IrisMemoryTracker：注册 LLM Tag（Iris/State/Initialization/Connection）││   └── 用 LLM Tag 追“哪一科目在涨”                                       ││                                                                        ││   🚨 问题排查                                                           ││   ├── 对象未复制：注册、过滤、属性配置                                   ││   ├── 属性不同步：复制条件、Push Model、序列化器                        ││   └── 性能瓶颈：分阶段分析、Insights 深入追踪                           ││                                                                        │└────────────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────────────┐
│                    ✅ 调试与性能分析最佳实践                             │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│   🔧 开发阶段                                                           │
│   □ 启用开发版日志级别                                                  │
│   □ 配置 Unreal Insights 追踪                                          │
│   □ 启用可视化调试工具                                                  │
│   □ 记录基准性能数据                                                    │
│                                                                        │
│   🧪 测试阶段                                                           │
│   □ 测试对象创建和销毁                                                  │
│   □ 测试属性同步                                                        │
│   □ 测试过滤器效果                                                      │
│   □ 进行性能回归测试                                                    │
│                                                                        │
│   🚀 发布阶段                                                           │
│   □ 关闭详细日志（只保留 Warning 以上）                                  │
│   □ 禁用可视化调试                                                      │
│   □ 设置性能监控告警                                                    │
│                                                                        │
│   🔍 问题排查                                                           │
│   □ 先看日志，再用工具                                                  │
│   □ 从现象定位到具体模块                                                │
│   □ 使用控制台命令快速验证                                              │
│   □ 记录问题和解决方案                                                  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘