コンテンツの クッキング

ドキュメントの概要: .ini ファイル設定を含め、クッカーを使用するためのゲームのセットアップ方についてを網羅。

ドキュメントの変更ログ: Josh Adams により作成。　Scott Sherman　によりアップデート。　Richard Nalezynski^? により管理。

概要

コンテンツのクッキングとは、コンテンツがどう変換され、コンソール(現時点では、 Xbox 360 と PS3)が求めるフォーマットにメッセージを伝えるかを処理することです。 PCも同様にクックデータを使用することができ、ダイレクトな MOD 機能(ＵＴ3 のクックデータと平行してサポートされる)のコストにて、ローディングスピードを格段に早くします。

ほとんどの部分は、単刀直入に述べていますが、チームで最低一人は知る必要のある事項があります。

クッカー自身は、Unreal コマンドレットです。 通常では、コマンドレットを呼び出す UnrealFrontend.exe を使用します。 詳細は、 UnrealFrontendJP をご覧ください。 コマンドレットを直接使用して、独自のコンテンツをクックすることができます（下記の「コマンドライン」オプションのセクションを参照してください)。

Cooking (クッキング)

Cooker(クッカ) の主な役割は、コンソール (任意的に PC) でのロードに最適なフォーマットでパッケージを保存することです。パッケージへの処理は以下を含みます。

• 「エディタ専用」データのように必要ないデータのストリップ (ファイル サイズへ大きな影響を与えます)。
• CPU オーバーヘッドなしでビッグエンディアン アーキテクチャによりロードされるように、すべてのデータのバイトスワッピング。
• Native フォーマットで格納され、コンソール上でそれ以上の処理をせずに直接ロードできるようにするためのリソースの処理。
• シークタイムの遅いメディアからの最適ロードのために、シークフリーで内蔵型のパッケージの作成 (例：DVD/BD)。

UE3 はコンソールで、クックされたパッケージのロードのみをサポートします。PC は 1 つ、または 2 つの混合さえもロードすることができます。

クックするものの決定

コマンドレットは、パッケージのロード、処理、再保存をすることにより機能します。ロードされたパッケージのリストは、コマンドラインと .ini 設定により決定されます。クックされたパッケージは、XXXGame\CookedYYY (XXX はゲーム名で、YYY はプラットフォーム名) のフォーマットでクックされたディレクトリに保存されます。クックされたパッケージ ファイルは、コンソール上で .xxx 拡張子を持ち、PC ではオリジナルの拡張子を持ちます。コマンドライン オプションによりオーバーライドされない限りは、デフォルトで、 クックされたパッケージの日付けより新しい日付けを持つパッケージのみがリクックされます。

特に、フローは以下のようになります。

• シークフリーでないパッケージ：
  • 古いシークフリーでないパッケージをクックします。
  • シークフリーでないパッケージがある場合は、現在の時間 T をグローバル パーシスタント変数にマークします。
• シークフリー パッケージ (スクリプト、スタートアップ、マップ)：
  • ソース ファイルに対して、古いシークフリー パッケージをクックします。
  • 時間 T に対して、古いシークフリー パッケージをクックします (これは、シークフリーでないパッケージからリファレンスを再帰的に得ることができ、新しいオブジェクトがクックされる必要があるからです)。
• スタンドアロン シークフリー パッケージ：
  • ソース ファイルに対して、古いスタンドアロン シークフリー パッケージをクックします。
  • 時間 T に対して、古いスタンドアロン シークフリー パッケージをクックしません。

-full、または指定されている場合は、すべてのクックされたパッケージは最初に削除されますので、すべてのファイルは日付けチェックに失敗し、クックされます。-forceseekfree の場合は、マップ、スタートアップ、スタンドアロン シークフリー パッケージは、必ずクックされます。

コマンドライン

通常、 Unreal Frontend と共に実行しますが、クッキングまたは同様のものを自動化したい場合は、 commandline インターフェースを使用します。

