XGRIDS文檔
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • 靈視 P1

    • 產品概述
    • 設備基本操作
    • 使用 LCC Scan App
    • 維護及保養
    • 常見問題
  • 靈光 K 系列

    • 靈光 K1

      • 產品概述
      • 設備基本操作
      • 設備激活與連接
      • 設備採集
      • 獲取絕對座標點雲數據
      • 地圖融合
      • 典型場景路線規劃建議
      • 注意事項
      • 常見問題
    • 靈光 K2

      • 產品概述
      • 設備基本操作
      • 設備激活與連接
      • 設備採集
      • 獲取絕對座標點雲數據
      • 地圖融合
      • 典型場景路線規劃建議
      • 注意事項
      • 常見問題
  • 靈光 L 系列

    • 靈光 L2 Pro

      • 產品概述
      • 設備基本操作
      • 設備激活與連接
      • 設備採集
      • 獲取絕對座標點雲數據
      • 實時測量功能
      • 附錄
      • 常見問題
  • Lixel Studio

    • 版權
    • 安裝與激活
    • 界面說明
    • 文件
    • 工程處理
    • 工具
    • 平面繪製
    • 行業應用
    • 設置
    • 設備感知
  • Lixel CyberColor

    • LCC Studio

      • 入門
      • 版本與更新
      • 下載及安裝
      • 介面概覽及導覽
      • 重建前準備
      • 模型重建
      • 單模型重建
      • 地圖融合
      • 空地融合
      • 航拍重建
      • 我的模型
      • 其他功能
      • 設定與帳戶
      • 設置與賬號
      • Converter
      • 影片重建
      • 視頻重建
      • 常見問題
    • LCC Scene Editor

      • 版本與更新
      • 賬號與登錄
      • 產品概覽與主頁
      • 編輯器界面介紹
      • 三種場景漫游快捷操作
      • 文件
      • 設置
      • 編輯操作
      • 窗口
      • 全局工具欄
      • 資產與屬性
      • 左側工具欄
      • 視點
      • 跳轉點
      • 天空盒
      • 標注
      • 測量
      • 場景漫游
      • 場景報告
      • 智能戶型圖(3D Layout)
      • 小地圖
      • 預覽模式(Viewer)
      • 幫助
      • 常見問題 / FAQ
      • 出生點
    • LCC Model Editor

      • 版本與更新
      • 新手指引
      • 概覽與界面
      • 文件操作
      • 選擇器
      • 編輯操作
      • 測量
      • 調色
      • 資產管理
      • 設置與幫助
      • 常見問題 / FAQ
    • 採集指南

      • 概述
      • 採集設備總覽
      • 通用採集原則
      • 室內場景採集
      • 室外場景採集
      • 大場景採集(地圖融合)
      • 空地融合採集
      • 物體採集
      • 人物採集
      • 影片重建採集
      • 高清補拍
      • 控制點(靈視 P1)
      • 常見問題與排查
    • 歷史版本
  • Plugin & SDK

    • Unreal

      • 介紹
      • 快速入門 - Windows
      • 快速入門 - Linux
      • 快速入門 - Quest3
      • 版本與授權
      • 渲染
      • 畫面調節
      • 法線與光照
      • 場景編輯
      • 性能參數說明
      • 性能優化指南
      • 第三方與引擎插件集成
      • 代理網格
      • 加載動畫
      • 碰撞
      • 尋路系統支持
      • 單層水支持
      • 本地化
      • 常見問題
      • 故障排查
      • 日誌與診斷
      • 聯繫我們
      • API 參考

        • ALCCActorBase
        • ULCCComponentBase
        • ULCCComponent
        • ULCC2Component
        • SOG / SPZ / PLY Actors
        • ALCC2ProxyMesh
        • ALCCClippingVolume
        • ALCCSectionPlane
        • ULCCUtilLibrary
        • Enums
        • Structs
      • 更新日誌

        • v3.3.1
        • v3.0.0
        • v2.2.1
        • v1.0.0
        • v0.9.0
        • v0.8.0
        • v0.7.1
        • v0.6.1
        • v0.5.2
        • v0.4.1
        • v0.4.0
        • v0.3.0
        • v0.0.5
        • v0.0.4
        • v0.0.3
        • v0.0.2
        • v0.0.1

