CFGファイルドキュメンテーション(翻訳+補足)

ここに示す内容はCFG File Documentationの翻訳です。
ただし全文訳ではなく、必要に応じて省略・補足・改訂を加えています。

configフォーマット

KSPで利用されるconfigフォーマットはUnityクラスではなく、KSP特有のものです。
KSPは.cfgファイルをconfigノードに読み込みます。
configノードは(シリアル化されたすべてのデータ型の)値と子ノードを持つことができます。
より詳しくはC#クラス ドキュメンテーションを参照してください。


KSPでは、パーツ、燃料資源、UIなど様々なものを定義するためにconfigファイル(*.cfg)を利用しています。
v0.24.2までにおいては、configファイルの必須要素は微々たるものです。
また、順序は不動です。
ただし、互換性及びデバッグ上の理由から一般的な構造を踏襲することを勧めます。
多くのバニラパーツにはあなたが学習する際に助けとなるようなコメント文を含んでいます。

さて、ここでは例として"DoesItAll"というパーツを考えます。
このパーツは以下のフォルダにおかれています。

KSP_win\GameData\ShadowSplat\Parts\Engine\DoesItAll

そしてこのフォルダは以下の3つのファイルを含みます。

KSP_win\GameData\ShadowSplat\Parts\Engine\DoesItAll.cfg

KSP_win\GameData\ShadowSplat\Parts\Engine\DoesItAll.mu

KSP_win\GameData\ShadowSplat\Parts\Engine\DoesItAll.mbm

注：これは一般例であり、追加の情報は各リンク先を参照してください。

moduleマネージャ

configデータはノード木もしくは文字列のみからなる単純なものです。
configの構文解析は.cfgファイルを利用する各moduleによって行われます。
詳しくはAPIのKSPFieldを参照してください。
MODモジュールマネージャは強力なフィルタリングと拡張機能をconfigノードフォーマットに与えます。
'@'、'[ ]'、その他プログラミングのような記号を見かけたとき、そのconfigはmoduleマネージャによって利用されています。
より詳しくはin the forum threadやon sarbian's Githubを参照してください。

CFGファイルの基本仕様

それぞれのCFGファイルは複数のセクションで構成されており、すべてのファイルに共通なものもあれば、特定のファイルのみに記述されるものもあります。
それらを理解することはMOD作成の上で必須となるでしょう。


CFGファイルでは改行が要素の区切りを表します。
そのため、1行に複数のフィールドを記述したり、逆に1つのフィールドを複数行にまたがって記述することはできません。


CFGファイルは構造体、フィールド、コメントからなります。
構造体は複数の子構造体とフィールドをまとめる構文です。
構造体の定義は以下のように、構造体名 + "{" + 構造体の内容 + "}"と記述します。

PART

{

～～～

}

フィールドは実際に値を設定するための構文です。
フィールドの定義は以下のように、フィールド名 + "=" + 値と記述します。

mass = 1.50

コメントはCFGファイルに補足説明を加えるためのものです。
コメント文はゲームに反映されることはありません。
以下のように、"//"からその行の終わりまでがコメント文となります。

mass = 1.50 // ここはコメント文です

標準的なパーツCFG作成ガイドライン

すべてのパーツはconfigファイル、モデル/コリジョンメッシュなど複数のファイルからなります。
バージョン0.25においては、モデル/コリジョンメッシュはモデリングソフトウェアで作成され、エクスポート時には材料が割り当てられている必要があります。
ここではモデリングについての導入は省きます。

新しいパーツを作るとき、すべてのファイル(必要ならば追加のモデルやメッシュを含む)を、そのパーツのフォルダにまとめておく必要があります。
この点においてはSquad自身が恐ろしく矛盾をしていますが、フォルダ名をパーツ名とし、なおかつcfgファイル中で参照するパーツ名と一致させることが望ましいです。
(ここで言うパーツ名とはビルド名ではありません。詳しくは後述)

