龍智是JetBrains授權(quán)合作伙伴、Perforce授權(quán)合作伙伴，為您提供TeamCity、Perforce Helix Core等熱門的游戲開(kāi)發(fā)工具及一站式服務(wù)

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

在這款新插件的開(kāi)發(fā)過(guò)程中，JetBrains一直與多位游戲開(kāi)發(fā)客戶保持密切聯(lián)系，以確保它符合從事實(shí)際 Unreal Engine 項(xiàng)目工作的 DevOps 團(tuán)隊(duì)的需求。

為 Unreal Engine 游戲設(shè)置合適的構(gòu)建管道可能是一項(xiàng)艱巨的任務(wù)，特別是對(duì)于那些在平臺(tái)獨(dú)特性方面經(jīng)驗(yàn)有限的人來(lái)說(shuō)。本文，我們將帶您了解基本設(shè)置，同時(shí)會(huì)展示該插件的功能，并演示分布式 BuildGraph 支持等高級(jí)功能。

主要功能

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

• 專為最常見(jiàn)用例（BuildCookRun、BuildGraph 和自動(dòng)化測(cè)試）定制的專用運(yùn)行程序。
• 基于 BuildGraph 描述構(gòu)建發(fā)行版。
• 即時(shí)自動(dòng)化測(cè)試報(bào)告。
• 自動(dòng)發(fā)現(xiàn)構(gòu)建計(jì)算機(jī)上的 Unreal Engine 安裝。
• 兼容最新的 5.x 版 Unreal Engine，還支持 4.x 版本。

演示

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

使用 BuildCookRun構(gòu)建 Cropout

構(gòu)建 Unreal 項(xiàng)目通常涉及多個(gè)?步驟，例如：

• 采用指定配置針對(duì)目標(biāo)平臺(tái)進(jìn)行編譯。
• 資源烘焙（將所有資源轉(zhuǎn)換為可在目標(biāo)平臺(tái)上讀取的資源）。
• 將項(xiàng)目封裝為合適的分發(fā)格式。
• 等等。

當(dāng)然，之后還要進(jìn)行測(cè)試！首先，我們來(lái)看一個(gè)簡(jiǎn)單的場(chǎng)景，并使用標(biāo)準(zhǔn) BuildCookRun 命令在一臺(tái)計(jì)算機(jī)上按順序運(yùn)行所有階段。對(duì)于此場(chǎng)景，我們將使用撰寫這篇博文時(shí)可以獲取的最新普通版 Unreal Engine，并通過(guò) EGL（Epic Games 啟動(dòng)器）進(jìn)行安裝。將代理成功連接到 TeamCity Cloud 服務(wù)器后，我們可以在 Agents（代理）標(biāo)簽頁(yè)中看到它。

現(xiàn)在，我想簡(jiǎn)單探討一下代理的一些屬性。

查看上圖，我們可以看到代理發(fā)現(xiàn)了引擎及其版本（如您所見(jiàn)，我們的計(jì)算機(jī)上安裝了多個(gè)引擎）。請(qǐng)記下此信息，因?yàn)樯院笪覀儠?huì)將此信息用于構(gòu)建步驟配置。現(xiàn)在，常用的方式是將您所有的配置以代碼形式存儲(chǔ)在源代碼控制系統(tǒng)下（也就是“配置即代碼”）。在 TeamCity 中，您可以使用 Kotlin DSL 執(zhí)行此操作。當(dāng)然，您還可以使用傳統(tǒng) UI 配置，但今天我們將使用第一種方式（由于 YAML 已得到廣泛使用，并且已成為事實(shí)上的標(biāo)準(zhǔn)，我們已將它添加到最近發(fā)布的 TeamCity Pipelines – 如果您還沒(méi)有查看，請(qǐng)查看）。用于在 TeamCity 中構(gòu)建 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" }

所有設(shè)置的作用都一目了然，但有幾項(xiàng)設(shè)置需要進(jìn)一步說(shuō)明：

• engine detection mode

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

• build configuration

通過(guò)調(diào)整此參數(shù)，我們可以指定所創(chuàng)建構(gòu)建的類型，它是單機(jī)游戲、客戶端、服務(wù)器，還是既是客戶端又是服務(wù)器組件。根據(jù)所選的值，插件將應(yīng)用 -client、-server、-noserver 標(biāo)志，并相應(yīng)地管理 -clientconfig、-serverconfig、-config、-targetplatform 和 -servertargetplatform 參數(shù)。

到現(xiàn)在為止都沒(méi)問(wèn)題。現(xiàn)在，該添加一些自動(dòng)化測(cè)試并運(yùn)行最終管道了。

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 自動(dòng)化框架時(shí)，通常使用以下自動(dòng)化“子命令”之一執(zhí)行測(cè)試：

