第004回　UE4のアセットを一括修正する

2019/01/11 2019/06/07

ツール系テクニカルアーティストのしばはらです。

プロジェクトが進んで、ある程度アセットがそろってきた段階で、新しいアイデアが出て設計を見直したり、バグが見つかったりして、これまで作ったアセットを一斉に直さなくてはいけなくなることがあります。

ひとつひとつアセットを開いて、必要になった修正を手作業でやっていけばいい話ではあるんですが… 数が増えてくると時間もかかるし、人力では修正ミスも出てくる、やっかいな面があります。

今回はアセットを開くことなく一括修正する方法をご紹介していきます！

こんな問題がありまして…

早速ですが、具体例を見ながら一括修正のイメージを持っていただこうと思います。
FBXや画像ファイルなど、UE4にファイルをインポートしてアセット化するタイプのものがあります。
これらのアセットに記録されている元データのパスがメンバーによってばらばらになっている問題を、一括修正で解決してみましょう。

まずは状況設定から。

インポート元ファイルは、ProjectDataというフォルダ下に置く、としてファイルの配置ルールを決めました。
ProjectData以下の階層は皆ルール通り配置しているものの、ProjectDataフォルダ自体の置き場所がメンバーによって食い違っていることが発覚しました。あるメンバーは D:\MyProject の下に、また別のメンバーは E:\の直下に ProjectData フォルダがあります。
ここが統一されていないせいで、UE4のコンテンツブラウザから再インポート操作を行うときに元ファイルが見つからない、ということが起きだしました。
全メンバーで D:\ProjectData というパス下にファイルを置くように修正します。

※D:\ProjectDataへのファイル移動は通常のファイル操作で行っていただいたくことにします。シンボリックリンクも検討できるでしょう。

実装手順

データの一括修正を実装するには、次の４ステップを踏みます。

（１）対象アセットの一覧を取得する
（２）アセットの修正を行う
（３）１，２の手順を呼び出す方法を提供する
（４）動作確認

本稿の内容は、UE4.20.3, Win64 の環境で動作確認を行っています。

（１）対象アセットの一覧を取得する

まずは、プロジェクトのデータの中から対象のアセットを絞り込みます。

こちらのコードは、プロジェクトのデータの中から StaticMesh, Texture2D のアセット情報をピックアップするコードになっています。

FAssetSourcePathChanger.cpp より抜粋

void FAssetSourcePathChanger::PickAssets(TArray<FAssetData>& OutAssetList) const
{
	FAssetRegistryModule& AssetRegistryModule = FModuleManager::LoadModuleChecked<FAssetRegistryModule>(FName("AssetRegistry"));
	IAssetRegistry& AssetRegistry = AssetRegistryModule.Get();

	FARFilter Filter;
	
	// 検索対象パスの指定
	Filter.PackagePaths.Add(TEXT("/Game/TestAsset"));	// Content/TestAssetフォルダ以下。 Contentフォルダ全体を対象にするなら "/Game/" を指定.
	Filter.bRecursivePaths = true;				// サブフォルダ以下も検索する

	// 検索対象クラスの指定
	Filter.ClassNames.Add(UStaticMesh::StaticClass()->GetFName());
	Filter.ClassNames.Add(UTexture2D::StaticClass()->GetFName());

	AssetRegistry.GetAssets(Filter, OutAssetList);
}

条件に沿ったアセットの一覧を取得するには、FAssetRegistry が便利です。
・特定のクラスのアセットを検索する GetAssetsByClass
・指定したパスのアセットを検索する GetAssetsByPath
といった条件ごとの関数も用意されていますが、条件を組み合わせて検索する場合は GetAssets 関数を使います。この関数では、条件の指定を FARFilter を使って行うことができ、サンプルでは、パス、クラスの条件を指定して使っています。

いずれの検索関数も、引数に指定した FAssetDataのTArrayに結果が格納されます。

（２）アセットの修正を行う

続いてFAssetDataからアセットのポインタを取得し、内容を変更する処理です。

FAssetSourcePathChanger.cpp より抜粋

