Wiki

Unreal Engine プラグイン

Unreal Engine 向け uVersion プラグイン：エディタ内のネイティブなバージョン管理、Blueprint 差分、Project Health 監査、そして送信を最も頻繁にブロックする 2 つのルール。

前提条件

Unreal プロジェクトは uVersion ワークスペースの「中」になければなりません これが有効化の条件であり、エディタのどこにも書かれていません。プラグインはプロジェクトから上位へさかのぼって .uversion/ フォルダを探します。見つからず、かつ以前に認証トークンが保存されていない場合、プラグインはまったく有効化されず、Unreal はバージョン管理のないままになります。これは障害ではありません。uVersion で versioning されていないあなたのプロジェクトに、勝手に割り込まないための仕組みです。プロジェクトは、desktop クライアントがクローンしたフォルダから開いてください。別の場所に置いたコピーからではありません。

実際には desktop クライアントが必須です uVersion サーバーはデフォルトで自己署名です。一方 Unreal エディタは、自己署名証明書をどう扱えばよいか分かりません。フィンガープリントのストアを持たず、それを確認してくれる者もいないからです。その結果、HTTPS サーバーでは Unreal からの直接接続は TLS で失敗し、エディタは desktop クライアントの起動を促す通知を表示します。ログインフォームは Revision Control Login ウィンドウに確かに存在しますが、この壁を越えられません。自己署名サーバーに対してそれを入力してもどこにもたどり着きません。うまくいく構成は一つだけです。desktop クライアントが動作しており、そこにログイン済みで、プラグインがそれを経由することです。1 時間を無駄にする前に、今すぐ知っておくとよいでしょう。

インストール

uVersion プラグインはプリコンパイル済みバイナリとして配布され、desktop クライアントが管理します。あなたがコンパイルする必要はなく、扱うべきソースファイルもありません。 決して versioning されません。リポジトリと一緒に届くこともなく、その中に送信してもいけません。各マシンは、その Unreal バージョンとそのシステムに対応したバイナリをインストールします。

サポートされる Unreal バージョン：5.6 以降。

1. desktop クライアントでワークスペースを開く

uVersion desktop クライアントをインストールしてログインし、Unreal プロジェクトを含むワークスペースを開きます。すべてはクライアントから行われます。ダウンロードするアーカイブも、プロジェクトに手作業で展開するものもありません。

2. クライアントにプロジェクトを検出させる

クライアントは、ワークスペースのルート以下（3 階層より深くに埋もれていないこと）であなたの .uproject（Unreal プロジェクトを記述するファイル）を探します。見つけるとすぐに、ワークスペースのタブ上部に Unreal バーが表示され、お使いの Unreal バージョンに対応したプラグインを Plugins/uVersion/ に配置します。左側のバッジにはプラグインの状態とバージョン番号が表示されます。アップデートもそこで確認できます。

desktop クライアントの Unreal バー：左に緑色の Plugin 1.0.5 バッジ、続いて Open Editor、Compile、Package、Publish Build、Sync、Status のボタン。

3. Unreal でプロジェクトを開く

プラグインはすぐに有効になります。エディタの Plugins ウィンドウでチェックを入れる必要も、再起動する必要もありません。もし見当たらないなら、それはクライアントがまだ配置していないだけであり、有効化が残っているわけではありません。

その後：アップデート

desktop クライアントは、プロジェクトを開いたときと、その後定期的に新しいバージョンを確認します。注意してください。自動チェックは、2 つのケースで同じことをするわけではありません：

プラグインが存在しない場合：何も尋ねずにインストールされます。これが初回起動をシームレスにします。
プラグインは存在するが古い場合（新バージョン、または Unreal バージョンの変更）：クライアントは 通知するだけです。インストール済みのプラグインを勝手に置き換えることは決してありません。Unreal パネルのバッジはそのとき Update ready に変わります。

アップデートを適用するには：Unreal エディタを閉じてから、バッジをクリックします。読み込み中のプラグインはディスク上で置き換えられません。エディタがまだ開いている場合、バッジには Restart UE と表示されます。

初回接続

通常のケースでは、接続すべきものは何もありません。プラグインは、プロジェクトの周囲に uVersion ワークスペースを検出するか、すでに保存されたトークンを検出した時点で、バージョン管理プロバイダーとして自らを選択します。認証情報は desktop クライアントから引き継がれ、再入力は不要です。プロジェクトを開くだけで十分です。

以下の 3 つの手順は、この自動選択が行われなかった場合にのみ必要です。

1. Revision Control メニューを開く

それはエディタのステータスバーの右下にあり、上部のメニューにはありません。上方向に開き、Submit Content を含む Unreal のアクションと、Audit Project (Project Health) エントリを備えた uVersion セクションが並びます。 Connect to Revision Control を選びます。

