Immersive Stream For XRの継続開発で注意すること（バージョン関連）



# はじめに

Google Cloud（以下、GCP）が提供するUnrealEngine（以下、UE）をビルドからデプロイまでを全部クラウド上で管理し、そのままクラウドレンダリングで利用でき、没入感のある体験を簡単に提供できるというなんとも未来を感じるマネージドサービスであるImmersive Stream For XR（以下、is4xr）をみなさん活用していますでしょうか。

is4xrの概要や仕組みについては、[こちら](https://qiita.com/1kjwk1/items/ed4f2d9683924cf2e375)の記事をご覧ください。

is4xrでは、Googleが提供するテンプレートプロジェクトを活用して開発を行いますが、継続して開発する上で利用するテンプレートのバージョンについては注意が必要なため、そちらについて説明します。

# テンプレートバージョンについて

is4xrを利用する上で注意すべきバージョンは以下の２つです。

- UEのバージョン
- テンプレートプロジェクトのバージョン

それぞれの組み合わせは以下のようになっており、現在までに大きく2回のメジャーバージョンの更新が行われました。

Unreal Engine® version | Template version |タイミング|
-----------------------|------------------------|---|
5.3.x                  | 3.0.x                  |GAから約１年後にUE5.3にアップデートされました
5.0.x                  | 2.0.x                  |GA時にUE5.0にアップデートされました
4.2x                  | 1.x.x                  |is4xrのプレGAはUE4で開始されました

もう少し細かいアップデートの履歴はテンプレートプロジェクト内の`CHANGELOG.md`に記載されています。（このファイルでバージョンが管理されています。）

```md
# Immersive Stream for XR Template Project - UnrealEngine

## [3.0.1] - 2024-03-08

Minor changes to the ISXR_3D_Pawn, camera distance can now be modified dynamically.

## [3.0.0] - 2024-02-21

Upgraded project to Unreal 5.3 and optimized blueprint logic and files.
Added new feature demos: Session ID and AR Virtual Background.

## [2.0.9] - 2023-10-10

Included safe area visual guidance and removed camera aspect ratio constraints.

## [2.0.8] - 2023-09-21

Added landscape UI for demos and improved Autos hotspots.

## [2.0.7] - 2023-08-03

Added configurable bounding box scale for AR placement.

## [2.0.6] - 2023-07-01

Added fix for cross-platform landscape mode.

## [2.0.5] - 2023-05-30

Added an audio-video sync level to the features demo.

## [2.0.4] - 2023-05-17

New template with Cloud assets.

## [2.0.3] - 2023-03-07

Enabled Lumen by default and added minor optimizations.

## [2.0.2] - 2023-02-28

Set TSR translucency in XR_Init.

## [2.0.1] - 2023-02-07

Add Spaces template demo.

## [2.0.0] - 2023-01-19

Upgrade version for UE5.

## [1.8.6] - 2022-12-27

Set static AR lighting as default and keep dynamic as an option.

## [1.8.5] - 2022-11-09

Replace hardcoded resolution with custom resolution in Default_InterfaceHUD blueprint.

## [1.8.4] - 2022-08-23

Remove ImEdgeActions folder and ImEdgeTemplate.png in the SyncContent script.

## [1.8.3] - 2022-06-09

Remove Server_Client_UI option.

## [1.8.2] - 2022-05-25

Fixed build failures not resulting in API error.

## [1.6.1] - 2022-05-10

First public release.
```

# 注意すること


is4xrは、クラウド上でプロジェクトのビルドを行いますが、ビルドを行うビルダーのバージョンとプロジェクトに存在する`CHANGELOG.md`のファイルに記載されているバージョンがあわないとビルドが失敗します。

テンプレートプロジェクトのreadmeにも記載があります。

https://github.com/GoogleCloudPlatform/immersive-stream-for-xr-templates/tree/main?tab=readme-ov-file#engine-and-template-compatibilty

![readme](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3489259/200092b8-6732-000c-d78f-df70a53c64c0.png)

**ここで一番注意しないといけないポイントは、メジャーバージョンがあがる際に基本的に下位互換に対応しないことです。**

テンプレートのメジャーバージョンがアップデートされるタイミングでビルダー側のバージョンも自動でアップデートされるため、古いバージョンで開発している際にこのタイミングと重なると急にビルドが通らなくなるといったことが起きます。

弊社でもテンプレートバージョンの2.x（UE5.0）で開発や興行を行っており、3.x（UE5.3）にあがったことを知らず、2.x（UE5.3）で作成したプロジェクトを再利用しようと少し修正を加えてビルドしようと思ったら、突然ビルドがエラーとなりこの事象に気づくといったことが発生しました。

# Tips

- あくまでもビルダーがUEプロジェクトのビルド時チェックとしてバージョンチェックを行うため、既にビルドが完了しているコンテンツは継続して利用することができます
    - ビルド済のコンテンツは大切にしましょう
    - ビルド済コンテンツの保持自体には費用がかからない仕組みとなっています
- ビルダーと`CHANGELOG.md`のファイル内のバージョンでチェックを行うため、意図せずテンプレートが新しくなってしまった場合に、`CHANGELOG.md`の最新バージョンのファイルだけ差し替えしてビルドを通すという荒技があります
    - メジャーバージョンがアップデートされるタイミングがUE側もアップデートされるタイミングなので、利用している機能によってはビルドが成功してもUEとして正常に動作しないこともありますが緊急時には試してみる価値があります

# 動作確認

実際に`CHANGELOG.md`の内容を編集してビルダーの動きを確認します。

## `CHANGELOG.md`のバージョンを下げる

現在3.x系になっていますので、3.x系に関わる以下の記述部分を削除して、2.0.9が最新になるように修正します。

```
## [3.0.1] - 2024-03-08

Minor changes to the ISXR_3D_Pawn, camera distance can now be modified dynamically.

## [3.0.0] - 2024-02-21

Upgraded project to Unreal 5.3 and optimized blueprint logic and files.
Added new feature demos: Session ID and AR Virtual Background.
```

## コンテンツのビルド

`CHANGELOG.md`以外のファイルについてはテンプレートそのままでGCSバケットにアップロードしてコンテンツのビルドを実行します。

基本的な利用方法などについてはこちらもご確認ください。

https://qiita.com/1kjwk1/items/ed4f2d9683924cf2e375

## 結果

コンテンツのビルドが`失敗`となります。

![contents_error](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3489259/9d647c58-6092-5b62-8485-cc87770705db.png)

ビルドログのリンクからログを確認できます。実際にバージョンの差分で失敗していることがわかります。このチェックは最初に行われるためこの場合のビルドは10-20分程度の短い時間で終了します。

```
Detected content to be an Unreal Engine project. Builder version is 3.0.0 and unreal template project version is 2.0.9.
Major builder and template versions don't match (3.0.0 vs. 2.0.9). Aborting build.
Failed building the project.
```


:::note info
リンクを参照する際に気がつくかもですが、is4xrで管理上出力されるビルドログの情報は自身のGCPプロジェクト内のGCSバケットが自動生成されてその中に出力されます。各ビルドのログとしてテキストデータが出力されるだけなので大きなデータ量にはなりませんが、GCSバケット費用がかかるので気をつけましょう。
:::


# おわりに

is4xrを継続的に開発するために注意すべきテンプレートのバージョン管理の仕組みや動きについて説明しました。
継続的に開発する場合には、githubのテンプレートプロジェクトの更新状況を定期的に確認することをオススメします！