在 Linux 上快速渲染 3DGS 場景

本文從安裝 Unreal Engine 開始,完整介紹如何安裝 LCC4Unreal、創建 C++ 工程、加載 LCC 數據、編譯、運行和打包 Linux 應用。

1. 推薦硬件和軟件環境

項目推薦配置
操作系統Ubuntu 22.04
CPUIntel/AMD 四核 2.5 GHz 或更高;源碼構建建議使用更多核心
內存32 GB;源碼構建建議 64 GB 或更多
顯卡NVIDIA GeForce RTX 2080 或更高性能的獨立顯卡
顯存8 GB 或更多
IDEVS Code 或 Rider
磁盤300 GB 及以上

2. 選擇 Unreal Engine 安裝方式

Linux 上有兩種 Unreal Engine 安裝方式:

方式特點適合人群
預編譯版(Installed Build)下載、完整解壓後即可使用;新建 C++ 工程體驗更直接初學者優先選擇
源碼版(Source Build)可以修改引擎源碼;第一次構建耗時較長需要修改引擎或插件底層的開發者

如果只需要使用 LCC4Unreal,不需要修改 Unreal Engine 源碼,優先使用預編譯版。

注:LCC4Unreal 以預編譯形式發佈,與官方引擎二進制保持一致。不要改動引擎源碼,改動後引擎與插件可能不兼容,導致插件無法加載或運行異常。


2.1 方式 A:安裝 Unreal Engine Linux 預編譯版(推薦)

  1. 打開 Epic 官方 Unreal Engine for Linux 頁面;

  2. 登錄 Epic Games 賬號;

  3. 下載所需 Unreal Engine 版本的 .zip 壓縮包。

    在 Epic Games 頁面下載 Unreal Engine Linux 預編譯版

    從 Epic Games 官方頁面選擇並下載所需版本的 Unreal Engine Linux 預編譯包

  4. 在文件管理器中創建引擎目錄,例如:

    /home/[USER]/Unreal/Engines/UnrealEngine
    
  5. 將壓縮包中的全部文件和目錄完整解壓到該引擎根目錄。不要只複製 UnrealEditor 單個文件,否則引擎缺少運行和構建所需的其他內容;

  6. 在文件管理器中進入引擎根目錄,在空白處右鍵並選擇 Open in Terminal(在終端中打開)。後續命令應在正確的引擎目錄中執行。

    在 Unreal Engine 根目錄打開 Linux 終端

    進入完整解壓後的 Unreal Engine 根目錄,並從該目錄打開終端

  7. 啟動 Unreal Engine 編輯器。

通用寫法:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"

如果提示沒有執行權限:

chmod +x "/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor"
示例:
chmod +x "/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"

2.1.1 為 C++ 開發準備工具鏈

根據 Epic Games 的 Linux 開發快速入門,在 Unreal Engine 目錄中執行:

cd "/[UE_ROOT]/Engine/Build/BatchFiles/Linux"
./SetupToolchain.sh
示例:
cd "/home/alice/Unreal/Engines/UnrealEngine/Engine/Build/BatchFiles/Linux"
./SetupToolchain.sh

2.2 方式 B:從源碼構建 Unreal Engine

如果已經能夠運行自己的源碼版 Unreal Engine,可以跳到第 4 節。

2.2.1 獲取源碼

從 GitHub 獲取:https://github.com/EpicGames/UnrealEngine

從 Epic Games GitHub 倉庫獲取 Unreal Engine 源碼