bool ReplaceAssetImportPath(UAssetImportData* AssetImportData)
{
	if (!AssetImportData) return false;

	const FString newPrefix(TEXT("D:/ProjectData/"));
	const FString mustInclude(TEXT("/ProjectData/"));

	// StaticMesh の インポートパスの取得
	FString currentPath = AssetImportData->GetFirstFilename();

	// パスの置換が必要かのチェック
	if (currentPath.Contains(newPrefix)) return false;

	// パスの置換ができそうかのチェック
	FString strRight, strDummy;
	if (!currentPath.Split(mustInclude, &strDummy, &strRight)) return false;

	// 置換パスの成形
	FString replacedPath = newPrefix + strRight;

	// 置換先のファイルが実在するかのチェック
	if (!IFileManager::Get().FileExists(*replacedPath)) return false;

	// パスの置換
	AssetImportData->Update(replacedPath);

	return true;
}

void FAssetSourcePathChanger::ChangeSourcePaths(const TArray<FAssetData>& InAssetList) const
{
	// 抽出した全アセットに対して走査
	for (FAssetData assetData : InAssetList)
	{
		// アセットの種類がマッチすれば
		if (UStaticMesh* StaticMesh = Cast<UStaticMesh>(assetData.GetAsset()))
		{
			// パスの修正を呼び出す
			if (ReplaceAssetImportPath(StaticMesh->AssetImportData))
			{
				StaticMesh->MarkPackageDirty();
			}
		}
		else if (UTexture2D* Texture = Cast<UTexture2D>(assetData.GetAsset()))
		{
			if (ReplaceAssetImportPath(StaticMesh->AssetImportData))
			{
				Texture->MarkPackageDirty();
			}
		}
	}
}

アセットのポインタが取得できたら、UStaticMesh, UTexture2D いずれもAssetImportDataという変数にインポート元の情報が格納されているので、これらのパスを加工していきます。

修正したアセットはコンテンツブラウザで編集中（未保存）であると認識できるよう、MarkPackageDirtyを呼び出しておきます。

アセットの修正処理に関して、注意点が３つあります。

一つ目は、この段階ではアセットは保存されていないということ。

UE4がクラッシュしたり、保存せずに終了してしまうと、修正は無効になります。逆に言えば、保存しない限りは、一度UE4を終了して同じ実験をすることもできます。保存の呼び出しまで行いたい場合は、GEditor->SavePackage が利用できます。

二つ目は、目的のパラメータの修正方法にたどり着くのが容易ではないケースがあるということ。

FAssetDataから取得したアセットクラスが直接持っている変数を書き換えれば済むなら話は簡単なのですが、アセット内のオブジェクトを深く深くもぐっていかないと、目的のパラメータを保持するオブジェクトにたどり着けないことはままあります。

目的のパラメータまでの到達方法は、基本的にUE4が提供しているコードから対象のアセットへのアクセス処理を調べていく必要があります。対象によっては、エンジンコードの修正も必要になるかもしれません。ここに時間が掛かると、手動で直していっても大差なかったということになりかねませんから、その点の算段は計画初期につけておきましょう。

三つ目はメモリの解放について。

サンプルコードでは、ループ処理で次々アセットのポインタを取得していますが、このとき裏ではアセットのロードが行われています。すなわち、どんどんメモリが消費されていきます。サンプルではループごとにポインタを保持している変数がスコープを外れるので、ガベージコレクションによってメモリは適宜解放されますが、アセットの参照が生き続けるコーディングをするとメモリが占有され続け、やがて足りなくなります。

変数のスコープに意識して処理を書きましょう。

（３）１，２の手順を呼び出す方法を提供する

今回は技術ブログ第003回で紹介したショートカットキーへ紐づけたコマンドから処理を呼び出すことにしましょう。

まずは、１，２の処理を呼び出す関数を追加します。

AssetSourcePathChanger.cpp

#if WITH_EDITOR

#include "MyProjectEditor.h"
#include "AssetSourcePathChanger.h"
#include "AssetRegistryModule.h"
#include "Editor.h"

#define LOCTEXT_NAMESPACE "AssetSourcePathChanger"
 
 // 処理の呼び出し
void FAssetSourcePathChanger::Call()
{
	TArray<FAssetData> AssetList;

	PickAssets(AssetList);
	ChangeSourcePaths(AssetList);
}