• RunAll – 這是一個(gè)非常簡(jiǎn)單的命令，能夠運(yùn)行所有必需的測(cè)試。
• RunFilter – 借助此命令，可以執(zhí)行使用一個(gè)指定篩選器（包括 Engine、Stress、Smoke 等值）標(biāo)記的測(cè)試。
• RunTests – 這是最通用的命令，因?yàn)槟梢允褂迷撁钪付ㄒ\(yùn)行的測(cè)試列表（包括使用 StartsWith 的前綴篩選器、運(yùn)行組篩選器和簡(jiǎn)單的子字符串匹配）。

我們嘗試在 Kotlin DSL 中保留相同的用詞，以便 Unreal 用戶對(duì)此感到熟悉。還要指出的是，插件會(huì)即時(shí)解析測(cè)試結(jié)果，并以 TeamCity 自帶的正確顯示的格式呈現(xiàn)測(cè)試結(jié)果。

以下是構(gòu)建結(jié)果示例：

在下方，我們可以看到發(fā)布到工件存儲(chǔ)的游戲二進(jìn)制文件。默認(rèn)情況下，工件會(huì)發(fā)布到內(nèi)置存儲(chǔ)；但 TeamCity 還支持多種外部存儲(chǔ)選項(xiàng)。在云環(huán)境中，可以配置發(fā)布到 S3。

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

下面是測(cè)試運(yùn)行的步驟：

由于我們已啟用 Kotlin DSL 配置并禁止在 UI 中對(duì)其進(jìn)行編輯，所有設(shè)置均被禁用。

使用 BuildGraph 構(gòu)建 Lyra

我們將逐步過(guò)渡到使用 Lyra 的更復(fù)雜示例。由于它是一款多人游戲，我們來(lái)構(gòu)建 Linux 服務(wù)器（據(jù)我們所知，一切高性能游戲都應(yīng)在 Linux 上運(yùn)行！）以及 Windows 和 Linux 游戲客戶端。在前面的示例中，我們?cè)谝慌_(tái)計(jì)算機(jī)上按順序運(yùn)行了所有步驟。這一過(guò)程通常需要大量時(shí)間。但還有一種更好的方式，即 BuildGraph。這是一種 Unreal 方法，以聲明方式（或幾乎以聲明方式）將構(gòu)建描述為一組具有依賴關(guān)系的任務(wù)。隨后，構(gòu)件圖的不同部分可以共同執(zhí)行，或拆分到不同的計(jì)算機(jī)上。后一種方式可以顯著加快整個(gè)構(gòu)建過(guò)程的速度，特別適合大型復(fù)雜項(xiàng)目。BuildGraph 的優(yōu)點(diǎn)是它會(huì)自動(dòng)管理作業(yè)之間的所有中間工件。您只需要共享存儲(chǔ)。構(gòu)建 Lyra 時(shí)，我們會(huì)將此共享存儲(chǔ)用于兩個(gè)目的：在單個(gè)構(gòu)建中的節(jié)點(diǎn)之間共享數(shù)據(jù)，以及維護(hù)共享派生數(shù)據(jù)緩存 (DDC)。我們之前提到過(guò)，我們還將通過(guò)源代碼構(gòu)建引擎。您通過(guò)源代碼構(gòu)建引擎可能是出于多種原因，但就我們的特定情況而言，我們這樣做是因?yàn)闊o(wú)法使用任何方式通過(guò)引擎（從 EGL 安裝）構(gòu)建 Linux 服務(wù)器（至少在撰寫這篇博文時(shí)無(wú)法實(shí)現(xiàn)）。這是因?yàn)榇颂囟ㄒ姘姹疚刺峁┫鄳?yīng)文件和 SDK。好的，序言介紹完畢 — 我們來(lái)看看代碼。項(xiàng)目結(jié)構(gòu)和 Perforce 中的相應(yīng)流如下所示（假設(shè)您已從 Epic 的 Perforce 獲取 Unreal Engine 源代碼）：

下面是我們將用于構(gòu)建的 BuildGraph XML 腳本的節(jié)選。腳本的這一特定部分給出了編輯器的構(gòu)建方式以及編譯所需的工具， 其中還包含幾項(xiàng)測(cè)試。在我們的簡(jiǎn)單示例中，這些測(cè)試采用硬編碼。在真實(shí)場(chǎng)景中，您可能會(huì)將測(cè)試列表傳遞給腳本并采用更復(fù)雜的邏輯。

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

有關(guān)完整語(yǔ)法的描述，請(qǐng)參閱 Epic 網(wǎng)站。這里，我們本質(zhì)上要做的是通過(guò)選項(xiàng) EditorPlatforms 迭代傳遞給腳本的平臺(tái)列表，并為每個(gè)平臺(tái)構(gòu)建編輯器。這部分代碼的一個(gè)有趣的功能是代理節(jié)點(diǎn)的 Type 屬性。

在文檔中查看此表：

因此，為了在特定代理上運(yùn)行一組任務(wù)，您可以修改此字段。撰寫這篇博文時(shí)，為了確保一切正常運(yùn)行，本部分需要對(duì)構(gòu)建代理進(jìn)行一些配置。也就是說(shuō)，您應(yīng)當(dāng)在代理配置文件中定義兩個(gè)屬性：

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

