Zenn
📑

[UEFN]URCコマンドラインツールを使ってみる

2023/07/02に公開
Unreal Engine
#
uefn
tech

はじめに

本記事では、URCと略されるUnreal Revision Controlについて、少しだけ詳しく見ていこうと思います。

UEFNの作業時に、編集をした覚えがないファイル(特にOFPAで管理されるファイル)が、意図せず未保存かつチェックアウト状態に自動でなってしまう現象に悩まされたことがきっかけで、URCについて調べ、そのまとめとして本記事を書くことにしました。(後ほど、どのように対処したかも書くことにします。)

Unreal Revision Control (URC)

Unreal Revision Control を使用すると、プロジェクトおよび個々のプロジェクト ファイルに加えられた変更を安全に追跡できます。リビジョン コントロールでは、変更の履歴を保持し、誰がどのファイルを、いつ、なぜ変更したかを追跡します。

UEFNでのコンテンツ制作では、URCは必須で共同開発のファイル共有と、途中でファイルが壊れたり昔のバージョンに戻りたいときに非常に便利です。(ちなみに、現在Unreal Engineでは、このツールは提供されていません!)

https://dev.epicgames.com/documentation/ja-jp/uefn/unreal-revision-control-best-practices-in-unreal-editor-for-fortnite

URCやリビジョン管理ツールには一般に、ファイルのロックシステムというものがあります。

これは、ほかの作業者が特定のファイルを操作するときに、その人以外がそのファイルを操作することを防ぎ、どちらか一方と操作が台無しにならないようにしてくれます。

一方で、このロックの仕組みがほかの作業者の作業の障壁になることも多々あります。意図せず、他人がファイルをロック(チェックアウト)していると、そのファイルを操作することができなくなり、作業が進みません。また、初めに例示したように、特定のファイルが自動でチェックアウトされる可能性もあります。

チェックアウト/ ロックのリリース

操作したいファイルがロックされている場合、誰がロックしているのかがアウトライナーのリビジョンコントロールアイコンにマウスをホバーすると確認することができます。もし、該当のファイルを操作したい場合は、ここの表示されている人に対して、チェックアウト(ロック)を外してもらうように依頼すると良いです。(revertするか変更をsubmitしていただくなど)

ただし、その人が寝てしまっている時は、プロジェクトから外れてしまったとき、ロックを外しても再度勝手にチェックアウトされてしまう場合などで、どうしても操作をしたいときは、管理者によってこのロックを外す方法があります。

このような時に、URCのコマンドラインツールが有効です。
https://dev.epicgames.com/documentation/ja-jp/uefn/unreal-revision-control-command-line-interface-in-unreal-editor-for-fortnite

URC コマンドラインインターフェイス

ここでは、上記のコマンドラインインターフェイスドキュメントに書かれているように、環境変数として、urc.exeへのパスが通っていることと、操作を実行したいEpicアカウントでログインされていることを前提に説明します。もしまだの場合は、ドキュメントに従って設定を行なってください。

Windowsの場合は、以下のコマンドをPowerShellから実行することで、特定のユーザーのチェックアウトを外すことができます。(ただし管理者権限が設定されている場合のみ実行できます)

urc project forcerelease <project-id> --user <username>

project-id

ここで、project-id は、ロックを解除したいプロジェクトファイル(今回は、UrcSampleという名前のファイルになります。)の .uefnproject ファイル内に記述されています。 .uefnprojectをメモ帳などで開くと確認できます。

"bindings":
{
	"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	"modules":
	{
		"SoundShot": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
	}
}

また、別の方法として、コマンドラインからも確認ができます。

urc project status

を実行すると、project固有のidが表示されます。

username

これは、クリエイターポータルなどで確認できる、ユーザーのDisplayNameに当たります。

以上から、username_1のすべてのロック(チェックアウト)をはずしたいときは、

urc project forcerelease xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --user username_1

を実行すると、ロックをすべて外すことができます。

その他のコマンドライン

上記のコマンドは、urcのコマンドラインインターフェイスが提供する機能の一つであり、

この他にUEFNエディターで実行可能な様々な操作をurcコマンドからも実行可能です。ここでは、そのコマンドについて説明していきます。

urc コマンドには、大きく分けて以下の4つの操作が可能です。

  • auth
    ログイン・ログアウト操作
  • asset
    アセットの操作に関する操作
  • checkout
    アセットのチェックアウト関連の操作
  • project
    プロジェクトファイル全般に関わる操作

これらのコマンドについて、それぞれを見ていきます。

auth

urcを実行するアカウントの認証に関するコマンドです。

ログイン

urc auth login

ログアウト

urc auth logout

asset

urc aset delete/history/print/revert <targets>
  • delete　
    アセットの削除
  • history
    アセットの変更履歴の表示
  • print
    特定のアセットに関する情報の表示
  • revert
    現在の最新のsnapshotに該当のアセットを巻き戻す。

