龍智是JetBrains授權合作伙伴、Perforce授權合作伙伴，為您提供TeamCity、Perforce Helix Core等熱門的游戲開發工具及一站式服務

TeamCity是游戲開發的熱門選擇，大家選擇它的原因包括支持 Perforce、可以進行本地安裝，并提供了多種配置選項。除了將它主要用作通用 CI/CD 解決方案之外，JetBrains 還努力為各種構建工具提供專門支持。JetBrains已提供 Unity 插件數年，去年也正式推出了Unreal Engine 支持插件！

在這款新插件的開發過程中，JetBrains一直與多位游戲開發客戶保持密切聯系，以確保它符合從事實際 Unreal Engine 項目工作的 DevOps 團隊的需求。

為 Unreal Engine 游戲設置合適的構建管道可能是一項艱巨的任務，特別是對于那些在平臺獨特性方面經驗有限的人來說。本文，我們將帶您了解基本設置，同時會展示該插件的功能，并演示分布式 BuildGraph 支持等高級功能。

主要功能

以下是此版插件所提供功能的快速概覽：

• 專為最常見用例（BuildCookRun、BuildGraph 和自動化測試）定制的專用運行程序。
• 基于 BuildGraph 描述構建發行版。
• 即時自動化測試報告。
• 自動發現構建計算機上的 Unreal Engine 安裝。
• 兼容最新的 5.x 版 Unreal Engine，還支持 4.x 版本。

演示

在本演示中，我們將為隨 Unreal 提供的兩款入門級游戲 Cropout 和 Lyra 設置管道：我們將為構建代理和安裝了 Unreal Engine 插件的 TeamCity Cloud 使用 AWS 基礎架構（EC2 和用于 FSx for OpenZFS）。我們將介紹兩個場景：引擎已安裝在代理上，以及引擎與游戲一起通過源代碼構建。目前，TeamCity Cloud 不為代理提供預裝的 Unreal Engine，但您可以隨時添加您自己的包含所有必需 SDK 的自托管代理。我們將在這篇博文中采用這種方式。

使用 BuildCookRun構建 Cropout

構建 Unreal 項目通常涉及多個?步驟，例如：

• 采用指定配置針對目標平臺進行編譯。
• 資源烘焙（將所有資源轉換為可在目標平臺上讀取的資源）。
• 將項目封裝為合適的分發格式。
• 等等。

當然，之后還要進行測試！首先，我們來看一個簡單的場景，并使用標準 BuildCookRun 命令在一臺計算機上按順序運行所有階段。對于此場景，我們將使用撰寫這篇博文時可以獲取的最新普通版 Unreal Engine，并通過 EGL（Epic Games 啟動器）進行安裝。將代理成功連接到 TeamCity Cloud 服務器后，我們可以在 Agents（代理）標簽頁中看到它。

現在，我想簡單探討一下代理的一些屬性。

查看上圖，我們可以看到代理發現了引擎及其版本（如您所見，我們的計算機上安裝了多個引擎）。請記下此信息，因為稍后我們會將此信息用于構建步驟配置。現在，常用的方式是將您所有的配置以代碼形式存儲在源代碼控制系統下（也就是“配置即代碼”）。在 TeamCity 中，您可以使用 Kotlin DSL 執行此操作。當然，您還可以使用傳統 UI 配置，但今天我們將使用第一種方式（由于 YAML 已得到廣泛使用，并且已成為事實上的標準，我們已將它添加到最近發布的 TeamCity Pipelines – 如果您還沒有查看，請查看）。用于在 TeamCity 中構建 Cropout 的 Kotlin DSL 配置如下所示：

unrealEngine { engineDetectionMode = automatic { identifier = "5.4" } command = buildCookRun { project = "cropout/CropoutSampleProject.uproject" buildConfiguration = standaloneGame { configurations = "Development+Shipping" platforms = "Mac" } cook = cookConfiguration { maps = "Village+MainMenu" cultures = "en" unversionedContent = true } stage = stageConfiguration { directory = "./staged" } archive = archiveConfiguration { directory = "./archived" } pak = true compressed = true prerequisites = true } additionalArguments = "-utf8output -buildmachine -unattended -noP4 -nosplash -stdout -NoCodeSign" }

