在 Linux 上快速渲染 3DGS 场景

本文从安装 Unreal Engine 开始，完整介绍如何安装 LCC4Unreal、创建 C++ 工程、加载 LCC 数据、编译、运行和打包 Linux 应用。

1. 推荐硬件和软件环境

2. 选择 Unreal Engine 安装方式

Linux 上有两种 Unreal Engine 安装方式：

如果只需要使用 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 预编译包

4. 在文件管理器中创建引擎目录，例如：

   /home/[USER]/Unreal/Engines/UnrealEngine
   

5. 将压缩包中的全部文件和目录完整解压到该引擎根目录。不要只复制 UnrealEditor 单个文件，否则引擎缺少运行和构建所需的其他内容；

6. 在文件管理器中进入引擎根目录，在空白处右键并选择 Open in Terminal（在终端中打开）。后续命令应在正确的引擎目录中执行。

   

   进入完整解压后的 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 的 Unreal Engine GitHub 仓库并获取所需版本源码

2.2.2 下载依赖和原生工具链

cd "/[UE_ROOT]"
./Setup.sh

示例：
cd "/home/alice/Unreal/Engines/UnrealEngine"
./Setup.sh

通过 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

为 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

限制并行任务数量并编译源码版 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

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 文件。

打开项目生成的 .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。

选择 Games 分类中的 Blank 模板并将项目类型设置为 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++ 编译错误。首次构建耗时较长属于正常现象。

选择 <项目名>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"

通过项目 Makefile 编译 <项目名>Editor 目标

5.3 编译成功后打开工程

图形界面方式：在文件管理器中找到 <项目名>.uproject，右键选择 Open With Unreal Engine Editor（使用 Unreal Engine Editor 打开）。这种方式适用于系统已经正确关联目标 Unreal Engine 版本的情况。

右键项目的 .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 编辑器

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 文件夹复制为 [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：

以下步骤以 .lcc2 数据和 LCC2Actor 为例。使用其他格式时，应改用表中对应的 Actor。

7.1 添加 LCC2Actor 并加载数据

1. 在 LCC4Unreal 面板中点击添加 LCC2Actor。

   

   根据 .lcc2 数据格式，在 LCC4Unreal 面板中添加 LCC2Actor

2. 在 World Outliner 中选中 LCC2Actor；

3. 在 Details 面板中找到 Actions；

4. 点击 Load；

5. 选择 .lcc2 数据文件。

   

   从 LCC2Actor 的 Details 面板加载 .lcc2 数据文件

6. 等待数据加载完成。

   

   .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 Package 将数据打进 pak 包时，碰撞数据无法正常加载，这是当前版本的已知缺陷，将在下一个版本修复。需要碰撞功能时请使用 Additional Non-Asset Directories To Copy。

配置的是 Content 下的顶层目录名（如 LCCData），不是具体文件路径，不需要加 Content/ 前缀。

将 Content/LCCData 配置为打包时复制的非资产目录

然后确保 LCC Actor 或 LCC2Actor 加载的相对路径与打包后的目录一致。

8.1 设置启动地图

打开：

Edit → Project Settings → Maps & Modes

在 Default Maps 中将 Game Default Map 设置为包含 LCC Actor/LCC2Actor 和已配置数据路径的目标关卡。设置后保存关卡和项目配置，避免打包程序启动到空白地图。

在 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

从 Platforms 菜单进入 Project Launcher

点击：

Add → Create Custom Profile

通过 Add → Create Custom Profile 创建 Linux 打包配置

10.2 配置 Profile

1. 在自定义 Profile 中选择目标平台 Linux，并将内容打包方案设置为 Pak 文件；

2. 勾选归档构建结果，并选择可写的归档目录。该目录是打包完成后可分发版本的实际保存位置。

   

   将目标平台设为 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"

进入 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 数据与授权功能

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"