🎮 Unreal Engine - UE_LOG

---

📝 定義

UE_LOG 是 Unreal Engine 中用于輸出日志信息的核心宏，用于在開發過程中調試程序、記錄運行狀態、追蹤錯誤等。它支持將信息輸出到控制臺、日志文件（如 Saved/Logs 目錄下的日志文件）以及調試器（如 Visual Studio 的輸出窗口），并可通過日志級別和日志類別進行過濾管理。

---

🏛 類/宏關聯

UE_LOG 本身是一個宏定義，其實現依賴于 Unreal Engine 的日志系統框架，核心關聯組件包括：

• FLogCategoryBase：日志類別基類，所有自定義日志類別均繼承自此
• ELogVerbosity：日志級別枚舉（如 Fatal、Error、Warning 等）
• FOutputDevice：日志輸出設備基類，負責將日志信息發送到控制臺、文件等目標

---

? 關鍵特性

• 分級日志：通過日志級別（Fatal、Error、Warning、Display、Log、Verbose、VeryVerbose）控制信息詳細程度，便于過濾無關內容
• 類別管理：支持自定義日志類別（如 LogMyGame），可單獨開啟/關閉某類日志
• 跨平臺兼容：在 Windows、Mac、Linux 等平臺均能穩定輸出日志
• 格式化輸出：支持類似 C++ printf 的格式化語法（如 %s、%d、%f），可輸出變量值、對象信息等
• 調試集成：日志信息可直接顯示在編輯器控制臺和調試器，便于實時追蹤程序流程

---

🛠? 常見配置

• 日志級別設置：

  • 在 DefaultEngine.ini 中配置全局或類別日志級別，例如：

    [Core.Log]
    LogMyGame=Verbose  ; 自定義類別 LogMyGame 輸出 Verbose 及以上級別日志
    LogTemp=Warning    ; 臨時類別 LogTemp 僅輸出 Warning 及以上級別日志

  • 通過命令行參數覆蓋配置：LogCmds="LogMyGame=VeryVerbose"

• 日志文件路徑：默認存儲在項目目錄 Saved/Logs/[項目名].log，可通過引擎配置自定義路徑

---

📚 使用方法

🔧 基礎語法

UE_LOG(LogCategory, LogVerbosity, FormatString, Parameters...)

• LogCategory：日志類別（如 LogTemp 臨時類別，或自定義類別）
• LogVerbosity：日志級別（如 Error、Warning）
• FormatString：格式化字符串
• Parameters：對應格式化字符串的參數

🔍 示例

1. 使用臨時日志類別：

   UE_LOG(LogTemp, Warning, TEXT("Player health: %d"), CurrentHealth);

2. 自定義日志類別：

   • 先在頭文件中聲明：

     DECLARE_LOG_CATEGORY_EXTERN(LogSpaceShooter, Log, All);

   • 在源文件中定義：

     DEFINE_LOG_CATEGORY(LogSpaceShooter);

   • 使用：

     UE_LOG(LogSpaceShooter, Display, TEXT("Enemy spawned at: %s"), *SpawnLocation.ToString());

3. 輸出致命錯誤（會導致程序崩潰）：

   UE_LOG(LogTemp, Fatal, TEXT("Critical error: Player controller is null!"));

---

🪂 典型應用場景

• 🐞 調試階段輸出變量值，驗證程序邏輯（如角色位置、屬性值變化）
• 🚨 記錄錯誤信息（如空指針、資源加載失敗），便于定位 Bug
• 📊 追蹤程序流程（如關卡切換、事件觸發），確認代碼執行順序
• 🔍 性能分析輔助（如記錄函數執行時間）

---

🔗 與其他組件對比

功能	UE_LOG	GEngine->AddOnScreenDebugMessage
輸出位置	控制臺、日志文件、調試器	游戲屏幕直接顯示
信息保留	持久化到日志文件	一段時間后自動消失
適用場景	詳細日志記錄、調試追蹤	實時顯示關鍵信息（如坐標、狀態）
性能影響	較低（可通過級別控制）	較高（頻繁調用可能影響幀率）

---

?? 常見問題與注意事項

• 日志級別濫用：避免在發布版本中保留過多 Verbose 或 VeryVerbose 級別日志，可能增加性能開銷和日志文件體積
• 格式化錯誤：格式化字符串與參數類型不匹配會導致編譯錯誤或運行時崩潰（如 %d 對應整數，%s 對應 FString 需加 轉換）
• 自定義類別未定義：使用 DECLARE_LOG_CATEGORY_EXTERN 聲明的類別必須用 DEFINE_LOG_CATEGORY 定義，否則會鏈接錯誤
• Fatal 級別謹慎使用：Fatal 級日志會強制程序崩潰，僅用于不可恢復的致命錯誤

---

🏷 小結

• ? UE_LOG 是 Unreal Engine 中最核心的日志工具，支持分級和分類管理
• ? 合理使用日志級別和類別可提高調試效率，便于后期問題排查
• ? 自定義日志類別能讓日志更有條理，建議按模塊或功能劃分（如 LogCombat、LogUI）
• ? 發布版本前需清理冗余日志，避免敏感信息泄露和性能損耗