所有設置的作用都一目了然，但有幾項設置需要進一步說明：

• engine detection mode

我們可以在此處指定“automatic”或“manual”。前者假定您已經在代理上安裝引擎并在系統中注冊。我借此機會澄清一下“注冊 ”的含義：當您通過 EGL 安裝 Unreal Engine 或通過源代碼構建 Unreal Engine 時，此操作會寫入目標計算機上的某些文件（如果使用的是 Windows，則會寫入注冊表）。這基本上就是自動檢測模式的用途。我們讀取這些文件并發布標識符作為代理屬性，這樣一來，您稍后便可使用這些屬性為構建選擇合適的代理。“手動”模式允許您設置 Unreal Engine 根文件夾的準確路徑，當您通過源代碼構建時可能會用到該路徑。稍后我們將介紹這部分內容。

• build configuration

通過調整此參數，我們可以指定所創建構建的類型，它是單機游戲、客戶端、服務器，還是既是客戶端又是服務器組件。根據所選的值，插件將應用 -client、-server、-noserver 標志，并相應地管理 -clientconfig、-serverconfig、-config、-targetplatform 和 -servertargetplatform 參數。

到現在為止都沒問題。現在，該添加一些自動化測試并運行最終管道了。

unrealEngine { engineDetectionMode = automatic { identifier = "5.4" } command = runAutomation { project = "cropout/CropoutSampleProject.uproject" execCommand = runTests { tests = """ StartsWith:JsonConfig Input.Triggers.Released """.trimIndent() } nullRHI = true } additionalArguments = "-utf8output -buildmachine -unattended -noP4 -nosplash -stdout -NoCodeSign" }

如您所知，使用 Unreal Engine 自動化框架時，通常使用以下自動化“子命令”之一執行測試：

• RunAll – 這是一個非常簡單的命令，能夠運行所有必需的測試。
• RunFilter – 借助此命令，可以執行使用一個指定篩選器（包括 Engine、Stress、Smoke 等值）標記的測試。
• RunTests – 這是最通用的命令，因為您可以使用該命令指定要運行的測試列表（包括使用 StartsWith 的前綴篩選器、運行組篩選器和簡單的子字符串匹配）。

我們嘗試在 Kotlin DSL 中保留相同的用詞，以便 Unreal 用戶對此感到熟悉。還要指出的是，插件會即時解析測試結果，并以 TeamCity 自帶的正確顯示的格式呈現測試結果。

以下是構建結果示例：

在下方，我們可以看到發布到工件存儲的游戲二進制文件。默認情況下，工件會發布到內置存儲；但 TeamCity 還支持多種外部存儲選項。在云環境中，可以配置發布到 S3。

UI 中的最終配置將如下所示：

下面是測試運行的步驟：

由于我們已啟用 Kotlin DSL 配置并禁止在 UI 中對其進行編輯，所有設置均被禁用。

使用 BuildGraph 構建 Lyra

我們將逐步過渡到使用 Lyra 的更復雜示例。由于它是一款多人游戲，我們來構建 Linux 服務器（據我們所知，一切高性能游戲都應在 Linux 上運行！）以及 Windows 和 Linux 游戲客戶端。在前面的示例中，我們在一臺計算機上按順序運行了所有步驟。這一過程通常需要大量時間。但還有一種更好的方式，即 BuildGraph。這是一種 Unreal 方法，以聲明方式（或幾乎以聲明方式）將構建描述為一組具有依賴關系的任務。隨后，構件圖的不同部分可以共同執行，或拆分到不同的計算機上。后一種方式可以顯著加快整個構建過程的速度，特別適合大型復雜項目。BuildGraph 的優點是它會自動管理作業之間的所有中間工件。您只需要共享存儲。構建 Lyra 時，我們會將此共享存儲用于兩個目的：在單個構建中的節點之間共享數據，以及維護共享派生數據緩存 (DDC)。我們之前提到過，我們還將通過源代碼構建引擎。您通過源代碼構建引擎可能是出于多種原因，但就我們的特定情況而言，我們這樣做是因為無法使用任何方式通過引擎（從 EGL 安裝）構建 Linux 服務器（至少在撰寫這篇博文時無法實現）。這是因為此特定引擎版本未提供相應文件和 SDK。好的，序言介紹完畢 — 我們來看看代碼。項目結構和 Perforce 中的相應流如下所示（假設您已從 Epic 的 Perforce 獲取 Unreal Engine 源代碼）：