2. Provider リストで uVersion を選ぶ

Revision Control Login ウィンドウが開きます。Provider を展開し、 uVersion を選びます。ワークスペースが認識されると、ウィンドウは緑色で自らそれを知らせ（Automatically configured from workspace）、Workspace、Server URL、Username の各フィールドはすでに入力されています。入力するものは何もありません。

Unreal の Revision Control Login ウィンドウ：uVersion が選択された展開済みの Provider リスト、緑色の自動設定メッセージ、そして Accept Settings ボタン。

3. Accept Settings で確定する

ウィンドウ下部の Accept Settings ボタンで選択が適用され、ウィンドウが閉じます。するとステータスバーに Connected to に続いてリポジトリ名とあなたのユーザー名が表示されます。この選択は記憶されます。次回以降のプロジェクトのオープンでは、ここを再び通ることはありません。

アセットをチェックアウトして送信する

コンテンツファイルについて、エディタからの一連の流れです。コードはここからは決して送られません。コードは desktop クライアントを経由するを参照してください。

1. 始める前にアセットの状態を確認する

Content Browser の各サムネイルには、アセットの状態を示すバッジが付いています：あなたがチェックアウト中、他の誰かがチェックアウト中、あるいはサーバーに対して古い状態、のいずれかです。ツールチップには完全な文が表示され、たとえば File is out of date, sync to get the latest version のようになります。その場合はまず同期してください（右クリック、Revision Control、Sync）。古いバージョンで作業を始めることは、競合を準備することにほかなりません。

黄色いバッジが付いた Content Browser のアセットサムネイルと、ファイルが古く同期が必要であることを示すツールチップ。

2. アセットをチェックアウトする

アセットを右クリックし、Revision Control サブメニュー、次に Check Out。すべて揃っています： Sync、Check Out、Check In、History、Diff Against Depot、 Revert。他の Unreal プロバイダーとまったく同じです。アーティストが新たに覚えることは何もありません。

実際には、多くの場合あなたは何もする必要がありません。アセットを変更するとすぐに、プラグインが手動チェックアウトなしでサーバー側のロックを自動的に取得します。

Unreal の Content Browser：アセットを右クリック、Sync、Check Out、Mark For Add、Check In、History、Diff Against Depot、Revert を備えた Revision Control サブメニューと、サムネイル上の状態アイコン。

3. 送信前に比較する

Diff Against Depot は、Blueprint を含め、エディタ標準のビジュアル比較ツールを開きます。 2 つのリビジョンが並べて表示され、追加・削除・変更されたノードが囲まれます。History から、履歴上のどのコミットに対しても機能します。

Blueprint Diff ウィンドウ：同じ Blueprint の 2 つのリビジョンを並べて表示し、追加されたノードが緑色で囲まれている。

4. 送信する

右クリック、Revision Control、選択に対して Check In、またはステータスバーのメニューから Submit Content で一括送信します。ウィンドウには対象ファイルが、 削除も含めて一覧表示され、説明の入力が求められます。送信時にプラグインはリネームで残った redirector を掃除し、有効な検証ルールを実行します。error のルールがあると送信は停止し、原因となったファイルが示されます。

Unreal の送信ウィンドウ：チェックが入った送信対象ファイルの一覧、変更の説明フィールド、そして Submit ボタン。

プラグインが Unreal で行うこと

Project Health：プロジェクトを監査する

ステータスバーの Revision Control メニューには Audit Project (Project Health) エントリがあります。これはプロジェクトのアセットレジストリを アセットを 1 つも読み込むことなく走査し、健全性レポートを生成します：命名、フォルダ構造、依存関係、孤立コンテンツ、コスト。オフラインで動作し（レポートは Saved/uVersionAudit の下に書き出されます）、接続時にサーバーへ送信されて、desktop クライアントの Project Health タブに反映されます。

redirector のクリーンアップ

アセットをリネームまたは移動すると、Unreal は背後に redirector を残します。これは古いパスを新しいパスへ向ける小さな転送ファイルで、古い名前を参照していたアセットが引き続き機能するようにします。これらはすぐに溜まり、最終的にツリーを読みづらくします。プラグインはこれらを検出し、 checkin 時にクリーンアップして、影響を受けるすべてのアセットの参照を更新します。

checkin 前の検証

プラグインは、送信されたファイルに対して一連のチェックを実行できます：Blueprint のコンパイル、命名規則、テクスチャサイズ、インポート設定、欠落した依存関係、循環依存、孤立アセット、重複、マテリアルの複雑さ。全部で 9 つのルールです。error のルールは送信をブロックし、 warning のルールは確認後に許可します。

9 つのルールは無効化された状態で出荷されます 新しいリポジトリでは、すべて非アクティブの状態で作成されます。管理者が Admin パネルの Rules タブから 1 つずつ有効化するまで、どのチェックも実行されません。送信が拒否されるはずなのに何も言わずに通ってしまう場合は、まずそこを確認してください。