訪問 Epic Games 的 Unreal Engine GitHub 倉庫並獲取所需版本源碼

2.2.2 下載依賴和原生工具鏈

cd "/[UE_ROOT]"
./Setup.sh
示例:
cd "/home/alice/Unreal/Engines/UnrealEngine"
./Setup.sh
運行 Setup.sh 下載 Unreal Engine 源碼依賴和 Linux 工具鏈

通過 Setup.sh 下載源碼構建所需依賴和原生 Linux 工具鏈

成功標準:

  • 命令最終正常返回;
  • 沒有 fatal 或未處理的下載失敗;
  • Engine/Extras/ThirdPartyNotUE/SDKs/HostLinux 中存在 Unreal Engine 對應工具鏈。

如果出現:

fatal: not a git repository

說明源碼來源、當前目錄或 Git 元數據有問題。不要忽略後繼續編譯,應先確認當前終端位於正確的 Unreal Engine 根目錄。

2.2.3 生成工程文件

cd "/[UE_ROOT]"
./GenerateProjectFiles.sh
示例:
cd "/home/alice/Unreal/Engines/UnrealEngine"
./GenerateProjectFiles.sh
運行 GenerateProjectFiles.sh 生成 Unreal Engine 工程文件和 Makefile

為 Unreal Engine 源碼生成工程文件和 Linux Makefile

2.2.4 編譯 UnrealEditor

建議第一次限制並行數量,避免內存不足。默認可使用 make -j4 UnrealEditor;如果內存只有 32 GB,可改用 make -j2 UnrealEditor;如果引擎 Makefile 不提供單獨目標,可使用 make -j4:

cd "/[UE_ROOT]"
make -j4 UnrealEditor

# 內存只有 32 GB 時使用:
make -j2 UnrealEditor

# Makefile 不提供單獨目標時使用:
make -j4
使用 make 編譯 UnrealEditor 源碼目標

限制並行任務數量並編譯源碼版 UnrealEditor

第一次源碼編譯出現數百甚至上千個 Action 是正常的。它們屬於引擎本體,不是空白項目自己的源文件。編譯時間取決於 CPU、內存和磁盤。

檢查是否成功:

test -x "/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor" \
  && echo "Source build UnrealEditor is ready" \
  || echo "Build not finished"
示例:
test -x "/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" \
  && echo "Source build UnrealEditor is ready" \
  || echo "Build not finished"

啟動項目瀏覽器:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"
啟動源碼版 UnrealEditor 並打開 Unreal Project Browser

源碼版 UnrealEditor 編譯完成後啟動 Unreal Project Browser


3. 安裝和配置 VS Code

3.1 安裝 VS Code 和 C++ 開發工具

Ubuntu 可以從 Visual Studio Code 官網下載安裝,也可以使用發行版支持的軟件包方式。

在使用 VS Code 編譯 C++ 項目前,應先完成第 2 節對應的 Unreal Engine Linux 工具鏈安裝,並準備基礎 C++ 編譯和調試工具。根據 Ubuntu 版本和團隊環境安裝 build-essential、clang、lldb、cmake 等常用工具;實際編譯器版本應以當前 Unreal Engine 版本要求和 SetupToolchain.sh/Setup.sh 安裝的工具鏈為準。

VS Code 建議安裝以下擴展:

  • C/C++:代碼瀏覽、補全和調試;
  • C/C++ Extension Pack:補充常用 C++ 開發能力;
  • CodeLLDB:在 Linux 上進行 LLDB 調試;
  • Makefile Tools:查看和執行 Makefile 目標(可選)。

也可參考 Epic Games 官方文檔:為 Unreal Engine 設置 VS Code。

3.2 生成並打開 VS Code 工作區

創建 C++ 工程後,項目目錄通常會生成 .vscode/ 和 <項目名>.code-workspace。如果未生成,執行:

"/[UE_ROOT]/GenerateProjectFiles.sh" \
  -vscode \
  -project="/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject" \
  -game \
  -engine

在 VS Code 中選擇 File → Open Workspace from File...,打開 <項目名>.code-workspace,不要只打開單個 .cpp 文件。

在 VS Code 中打開 Unreal Engine 項目的 code-workspace 工作區

打開項目生成的 .code-workspace,加載 Unreal Engine C++ 工程配置

4. 創建 C++ 工程

4.1 啟動 Unreal Engine

從終端運行:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"

4.2 項目瀏覽器設置

在 Unreal Project Browser 中:

  1. 選擇 Games;

  2. 選擇 Blank;

  3. Project Defaults 選擇 C++;

  4. Target Platform 選擇 Desktop;

  5. Quality Preset 初次測試可選擇 Scalable,高性能工作站可選擇 Maximum;

  6. Starter Content 可根據需要選擇;

  7. 項目位置填寫:

    /home/[USER]/Unreal/Projects
    
  8. 項目名填寫:

    [PROJECT_NAME]
    
  9. 點擊 Create。

在 Unreal Project Browser 中選擇 Games 和 Blank C++ 模板

選擇 Games 分類中的 Blank 模板並將項目類型設置為 C++

設置 Unreal Engine C++ 項目的保存位置和項目名稱

設置項目位置、名稱和平台選項後創建 C++ 工程

項目名和路徑建議只使用:

  • 英文字母;
  • 數字;
  • 下劃線。

不要使用中文、空格、&、括號等特殊字符。

4.3 預編譯版和源碼版此時表現不同

情況 A:預編譯版(Installed Build)

通常流程為:

創建工程 → 自動編譯 <項目名>Editor → 打開 VS Code → 打開新項目編輯器

舊的項目瀏覽器窗口會短暫關閉,這是因為 Unreal Engine 要啟動加載新 .uproject 的編輯器進程。

情況 B:源碼版(Source Build)

通常流程為:

創建工程 → 生成 Source/、Makefile、.vscode/ → 關閉項目瀏覽器 → 打開 VS Code

源碼版 Unreal Engine 可能不會自動構建並打開新工程,而是讓開發者先在 IDE 或終端完成編譯。這不是 VS Code 配置錯誤,也不表示工程創建失敗。

此時項目通常只有:

.vscode/
Config/
Content/
Intermediate/
Saved/
Source/
Makefile
[PROJECT_NAME].code-workspace
[PROJECT_NAME].uproject

尚未出現:

Binaries/Linux/

這表示工程模塊還沒有編譯。

5. 第一次編譯不帶插件的工程

先編譯一次未安裝 LCC4Unreal 的空白工程,可以確認 Unreal Engine、工具鏈和項目本身正常。

5.1 使用 VS Code 編譯(推薦)

  1. 按第 3.2 節生成並打開 <項目名>.code-workspace;
  2. 打開 VS Code 左側的 Run and Debug(運行和調試);
  3. 在頂部配置列表中選擇 <項目名>Editor (Development);
  4. 點擊啟動按鈕進行首次編譯;
  5. 等待構建完成,確認沒有 C++ 編譯錯誤。首次構建耗時較長屬於正常現象。
在 VS Code Run and Debug 中編譯項目的 Editor Development 配置

選擇 <項目名>Editor (Development) 配置並完成項目的首次 C++ 編譯

生成成功後,VS Code 可以直接啟動項目編輯器。

5.2 可選:使用工程 Makefile

cd "/[UE_PROJECTS_DIR]/[PROJECT_NAME]"
make "[PROJECT_NAME]Editor"
示例:
cd "/home/alice/Unreal/Projects/Test2"
make "Test2Editor"
在 Linux 終端中使用項目 Makefile 編譯 Editor 目標

通過項目 Makefile 編譯 <項目名>Editor 目標

5.3 編譯成功後打開工程