下面是我們將用于構建的 BuildGraph XML 腳本的節選。腳本的這一特定部分給出了編輯器的構建方式以及編譯所需的工具， 其中還包含幾項測試。在我們的簡單示例中，這些測試采用硬編碼。在真實場景中，您可能會將測試列表傳遞給腳本并采用更復雜的邏輯。

... ... ... ...

有關完整語法的描述，請參閱 Epic 網站。這里，我們本質上要做的是通過選項 EditorPlatforms 迭代傳遞給腳本的平臺列表，并為每個平臺構建編輯器。這部分代碼的一個有趣的功能是代理節點的 Type 屬性。

在文檔中查看此表：

因此，為了在特定代理上運行一組任務，您可以修改此字段。撰寫這篇博文時，為了確保一切正常運行，本部分需要對構建代理進行一些配置。也就是說，您應當在代理配置文件中定義兩個屬性：

• unreal-engine.build-graph.agent.type：此屬性可以是任意值（或由 ; 分隔的值列表）。相應的任務集隨后將僅在至少有一個匹配項的代理上運行。
• unreal-engine.build-graph.agent.shared-dir：前文中討論過，為了運行分布式 BuildGraph 構建，我們需要一個共享存儲位置。通過此屬性，我們可以在特定代理上設置該存儲位置的路徑。

以下是我們的 EC2 構建代理設置：

• 對于 Linux：

unreal-engine.build-graph.agent.type = CompileLinux;CookLinux;Linux unreal-engine.build-graph.agent.shared-dir = /mnt/agent-shared-dir/intermediate

• 對于 Windows（由于某些原因，將文件夾作為單獨的驅動器進行裝載導致一次 Windows 系統調用失敗，因此我們在配置中選擇了網絡共享）：

unreal-engine.build-graph.agent.type = CompileWin64;CookWin64;Win64 unreal-engine.build-graph.agent.shared-dir = \\\\fs-040b8d6dab476baf1.fsx.eu-west-1.amazonaws.com\\fsx\\

在真實場景中，可能需要區分執行烘焙的代理和執行編譯的代理，并確保它們采用合適的規范。我們來快速瀏覽一下游戲的編譯、烘焙和封裝過程。在我們的腳本中，我們已將構建客戶端的邏輯和構建服務器的邏輯分開（因為它們傳遞的標志不同）：

腳本本身不需要過多解釋。我們會迭代希望客戶端在其上運行的平臺列表，該列表會再次作為選項傳遞。我們針對每個平臺進行編譯、烘焙資源，最后將一切封裝起來。作為封裝過程的最后一步，我們使用服務消息將構建的客戶端作為 TeamCity 構建工件發布。您可能已經注意到，在這部分腳本中，我們有三個代理代表構建過程的三個階段（編譯、烘焙和封裝）。編譯需要使用屬于編輯器的工具，但不需要編輯器本身：

同時，烘焙過程需要實際的編輯器：

由于這兩個過程之間沒有依賴關系，它們可以在不同的計算機上并行運行（在有足夠多的計算機可用的情況下）。這一簡單示例演示了使用 BuildGraph 的強大功能：您只需描述共享依賴項的各項工作，然后它們就會同時運行。為了簡潔起見，我們不會顯示包含服務器部分的腳本的其余部分，因為這部分內容與我們剛才描述的內容非常相似，只有標志集合不同。最后，我們要介紹 TeamCity 中的插件配置。由于大部分工作已在 BuildGraph XML 腳本中描述，DSL 配置相當簡單：