// アセットの絞り込み
void FAssetSourcePathChanger::PickAssets(TArray<FAssetData>& OutAssetList) const { ... }
// 問題のパスの修正
bool ReplaceAssetImportPath(UAssetImportData* AssetImportData) { ... }
// アセットを取得してパスの修正を呼び出し
void FAssetSourcePathChanger::ChangeSourcePaths(const TArray<FAssetData>& InAssetList) const { ... }

#undef LOCTEXT_NAMESPACE
#endif //WITH_EDITOR

冒頭の関数 Call で順に呼び出しを行っていますね。

※これまで紹介してきた関数は略記してあります。

クラスのヘッダーはこんな感じになっています。

AssetSourcePathChanger.h

#pragma once

#if WITH_EDITOR
class FAssetSourcePathChanger
{
public:
	FAssetSourcePathChanger(){};
	void Call();

private:
	void PickAssets(TArray<FAssetData>& OutAssetList) const;
	void ChangeSourcePaths(const TArray<FAssetData>& InAssetList) const;
};
#endif // WITH_EDITOR

続いて、コマンドの紐づけ部分の変更点を見てみましょう。

MyEditorCommandBinder.cpp

// コンストラクタ
FMyEditorCommandBinder::FMyEditorCommandBinder()
	: IsBinded(false)
{
	PathChanger = MakeShareable(new FAssetSourcePathChanger());     // クラスのポインタを保持
}

void FMyEditorCommandBinder::OnEditorLoaded(SWindow& SlateWindow, void* ViewportRHIPtr) { ... }

// コマンドの処理の紐付け
void FMyEditorCommandBinder::BindCommands()
{
	const FMyEditorCommands& Commands = FMyEditorCommands::Get();
	
	if (FPlayWorldCommands::GlobalPlayWorldActions.IsValid())
	{
		// UE4のあらゆるところで呼び出せるコマンドとして紐付け
		FPlayWorldCommands::GlobalPlayWorldActions->MapAction(
			Commands.MyEditorCommand,
			FExecuteAction::CreateSP(PathChanger.ToSharedRef(), &FAssetSourcePathChanger::Call)     // 一括変更呼び出し
		);
	}
}

前回のブログ記事のサンプルでは、ラムダ式でメッセージウィンドウを表示する処理と紐づけを行っていました。今回は、これを修正関数の呼び出しに変更しただけです。

（４）動作確認

まずは修正前の状態です。

StaticMesh	Texture

ご覧のとおり、アセットのルートフォルダがばらばらになっています。
※右側のテクスチャはEドライブを指しています。私の環境ではUE4がEドライブ置かれていたため、相対パス表示になっています。

ショートカットキー (サンプル通りならCtrl + F12です) を押してコマンドを実行すると、修正対象となったファイルに編集中（未保存）のマークが付きます。

ファイルを開いて、パス情報が修正されているのを確認します。

StaticMesh	Texture

※修正されたのはインポート元のパス情報のみになります。再インポートはしていませんので、パス以外のアセットの内容は処理前と変わっていません。

修正にあたって考えたいこと

さて、一括修正の方法をご紹介しましたが、一括修正には大量のデータが差し替わるリスクが伴いますので、計画を立てる段階こそ重要だと思っています。ここでは、考えるべきポイントについて少しだけ掘り下げたいと思います。

・どこを直すのか

アセットの内容なのか、アセットのデータの持たせ方なのか、プログラム側のデータの扱い方なのか。どこを直す方法もとれる、という状況がほとんどだと思いますので、それぞれのメリット・デメリットを洗い出しましょう。

・いつ、何をきっかけに直すのか

今回は修正処理を明示的に（ショートカットキーで）呼び出して、その場で全データを直す方法を紹介しました。直したことをチームメンバーが認識する必要があるか、目的のアセットすべてが修正されることをどう保証するかを明確にしましょう。

・どう確認するのか

修正後の挙動確認まで自動化できれば幸せなのですが、ケースによっては難しいと思います。人力で確認が必要な場合は、どのような手順で修正を確認していくのか、関係者と相談しておきましょう。また、問題発覚時は速やかにバージョン管理ツールによるロールバックができるようにしておくなど、もしもに備えておきましょう。