Ichizokuは日本唯一のSentry公認販売業者です。日本語のドキュメント、動画、サポート窓口で日本のお客様のSentry活用を支援します。

GitHub Actionsを使った Sentry Unreal Engine SDKの構築

03/14/2025

ゲーム開発者にとって、シームレスなプレイヤー体験を提供することは非常に重要です。しかし、予期しないクラッシュやパフォーマンスの問題がゲームの評判を損ない、プレイヤーのエンゲージメントを妨げることがあります。

この問題に対処するためには、複数のプラットフォームで積極的なエラーモニタリングが必要です。

幸い、SentryはUnreal Engine専用に設計された強力なSDKを提供しており、開発者がデバッグとパフォーマンスの維持を効果的に行えるよう支援します。

しかし、Unreal Engine用のSDKを構築するのは容易ではありませんでした。設計時には、Unreal Engineの独特なアプリケーション構造やゲーム開発者が直面する課題を考慮しました。しかし、Sentryを真に効果的にするためには、開発中のエディタモードと製品版のゲームをさまざまなプラットフォームで動作させるために、エンジンとシームレスに統合する方法を見つける必要がありました。

本記事では、ゲーム開発者向けのデバッグソリューションを構築する際の課題と機会について解説します。以下のような方々にとって有益な内容となっているはずです。

Unreal Engine用のSDKを開発したい方
カスタムエンジンのプラグインにサードパーティライブラリを統合したい方
反復的なタスクを自動化し、開発ワークフローを効率化したい方
次世代の対策ゲームを支えるプラットフォームの構築方法に関心がある方

また、SentryのUnreal Engine SDKがサポートする以下のプラットフォーム向けのビルドとテストについても紹介します。

Android
iOS
macOS (x64 / arm64)
Linux (x64 / arm64)
Windows (x64)

注意: 本記事ではSentryのUnreal Engine SDKのすべての機能を説明していますが、フル活用するにはGitHubのリリースページからSDKをインストールする必要があります。Epic GamesのFab（旧Marketplace）で提供されているバージョンには一部制限があります。詳細については公式ドキュメントをご覧ください。

SentryのUnreal Engine SDKのアーキテクチャ設計

SentryのUnreal Engine用SDKは、ゲーム内クラッシュをキャプチャするためのクロスプラットフォームソリューションです。

複数のSentryネイティブSDKの上に構築された抽象化レイヤーとして機能し、統一されたC++/Blueprints APIを提供します。これにより、プラットフォーム固有の低レベルな実装に煩わされることなく、Unrealプラグインの設定に集中できます。

Sentry Unreal SDKには、ゲームビルド完了時にデバッグ情報ファイルを自動アップロードするSentry CLIも含まれています。

これらのデバッグファイルには、オリジナルの関数名、行番号、ファイルパス、スタックトレース、コールフレーム情報（CFI）などが含まれ、Sentryはこれらの情報を利用して、問題解決のための有益な洞察を提供します。

さらに、Unreal SDKはUnreal専用に構築されているため、SDKを導入するとAPIを呼び出し、エディタ内の自動インストゥルメンテーション機能を利用できます。

Sentryプラグインを使うことで、エディタメニューからデバッグシンボルのアップロードやUnreal Engineのログシステム用リスナーの追加などが簡単に行えます。

〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜

開発中のゲームに統合する前に、Sentry Unreal SDKを試してみたい場合は、プラグインのリポジトリに含まれているサンプルゲームをご利用ください。こちらのサンプルゲームは、SDKの開発中にも実際に使用されているものです。

GitHub Actionsを活用してSDKの信頼性を確保

ゲーム開発において、GitやGitHubは必ずしも業界標準ではありません。しかし、ゲーム開発のサポート（例：モニタリング）を強化するために、豊富なツールやクラウドサービスのエコシステムを活用しない手はありません。

特に、Sentry SDK（Unreal Engine SDKを含む）は、GitHub Actionsを利用して、ビルド、テスト、リリースなどの一般的なCI/CDタスクを自動化しています。これにより、開発や保守にかかる手作業を大幅に削減し、より効率的なワークフローを実現しています。

GitHub Actionsは、YAMLファイルで定義された宣言型ワークフローを使用します。これらのワークフローは、リポジトリ内の .github/workflows ディレクトリに配置され、指定されたトリガーによって実行されます。

各ワークフローは、実行タイミングを指定するトリガーと、実行するタスクを定義したジョブで構成されています。

もちろん、私たちのUnreal SDKには、ゲームエンジンのサポートを構築するために特有のワークフローがいくつか存在します。