上記の操作が可能です。例えば、historyコマンドは、変更履歴を確認したアセットのパスを指定することで、実行できます。

urc asset history "Plugins\UrcSample\Content\__ExternalActors__\UrcSample\C\NX\YKY3FK98STV96XTQG362VL.uasset"

同様にrevertコマンドは、指定したアセットに対する巻き戻しが実行できます。

複数のアセットを一括で、巻き戻したい場合は、それらのファイルへのパスを複数列挙することで実行が可能です。

urc asset revert "Plugins/UrcSample/Content/__ExternalActors__/UrcSample/0/5B/Z90AM6UM0A21N45EOX8D66.uasset" "Plugins/UrcSample/Content/__ExternalActors__/UrcSample/0/A1/33BPV8I9QJ0TURL02GPKFI.uasset" "Plugins/UrcSample/Content/__ExternalActors__/UrcSample/0/T2/ALHTGE8M187W9BISAQ7QTH.uasset"

アセット関連のコマンドを利用すると、たまに意図せずログアウトされてしまいます。現状、原因はわかりません。

checkout

チェックアウトコマンドも同様にチェックアウトしたいアセットのパスを指定することで実行可能です。

urc checkout acquire/release <targets>
  • acquire
    該当のアセットをチェックアウト
  • release
    該当のアセットのロックを外す(ただし、revertとは異なりファイル自体への変更/巻き戻しは行われません)

例えば、

urc checkout release "Plugins\UrcSample\Content\__ExternalActors__\UrcSmaple\7\OB\CX8J6BIK5N2KYXKTQFMYIX.uasset"

というように利用します。ただし、現在は管理者権限でも、他人のファイルに対してロックをリリースすることはできないようになっています。

project

冒頭で説明した、forcereleaseもprojectコマンドの操作でした。このコマンドでは、プロジェクト全体の設定や確認ができます。

urc project create/init/list/snapshot/status
  • create
    プロジェクトの作成
  • init
    プロジェクトの初期化
  • list
    ログインしているユーザーがアクセスできるプロジェクト一覧の表示
  • snapshop
    　該当のプロジェクトのsnaphotの一覧確認および、getコマンドを利用することにより時のsnapshotにプロジェクト全体を巻き戻す
  • status
    該当のプロジェクトのステータスの表示。チェックアウト/編集済みファイルなどの一覧を表示することができる。

stage

stageコマンドは、チェックアウト済みのファイル群に対して、submitを行うことができます。

urc stage apply/create/delete/inspect/list
  • apply
    stage-idに紐ずくファイル群のsubmit
  • create
    チェックアウト済みのファイルを元にstagingを行います。stage-idをレスポンスとして返す
  • delete
    該当のstage-idのステージングを削除
  • inspect
    該当のstageのコンテンツを一覧化
  • list
    ステージング状態を一覧表示

stagingコマンドは、実行するとエラーが出たりで現在使えなそうな雰囲気でした。

補足

自動チェックアウト

URCに関連する内容で、いくつか補足説明を追加します。

初めに触れさせていただいた、特定のアセットが意図せず、チェックアウトされてしまう問題についてです。本記事では、主にurcコマンドを利用して対処する方法を書きました。

この問題は、

  1. ファイルが意図せず編集されてしまう
  2. 編集されたことにより、意図せずチェックアウトされる

という二つの事象によって引き起こされていると思われます。1に関しては、Unreal EngineのUEFNもしくは、UEFN自体のバグ(/仕様?)なのではと思っています。

一方で、自動でチェックアウトされてしまうのは、リビジョンコントロールでの初期設定で変更可能です。

ファイルが編集されたときに自動でチェックアウトするという項目を、有効にしないことで上記の事象は防げると思われます。

また、ファイルがチェックアウトされなかった時に、そのファイルの変更を自動で巻き戻す項目も、せっかく編集した内容が自動で巻き戻しされてしまうので、個人的には、使わないようにしています。この設定をせずとも、ファイル編集して保存したタイミングで、チェックアウトするかどうかを尋ねられます。これだけで十分だと考えています。

ユーザーid

URCでは、様々なidが必要だったり確認することができます。ちなみに、UEFNの右上に表示されている文字列は、現状ログインしているユーザーのidになっています。

コマンドラインの省略

ドキュメントには、project を p、assetをaと省略するような書き方も載っていますが、残念ながらうまくいかないことがあります。ここでは、省略せずすべてのコマンドを打つようにしています。

urcはsqliteのクエリ?

urcでの操作は、.urcフォルダー内をもとに実行されていそうです。

ここには、.sqliteファイルがあり、中には、UEFNで利用しているアセットのid、パス、ハッシュ値、stageに関する情報などが保存されています。

Discussion