圖形界面方式:在文件管理器中找到 <項目名>.uproject,右鍵選擇 Open With Unreal Engine Editor(使用 Unreal Engine Editor 打開)。這種方式適用於系統已經正確關聯目標 Unreal Engine 版本的情況。

在 Linux 文件管理器中右鍵使用 Unreal Engine Editor 打開 uproject

右鍵項目的 .uproject 文件並選擇使用 Unreal Engine Editor 打開

命令行方式:同時指定 UnrealEditor 和 .uproject 的完整路徑。多個 Unreal Engine 版本並存時,這是更可靠的打開方式:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor" "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" "/home/alice/Unreal/Projects/Test2/Test2.uproject"

如果工程能進入編輯器,關閉編輯器,再繼續安裝插件。

Unreal Engine 正在打開指定的 C++ 項目

使用指定 Unreal Engine 版本加載項目

C++ 項目成功進入 Unreal Engine 編輯器主界面

空白 C++ 工程成功編譯並進入 Unreal Engine 編輯器

6. 安裝 LCC4Unreal

Linux 版本插件目前未在開發者平台提供下載,需要通過郵件申請。請發送郵件至 sdk@xgrids.com,郵件模板:

  • 公司名:
  • 用途:插件用途
  • 引擎版本:需要哪個引擎版本的插件
  • 獲知渠道:從哪裏知道插件的

6.1 關閉相關程序

在複製插件前:

  1. 保存工程;
  2. 關閉 Unreal Engine 編輯器;
  3. 等待 UnrealEditor 後台進程退出;
  4. 可以保持 VS Code 打開,但不要同時構建工程。

檢查 UnrealEditor 是否仍在運行:

pgrep -a UnrealEditor

沒有輸出表示編輯器已經退出。

6.2 將完整插件複製到項目中

  1. 在項目根目錄創建 Plugins 目錄:

    mkdir -p "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Plugins"
    
    示例:
    mkdir -p "/home/alice/Unreal/Projects/Test2/Plugins"
    
  2. 解壓下載的插件包,將完整的 LCC4Unreal 文件夾複製到項目中,最終目錄必須為:

    [PROJECT_ROOT]/Plugins/LCC4Unreal/
    

    不要只複製其中的 Binaries、Content 或單個文件,也不要形成 Plugins/LCC4Unreal/LCC4Unreal/ 的重複嵌套目錄。

  3. 檢查插件描述文件存在。目錄中應能找到:

    [PROJECT_ROOT]/Plugins/LCC4Unreal/LCC4Unreal.uplugin
    

    如果實際 .uplugin 文件名隨發佈包變化,也必須確認它直接位於 Plugins/LCC4Unreal/ 下,而不是更深一層目錄中。

將完整 LCC4Unreal 插件文件夾複製到項目 Plugins 目錄

把完整 LCC4Unreal 文件夾複製為 [PROJECT_ROOT]/Plugins/LCC4Unreal,並檢查 .uplugin 文件

6.3 重新啟動項目

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor" "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" "/home/alice/Unreal/Projects/Test2/Test2.uproject"

這條命令同時指定使用哪個 Unreal Engine 和打開哪個工程。多個 Unreal Engine 版本並存時,它比雙擊 .uproject 更可靠,也不需要把某一個版本註冊為全局默認版本。

6.4 出現 Rebuild 提示怎麼辦

提示類似:

The following modules are missing or built with a different engine version.
Would you like to rebuild them now?

含義是工程動態庫不存在或與當前 Unreal Engine 版本不匹配。

  • 如果確認命令中的 Unreal Engine 根目錄完整路徑正確,可以選擇 Yes/Rebuild;
  • 如果很快完成並進入編輯器,通常只是項目模塊增量編譯;
  • 如果每次打開都提示,檢查是否每次使用了不同引擎、Binaries/Linux 是否可寫、系統時間是否正確;
  • 多引擎環境優先退出提示,然後使用本文第 13 節的 Build.sh 命令明確構建。