これらのプロセスを自動化することで、開発者は手作業の負担を減らし、Unreal Engine SDKの品質を維持しながら、迅速なアップデートや改善を行うことができます。

プラットフォーム固有のSentry SDKの追加依存関係の管理

私たちのUnreal SDKは、ターゲットとするすべてのプラットフォームでゲームを効果的に監視するために、他のSentry SDKに大きく依存しています。

迅速な反復開発を行うFair Sourceスタートアップとして、これらの依存関係を常に最新の状態に保つことは極めて重要です。これにより、ゲーム開発者はSentryの持つ機能を最大限に活用でき、新機能の追加、最新のバグ修正、さらにはネイティブレイヤーでのパフォーマンス向上といった恩恵を受けることが可能になります。

一部の依存関係は、GitサブモジュールとしてUnreal Engine SDKに統合されており、メインリポジトリ内で管理されています。この仕組みにより、それぞれのバージョンを容易に管理・更新することができます。

これらの依存関係を常に最新に保つために、私たちはupdate-dependencies.ymlというGitHub Actionsのワークフローを活用しています。

このワークフローは、日次かメインブランチへのマージ時に実行されます。

これにより、Unreal Engine SDKの依存関係が常に最新の状態に保たれ、変更履歴（changelog）の競合が発生しないようにしています。

〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜〜

ワークフローヒント：依存関係には updater.yml を使用する

私たちの update-dependencies.yml ワークフローでは、updater.yml を呼び出していることにお気づきかもしれません。これはカスタムアクションで、サブモジュール内のリリースタグと対応するベースリポジトリのタグを比較し、指定された依存関係が最新かどうかを確認します。新しいバージョンが見つかった場合、このアクションはサブモジュールを最新のタグに更新し、変更履歴（changelog）を反映したプルリクエストを作成します。

また、Unreal Engine SDK を最新のSentryネイティブSDKの変更に合わせるだけでなく、sentry-cliのアップデートも追跡する必要があります。

ただし、Unrealプラグインではビルド済みの実行ファイルのみを使用しているため、SDKのリポジトリに新たなサブモジュールを追加する必要はありません。代わりに、sentry-cli.propertiesというシンプルなファイルでバージョンを管理しています。

updater カスタムアクションを活用することで、依存関係のチェック方法を柔軟に設定できます。sentry-cli の場合、updater はplugin-dev/sentry-cli.properties ファイルからバージョン情報を取得し、リポジトリの最新の公開タグと比較します。

その後、プロパティファイルのバージョン情報をもとに、必要な Sentry CLI のバイナリをリポジトリのリリースページからダウンロードするスクリプトが実行されます。

Unreal Engineパッケージコンテンツの準備と検証

すべての依存関係が最新の状態になったら、それらをUnreal Engine SDKで利用できる形に処理する必要があります。ネイティブSDKやAndroid SDKなどの一部の依存関係は、エンジンとの互換性を確保するためにCI環境でビルドする必要があり、少し手間がかかります。

一方で、Sentry CLIやApple/Cocoa SDKのような依存関係は、必要なバイナリをダウンロードするだけで簡単に統合できます。

このプロセスを実行するのが、継続的インテグレーション（CI）のGitHub Actionである ci.yml です。

これはUnreal Engine SDK の CIパイプライン全体において重要な役割を果たします。最初に、実際の依存関係の準備を担当するジョブのセットがあり、プラグインがサポートする各プラットフォームごとに1つずつ設定されます。

このプロセスの詳細な処理は、sdk-download.yml と sdk-build.yml のワークフローで管理されています。

これらのワークフローでは、環境のセットアップ、特定のサブモジュールの取得、ライブラリのビルド、生成されたアーティファクトのGitHubキャッシュへの保存などを行います。

すべてのSDK依存関係がダウンロード・ビルドされた後、プラグインのソースコードを、これまでに生成されたすべてのアーティファクトと共に、サポートされている各エンジンバージョン用にパッケージ化する必要があります。

このパッケージが最終的な成果物となり、ユーザーはGitHubのリリースページからダウンロードするか、Epic Games Launcherを通じてプラグインをインストールする際に取得しましょう。

最後に、プラグインパッケージの完全性を確認するため、事前に定義されたスナップショットと比較し、不足しているファイルや新しく追加されたファイルがないかをチェックします。

不一致が見つかった場合、CIパイプラインは失敗し、ゲーム開発者が常に正常に動作する完全なバージョンのプラグインのみを使用できるようにします。