複数のパーツを作る場合、パーツの種類ごとにフォルダ分けしたいと考えるかもしれません。
これは実際利にかなっており、Squadもそのようにしています。
例えば、エンジンを作ったならば"/Engines/"ディレクトリに配置するのがよいでしょう。

ただパーツを提供する以上のことをするMODをつくるなら、パーツフォルダや他の機能のフォルダといったように更なるサブフォルダを作りたい場合もあるでしょう。

MODフォルダはどれほど深くネストしても構いませんが、MOD固有のフォルダにまとめて/GameDataフォルダに配置しておくべきでしょう。
これは、MOD配布の際に非常に利便性を向上させます。

例えば、"ShadowSplat"というMODパッケージを作成した場合、そのディレクトリ構造を以下のようにするということが考えられます。

KSP_win\GameData\ShadowSplat\

KSP_win\GameData\ShadowSplat\Agencies

KSP_win\GameData\ShadowSplat\Resources

KSP_win\GameData\ShadowSplat\Parts

KSP_win\GameData\ShadowSplat\Parts\Engine

KSP_win\GameData\ShadowSplat\Parts\FuelTank

KSP_win\GameData\ShadowSplat\Parts\Science

KSP_win\GameData\ShadowSplat\Parts\Electrical

このように、"\GameData\[MODパッケージ名]\[グループ]\[カテゴリ名]\[パーツ名]\"などのようにするのが実用的でしょう。

パーツの定義は、すべてPART構造体の中に記述します。

基礎パラメータ

これらはPART構造体において基本的に必須であると考えられるフィールドです。

Part

{

name = InternalUniqueModelName

module = Part

author = AuthorName

～～～

}

モデルパラメータ

レガシーバージョンではmeshフィールドにより定義していましたが、現在は以下のフィールドからなるMODEL構造体で定義することが推奨されます。
が、やはりレガシー構文を現在も利用しているMODも多いようです。

互換性のため以下の構文が残されています。

Part

{

～～～

MODEL

{

model = Squad/Part/Utility/ModelFileDir/ModelFileName

scale = 1.0

texture = TextureFileName.png

}

～～～

}

アセットパラメータ

Part

{

～～～

mesh = ModelFileName.mu

scale = 1.0

～～～

}

コネクタノードの定義

他パーツをアタッチできる/にアタッチするためのコネクタノードを定義します。
記述形式をいかに示します。

[ノード名] = x, y, z, angx, angy, angz, size

以下に示す複数のノード名が利用できることが知られていますが、node_attach以外は単にノードの位置をわかりやすくするために便宜的に名づけられているに過ぎないようです。

• node_attach
• node_stack_top
• node_stack_bottom
• node_stack_connect01
• node_stack_connect02
• node_stack_connect03
• node_stack_bottom01
• node_stack_bottom02
• node_stack_bottom03
• node_stack_bottom04

以下にコネクタノード定義の例を示します。

Part

{

～～～

node_stack_top=0.0, 1.65, 0.0, 0.0, 1.0, 0.0, 2 // ノード名"node_stack_top"として、位置(0.0, 1.65, 0.0)に向き(0.0, 1.0, 0.0)でサイズ2のコネクタを作る。

～～～

}

FX定義

視覚FX

比較的新しいパーツではこれらフィールドを設定する代わりにEFFECTS構造体を定義しているようです。
パーツに関連付けられた、エンジンの噴煙・爆発・着色などの視覚エフェクトを視覚FXとして定義します。
各々が固有のエフェクトを表し、エフェクトの配置のパラメータを持ちます。
末尾の'Active'スイッチはエフェクトがどのようなときに表示されるかを表します。
視覚FX定義は以下のように記述します。

[fxName] = x, y, z, angx, angy, angz, [scenes]

どのようなエフェクトが利用可能で、どのようなときに使用されているかを知りたいときはFXグループリストを参照してください。
複数のscenesをエフェクトに割り当てることも可能です。
例えば、activeでもdeactiveでも煙のエフェクトを表示させたいときには以下のように記述するといいでしょう。