7. 根據數據格式選擇正確的 Actor

不同數據格式需要使用對應的 Actor:

數據格式Unreal Engine 中建議搜索的 ActorC++ 類名
.lcc2LCC2ActorALCC2Actor
.lccLCC ActorALCCActor
.sogSogActorASogActor
.spzSpzActorASpzActor
.plyPlyActorAPlyActor

以下步驟以 .lcc2 數據和 LCC2Actor 為例。使用其他格式時,應改用表中對應的 Actor。

7.1 添加 LCC2Actor 並加載數據

  1. 在 LCC4Unreal 面板中點擊添加 LCC2Actor。

    在 LCC4Unreal 面板中向場景添加 LCC2Actor

    根據 .lcc2 數據格式,在 LCC4Unreal 面板中添加 LCC2Actor

  2. 在 World Outliner 中選中 LCC2Actor;

  3. 在 Details 面板中找到 Actions;

  4. 點擊 Load;

  5. 選擇 .lcc2 數據文件。

    在 LCC2Actor 的 Actions 面板中選擇並加載 lcc2 數據

    從 LCC2Actor 的 Details 面板加載 .lcc2 數據文件

  6. 等待數據加載完成。

    lcc2 數據成功加載並顯示在 Unreal Engine 場景中

    .lcc2 數據加載完成後顯示在 Unreal Engine 視口中

大型數據加載時,編輯器可能暫時無響應。觀察內存、顯存和 Output Log,不要立即強制關閉。

8. 將非資產 LCC 數據加入打包

.lcc2、.lcc、.sog、.spz、.ply 通常不是 Unreal Engine 的 .uasset。僅把文件放入 Content,不會自動進入安裝包。

建議目錄:

/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Content/LCCData/

打開:

Edit → Project Settings → Packaging

找到:

Additional Non-Asset Directories To Copy

添加:

LCCData

Packaging 下有兩種非資產目錄配置:

設置項數據形態適用場景
Additional Non-Asset Directories To Copy以普通文件形式複製到打包產物希望數據在成品目錄裡可見、可替換
Additional Non-Asset Directories To Package打進 pak 包希望數據隨 pak 一起分發,不單獨暴露文件

注:使用 Additional Non-Asset Directories To Package 將數據打進 pak 包時,碰撞數據無法正常加載,這是當前版本的已知缺陷,將在下一個版本修復。需要碰撞功能時請使用 Additional Non-Asset Directories To Copy。

配置的是 Content 下的頂層目錄名(如 LCCData),不是具體文件路徑,不需要加 Content/ 前綴。

在 Packaging 中將 LCCData 添加到 Additional Non-Asset Directories To Copy

將 Content/LCCData 配置為打包時複製的非資產目錄

然後確保 LCC Actor 或 LCC2Actor 加載的相對路徑與打包後的目錄一致。

8.1 設置啟動地圖

打開:

Edit → Project Settings → Maps & Modes

在 Default Maps 中將 Game Default Map 設置為包含 LCC Actor/LCC2Actor 和已配置數據路徑的目標關卡。設置後保存關卡和項目配置,避免打包程序啟動到空白地圖。

在 Maps and Modes 中設置 Unreal Engine 項目的 Game Default Map

在 Maps & Modes 的 Default Maps 中設置打包應用啟動時使用的 Game Default Map

9. 打包前檢查清單

打包前逐項確認:

  • [ ] 使用正確的 Unreal Engine 版本;
  • [ ] LCC4Unreal 插件包與 Unreal Engine 版本、Linux 架構匹配;
  • [ ] <項目名>Editor Linux Development 編譯成功;
  • [ ] 插件已啟用;
  • [ ] 專業版授權有效(僅使用專業版功能時需要,詳見版本與授權);
  • [ ] LCC 數據在編輯器 Play 中可見;
  • [ ] Game Default Map 已設置;
  • [ ] 需要打包的數據已加入 Additional Non-Asset Directories To Copy;
  • [ ] 磁盤有足夠空間;
  • [ ] 輸出目錄可寫;
  • [ ] 已保存所有關卡和資產;
  • [ ] 第一次先打 Development 包,成功後再嘗試 Shipping。

