Overview
Dead CellsのMOD機能の解説ドキュメント（2018年6月27日公開）を翻訳したものです。
このガイドについて
このガイドは、Dead CellsのMOD機能の解説ドキュメント（2018年6月27日公開）を翻訳したものです。
[link]
[link]
Dead CellsのMOD機能はアルファ版なため、今後内容が変更される可能性があります。
Dead CellsのMODを作成するには「コマンドライン」の基本的な知識が必要です。
【履歴】
20180804：原文の修正を反映（スクリプト機能の追加などについて）
20180628：原文の修正を反映（CastleDBが使えない件について）
20180627：翻訳して公開
このドキュメントの目的
このドキュメントでは、ゲームデータのワークフローの仕組み、データの操作方法、スクリプトの作り方、MODのSteamワークショップへのアップロード方法の詳細を説明します。MODを作成したい方を対象に、ゼロから一つ一つ説明しています。また、データの変更とスクリプトの違いを見ていきます。pakファイル、cdbファイルやその他のDead Cellsのデータファイルを扱ったことがある方にとっては、既にご存知の内容が含まれている可能性があります。
概要説明
データの改造とスクリプトの作成には、大きな違いがあります。スクリプト作成のプロセスはより単純ですが、より技術的なスキルが必要です。
本ゲームではデータをPAK形式で格納しています。Dead Cellsのインストールフォルダを確認するとres.pakというファイルがあります。このファイルに、ゲームで使用される全てのファイルが埋め込まれています。
ゲーム内のデータを変更する場合は、このpakファイルを開き、各ファイルを取り出す必要があります。これがPAKToolの機能の一つです。
MODによってオリジナルのpakファイルのデータを上書きするために、私たちがmod pakと呼ぶ機能を導入しました。このmod pakは実行時にロードされ、その内部のファイルがオリジナルのファイルを上書きします。この「シンプル」な処理の唯一の例外がCDBファイルです。詳細はCDBToolの項をご覧ください。
したがってMODを作成するためには、res.pakからファイルを取り出し、取り出したファイルを修正し、mod pakを再構成する必要があります。このmod pakはPAKToolによって生成され、オリジナルのres.pakから修正したファイルのみを含みます（容量削減のため）。
これらのツールを実行するためには、.NET Framework version 4.5.2以降がインストールされている必要がります。これは以下のMicrosoftのページからダウンロードすることができます。
[link]
現在のゲームは、エルア構造の作成と、エリア情報とエリア内のモンスター名簿の定義を行うためのスクリプトをサポートしています。そのフローは非常にシンプルです。MODが有効化されると、MODディレクトリ内の./Script/Struct/ディレクトリの存在をチェックし、その中にあるスクリプトをロードしようとします。これはいくつかのres.pakの修正と互換性があります（同じMOD内でres.pakを変更し、スクリプトを導入することができます）。
res.pak
前述のように、res.pakはすべてのゲームファイルの入れ物です。これはゲームのディレクトリの最上階層にあります。PAKToolを使用することで展開することができます。
data.cdb
Data.cdbはゲームプレイやグラフィックに関する様々な情報を含むファイルです。巨大なJSONファイルであり、CastleDBで編集することができます。このファイルには部屋の配置、武器のパラメータ、霧の色などが記載されています。
.atlas & .png
Dead Cellsでは、すべてのテクスチャはPNG画像で、その大部分がAtlas形式です。Atlas形式とは、複数のPNG画像を一つの大きなPNG画像にまとめたものです。Dead Cellsには（少数の）単一PNG画像と、.png＆.atlasのペアファイルがあります。.atlasファイルは.pngファイルに格納されている画像のサイズと位置の情報が書かれています。Atlasファイルを展開し複数の「オリジナルファイル」を取り出すことができるAtlasToolにより、そのファイルを修正し、Atlasファイルを再構成することができます。
.hx
スクリプトのコードファイルです。これらのファイルは、エリア構造の生成、エリアパラメータの設定、モンスター名簿の生成、モンスターのスポーンなどの、ゲームの様々なステップで読み込まれ、解釈されます。
今のところ、ゲーム内で有効化できるMODは一つだけです。私たちは、すぐに複数のMODの有効化をサポートする予定です。二つMODが共通のファイル（CDBファイル以外）を上書きする場合、もしくは両方のMODの同じパスにスクリプトがある場合、それらのMODは互いに互換性がないと見なされる（そのため同時に有効化されない）という制約があります。
cdbファイルは様々なパラメータを含むため、私たちはこのファイルのための異なるシステムを実装することにしました。要約すると、二つのMODがCDBファイルを変更する場合、特定のテーブルの同じ行を変更するか、同じテーブルの構造を変更する場合にのみ、それらのMODは互換性がないと見なされます。すなわち、列を追加・リネームする（これは行うべきではありません）場合や、同じテーブルのセパレータを追加・リネームする（これは推奨されません）場合です。
MODは、新規セーブデータを作成するか、監獄の最初からランをリスタートした時に有効化することができます。
今のところ、ゲームのアップデートによって（マイナーアップデートの場合も）MODは無効になり、MODを使用していたセーブデータのランはリセットされます（ゲームの進捗は保存されます）。これはゲームのクラッシュやセーブデータの破損を防ぐための措置です。
以下のリストはすべてを網羅しているわけではありません。
- Atlasファイル（もしくはその一部）の変更（変更不可能なAtlasファイルはリストを参照）
- フロアのガラクタの追加
- CDBファイル内のパラメータの変更（「Truelle」テーブルを除く）
- カスタマイズされたエリア構造、ワールドグラフ、モンスター名簿を定義するスクリプトの作成
将来のアップデートで変更の可能性があり、またすべてを網羅しているわけではありません。
今のところ、いくつかのAtlasファイルは変更できません。
- atlas/ui.atlas
- atlas/fxCommon.atlas
- atlas/ui.atlas
- atlas/fxCommon.atlas
- atlas/fxEnemy.atlas
- atlas/fxWeapon.atlas
- atlas/fxDisplace.atlas
- atlas/beheaded.atlas
- atlas/gameElements.atlas
- atlas/lore.atlas
キャッシングの理由から、これらのファイルを実行時にリロードすることはできず、これらを変更しても反映されません。
data.cdbの「Truelle」テーブルは変更することができません。こちらも変更しても反映されません。
CDBファイルの幾つかのパラメータは変更しても効果がありません。しかし今のところ、そのようなパラメータの網羅的なリストはありません。
CDBファイルのセパレータの行を削除すると、ゲームがクラッシュします。
Atlasファイルの中身を削除すると、ゲームがクラッシュするかグラフィックのバグが発生します（Atlasファイルによって変わります）。
一般的に、ファイルやファイルの一部を削除すると、ゲームがクラッシュする可能性があります。
言語については、既存の方法によって追加もしくは変更する必要があります。
[link]
ツール一覧
castleDB以外はコマンドラインツールです。
引数の始めに「-」と「/」を使うことができます。引数名は大文字と小文字を区別しません。
引数の順番は重要ではありません（-引数 <パラメータ>の順番を守っている限り）。
例：
は下記と同一です。
ツールを実行するためには、.NET Framework version 4.5.2以降がインストールされている必要がります。これは以下のMicrosoftのページからダウンロードすることができます。
[link]
これはなに？
PAKToolは.pakファイルを操作するために使用します。下記のことが可能です。
- すべてのファイルデータをディレクトリに展開します。これにより、ファイルの確認と改造が可能になります。
- 完全なディレクトリツリーをpakファイルに再構成します。
- 比較対象のpakファイルに対する差分ファイルを作成します（mod pakの作成）。これは変更したファイルと、書き換えたCDBファイルの行のみを含みます。
どうやって使う？
引数 :
Atlasツールは64bitの実行ファイルであり、32bitのシステムでは実行できないことにご注意ください。またExpandAllとCollapseAllコマンドは、数GBのRAM（最大3.5 GB）を消費する可能性があります。
これはなに？
このツールは下記のために使われます。
- PNGファイルを含むディレクトリツリーからAtlasファイルを生成する。
- AtlasファイルからすべてのPNGファイルを含むディレクトリツリーを生成する。
どうやって使う？
引数 :
例 :
これはなに？
CDBファイルを操作するために使われます。下記のことが可能です。
- 各テーブルがディレクトリに、テーブル内の各行がディレクトリ内のjsonファイルに対応するディレクトリツリーを作成します。また、テーブルの構造とプロパティのファイルも作成されます。
- 各テーブルがディレクトリであり、テーブル内の各行がディレクトリ内のjsonファイルであるディレクトリツリーからCDBファイルを作成します。
- 対象のCDBファイルと、「拡張された」CDBディレクトリツリーから、変更もしくは追加された行およびテーブルのみを含むディレクトリツリーを作成します。
メモ帳を使ってCDBファイルを一行ずつ編集する場合（これは有効な選択肢かもしれません）や、より簡単にCastleDBでCDBファイルを確認したい場合は、CDBToolは必要ありません。
どうやって使う？
これはなに？
MODでスクリプトを使用するための、bootstrapスクリプトファイルを作成するために使われます。また様々な構造や機能を使用する方法に関する、多くのコメントと指示が含まれています。
引数なしで起動した場合、UIを用いてスクリプトコードをコピー＆ペーストし、コードの作成と視覚化に使うことができますが、現在は非常に基本的なものです。
どうやって使う？
引数 :
例 :
これは既存のファイルを警告なしに上書きすることに注意してください。
これはなに？
cdbファイルを編集し、部屋を編集します。
どこにある？
[link]
どうやって使う？
- [link] から.zipをダウンロード
- 展開したフォルダ内のcastle.jsを、下記のものと置き換える
<Steamインストールディレクトリ>steamappscommonDead CellsModToolsCastleDB（デフォルトではC:Program Files (x86)SteamsteamappscommonDead CellsModToolsCastleDB by default）
全行程
始めに、ゲームで使用されるオリジナルのres.pakを見つける必要があります。これはインストールディレクトリの最上階層で見つけることができます。
<Steam installation directory>steamappscommonDead Cells
（デフォルトでは C:Program Files (x86)SteamsteamappscommonDead Cells）
新しいコマンドラインウィンドウを開きます。PAKTool.exeが存在するディレクトリに移動し、下記コマンドによって、res.pakファイルを空のディレクトリへ展開します（このディレクトリの書き込み権限が必要）。
実行後、res.kapに含まれるデータファイルがディレクトリに出力されます。
CDBファイル
展開したディレクトリの最上階層に、data.cdbという名前のCDBファイルがあります。これはCDBToolで分割するか、CastleDBを使うことで編集できます。
CDBファイルの分割
CDBToolを使うことで、CDBファイルを、各行に対応するjsonファイルが入ったディレクトリツリーに分割することができます。下記コマンドで、res.pakから展開したCDBファイルを分割します。
これによりdata.cdbの各テーブルがディレクトリで、各行がjsonファイルのディレクトリツリーが作成されます。また特別なファイルである__PROPS__.json と __STRUCTURE__.json が、テーブルごとに作成されます。ゲームを破壊したり、作成するMODのゲームや他のMODとの互換性がなくなるため、これらのファイルは絶対に修正しないでください。
CDBファイルの再構成
このディレクトリツリーにファイルを修正・追加した後、最終的なMODを作成する前に、CDBファイルを再構成し、編集した他のファイルと共に元のディレクトリに戻す必要があります。再構成するために、下記のように引数を設定してCDBToolを実行します。
CastleDBでCDBを編集（今のところ動作しない方法）
CastleDBを使うことでdata.cdbを適切に編集することができます。
Atlasファイル
これまで見てきたように、Dead Cellsのグラフィックデータの大部分はatlasファイルに格納されています。これを修正するには、PNGを直接編集するか、AtlasToolを使用してAtlasファイルを分割・再構成します。前者の方法は確かに要求される操作が少なく済みますが、すべてのデータがシャッフルされているため、例えばモブのアニメーションを一つだけ修正したい場合はやりにくい可能性があります。
atlasファイルを個別のファイルに分割した場合、すべてのファイルに意味ある名前が付くため、探しているものを簡単に特定することや、またアニメーションのフレームには連番の同じ名前が付くため、それらをグループ化することもできます。
例としてベースゾンビを扱ってみましょう。その歩行アニメーションを変更したい場合、下記の作業を行います。
atlasファイルの分割：
これにより、歩行アニメーションを簡単に特定することができます。
各フレームには2つのファイルがあります。「紫色」のゾーンを含み、ゲームシェーダーに「輝き」と解釈される、「拡散」を表現するファイルと、モデルに「隆起」を与える「法線マップ」ファイルです。
ファイルを追加・変更することで、アニメーションの見た目やタイミングが変化しますが、いくつかのアニメーション（攻撃など）は所定の時間に依存することに注意してください。また、各ファイル名の終わりには-=-xx-=-（xxは数字）が書かれていますが、これを削除したり変更したりしないでください。これは各フレームが同じように名付けられている場合に、AtlasToolがアニメーションを分割することができるように追加されています。
必要な修正が完了したらmod res.pakを作成し、ゲーム内でのテストや最終的にSteamへのアップロードを行います。
再びPAKToolを使用し、オリジナルのpakファイルとの差分ファイルを作成します。
分割したcdbファイルを扱っている場合は、mod pakファイルの作成の前にdata.cdbを再構成することを忘れないでください。
次に、前のステップで作成したres.pakのディレクトリに、settings.jsonという名前のjsonファイルを作成し、下図の内容を入力します。
MODをアップロードした後は名前（name）を変更できないことに注意してください。公開設定（visibility）はオプション（デフォルトでは公開）で、Private、Public、Friend（大文字小文字は区別されません）を設定でき、それぞれ「自分だけに公開」、「全員に公開」、「自分とフレンドに公開」を表します。
現時点ではカテゴリー名（category）には、ローカライゼーションMOD用の「Language」にしてはならない以外の制限はありません。
最初のスクリプトを作成するために、ダミーMODを使います。これは既存のエリアからモンスター名簿とパラメータを流用し、入り口、戦闘部屋と出口だけの非常にシンプルなエリアを生成します。
その後、さらに高度なスクリプトチュートリアルをMOD経由でダウンロードすることができます。
- ダミーMODをインストール
- コマンドラインウィンドウで、下記の引数でツールを実行
ScriptTool.exe -commandline -newfile -outscript “C:Program Files (x86)Steamsteamappsworkshopcontent5886501405810340ScriptsStructtest.hx”
- 下記フォルダ内のtest.hxをmain.hxにリネーム
C:Program Files (x86)Steamsteamappsworkshopcontent5886501405810340ScriptsStruct
最初からmain.hxという名前で出力することもできますが、その場合、既存のmain.hxは警告なしに上書きされてしまうことに注意してください。
- （オプション）ゲームを起動して新しいランを生成すると、一つのランダムな入り口、ランダムな戦闘部屋、そしてエリアの開始地点に戻る出口からなるデフォルト構造が使用されていることを確認できます。
- 好きなテキストエディタでmain.hxを開くことで、ここで使われているコード（およびコメント）を確認することができます。
スクリプトAPIに関する技術資料を、ModToolsディレクトリ（Dead Cellsのインストールディレクトリ内にあります）の中のScripts/TechnicalDocumentationで、もしくは [link] で確認することができます。
また、いくつかのサンプルを [link] で見ることができます。
作成したMODは、インターネットへアップロードすること無く、お手持ちのPC上でテストすることができます。
- [link] を開き、ダミーMODをダウンロード
- <Steam installation Directory> steamappsworkshopcontent5886501405810340（デフォルトではC:Program Files (x86)Steamsteamappsworkshopcontent5886501405810340）へ移動
- ディレクトリ内のres.pakを、作成したMODのpakファイルで置き換える
- ゲームを起動して新しいランをスタートし、「Dummy Mod」を有効化することで作成したMODを試すことができます
作成したMODをSteamワークショップへアップロードして共有するには、再びコマンドラインツールを使用します。
- コマンドラインを開く
- Dead Cellsフォルダに移動（<DRIVE>:steamsteamappscommonDead Cells）
- 「deadcells.exe –workshop」と入力
- SteamのポップアップでOKをクリック（他のウィンドウに隠れている場合があります）
- これにより、下図のような新たなコマンドラインウィンドウが開きます
- 「n」を入力して「Create a new workshop item（新たなワークショップアイテムの作成）」を選択し、MODのパス（先ほど作成したフォルダ）を入力
- メッセージを確認してyesと入力し、アップロード
（Awesome Modという名前で新しいMODを作成しようとしています。この名前は後から変更できません！ 大丈夫でしょうか？ (yes/no): ）
- これによりファイルがSteamワークショップにアップロードされ、Steamのインターフェースからワークショップアイテムを編集することができます。
