MODガイド　リソース編

本ガイドはリソース(ファイル)の追加／差し替えの仕組みや一部のリソースの扱い方について説明します。

ほとんどのリソースはOGREの管理下にあります。

OGREのリソース管理のデータ構造について簡単に説明すると、OGREはグループごとにキーがファイル名で要素がフォルダパスのstd::map(連想配列)を持っています。

KenshiがOGRE管理下のリソースを呼び出すときは、グループ名とファイル名を指定して目的のリソースにアクセスしています。

std::mapはキーの重複を許可しないので、各グループのファイル名はユニークにする必要があります。
キーが重複した場合は、後から追加するリソースのフォルダパスで要素を上書きします。
(リソースフォルダはoperator[]で追加しています)

カナなどの非ASCII文字は、文字化けでリソースが見つからない可能性があるため非推奨
(ファイル名は、ゲームデータがUTF-8、OGREのリソース管理がシステムロケールに依存している)

バニラのリソースが所属するグループはresources.cfgに従います。
ただし、LandscapeとOverlaymapsは例外で「./data/land」を「./data/newland/land」に読み替えます。

MODや公式翻訳のリソースはmodファイルのあるフォルダをdataフォルダと見立てて一番近いフォルダ構成と同じグループになります。

例

LandscapeとOverlaymapsはresources.cfgに合わせてmods/test_mod\landにするとGeneralになるので気をつけてください。

ゲーム起動後、以下の順でフォルダをリソース管理に追加します。

1. バニラ

   resources.cfgに記載されているフォルダをリソース管理に追加します。
   再帰しないので記載のないフォルダは追加されません。

2. 公式翻訳

   言語設定に応じて言語フォルダをサブフォルダ含めリソース管理に追加します。
   日本語なら./locale\ja_JPフォルダとそのサブフォルダが対象になります。

3. MOD

   mods.cfgの昇順に各MODフォルダをサブフォルダ含めリソース管理に追加します。
   ワークショップでサブスクライブしたMODは絶対パスになります。

前項で説明した要素の上書きとロードオーダーにより、MODに含めるファイルをバニラや前提MODと同名にすることで使用するファイルの差し替えが可能です。

例えばtest_modというMODを作成し、test_modフォルダにarmour\Samurai_BodyTop.meshを配置するとOGREが保有するデータが図のようになります。

ただし、OGREのスクリプトファイル(material、programなど)は差し替えできません。

OGRE管理下のリソースはファイル名のみ使います。
一応、フォルダパスはFCSのAssetウィンドウでファイルの存在チェックで使っています。

3Dモデルやテクスチャ等のリソースは、全てのリソースグループから探索して最初に見つかったファイルを使用するので、適当に配置してもロード可能です。
しかし、地形のテクスチャやアイコン等のリソースは、リソースグループが決まっているので、なるべくバニラのフォルダ構成を真似た方がいいです。

※features.datとfogfeatures.datは例外でバニラのフォルダ構成を真似ると誤ったリソースグループになります。

以下はOGRE管理外のリソースになります。

• Kenshiの固有ファイル(mod, zoneなど)
  
• Scythe
  
• 地形のハイトマップ
  
• Havok
  
• Wwise

「バニラ → バニラの.translation → mods.cfgの昇順 → MODの.translation」の順にロードします。

.modファイルと.translationファイルは1つのデータに統合されます。
ただし、MODの.translationが存在している場合は、バニラの.translationをロードしません。

.levelファイルや.zoneファイルなどは同名ファイルが1つのデータに統合されます。

Scytheの.phsファイルはFCSでパスが指定できるのでMODフォルダからロード可能です。
ただし、ワークショップのMODはファイルの所在とFCSで設定したパスが一致しないのでロードできません。

以下の回避策があります。

• ユーザーにmodsフォルダへコピー＆リネームしてもらう

  あるいはシンボリックリンクを作成してもらうとMODが自動更新されるようになります。

• RE_Kenshiの機能でファイルパスを再バインディングさせる

  GitHubのwiki[github.com]を見ればできますが、念のため例を記載します。

  { "FileRebinds" : { "./mods/test_mod/items/scythe_test.phs" : "$(modroot \"Your mod name here\")/items/scythe_test.phs" } }
  
  JSONのキー名は、FCSで設定したパスと一致する必要があります。
  最新のFCSは、パス区切り文字を「/」に正規化するので、気をつけてください。

  また、当たり前ですがユーザーがRE_Kenshiを導入していないと意味がないです。

一方で.phsファイルが参照するモデルは、OGREのリソース管理に従います。
全てのリソースグループから探索するので、ファイル名さえ正しければロード可能です。

ファイルパスが「data\newland/land\fullmap.tif」でハードコーディングされているので、バニラのファイルを上書きしないと反映できません。
しかし、前項で紹介したRE_Kenshiの機能を使うとMODフォルダからロード可能になります。

Wikiに記載されていないので保証しませんが、以下の手順でハイトマップ圧縮も対応可能です。
(一応、RE_Kenshiのファイルログ含め参照先の変更を確認しています)

1. ハイトマップを圧縮

   インストーラに同梱されているCompressTools.exeを使います。

   PowerShell等を起動して以下のコマンドを実行します。
   
   CompressTools.exe "圧縮元パス" "圧縮先パス"
   ※CompressTools.exeはフルパスで指定するか、カレントディレクトリを移動してから実行してください