fx_gasBurst_white = x, y, z, angx, angy, angz, activate, deactivate

これは、RCSのガス放出など多くのエフェクトを定義したい場合に便利です。

fx_exhaustFlame_yellow = x, y, z, angx, angy, angz, activate

fx_exhaustLight_yellow = x, y, z, angx, angy, angz, activate

fx_smokeTrail_medium = x, y, z, angx, angy, angz, activate

以下のようなFXが知られています。

• fx_exhaustFlame_blue_small
• fx_exhaustFlame_yellow
• fx_exhaustFlame_yellow_tiny
• fx_exhaustFlame_blue
• fx_exhaustFlame_white_tiny
• fx_exhaustLight_yellow
• fx_exhaustLight_blue
• fx_smokeTrail_medium
• fx_smokeTrail_light
• fx_gasBurst_white
• fx_exhaustSparks_flameout
• fx_exhaustSparks_yellow

PART

{

～～～

fx_exhaustFlame_blue = 0.0, -10.3, 0.0, 0.0, 1.0, 0.0, running

～～～

}

効果音FXの定義

比較的新しいパーツではこれらフィールドを設定する代わりにEFFECTS構造体を定義しているようです。
視覚エフェクト同様に効果音も定義することができます。
効果音FX定義は以下のように記述します。

[soundName] = [scenes]

以下のような効果音FXが知られています。

• sound_jet_low
• sound_jet_deep
• sound_vent_soft
• sound_vent_large
• sound_vent_medium
• sound_rocket_hard
• sound_rocket_mini
• sound_decoupler_fire
• sound_explosion_low
• sound_parachute_open
• sound_parachute_single

PART

{

～～～

sound_rocket_hard = running

～～～

}

視覚FXおよび効果音FXでscenesに設定できる値は以下のようなものが知られています。

エディタパラメータ

PART

{

～～～

CrewCapacity = 1

TechRequired = start

entryCost = 0

cost = 600

category = Pods

subcategory = 0

title = Mk1 Command Pod

manufacturer = Kerlington Model Rockets and Paper Products Inc

description = Originally built as a placeholder for a demonstration mock-up of a rocket, the Mk1 Command Pod was heralded as a far safer and more reliable option than its predecessors by rocket scientists throughout the world. It is now commonly seen in active service.

～～～

}

アタッチメントルール

attachRulesは以下のように5つの値(0または1)により定義されます。

attachRules = stack, SrfAttach, allowStack, allowSrfAttach, allowCollision

stack

このパーツを他パーツのコネクタに取り付けることができるか

SrfAttach

このパーツを他パーツの側面に取り付けることができるか

allowStack

他パーツをこのパーツのコネクタに取り付けることができるか

allowSrfAttach

他パーツをこのパーツの側面に取り付けることができるか

allowCollision

このパーツを他パーツと重なるように取り付けることができるか

0は不可を、1は許可を表します。


stackSymmetryは0:対称性なし、1:2回対称、2:3回対称、3:4回対称…という風になっています。

PART

{

～～～

attachRules = attachRules = 1,0,1,0,0 // 他パーツのコネクタに取付可、他パーツの側面に取付不可、他パーツをコネクタに取付可、他パーツを側面に取付不可、他パーツと重なる取付不可

stackSymmetry = 2 // このパーツのコネクタへの対称配置を3回対称に限定

～～～

}

標準パーツパラメータ

パーツの物理的ふるまいを定義します。
必ずしもすべてを定義する必要はありません。省略された値にはデフォルト値が適用されます。
ここで定義された値は、射点や滑走路に機体が配置されてから常に利用され続けます。

MODULE

MODULE構造体はパーツの挙動を定義するために使用します。
これら構造体はゲーム中においてKSP本体やMODのライブラリが実装するメソッドを呼び出し実行します。
nameフィールドでは呼び出したいMODULEの具体名を指定します。
例えばClamp-O-Tron Docking Port Sr.にはドッキングポートの機能を提供するModuleDockingNodeモジュールが定義されています。