以下是我們的 EC2 構(gòu)建代理設(shè)置：

• 對(duì)于 Linux：

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

• 對(duì)于 Windows（由于某些原因，將文件夾作為單獨(dú)的驅(qū)動(dòng)器進(jìn)行裝載導(dǎo)致一次 Windows 系統(tǒng)調(diào)用失敗，因此我們?cè)谂渲弥羞x擇了網(wǎng)絡(luò)共享）：

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\\

在真實(shí)場(chǎng)景中，可能需要區(qū)分執(zhí)行烘焙的代理和執(zhí)行編譯的代理，并確保它們采用合適的規(guī)范。我們來(lái)快速瀏覽一下游戲的編譯、烘焙和封裝過(guò)程。在我們的腳本中，我們已將構(gòu)建客戶端的邏輯和構(gòu)建服務(wù)器的邏輯分開(kāi)（因?yàn)樗鼈儌鬟f的標(biāo)志不同）：

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

同時(shí)，烘焙過(guò)程需要實(shí)際的編輯器：

由于這兩個(gè)過(guò)程之間沒(méi)有依賴關(guān)系，它們可以在不同的計(jì)算機(jī)上并行運(yùn)行（在有足夠多的計(jì)算機(jī)可用的情況下）。這一簡(jiǎn)單示例演示了使用 BuildGraph 的強(qiáng)大功能：您只需描述共享依賴項(xiàng)的各項(xiàng)工作，然后它們就會(huì)同時(shí)運(yùn)行。為了簡(jiǎn)潔起見(jiàn)，我們不會(huì)顯示包含服務(wù)器部分的腳本的其余部分，因?yàn)檫@部分內(nèi)容與我們剛才描述的內(nèi)容非常相似，只有標(biāo)志集合不同。最后，我們要介紹 TeamCity 中的插件配置。由于大部分工作已在 BuildGraph XML 腳本中描述，DSL 配置相當(dāng)簡(jiǎn)單：

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" } }

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

啟動(dòng)構(gòu)建時(shí)，我們會(huì)獲得此構(gòu)建鏈：

因此，如我們所見(jiàn)，插件已將構(gòu)建圖轉(zhuǎn)換為適當(dāng)?shù)?TeamCity 構(gòu)建鏈。

我們可以在指定構(gòu)建的相應(yīng)標(biāo)簽頁(yè)上查看已發(fā)布的工件。Linux 服務(wù)器的顯示如下：

在結(jié)束之前，我們想強(qiáng)調(diào)一些要點(diǎn)，請(qǐng)您務(wù)必牢記：

• 為了確保 BuildGraph 分發(fā)過(guò)程正常運(yùn)行，您的構(gòu)建配置應(yīng)僅包含一個(gè)有效構(gòu)建步驟。
• 目前，該插件不會(huì)以任何方式管理共享存儲(chǔ)中生成的工件的保留期。您負(fù)責(zé)正確設(shè)置保留期。
• 這篇博文中的示例絕不可用于生產(chǎn)。您的真實(shí)場(chǎng)景可能會(huì)更加復(fù)雜。但這些示例可作為一個(gè)良好的起點(diǎn)。

立即試用！

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

后續(xù)計(jì)劃

首先，我們期待收到您的反饋。您可以隨時(shí)聯(lián)系我們：通過(guò)我們的問(wèn)題跟蹤器提交工單或?qū)@篇博文發(fā)表評(píng)論。

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

提供更加深入的構(gòu)建日志分析。

包含與 UnrealGameSync (UGS) 的集成，添加構(gòu)建狀態(tài)發(fā)布等功能，以及提供開(kāi)箱即用的元數(shù)據(jù)服務(wù)器。

添加對(duì)構(gòu)建計(jì)算機(jī)上可用 SDK 的檢測(cè)，可能會(huì)使用整體解決方案。

了解 Gauntlet 自動(dòng)化框架以及我們可以在其中執(zhí)行的操作。

了解我們?nèi)绾卫?Epic Games 推出的構(gòu)建過(guò)程中的最新進(jìn)展，即查看 Unreal Build Accelerator (UBA) 并通過(guò) TeamCity 在代理上進(jìn)行協(xié)調(diào)。

將插件開(kāi)源。我們相信這將提高透明度，并從整體上創(chuàng)建更好的插件。此外，開(kāi)源會(huì)帶來(lái)很多樂(lè)趣。

本博文英文原作者：Vladislav Grinin

關(guān)于 TeamCity

TeamCity 是一款強(qiáng)大的持續(xù)集成和部署服務(wù)器，面向以 DevOps 為中心的團(tuán)隊(duì)提供開(kāi)箱即用的測(cè)試智能、構(gòu)建問(wèn)題的實(shí)時(shí)報(bào)告以及無(wú)與倫比的可擴(kuò)展性。安裝和部署 TeamCity，幾分鐘之內(nèi)即可開(kāi)始構(gòu)建您的 DevOps 管道。TeamCity 提供本地部署和基于云的版本。