10. 使用 Project Launcher 打包 Linux

10.1 打開 Project Launcher

在 Unreal Engine 編輯器中選擇:

Platforms → Project Launcher
從 Unreal Engine Platforms 菜單打開 Project Launcher

從 Platforms 菜單進入 Project Launcher

點擊:

Add → Create Custom Profile
在 Project Launcher 中創建自定義啟動配置

通過 Add → Create Custom Profile 創建 Linux 打包配置

10.2 配置 Profile

  1. 在自定義 Profile 中選擇目標平台 Linux,並將內容打包方案設置為 Pak 文件;

  2. 勾選歸檔構建結果,並選擇可寫的歸檔目錄。該目錄是打包完成後可分發版本的實際保存位置。

    在 Project Launcher 自定義 Profile 中選擇 Linux、Pak 並設置歸檔目錄

    將目標平台設為 Linux、選擇 Pak 文件,並啟用歸檔和指定打包結果目錄

  3. 在自定義 Profile 右側點擊啟動圖標。

打包過程通常包括:

Build → Cook → Stage → Package → Archive

第一次打包會比增量打包慢。不要因為短時間停留在某個百分比就強制結束。成功時應看到類似:

BUILD SUCCESSFUL

10.3 如果一直顯示「正在查詢 / Querying」

依次檢查:

  1. 等待 Unreal Engine 完成平台和 SDK 檢測;
  2. 打開 Window → Developer Tools → Output Log;
  3. 搜索 Turnkey、SDK、Linux、Error;
  4. 確認當前主機為 Linux,目標平台也選擇 Linux;
  5. 確認源碼版 Unreal Engine 的依賴和工具鏈已由 Setup.sh 安裝;
  6. 確認預編譯版已執行 SetupToolchain.sh;
  7. 關閉重複的 Project Launcher 窗口後重新打開;
  8. 不要同時在另一個終端構建同一工程。

11. 使用命令行打包(可選)

圖形界面打包穩定後,可以使用 RunUAT:

mkdir -p "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Packaged"

"/[UE_ROOT]/Engine/Build/BatchFiles/RunUAT.sh" BuildCookRun \
  -project="/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject" \
  -noP4 \
  -targetplatform=Linux \
  -clientconfig=Development \
  -build \
  -cook \
  -stage \
  -pak \
  -archive \
  -archivedirectory="/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Packaged"
示例:
mkdir -p "/home/alice/Unreal/Projects/Test2/Packaged"

"/home/alice/Unreal/Engines/UnrealEngine/Engine/Build/BatchFiles/RunUAT.sh" BuildCookRun \
  -project="/home/alice/Unreal/Projects/Test2/Test2.uproject" \
  -noP4 \
  -targetplatform=Linux \
  -clientconfig=Development \
  -build \
  -cook \
  -stage \
  -pak \
  -archive \
  -archivedirectory="/home/alice/Unreal/Projects/Test2/Packaged"

使用 -archive 和 -archivedirectory 後,應從指定歸檔目錄查找最終可運行版本,而不是固定假設它位於 Saved/StagedBuilds/Linux。

如果工程使用特定地圖,可根據項目設置和當前 Unreal Engine 命令參數增加地圖限制。初學者應先使用 Project Launcher,避免因命令參數遺漏而產生不完整包。

12. 運行打包結果

12.1 運行歸檔結果

如果在 Project Launcher 中啟用了歸檔,或 RunUAT 使用了 -archive -archivedirectory="...",請進入實際設置的歸檔目錄。不同 Unreal Engine 版本可能會在該目錄下再生成 Linux 子目錄,因此先查找項目啟動腳本,再運行:

