ディレクトリ構造

FreeTrainは、起動時に pluginsディレクトリ内をスキャンし、有効なプラグインをすべて読み込みます。 プラグインは、pluginsディレクトリの下に個別のフォルダを作成して配置します。

FreeTrain/
  ├── FreeTrain.exe
  ├── ...
  └── plugins/
       ├── org.kohsuke.freetrain.system/  (システムプラグイン)
       ├── my.first.plugin/               (自作プラグイン)
       │    ├── plugin.xml                (定義ファイル: 必須)
       │    ├── house.bmp                 (画像ファイル)
       │    └── ...
       └── ...

• プラグインID: 各プラグインフォルダには、一意な名前（ID）を付けることが推奨されます。慣習として、Javaのパッケージ名のようにドメインを逆にした形式（例: org.kohsuke.freetrain.trains）がよく使われますが、重複しなければ自由に命名できます。
• 必須ファイル: プラグインとして認識されるためには、フォルダ直下に plugin.xml というファイルが必ず存在する必要があります。

ロード順序と依存関係

プラグイン間には依存関係が存在する場合があります。例えば、あるプラグイン（A）が別のプラグイン（B）の機能や画像を利用している場合、Bが先に読み込まれている必要があります。

これを制御するのが、plugin.xml内の <depend> タグです。

<plug-in>
  <!-- このプラグインは org.kohsuke.freetrain.rail.signal に依存している -->
  <depend on="org.kohsuke.freetrain.rail.signal"/>
  ...
</plug-in>

FreeTrainは、これらの依存関係を解析し、正しい順序でプラグインをロードします。

基本構造の例

<?xml version="1.0" encoding="Shift_JIS"?>
<plug-in>
  <!-- プラグイン全体の情報 -->
  <title>サンプルの建物プラグイン</title>
  <author>FreeTrain Developer</author>
  
  <!-- 1つ目の要素: 商業ビル -->
  <contribution type="commercial" id="{GUID-1234-5678...}">
    <name>小さな商店</name>
    <price>1000</price>
    <size>1,1</size>
    <height>1</height>
    <!-- 画像の定義など -->
    ...
  </contribution>

  <!-- 2つ目の要素: 住宅 -->
  <contribution type="commercial" id="{GUID-8765-4321...}">
    <name>平屋の住宅</name>
    ...
  </contribution>
</plug-in>

※ XMLのエンコーディングは、日本語を含む場合はShift_JISが標準的に使用されます（歴史的経緯による）。UTF-8も使用可能ですが、既存の多くのプラグインはShift_JISで記述されています。

プロファイルの作成

プロファイルは .ftprofile という拡張子のXMLファイルです。FreeTrainの実行ファイルと同じディレクトリや、マイドキュメントなどに保存します。

<?xml version="1.0" encoding="Shift_JIS" ?>
<profile>
  <!-- 指定したディレクトリ以下のすべてのプラグインを読み込む -->
  <!-- dir属性は、このプロファイルファイルが存在するディレクトリからの相対パス、または絶対パスで指定します -->
  <plugin dir="plugins\system" includes="*" />
  
  <!-- 特定のパターンのプラグインのみ読み込む -->
  <plugin dir="plugins\trains" includes="jp.co.trains.jr.*" />
  
  <!-- 特定のプラグインを除外することはできないため、必要なものだけを列挙する -->
</profile>

プロファイルによる起動

作成したプロファイルを使用して起動するには、コマンドライン引数を使用するか、プロファイルファイルをFreeTrain.exeにドラッグ&ドロップします。

FreeTrain.exe my_city.ftprofile

プロファイルを指定せずに起動した場合、デフォルトの挙動（通常はすべてのプラグインをロード、または標準プロファイルを使用）となります。開発中は、テスト用の軽量なプロファイルを作成しておくと、起動時間を短縮できます。

FreeTrain.exeは起動時の引数として、読み込むプロファイルファイルのパスを1つだけ受け取ることができます。現在のバージョンでは、これ以外のコマンドラインオプション（引数による詳細な動作設定など）は用意されていません。複数の環境を使い分けたい場合は、用途ごとにプロファイルを作成して使い分けるのが標準的な方法です。

画像の形式と最適化

FreeTrainでは、メモリ効率の良い256色(8bit)モードのBMP形式が標準として推奨されています。透過色は画像の左上隅のピクセルで判定され、半透明（アルファチャンネル）はサポートされません。

詳細な仕様や作成時の注意点については、第4部の以下のセクションを参照してください。

• サポートされる画像形式
• 透過色と画像作成の注意点

コントリビューションIDの命名規則

コントリビューションの id 属性は、他のすべてのコントリビューションの中で一意（被らない）である必要があります。
ツールで生成したGUID（例: {FE923791-6537-446D-9617-E55344FEAC2F}）をそのまま使用することも可能ですが、これではログやデバッグ時に何のエラーか判別しづらくなります。

推奨フォーマット: {作者ID-カテゴリ-名称-GUIDの一部}

例: {username-train-jreast-e231-02C7DAAA}

このように、可読性と一意性を兼ね備えたIDを付けることで、作者自身もユーザーもトラブルシューティングが容易になります。

互換性の維持（プラグイン更新時の注意）

一度公開され、ユーザーのセーブデータで使用されているプラグインを更新する場合、互換性を損なわないように注意が必要です。

• やってはいけないこと (NG):
  • IDの変更: コントリビューションIDを変えると、ゲームはそれを「全く新しい別の建物」と認識します。セーブデータ上の古い建物は「IDが見つからない」状態となり、消滅したりエラーになったりします。
  • 建物のサイズの変更: 既に配置された建物のサイズが変わると、周囲の地形や他の建物と整合性が取れなくなります。
  • プラグインフォルダ名の変更: ユーザーが古いフォルダを残したまま新しいフォルダを入れると、同じIDを持つプラグインが重複して読み込まれ、衝突エラーが発生します。
• やってもよいこと (OK):
  • 画像の差し替え: 画像の変更や、スプライトの切り出しの変更、オーバーライドの追加などは問題ありません。
  • パラメータの調整: 価格、定員などの数値変更は、既存のセーブデータにも反映されます（一部、再配置が必要な場合もあります）。