params { param("env.UE_SharedDataCachePath", "/mnt/agent-shared-dir/ddc") param("env.UE-SharedDataCachePath", "\\\\fs-040b8d6dab476baf1.fsx.eu-west-1.amazonaws.com\\fsx\\ddc") } steps { unrealEngine { id = "Unreal_Engine" name = "Build" engineDetectionMode = manual { rootDir = "engine" } command = buildGraph { script = "game/BuildProject.xml" targetNode = "BuildProject" options = """ ProjectPath=%teamcity.build.checkoutDir%/game ProjectName=Lyra ClientPlatforms=Linux+Win64 ServerPlatforms=Linux EditorPlatforms=Linux+Win64 TargetConfigurations=Shipping """.trimIndent() mode = UnrealEngine.BuildGraphMode.Distributed } additionalArguments = "-utf8output -buildmachine -unattended -noP4 -nosplash -stdout -NoCodeSign" } }

在這里，指定我們希望在分布式模式下運行提供的 BuildGraph 腳本。但我們可以根據自己的意愿隨時選擇在一臺計算機上按順序運行所有節點。我們還指定了一些環境變量，如果引擎要啟用共享 DDC，則需要使用這些變量。這些文件夾應當已裝載到連接至 TeamCity 的代理。現在，您可以為我們的游戲傳遞以下包含三個平臺選項的列表：ClientPlatforms、ServerPlatforms 和 EditorPlatforms。UI 中的顯示如下：

啟動構建時，我們會獲得此構建鏈：

因此，如我們所見，插件已將構建圖轉換為適當的 TeamCity 構建鏈。

我們可以在指定構建的相應標簽頁上查看已發布的工件。Linux 服務器的顯示如下：

在結束之前，我們想強調一些要點，請您務必牢記：

• 為了確保 BuildGraph 分發過程正常運行，您的構建配置應僅包含一個有效構建步驟。
• 目前，該插件不會以任何方式管理共享存儲中生成的工件的保留期。您負責正確設置保留期。
• 這篇博文中的示例絕不可用于生產。您的真實場景可能會更加復雜。但這些示例可作為一個良好的起點。

立即試用！

您可以從 GitHub 倉庫中獲取這篇博文中展示的演示代碼。如果您想嘗試用于 TeamCity 的 Unreal Engine 插件，可從 JetBrains Marketplace 下載，并在 TeamCity On-Premises 服務器上安裝。[如需獲取更多支持，請咨詢TeamCity代理商-龍智]對于 TeamCity Cloud 用戶，我們已預裝了 Unreal Engine 插件，您只需添加 Unreal Engine 構建步驟便可使用此插件。需要提醒您的是，TeamCity Cloud 代理沒有預裝 Unreal Engine，因此您需要使用自托管代理運行 Unreal Engine 構建。針對一直使用預覽版插件（從 0.x.x 開始的任何版本）的用戶的重要說明：請注意，由于我們在 1.0.0 版中進行了更改并重新設計了多個功能，您的現有配置將被破壞。您可能需要使用新版插件重新創建這些配置。

后續計劃

首先，我們期待收到您的反饋。您可以隨時聯系我們：通過我們的問題跟蹤器提交工單或對這篇博文發表評論。

我們對今后的工作還有一些想法，包括：

提供更加深入的構建日志分析。

包含與 UnrealGameSync (UGS) 的集成，添加構建狀態發布等功能，以及提供開箱即用的元數據服務器。

添加對構建計算機上可用 SDK 的檢測，可能會使用整體解決方案。

了解 Gauntlet 自動化框架以及我們可以在其中執行的操作。

了解我們如何利用 Epic Games 推出的構建過程中的最新進展，即查看 Unreal Build Accelerator (UBA) 并通過 TeamCity 在代理上進行協調。

將插件開源。我們相信這將提高透明度，并從整體上創建更好的插件。此外，開源會帶來很多樂趣。

本博文英文原作者：Vladislav Grinin

關于 TeamCity

TeamCity 是一款強大的持續集成和部署服務器，面向以 DevOps 為中心的團隊提供開箱即用的測試智能、構建問題的實時報告以及無與倫比的可擴展性。安裝和部署 TeamCity，幾分鐘之內即可開始構建您的 DevOps 管道。TeamCity 提供本地部署和基于云的版本。