起動時の照合

プロジェクトを開くと、プラグインはあなたのアセットの状態をサーバーと比較します。Content/ と、プロジェクトのプラグインの Content/ を走査し、ディスク上で書き込み可能になっているアセットで、まだそうなっていなかったものをすべて自動的にチェックアウトします。目的はあなたを守ることです。あなたが変更を始めたファイルが、2 つのセッションの間にチームメイトに取られてしまうことを防ぎます。

知っておくべき結果：気づかないうちにロックを保持していることがあります この自動チェックアウトは静かに行われ、しかもuVersion のロックは決して期限切れになりません。checkin、revert、または管理者による強制ロック解除によって明示的に返却されるまで保持され続けます。どんなタイムアウトでも解放されません。したがって、書き込み可能なファイルがいくつか放置されたプロジェクトでエディタを開くだけで、何の合図もないままチーム全体に対してそれらのファイルをロックしてしまうのに十分です。desktop クライアントの Pending タブ、My Pending Changes リストを確認し、作業していないものは返却する習慣をつけてください。

コードは Unreal ではなく desktop クライアントを経由する

プラグインはコードファイルの送信を拒否します：.cpp、.h、 .hpp、.c、.cs。試みは、原因となったファイルを示すブロッキングウィンドウで停止します。これは欠陥ではありません。desktop クライアントは送信前にコンパイルし、チームメイトが同期時に取得するエディタバイナリを公開します。エディタから送られたコードのコミットは、その両方を素通りしてしまい、チーム全体に対するバイナリの配布を停止させてしまいます。

ですからコードは desktop クライアントから送信してください。一方、コンテンツファイルは Unreal から自由に送信できます。

落とし穴：チェックアウト中のコードファイルが 1 つあるだけで、コンテンツの送信もブロックされます このルールは、あなたが送信するファイルにとどまりません。コードファイルのチェックアウトを保持している限り、たとえ 1 つでも、たとえ手を触れていなくても、たとえ送信に含まれていなくても、Unreal からのあらゆる checkin が拒否されます。純粋な .uasset の送信であってもです。メッセージは、まず desktop クライアントからコードを送信するよう伝えます。

これは最も一般的なブロックであり、コードを書かない人にも平気で降りかかります。ソースファイルがディスク上で書き込み可能になっただけで、起動時の照合がそれを自動でチェックアウトしてしまうからです。理由は本物です。未送信のコードに対して保存されたアセットは、それを同期するすべての人を壊します。彼らのバイナリには、そのアセットが依存するコードがないからです。

解除方法：desktop クライアントの Pending タブ、 My Pending Changes リストを開き、コードファイルを見つけて、変更したなら Checkin Selected、手を触れていないなら Revert を行います。その後、コンテンツの送信は通常どおり進みます。エディタがロックのビューを更新するまで、数秒かかることがあります。

desktop クライアントの Pending タブ：2 つの .h ファイルが .uasset と並ぶ My Pending Changes リストで、それぞれに Revert ボタンがあり、下方には Other Users' Locks セクションがある。

よくある問題

uVersion メニューがない：エディタがバージョン管理を無視する

プロジェクトはおそらく uVersion ワークスペースの中にありません。クローンしたフォルダのルートに .uversion/ フォルダが存在すること、そして別の場所に置いたコピーではなく、そのフォルダからプロジェクトを開いていることを確認してください。

「Failed to connect to source control」

desktop クライアントが起動していて、そこにログイン済みであることを確認してください。あなたの認証情報を保持し、自己署名サーバーと対話できるのはそちらです。ワークスペースを所有するアカウントがクライアントにログインしていない場合、プラグインは別の identity で作業することを拒否します。これは意図された動作です。

コードに一切触れていないのに送信が拒否される

あなたはコードファイルのチェックアウトを保持しています。コードは desktop クライアントを経由するを参照してください。

他の誰かがロックしたアセットが欲しい

これは Unreal からは依頼できません。プラグインには解放リクエストの機能がありません。 desktop クライアントの Pending タブ、Other Users' Locks セクションで、ファイルの行にある Request Release ボタンを使ってください。保持者は Production ボードのカードとしてリクエストを受け取ります。

プラグインがアップデートされない

これは想定どおりの動作です。自動チェックは不足しているプラグインをインストールしますが、アップデートについては通知するだけです。Unreal エディタを閉じ（読み込み中のプラグインは置き換えられません）、次に desktop クライアントの Unreal バーにある Update ready バッジをクリックして適用してください。

検証ルールが一度も発火しない

9 つのルールは無効化された状態で出荷されます。管理者が Admin パネルの Rules タブからプロジェクトごとに有効化する必要があります。