cd "/[ARCHIVE_DIR]"
find . -maxdepth 3 -type f -name "*.sh" -print

chmod +x "./[SUBDIR]/[PROJECT_NAME].sh"
"./[SUBDIR]/[PROJECT_NAME].sh"
示例(歸檔結果位於 Packaged/Linux):
cd "/home/alice/Unreal/Projects/Test2/Packaged"
find . -maxdepth 3 -type f -name "*.sh" -print
chmod +x "./Linux/Test2.sh"
"./Linux/Test2.sh"
在 Linux 文件管理器中查看並啟動已歸檔的打包結果

進入 Project Launcher 或 RunUAT 配置的實際歸檔目錄並啟動項目腳本

12.2 運行未歸檔的 staged output

只有未執行歸檔、需要直接檢查暫存結果時,才通常從以下目錄運行:

cd "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Saved/StagedBuilds/Linux"
chmod +x "./[PROJECT_NAME].sh"
"./[PROJECT_NAME].sh"
示例:
cd "/home/alice/Unreal/Projects/Test2/Saved/StagedBuilds/Linux"
chmod +x "./Test2.sh"
"./Test2.sh"

運行後檢查:

  • 能夠啟動;
  • 默認地圖正確;
  • LCC 數據可見;
  • 關閉應用後沒有持續殘留進程。
運行 Linux 打包應用並顯示已加載的 LCC 場景

啟動 Linux 打包應用並驗證默認地圖、LCC 數據與授權功能

13. 命令速查

以下命令中的 [UE_ROOT]、[UE_PROJECTS_DIR]、[PROJECT_NAME]、[ARCHIVE_DIR] 等為佔位符。執行前替換為實際完整路徑和名稱。

啟動項目瀏覽器:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor"

生成 VS Code 工程文件:

"/[UE_ROOT]/GenerateProjectFiles.sh" \
  -vscode \
  -project="/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject" \
  -game \
  -engine
示例:
"/home/alice/Unreal/Engines/UnrealEngine/GenerateProjectFiles.sh" \
  -vscode \
  -project="/home/alice/Unreal/Projects/Test2/Test2.uproject" \
  -game \
  -engine

編譯項目 Editor Target:

"/[UE_ROOT]/Engine/Build/BatchFiles/Linux/Build.sh" \
  "[PROJECT_NAME]Editor" Linux Development \
  -Project="/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject" \
  -WaitMutex
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Build/BatchFiles/Linux/Build.sh" \
  "Test2Editor" Linux Development \
  -Project="/home/alice/Unreal/Projects/Test2/Test2.uproject" \
  -WaitMutex

指定 Unreal Engine 打開指定項目:

"/[UE_ROOT]/Engine/Binaries/Linux/UnrealEditor" "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/[PROJECT_NAME].uproject"
示例:
"/home/alice/Unreal/Engines/UnrealEngine/Engine/Binaries/Linux/UnrealEditor" "/home/alice/Unreal/Projects/Test2/Test2.uproject"

運行歸檔結果:

cd "/[ARCHIVE_DIR]"
find . -maxdepth 3 -type f -name "*.sh" -print
chmod +x "./[SUBDIR]/[PROJECT_NAME].sh"
"./[SUBDIR]/[PROJECT_NAME].sh"

運行未歸檔的 staged output:

cd "/[UE_PROJECTS_DIR]/[PROJECT_NAME]/Saved/StagedBuilds/Linux"
chmod +x "./[PROJECT_NAME].sh"
"./[PROJECT_NAME].sh"
示例(未歸檔的 staged output):
cd "/home/alice/Unreal/Projects/Test2/Saved/StagedBuilds/Linux"
chmod +x "./Test2.sh"
"./Test2.sh"
上一頁
快速入門 - Windows
下一頁
快速入門 - Quest3