3DGS 渲染日志与调试工具

本页说明怎么获取诊断信息、各项工具怎么读。按现象定位问题见故障排查。

查看插件日志

插件的日志分两个分类：

分类	来源
`LogLCC`	LCC 管线与通用功能（加载、碰撞、授权、工具函数）
`LogLCC2`	LCC2 管线专属

在编辑器中查看

打开 Window > Output Log。自己排查时可以在过滤框输入 LogLCC 快速定位插件信息，也可以在控制台执行下面的命令提高日志级别：

log LogLCC Verbose
log LogLCC2 Verbose

编辑器的日志文件位于：

<工程目录>/Saved/Logs/<项目名>.log

在打包后的程序中查看

打 Development 包时加 -log 参数启动，会弹出控制台窗口。日志文件位于：

<打包目录>/<项目名>/Saved/Logs/<项目名>.log

Shipping 包默认不输出日志，排查问题请用 Development 包。

提交问题时请附上出问题那一次运行的完整日志文件，不要过滤后只发插件相关的几行。定位问题往往需要看插件之外的上下文。

渲染统计：stat XGrids

在控制台执行 stat XGrids，或用 Actor 细节面板 Actions 分类下的 Stats 按钮。

配合 stat unit 一起看，先判断瓶颈在不在 3DGS 上。

数量项

最常看的几项：

统计项	含义
`Total Splats`	数据的 Splat 总量
`Level0 Splats`	Level 0（最高精度）的 Splat 数量
`Current Render Splats`	当前帧实际渲染的 Splat 数，判断渲染压力主要看这个
`Current Render Main Splats`	当前帧渲染的主体数据量
`Current Render Environment Splats`	当前帧渲染的环境数据量
`Total Nodes`	节点总数
`Current Render Nodes`	当前帧渲染的节点数
`Visible Node Num`	可见节点数
`LCC Draw Call`	插件产生的 Draw Call 数
`LCC Sort Num`	排序次数
`Camera Num`	参与渲染的摄像机数量

怎么用：Current Render Splats 持续贴近 Max Splat Num 的上限，说明已经被数量限制截断，此时画面细节是打了折的。要么提高上限（性能换画质），要么调 Level Factor 从源头减少节点。

数据总量也可以用代码读，见 GetSplatNumber。

耗时项

按阶段拆分的耗时，用于定位卡在哪一步：

统计项	对应阶段
`Render LCC`	插件渲染总耗时
`Traversal Time`	节点遍历，决定这一帧渲染哪些节点
`Determine Nodes Level`	计算各节点的精度层级
`Load Data To CPU`	数据读到内存
`Upload To GPU`	数据上传显存
`Splat Sort`	Splat 排序（半透明渲染需要）
`Node Sort`	节点排序
`Build Mesh Batch`	构建绘制批次
`Wait Node Ready`	等待节点数据就绪
`Component Update`	组件更新
`Update Camera Info`	摄像机信息更新
`Load Meta File`	加载元信息文件
`Load Index Data`	加载索引数据（LCC 管线）
`Load Collision Data`	加载碰撞数据
`Load Environment Data`	加载环境数据
`Update Collision`	碰撞更新
`Get Physics Trimesh Data`	生成物理碰撞网格
`Release Memory`	内存释放
`Preload Node`	节点预加载
`Get From Cache`	从缓存取数据
`Create Thread`	线程创建
`Draw Node Box`	节点边界绘制（仅开启调试可视化时）

怎么用：

Splat Sort 偏高，LCC 管线可以调大 Sort Factor 降低排序频率
Wait Node Ready 偏高，说明数据加载跟不上，可能是磁盘慢或线程数不足
Upload To GPU 偏高，说明每帧上传的数据量大，调 Level Factor 或 Max Splat Num
Update Collision 与 Get Physics Trimesh Data 偏高，减小 Max Load Collision Distance

完整的调优流程见性能优化指南。

内存与显存项

统计项	含义
`CPU Usage`	插件占用的内存
`GPU Usage`	插件占用的显存
`Position Data(For Raycast) Usage`	射线检测用的位置数据占用
`Collision Data Usage`	碰撞数据占用
`CPU Occupy Percentage`	CPU 内存占用百分比
`GPU Occupy Percentage`	显存占用百分比

百分比项与项目设置里的释放阈值对应。占用率长期贴近 Max GPU Usage Percetage For Free 说明会频繁触发资源回收，可能造成卡顿。

显存的分配规则与预算上限见渲染。

线程项

统计项	含义
`Collision Loader Thread Num`	碰撞加载线程数
`Exporter Thread Num`	导出线程数

节点边界可视化

用 Actor 细节面板 Actions 分类下的 Debug Node Bound 按钮开关，或控制台执行：

r.Xgrids.DrawNodeBox 1

会用线框盒画出当前加载的节点。盒体颜色对应节点的 Level：红、橙、黄、绿、蓝、紫依次递进，红色是 Level 最低（精度最高），白色是 Level 最高（精度最低）。

