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 裏可以看到。

聯繫方式見聯繫我們。