PART

{

～～～

MODULE

{

name = ModuleDockingNode

～～～

}

～～～

}

既知のモジュールは以下の様なものがあります。

MODULEは1つのパーツにいくつでも持たせることができます。
基本的にはMODULE名が同一のものが複数含まれていても問題ありません。

INTERNAL

INTERNAL構造体は、IVAで見られる船の内装を作成するためのファイルを指定するために使用します。
一般的には、内装CFGはMOD中のSpacesディレクトリに配置されます。
KSPはパーツCFGのPART.INTERNAL.nameフィールドと内装CFGのINTERNAL.nameフィールドを比較し、一致するものをその有緑パーツの内装として呼び出すようです。

バニラでは以下の9つの内装が用意されています。

• crewCabinInternals
• cupolaInternal
• GenericSpace1
• GenericSpace3
• landerCabinInternals
• landerCabinSmallInternal
• mk1CockpitInternal
• mk1PodCockpit
• PodCockpit

PART

{

～～～

INTERNAL

{

name = mk1PodCockpit

}

～～～

}

RESOURCE

RESOURCE構造体は、そのパーツが燃料や電気などのリソースを備蓄できることを指定するために使用します。
リソース1つにつき1つのRESOURCE構造体が必要になります。
RESOURCEは1つのパーツにいくつでももたせることができます。

バニラでは以下のリソース名が利用できます。

• LiquidFuel
• Oxidizer
• SolidFuel
• MonoPropellant
• XenonGas
• ElectricCharge
• IntakeAir
• EVA Propellant
• Ore
• Ablator

PART

{

～～～

RESOURCE

{

name = ElectricCharge

amount = 100

maxAmount = 100

isTweakable = false

hideFlow = true

}

～～～

}

リソースCFGファイル

KSPではゲーム中必要な燃料や電気などのリソースもCFGファイルで定義しており、好きな様に変更や追加が可能です。
バニラのリソースは\GameData\Squad\Resources\ResourcesGeneric.cfgで定義されています。

リソースの定義はRESOURCE_DEFINITION構造体で行います。

flowModeには以下の値を指定できます。

STACK_PRIORITY_SEARCH

建造時の積み重ね順に消費されます。すなわち、VAB/SPHにおけるルートパーツに近い順に消費されます。FuelLineを利用すると消費順を変更することができます。

STAGE_PRIORITY_FLOW

現在のステージに属するパーツから消費されます。ステージが異なるパーツからは消費されません。FuelLineを利用すると他のステージからも消費できるようになります。

ALL_VESSEL

機体全体から一様に消費されます。

NO_FLOW

リソースは他のパーツに移動しません。リソースを備蓄しているパーツのみが消費できます。

RESOURCE_DEFINITION

{

name = LiquidFuel

density = 0.005

unitCost = 0.8

hsp = 2010

flowMode = STACK_PRIORITY_SEARCH

transfer = PUMP

isTweakable = true

}

Science CFG

サイエンス実験の種類を定義します。
(編集中・・・)

Contracts Definitions CFG

Mission Controlで受けられるミッションの説明文を自動生成するためのジェネレータを定義します。
(編集中・・・)

Contracts CFG

Mission Controlで受けられるミッションの内容を定義します。
(編集中・・・)

Agent CFG

Mission Controlで受けられるミッションの発注者を定義します。
(編集中・・・)

Kerbal CFG

ユニークKerbalを定義します。
(編集中・・・)

Props CFG

ゲーム中に利用されるUIなどを定義します。
(編集中・・・)

Internals CFG

有緑パーツの内装を定義します。
(編集中・・・)

Strategies CFG

Administration Buildingで実行できる戦略を定義します。
(編集中・・・)

Department CFG

Administration Buildingで実行できる戦略の分類を定義します。
(編集中・・・)

コメント