节点与 Level 的概念见渲染。

怎么读：

远处还在渲染红色盒子，说明精度过高、性能被浪费。调大 Level Factor
近处全是冷色盒子，说明精度被压得过狠，画面会发糊。调小 Level Factor 或检查 Start Level
盒子数量远超预期，检查 Max Distance 是否设得过大

只在编辑器与 Development 构建下有效。对应的代码接口是 DebugNodeBound。

碰撞可视化

用 Actor 细节面板 Actions 分类下的 Show Collision 按钮开关，或控制台执行：

r.xgrids.DrawCollision 1

会画出已加载的碰撞体线框。

怎么读：

完全没有线框：数据不含碰撞文件，或 bEnableCollision 没开，见碰撞前置条件
只有近处有线框：正常表现，碰撞按距离流式加载，受 Max Load Collision Distance 限制
线框与画面内容有偏移：碰撞数据与渲染数据不匹配，联系技术支持

排查射线打不中、角色穿模时先开这个确认碰撞到底有没有加载出来。加载机制见碰撞，代码接口是 ShowCollision。

帧率显示

Actor 细节面板 Actions 分类下的 Show FPS 按钮，等价于控制台执行 stat fps。配合 stat unit 看各线程耗时分布。

常见日志信息对照

按信息内容查含义与处理。以下都是插件实际输出的原文。

加载相关

日志信息	含义与处理
`LCC file :<路径> does not exist.`	路径不存在。核对路径，相对路径以 `Content` 为基准
`meta.lcc file :<路径> load error,Please check.`	LCC1 元信息文件解析失败，文件可能损坏
`Load Meta.lcc error,Please check your file!`	同上
`Read index.bin error,path:<路径>.`	索引文件读取失败。确认 `index.bin` 存在且未损坏
`LCC4Unreal do not support this file format!`	格式不支持，确认扩展名在支持范围内
`The data file:<路径> does not exist,Please check your file!`	数据分块文件缺失，数据目录可能不完整

碰撞相关

日志信息	含义与处理
`There is neither collision.bin nor collision.lci in the folder:<路径>, please check.`	数据目录下没有碰撞文件，该数据无法开启碰撞
`Failed to open file <路径>`	碰撞文件打开失败，检查文件权限与完整性
`Read collision data error,path:<路径>.`	碰撞数据读取失败，文件可能损坏
`Invalid indices in collision data!`	碰撞数据内容异常，联系技术支持

渲染相关

日志信息	含义与处理
`r.PostProcessing.PropagateAlpha is 0. LCC4Unreal requires this to be enabled for correct rendering.`	必须开启该项，否则 alpha 混合不正确。插件会同时弹出提示
`Unlicensed: enabled clipping volumes limited to <N> ...`	免费版裁剪体数量超配额，超出部分不渲染。见版本与授权
`Unlicensed: enabled section planes limited to <N> ...`	同上，剖切面数量超配额

GIS 相关

日志信息	含义与处理
`This lcc does not have RTK information!`	数据不含 RTK 地理信息，无法使用地理放置
`MetaInfo's Offset has no 3 elements!`	元信息里的偏移字段异常，数据可能有问题

授权相关

日志信息	含义与处理
`ProjectID is invalid; generate one in Project Settings (Project/Description). Refusing authentication.`	工程缺少 Project ID，在项目设置里生成
`Failed to decode AppKey, please check.`	AppKey 内容不完整，重新复制
`Invalid AppKey, please check.`	AppKey 格式错误
`Authorization has expired, please check.`	授权过期，重新生成
`AppKey has expired. Please generate a new one.`	同上
`Authentication Failed: <消息>`	服务端返回的失败原因，按消息内容处理
`HTTP request failed`	无法连接授权服务器，检查网络
`HTTP error! Status: <代码>`	服务器返回错误状态码
`Signature Verification Failed`	签名校验失败，联系技术支持

代理网格相关

日志信息	含义与处理
`has a null StaticMesh`	代理网格 Actor 没有赋 StaticMesh，不会起作用。每个实例只提示一次

提交问题时该附上什么

按下面这个清单收集，能明显加快定位速度。

插件版本与引擎版本。 插件版本在插件面板右下角可以看到，也可以在引擎的 Edit > Plugins 窗口里搜索 LCC4Unreal 查看。
出问题时的完整日志文件。 直接提供 .log 文件本身，不要过滤、不要只截报错那一行。日志的前后文往往包含定位所需的关键信息，过滤后反而丢失线索。日志位置见查看插件日志。
数据信息。 格式、大致规模（Total Splats）、是否含碰撞。
复现步骤。 从新建工程开始的最小复现路径最有价值。
硬件环境。 显卡型号、驱动版本、显存大小。
Project ID。 授权类问题需要，在 Project Settings > Project > Description 里可以看到。

联系方式见联系我们。