ただし、このチェックは意図的に失敗する場合もあります。たとえば、新しいスクリプトやアセットをプラグインに追加した際には、スナップショットとの差分が発生するためです。そのような場合は、ローカルで test-contents.ps1 スクリプトを accept という引数を付けて実行し、新しいスナップショットの内容を受け入れることができます。その後、変更をブランチにコミットすれば、CIのチェックを通過できるようになります。

最終的に、成功したCIグラフは次のように表示されます。

Unreal Engineコンテナでのビルド・テスト・実行

ここまで進んだということは、Unreal Engine SDKがUnreal Engineで使用できるように正しくパッケージ化されたことを意味します。しかし、実際に使用する前に、エラーなくコンパイルできることを確認し、テストを実行する必要があります。

この作業に役立つのがUnreal Engine用のDockerコンテナです。これにより、必要なツール、ライブラリ、そして何よりもSentry SDKをビルドするためのUnreal Engine本体を含んだ再現性のある環境が提供されます。

Sentry Unreal Engine SDKは、現在4.27から5.5（執筆時点の最新バージョン）までのすべての Unreal Engine のバージョンに対応しています。Epic Games は、Unreal Engine Marketplaceのパブリッシャー（開発者）に対して、最新の3つのエンジンバージョンのみをサポートすることを求めていますが、私たちはより幅広いサポートを提供し、多くのゲームの長いライフサイクルに対応しています。これらのリリースはGitHubのリリースページで確認できます。

また、Unreal Engine のバージョン変数に基づいて、1つのジョブ定義内で複数のジョブを実行するために、マトリックス戦略を使用していることにもご注目ください。

GitHub ActionsでUnrealコンテナを扱う際は、以下の点にご注意ください。

ディスクスペースの確保
デフォルトのGitHubランナーにはストレージ制限があるため、Unreal Engineコンテナイメージをプルする前にディスクスペースを確保してください。
「スリム」バージョンであっても、イメージサイズは最大40GBに達することがあります。
権限の管理
GitHubランナーとUnreal Engineコンテナ間でボリュームを共有する際、権限の問題を避けるため、rootユーザーを使用しないでください。代わりに、親GitHub ActionのユーザーIDでコンテナを起動し、Unreal Engine のパスをコンテナ内でchownしてください。
IPv6の有効化（Unreal Engine 5.4以降）
Unreal Engine 5.4以降では、コンテナを正常に起動させるためにIPv6を有効にする必要があります。

コンテナが起動して稼働したら、実際のSDKビルドやテストの実行はシンプルです。
いくつかのUAT（Unreal Automation Tool）やエディタコマンドを呼び出すだけで完了します。

私たちのSDKでは、この工程の最後に、ビルドログや自動テストのレポートを収集します。これらは、後でこの段階で問題が発生した場合に、より詳細な分析を行うために使用できます。

【まとめ】Sentry Unreal Engine SDKは本日から利用可能！

以上が、Sentry Unreal Engine SDKの設計、構築、パッケージ化までの流れを説明しました。

この過程で得た知見を活かしながら、ぜひUnreal Engineの開発にご活用ください！プラグインのインストール方法や導入手順に関するドキュメントも用意しています。

また、私たちのGitHub Actionsのワークフローファイルをチェックして、Unreal Engine での自動化のヒントを見つけてみてください。そして是非、Discordで共有してください！

※本記事はUSにて2024/12/10に公開

【今後の展望】ゲーム開発者のデバッグをさらに効率化

現在のUnreal Engine SDKのデプロイプロセスは、Sentry Unreal Engine SDKの自動化機能を十分にカバーしていますが、さらなる強化も計画しています！

スモークテストの導入
ユニットテストには十分な信頼性がありますが、さらに自動化された統合テストを追加することが可能です。
Sentryプラグインを統合したUnreal Engineゲームのクラッシュモニタリングがあらゆる環境でも確実に機能することを保証します。詳細はGitHubのIssueをご覧ください。
このプロセスは、Unityで実施したものと似ています。Unityでは、新しくビルドされたパッケージを用いて完全なゲームを構築し、シンボルのアップロードやクラッシュ処理機能の動作をテストしました。
他プラットフォームへの拡張
今回のSentry SDKの新しいパッケージング方法により、ワークフローをサポート対象のすべてのプラットフォーム（ゲームコンソールを含む）に拡張できる可能性が見えてきました。ただしゲームコンソール向けには開発キット（devkits）を使用した自社ホスティングのビルドエージェントが必要となるため、さらなる準備が求められます。