2. RE_Kenshi.jsonを編集
   { "FileRebinds" : { "data\\newland/land\\fullmap.tif" : "$(modroot \"Your mod name here\")/fullmap.tif", "data/newland/land/fullmap.cif" : "$(modroot \"Your mod name here\")/fullmap.cif" } }

以下のリソースは大なり小なり注意が必要です。

• アニメーション(.skeleton)
  
• パーティクルのテクスチャ
  
• PhysXオブジェクト(.xml, .bin)
  
• features.dat, fogfeatures.dat
  
• bodyデータ(.bod2)
  
• アイコン
  
• 建物の3Dモデル(.mesh)
  
• GUI翻訳データ(main.mo)

扱いを誤るとCTDのリスクがあります。
以下の点に注意しましょう。

種族やキャラクターに追加する.skeletonファイルは必ずTrueにします。
preprocessはトラックの除外処理が本来の役割ですが、この処理はタイトル画面からロード画面に遷移するタイミングでファイルを安全にロードするので結果としてCTDを防止します。

ボーンドッグなど動物の.skeletonファイルはトラックの除外処理の後に行う種族データの初期処理で.meshファイルと一緒にロードするので、必須ではありません。
ただし、追加の.skeletonファイルは動物用であってもpreprocessをTrueにします。

preprocessはデフォルト値がTrueのため、CTDの原因になることはほとんどありません。
しかしながら、CTDを引き起こすアニメーションMODが存在しています。
これらは共通してリソースグループがGeneralになっています。

Generalはロード画面や「読込中...」を表示するタイミングで未使用のリソースをアンロードします。(foliage、Landscape、Overlaymapsもアンロード対象)
そのため、アニメーションの.skeletonファイルをトラックの除外処理でロードしたのに未使用としてアンロードされます。
そして、アニメーションを再生するまでにリロードが間に合わないとCTDになります。

ParticleUniverseのスクリプトが参照するマテリアルのテクスチャは、タイトル画面を表示する前に全てロードされますが、リソースグループParticleはアンロード対象外のため、VRAMに常駐します。
したがって、テクスチャの数が多い／サイズが大きいとVRAMを圧迫します。

また、Particle Systemの再登録によってテクスチャを差し替えると不要になった差し替え元がVRAMに残ってしまいます。

FCSで.xmlファイルを指定しますが、Kenshiは.binファイルを使用します。
.binファイルが存在しない場合のみ.xmlファイルから.binファイルを作成します。
そのため、.xmlファイルを変更した場合は.binファイルの再作成が必要になります。
ユーザーに.binファイルを削除してもらうのは面倒ですので、.xmlファイルと.binファイルはセットで配布しましょう。

これらのファイルは、バニラのフォルダ構成を真似て「mod root\newland\land」とすると差し替えに失敗します。

features.datとfogfeatures.datはLandscapeからロードするので、Overlaymapsである「mod root\newland\land」ではなく、「mod root\newland\land\textures」が正解です。

(「./data/newland/land」は、resouces.cfgのLandscapeとOverlaymapsの両方に定義されているため、正しく動作しますが、modフォルダは、一つのリソースグループしか割り当てられない仕様になっています。)

.bod2ファイルは、Kenshi固有のファイルですが、OGREのリソース管理の対象になります。ただし、バニラの.bod2ファイルはOGREのリソース管理外であり、その場合はFCSで設定したパスをロードします。

ファイル名にカナ(非ASCII)が含まれている場合、modsフォルダからはロードできますが、ワークショップからはロードできません。

余談ですが、NPCにbodyデータを設定した場合、ハッシュ値の衝突が原因でシェイプキーが(同じ3Dモデルが割り当てられた)他のキャラクターの値で描画されるバグがあります。

アイコン用のファイルを含める場合は、必ずリソースグループを「Icons」にしてください。

自動生成する場合は、以下の理由により自動生成した.pngファイルの配布を推奨します。(染色など自動生成が前提のアイコンを除く)

• 自動生成のレンダリング負荷が高い(特に義肢)
  
• ゲーム中はリソースを登録しないため、アイコンを参照するたびにレンダリングとファイル作成を行う
  
• 3Dモデルやテクスチャを修正するとファイルの再作成が必要になる

以下の条件を満たすと膨大なエラーログ(数十秒で数MBまで肥大化)が出力され、最悪クラッシュします。

• materialのmaterial typeがDUAL
  
• .meshファイルに頂点カラーがない
  
• 建物が未完成の状態

GUIの翻訳を変更するには以下のファイルが必要です。

• mod_root\locale\ja_JP\LC_MESSAGES\main.mo
  
• mod_root\locale\ja_JP\ja_JP.translation

注意事項は以下の通りです。

• MODのlocaleフォルダはmain.moと.translationしかロードできない
  上記以外のファイルは、リソースグループに従って配置してください。

• バニラの.translationが無効になる
  目的がGUI翻訳の変更だけであっても、ゲームデータの翻訳データが必要になります。

  ただし、.translationで翻訳すると下記の問題が発生します。

• MODの.translationは必ず最後にロードされる
  MODの.translationでバニラデータを翻訳してしまうとバニラデータの名称を変更するMODと競合します。また、ロードオーダーの変更では解決できません。

  競合を防止するには、翻訳を.modの方で行い、.translationは何も変更しないようにします。