gamename.exe CookPackages [map1 [map2] ... [mapn] -platform= -[options]

オプション

• platform=PLATFORM:プラットフォームをクックするために設定します。PLATFORM は pc, ps3, xbox360 xenon のうちの一つになります。
• full: Forces all すべての既存パッケージが再保存されるよう強制します。 このオプションが指定され束愛は、 CookedYYY フォルダのコンテンツが最初に削除されます。
• recookseekfree:すべてのシークフリーパッケージが再クックされるように強制します(コマンドラインまたは .iniでの起動、スタンドアロンシークフリー、マップ)。デフォルトの依存性チェックが作動しないときに便利です(マップとは異なり、非シークフリーパッケージに変更がない場合は、すべてのスタンドアロン シークフリーパッケージを再クックしないため、特にスタンドアロン シークフリーパッケージに便利)。
• cookallmaps:ゲームのすべてのマップをクックします。
• mapsonly:マップのみをクックします。その他のクックは試行しません。
• inisonly: .ini とローカライゼーションファイル( Coalesced.ini と Coalesced.int などのファイル内に)のみをクックします。
• sha: スタートアップと結合ファイル用の SHA ハッシュを生成し、 Hashes.sha にアウトプットします。
• skipsavingmaps: クックするがマップを保存しない。 マップで使用された LOC データのクッキングに便利です。
• skipnotrequiredpackages: LOC クッキングのスピードアップのための、クッキングプロセスに要求されていないパッケージのローディングと保存のスキップします。
• languageforcooking=LANG: ローカライズされたクッキング用の言語として LANG を設定します。 ini (英語）をデフォルトとします。

出力

クッカの出力はレベル、Native スクリプト パッケージ、組み合わされたスタートアップ パッケージ、テクスチャ ストリーミング パッケージ、スタンドアロン シークフリー ファイル、テクスチャ ファイル キャッシュ、メタデータ/ヘルパー ファイルの 6 タイプです。

レベル は、ハイレベルなテクスチャ ミップ以外の必要なコンテンツをすべて含むパッケージで、レベルをロードするのにおおむね (ハイディテールなテクスチャなしで) シークフリーにします。

Native スクリプト パッケージ は Native クラスが中に入っている UnrealScript パッケージで、スタートアップ時にゲームにより常にロードされます。その中にクックされたスクリプト コードによりリファレンスされたコンテンツを含んでいるので、スクリプト コードによりどれぐらいのコンテンツが直接リファレンスされるかに気を付けなければいけません。

Gears of War には、1 つのメイン Native スクリプト パッケージである WarfareGame.u があり、これは Native ベース クラスを持ちます。Native クラスを持たないが、多くのサブクラスを持ち多くのコンテンツをリファレンスする WarfareGameContent.u は、常にロードされる必要はありません (モンスターなど)。

組み合わされたスタートアップ パッケージ は、ゲームを起動するのに必要なすべてのパッケージを組み合わせたパッケージですが、そのデータはメイン メニュー レベルにクックされません。これは、DefaultMaterial のようなオブジェクトを含みます。スタートアップ パッケージの中のいかなるオブジェクトも常にロードされます。

テクスチャ ストリーミング パッケージ は実際のハイレベル (大きな) ミップ データを含んでいるので、DVD で何度も複製されませんし、ランタイム時から容易にストリームすることができます。

スタンドアロン シークフリー パッケージ は、マップでもスクリプトでもないパッケージですが、すべてのリファレンスを 1 つのパッケージに取り込みます。これは Unreal Tournament で、カスタム キャラクター ピース パッケージに使われています。多くのピースからキャラクターを構成する際に、メッシュとそれに依存するテクスチャを素早くロードするために、スタンドアロン シークフリー パッケージを (非同期に) ロードします。DynamicLoadObject はコンソールでサポートされていないので、オブジェクトをロードするのにフル パッケージ ローディングを使用します。クックされた際、スタンドアロン シークフリー パッケージは 2 つの出力パッケージを持つことができます。1 つは _SF 拡張子付きで、もう 1 つはその拡張子なしです。 _SF ファイルは、すべてのオブジェクトとそれの依存関係を含む実際のシークフリー パッケージであり、_SF なしのファイルは、ストリーミング テクスチャ (圧縮差異のため、エンジンはシークフリー ファイルからテクスチャをストリームしません) を含みます。

テクスチャ ファイル キャッシュ は、1 つのファイルに組み合わされたストリーミング テクスチャに値するような多くのパッケージを含む 1 つのファイルです。これは、ディスクのファイルの総数を減らすのに使用できますし、一度に開くファイルの総数を減らすこともできます (プラットフォームに何らかの制限がある場合など)。

オーディオストリーミングパッケージ は作成されません。ただし、オーディオのあるパッケージをストリームすることができます。可能な限り多くのバンド幅をテクスチャストリーミングに投入したかったため、任意のオーディオの同時ストリーミングのサポートの実装をする代わりに、また、Unreal Tournament や Gears of War などのような敏速なアクションゲームの遅れは受け入れ難く、この時点ではFaceFX アニメーションの同期は追加の課題となるものだったため、この方法は優遇されていました。代替策として Gears of war 用に特別な ダイアログシステム が作成されました。

PC とクッキング

PC はクックされたデータでも、クックされていないデータでも実行できます。現在、クックされたデータで実行する方法は -seekfreeloading コマンドライン オプション (または UnrealFrontend 内の Run with Cooked Data (クックされたデータで実行) チェックボックス) となっています。クック済みデータでエディタを実行するには、-cookededitor コマンドラインオプションを使用してください。

PC とコンソールのクッキングの違い：

• PC パッケージは拡張しを保持しますが、コンソールは.xxxに変更します。
• PC 非シークフリーパッケージは、コンソールのテクスチャとは異なり、それらにあるすべてのオブジェクトを保持します。
• コンソールクッキングは TextureFileCache パッケージをサポートします。
• コンソールクッキングはむしろ、PC クッキングよりも「生データ」を削除します。理由としては PC エディタはmod サポート用のクック済みパッケージ(UT3 を参照)を使いロードが可能なためです。

クックデータでのUT3 PC 出荷はmod 用に許可されています。弊社ではユーザーの方には「パブリッシング」として提示しました。これはクッキングに類似していますが、パッケージがmodにある場合のみクックされます。基本的にPC用に"-usermode" でクッキングしています(例：ネイティブスクリプトパッケージのクッキングはない)。

クックされたパッケージ

型

クックされたパッケージは、おおざっぱに 4 つの型があります。 それらの解説とどうロードされるかを次で述べています。

Native スクリプト パッケージ

解説 : パッケージには、 native スクリプトコードがあります。 それらのパッケージはクックされ、「シークフリー」にされます(しかし、 Core や Engine のようなスクリプトパッケージでは、検索が意味を成さないメモリの読み取りにより、bPreloadPackagesFromMemory オプションに対応するオブジェクト間の異常な相互依存性のため、 100 % シークフリーにはなりません)。 クッキングすることにより、すべての参照コンテンツ(テクスチャ、メッシュなど)は、パッケージに取り込まれます。

ローディング : 常に、いつでも、永久に、 100 % 完全にロードされます。 スタートアップ時に最初のこととして、ロードされます(例、 Core、 Engine、 GameFramework、 UTGame など)。

スタートアップ パッケージ

解説 : パッケージは、ゲームを最初に起動するのに必要な追加のパッケージで、コンテンツは、他のパッケージ内にクックされません。 [Engine.StartupPackages] セクションでリストされています。 必要とされる、通常の理由としては、パッケージにあるオブジェクトがスクリプトコード、またはマップにより直接参照されないため、手動でクックされたり、ロードされる必要があります。

ローディング : パッケージにあるすべてのオブジェクトは、スタートアップ時にロードされます。 それらは決して、ガーベジコレクション(これは、QA 2007 年 3 月現在で新しいものです)されません。 つまり、ランタイムメモリを節約するため、パッケージから必要のないオブジェクトを削除してください。

マップ パッケージ

解説 : そのマップ(Native スクリプトパッケージにあるクラスを除く)により参照されたマップとすべてのコンテンツです。 これは、シークフリーです。 複数のクックされたマップは、同じオブジェクトを含みます(同じテクスチャを使用している 2 つのマップは、両方にクックされたテクスチャを持ちます)。 これは、 DVD/BD の使用量を増加しますが、オブジェクトを使用している他のマップが提供するメモリに、オブジェクトがすでにある場合は、それがスキップされるため、ランタイムメモリは増加しません。

ローディング : ゲームまたはプレイヤーがマップを切り替え時にロードされます。 完全にロード(頻繁に、ストリーミングには非同期で)され、LoadMap の呼び出し、またはストリームアウトによりレベルがアンロードされるまで、オブジェクトは保持されます。

テクスチャ パッケージ

解説 : パッケージは、テクスチャ ストリーミング用のハイレベル ミップマップデータを含みます。 クッキング中、パッケージから、ハイレベルミップマップが除かれます。

ローディング :それらは、決してパッケージとしてロードされず、ストリーミングテクスチャとしてのみ使用されます(ローレベルミップマップは、クックされたパッケージにあります)。

使用法

アセットをクックする方法は、使用法により変わってきます。

Directly referenced(直接リファレンス) ：オブジェクトが直接オブジェクト リファレンスを持っている場合、それを必要とするシークフリー パッケージ (Native スクリプト、マップ) は、それをクックされたシークフリー パッケージから取り込み、それがストリーミング テクスチャを持たなかったり、テクスチャ ファイル キャッシュが使用されていない限り、アセット パッケージはクックされたディレクトリに存在しません。

ソリューション : 特にありません。予期されたとおりです。

Loaded dynamically from any level(いかなるレベルから動的にロード) ：いかなるシークフリー パッケージ (Native スクリプト、マップ) もオブジェクトをリファレンスせず、オブジェクトがランタイム時にロードされる場合は、=LoadPackage= を使用してオブジェクトをロードできるはずです。なぜなら、 LoadPackage を通して既にオブジェクトがロードされていない限り、 DynamicLoadObject だとコンソール上で NULL を戻してしまうからです。

ソリューション ：ゲームの DefaultEngine.ini の [Engine.PackagesToAlwaysCook] セクションで、スタンドアロン シークフリー パッケージとしてマークしてください。

[Engine.PackagesToAlwaysCook]
+SeekFreePackage=MyGamePackage

これで、MyGamePackage_SF.xxx (テクスチャがあり、TextureFileCache が使用されていない場合は、ストリーミング テクスチャのために MyGamePackage.xxx) が作成されます。このパッケージは、コンソール ローディングのために、以前、外部リファレンスやストリーミング テクスチャとうまく動作しなかった状態よりも、より適切なフォーマットになります。

Loaded dynamically from one level(1 つのレベルから動的にロード) ：1 つや 2 つのレベル (例：メニュー レベル) がオブジェクトを動的にロードすると、パッケージをマップ ファイルに強制的に組み込むことができます。そうすると、それはマップのロード時に常にロードされるようになります。

ソリューション ：ゲームの DefaultEngine.ini の [Engine.PackagesToForceCookPerMap] セクションで、パッケージがマップに強制的に取り込まれるように設定してください:

[Engine.PackagesToForceCookPerMap]
.Map=MyFrontend
.Package=MyGamePackage

これで、MyFrontend がロードされるといつでも MyGamePackage 内のすべてのオブジェクトはロードされ、 DynamicLoadObject=/=FindObject を使用して得ることができます。

Used in EVERY level(すべてのレベルで使用) ：オブジェクトがいつでも使用できる場合は、一度ロードされると常にメモリ内にいるようにするのに、スタートアップ パッケージに組み込むべきです。

ソリューション ：ゲームの DefaultEngine.ini の [Engine.StartupPackages] セクションで、パッケージを追加します。

[Engine.StartupPackages]
+Package=MyGamePackage

コンフィギュレーション

コンフィギュレーションファイル

クッキングのためにゲームをセットアップする際、いくつかの .ini 設定を変更しなければいけません。コンソールの Engine.ini ファイルは、メインの Engine.ini ファイルから生成されるので、ゲームの DefaultEngine.ini ファイル内でこれらの設定を指定することができるはずです。しかしながらクッカは、生成されたターゲット プラットフォームのEngine.ini ファイルの中で設定を探すので、それらをゲームのプラットフォーム固有の Engine.ini ファイルで指定することも可能です。

[Engine.PackagesToAlwaysCook]

解説 ：このセクションは、すべてのユーザーによりクックされていることを確かめたいマップや、スタンドアロン シークフリー パッケージを組み込むためのものです。12月 QA 承認済みビルドの時点で、すべてのシークフリーではないパッケージがクックされるようになったので、クックしたいランダムなパッケージを指定する必要はなくなりました。

時間とともに使用法が変わったので、このセクションは将来的に名前が変更され、2 つのセクションに分けられるかも知れません。また、スタンドアロン シークフリー パッケージは、コマンドラインでオーバーライドされない限り、毎回リクックされません。

使用時期 ：メイン メニュー レベルなどのなければならないパッケージを入れます。また、スタンドアロン シークフリー パッケージが必要な時 (上記の「オペレーション」セクションを参照してください) もです。クックされているかどうか確かめたいマップには "Package=" を、シークフリー パッケージを指定するには "SeekFreePackage=" を使用してください。

フォーマット ：

[Engine.PackagesToAlwaysCook]
+Package=entry
+Package=UTFrontend
+SeekFreePackage=CH_IronGuard_Male

[Engine.StartupPackages]

解説 ：ここでリストされているパッケージは言語ごとに 1 つのシークフリー スタートアップ パッケージに組み合わせられています (Startup_int.xxx、Startup_kor.xxx など)。これらのパッケージ内のオブジェクト (とその依存関係) は、ゲームの初期起動時に必要であり、常にメモリに入ります。 常にです 。また、これらのパッケージのオブジェクトは、他のパッケージにクックされません。

使用時期 ：初期の起動時でオブジェクトが必要な時や常にメモリ内にあって欲しいときに使用します。以下の例では、UI_Fonts の代わりに適切なフォント ファイルが使用されるようになります。韓国語でクッキングをしている時に、UI_Fonts_KOR.upk があると、UI_Fonts_KOR オブジェクトは Startup_KOR.xxx に組み込まれます。

フォーマット ：

[Engine.StartupPackages]
+Package=FX_HitEffects
+Package=UI_Fonts
+Package=UI_Scenes_HUD
+Package=UI_Skins
+Package=UI_Skin_Derived
+Package=SpeechRecognition

bSerializeStartupPackagesFromMemory

解説 ：初期の起動時に膨大な量の一時的なメモリを犠牲にして、スタートアップ時間を早くします。これは、スタートアップ時にバックグラウンドで非同期的に、スタートアップ パッケージのリストをメモリに読み込み始めます。これにより、いくつかのパッケージは (比較的遅い) DVD から読み取られますが、他のパッケージを処理することができます。デフォルトで、エンジンは Native スクリプト パッケージ、スタートアップ マップ、Startup_*.xxx をプリロードします。

これは、以下のように動作します。

• 割り当てされたメモリ チャンクに、DVD から Core.u の読み取りを開始します。
• 終わるまで待ちます。
• Engine.u の読み取りを開始しします。
• (LoadPackage) Core.u をメモリ チャンクからエンジンへ直列化します。
• パッケージ内で既に読み込まれたものを直列化している間に、パッケージの読み取りを継続します。

使用時期 ：これらの膨大な追加メモリ チャンクを割り当てできるぐらいの十分なメモリがあり、起動を早めたいときに使用します。

フォーマット ：

[Engine.StartupPackages] bSerializeStartupPackagesFromMemory=True

[Engine.PackagesToForceCookPerMap]

解説 ：このセクションは、特定のパッケージを完全にマップ パッケージに強制的にクックします。

使用時期 ：オブジェクト リファレンスによりではなく文字列名により、ロード オブジェクトを得るのに、DynamicLoadObject (DLO) を使用したいときに使います。クッカはオブジェクト リファレンスのみに従い、文字列リファレンスには従わないので、オブジェクトがマップにクックされる原因となりません。例えば、UI システムは DLO を使用して、UIScenes やテクスチャを開きます。ですので、Unreal Tournament では、シーンやテクスチャを含むパッケージはメイン メニューへ強制的に組み込みまれました。これで、単純に UTFrontEnd マップをロードすることにより、シーンやテクスチャがロードされます。レベルがロードされている限り、オブジェクトはガーベジ コレクトされません。

フォーマット ：

フォーマットは Map= で、Package= ラインの数が後に続き、マップに組み込まれるパッケージのリストをします。

[Engine.PackagesToForceCookPerMap]
.Map=UTFrontEnd
.Package=UI_Scenes_Mutators
.Package=UI_FrontEnd_Art
.Package=UI_Portrait
.Package=UI_Scenes_ChrisBLayout
.Package=UI_Scenes_FrontEnd
.Package=UI_Scenes_Common
.Package=UI_Skin_Derived
.Package=UI_Skins
.Package=UI_Scenes_Campaign
.Package=UI_Weapons
.Map=UTM-MissionSelection
.Package=UI_Scenes_Campaign
.Package=UI_Skin_Derived
.Package=UI_Skins

[Core.System] SeekFreePCPaths

解説 ：このセクションは CookedPC ディレクトリ内の拡張子と関連ディレクトリ構造体を (-cookededitor フラグを持つエディタ機能のために) 保持します。

使用時期 ：PC クック ビルド時。

フォーマット ：

[Core.System]
SeekFreePCPaths=<PATH>