FreeTrain 開発者マニュアル > 第3部：XML記述リファレンス (1/2)

第3部：XML記述リファレンス (1/2)

本章では、plugin.xmlに記述する各コントリビューションの詳細な仕様を解説します。実際のプラグイン開発で使用されているタグや属性に基づき、具体的な記述例を示します。

3.1 基本要素

すべてのプラグインに共通する基本的な記述ルールです。

XML宣言とルート要素

plugin.xmlは <plug-in> をルート要素とします。

<?xml version="1.0" encoding="Shift_JIS" ?>
<plug-in>
  <title>プラグインのタイトル</title>
  <author>作者名</author>
  <homepage>http://example.com/</homepage>

  <!-- ここに各コントリビューションを記述 -->
  
</plug-in>

コントリビューションの定義

ゲームに追加する個々の要素は <contribution> タグで定義します。

type 属性: 追加する要素の種類を指定します（必須）。例: trainCar (車両), commercial (建物), road (道路)。
id 属性: 要素を一意に識別するIDを指定します（必須）。他のプラグインと衝突しないよう、作者名や名称を含む可読性の高い形式が推奨されます。詳細は第2部 2.4 コントリビューションIDの命名規則を参照してください。例: {username-train-jreast-e231-02C7DAAA}

外部ファイルの参照

大規模なプラグイン（多数の車両を含む場合など）では、plugin.xmlが肥大化しがちです。XMLのENTITY機能を使うことで、記述を複数のファイルに分割管理できます。

plugin.xml:

<?xml version="1.0" encoding="Shift_JIS" ?>
<!DOCTYPE plugin [
  <!-- 外部ファイルの定義 -->
  <!ENTITY myTrain1 SYSTEM "trains/train1.xml">
  <!ENTITY myTrain2 SYSTEM "trains/train2.xml">
]>
<plug-in>
  <title>分割管理の例</title>
  
  <!-- 定義したファイルを読み込み -->
  &myTrain1;
  &myTrain2;
</plug-in>

trains/train1.xml:

<contribution type="trainCar" id="{...}">
  <!-- 車両1の定義内容 -->
</contribution>

3.1.3 画像リソース

複数の場所（複数の建物や車両など）で同じ画像を使用する場合、画像を独立したコントリビューションとして定義し、それを参照することができます。これによりメモリ消費を抑えることができます。画像データの具体的な座標指定方法については、第4部 4.2 スプライトの定義を参照してください。

<!-- 画像のみの定義 -->
<contribution type="picture" id="{GUID-PIC-001}">
  <picture src="shared_building.bmp" />
</contribution>

<!-- 参照する側（例: 建物） -->
<contribution type="commercial" id="{GUID-BLDG-002}">
  ...
  <sprite origin="0,0" offset="40">
    <!-- src属性の代わりにref属性でIDを指定 -->
    <picture ref="{GUID-PIC-001}" />
  </sprite>
</contribution>

3.1.4 人口定義

建物などが持つ「人口」や「利用客数」の定義です。 <population> タグ内にクラスと基礎人口 base を指定します。

<population>
  <class name="freetrain.contributions.population.ResidentialPopulation" />
  <base>50</base> <!-- 基礎人口 -->
</population>

ResidentialPopulation（住宅）、OfficePopulation（オフィス）など、多数のクラスが用意されています。全クラスの一覧については、第5部 5.5 人口動態を参照してください。

人口クラスの複合:

ひとつの建物に、住宅と店舗の両方の特性を持たせたい場合は、CombinationPopulation を使用し、以下のように <population> タグを入れ子にして記述します。各クラスの人口が単純に合算されて計算されます。

<population>
  <class name="freetrain.contributions.population.CombinationPopulation" />
  <population>
    <class name="freetrain.contributions.population.ResidentialPopulation" />
    <base>50</base>
  </population>
  <population>
    <class name="freetrain.contributions.population.ShopperPopulation" />
    <base>20</base>
  </population>
</population>

3.1.5 カラーライブラリ

色置換 (hueTransform等) を行う際、特定の色コードではなく「カラーライブラリ」を指定することで、ユーザーが設置時に色を選択できるようになります。これは主に半ボクセル建築で使用されますが、他のコントリビューションでも利用可能です。

使用方法:

map タグの to 属性に、色コードの代わりにライブラリIDを指定します。

<map from="0,*,0" to="{COLORLIB-PASTEL}"/>

組み込み済みカラーライブラリ一覧 (10種):

各ライブラリのIDと、含まれる色の一覧です。

ID	説明	収録色
`{COLORLIB-STONES}`	石材
`{COLORLIB-WOODS}`	木材
`{COLORLIB-METALS}`	金属
`{COLORLIB-BRICKS}`	レンガ
`{COLORLIB-DIRTS}`	土・コンクリ
`{COLORLIB-PASTEL}`	パステル
`{COLORLIB-RAINBOW}`	カラフル
`{COLORLIB-COLPLATE}`	カラー鋼板
`{COLORLIB-ROOF}`	屋根・スレート
`{COLORLIB-NULL}`	色置換を行わない（プレースホルダ用）	(なし)

コントリビューションごとの挙動の違い:

半ボクセル建築 (HalfVoxelStructure): ライブラリIDを指定するだけで、ライブラリ内の全色が自動的にバリエーションとして展開されます。ユーザーは設置ウィンドウの「カラー」欄からこれらを選択できます。
建物総合 (GenericStructure): ライブラリID {...} を直接記述することはできません。 システムがIDを解釈できずエラーとなります。建物総合でこれらの色を使いたい場合は、上記のRGB値を参照し、必要な色の数だけ <spriteType> (または <colorVariation>) タグを手動で並べて記述してください。

カラーライブラリの自作

独自のカラーバリエーションを定義するには、ColorLibrary コントリビューションを使用します。
※この機能を使用するには、jp.co.tripod.chiname.lib.halfvoxel プラグインへの依存定義が必要です。

<contribution type="ColorLibrary" id="{GUID-MY-COLORS}">
  <name>マイカラーセット</name>
  <!-- 選択肢として表示したい色を列挙 -->
  <element color="255,0,0"/>
  <element color="0,255,0"/>
  <element color="0,0,255"/>
</contribution>

3.1.6 価格設定

各コントリビューション（建物、車両など）の <price> タグに設定する価格には、ゲーム全体の経済バランスを保つための推奨基準があります。

<price>, <fare>, <base> などのタグに記述する数値には、カンマ（,）を含めてはいけません。カンマが含まれているとシステムが数値を正しく読み込めず、エラーとなります。

価格スケール: FreeTrain EX Av ver.2以降では、現実の価格の 約1/3 を目安に設定することが強く推奨されています。
- 背景: ゲーム内の時間軸では、列車の運行速度や1日の長さの関係上、1日に得られる運賃収入が現実の1/10程度に留まります。これを補うため、運賃収入が現実のおよそ3倍のペースで発生するように計算式（第5部 5.2 運行・運賃の計算式の ×2 係数など）が調整されていますが、それでもまだ収益性が低いため、支出側（建設費や購入費）を現実の1/3の価格に抑えることで、ゲームとしての経営バランスを適正化しています。
- 例: 現実で建設費が1億円のビル → ゲーム内では 33000000 (3300万円) 程度に設定。
車両価格の目安: 鉄道車両については、運賃設定との整合性を取るため、基礎運賃 (fare) × 70,000 という計算式も推奨されています（詳細は3.2.2節参照）。

3.2 車両・交通

3.2.1 鉄道車両

個々の車両（先頭車、中間車など）を定義します。

<contribution type="trainCar" id="{GUID-CAR-001}">
  <!-- クラス定義: 通常は以下のいずれかを使用
       SymTrainCarImpl: 対称形（中間車など、前後同じ形状）
       AsymTrainCarImpl: 非対称形（先頭車など、前後で形状が異なる）
       ColoredTrainCarImpl: 色替え可能な車両
       ReverseTrainCarImpl: 他の車両を反転（baseタグで参照）
  -->
  <class name="freetrain.contributions.train.SymTrainCarImpl"/>
  
  <capacity>140</capacity>     <!-- 定員 -->
  <seatedcapacity>50</seatedcapacity> <!-- 着席定員（評価に影響） -->
  
  <!-- 画像定義: 32x32ピクセルのスプライト -->
  <sprite origin="0,0">
    <picture src="car_image.bmp" />
  </sprite>
</contribution>

※一両ごとに異なる価格を設定することはできません。価格は編成 (train) 側で設定します。

色替え可能な車両 (ColoredTrainCarImpl)

あらかじめ定義されたベース画像（colorMapTrainPicture）に対し、XML上で指定した色を合成して表示する形式です。画像ファイル自体を新規に作成することなく、1つのベース画像から多様なバリエーションを作成できます。

<contribution type="trainCar" id="{GUID-CAR-COLORED}">
  <class name="freetrain.contributions.train.ColoredTrainCarImpl" />
  <capacity>140</capacity>
  <seatedcapacity>50</seatedcapacity>
  <!-- 
    picture: ベースとなる色替え用画像リソースのID
    base: 車体メインの色 (RGB)
    line1, line2, line3: 各帯の色 (RGB)
  -->
  <colorMap picture="{BASE-PIC-ID}"
            base="255,255,255" line1="0,128,0" line2="192,192,192" line3="0,0,0" />
</contribution>

colorMapの自動生成

試験列車の色設定機能を使用すると、GUI上で色を調整しながら、上記の <colorMap> タグを自動生成できます。調整後、「クリップボードに色設定をコピー」ボタンを押すことで、そのままplugin.xmlに貼り付け可能なテキストを取得できます。自作車両のカラースキームを検討する際にも非常に有用です。

3.2.2 列車編成

定義した車両を組み合わせて、編成可能な列車セットを定義します。

<contribution type="train" id="{GUID-TRAIN-001}">
  <name>通勤電車 1000系</name>
  <type>通勤形</type>
  <company>FreeTrain鉄道</company>
  <description>1990年代に導入された標準的な通勤電車です。</description>
  
  <fare>400</fare>            <!-- 基礎運賃 -->
  <price>28000000</price>     <!-- 一両あたりの価格 (fare * 70000 程度) -->
  <amenity>100</amenity>      <!-- 魅力 (80-130) -->
  <triprange>short</triprange> <!-- 移動距離: short/middle/long -->
  <speed>medium</speed>       <!-- 速度: slow/medium/fast/superb -->
  
  <!-- 編成パターンの定義 (ParamTrainImpl: 自由編成) -->
  <class name="freetrain.contributions.train.ParamTrainImpl"/>
  <composition>
    <head carRef="{GUID-CAR-HEAD}"/> <!-- 先頭車 -->
    <body carRef="{GUID-CAR-BODY}"/> <!-- 中間車 -->
    <tail carRef="{GUID-CAR-TAIL}"/> <!-- 後尾車 -->
  </composition>
</contribution>

パラメータの決定基準

魅力 (amenity)

乗客の乗車意欲に影響します。標準的な山手線（E231系等）を 100 として、80 ～ 130 の範囲で設定するのが一般的です。
- システム上の制限: プログラム内部では 50 ～ 200 の範囲に制限されます。この範囲外の数値を指定しても、最小50、最大200として扱われます。
- 120 ～ 130: 特急、豪華列車、観光列車など。
- 110: クロスシートを備えた近郊型電車。
- 100: 標準的な通勤電車（205系、E231系など）。
- 90: 非冷房車、古い国鉄型車両（103系、旧型客車など）。
- 80: 貨物列車、あるいは極端に設備が劣る車両。
基礎運賃 (fare)

その列車に乗った際に発生する収益の基準値です。列車の格に合わせて以下の数値を参考に設定してください。
- 1100: 豪華寝台特急（ブルートレイン等）
- 800: 一般特急、有料急行
- 500 ～ 600: 急行、新快速（クロスシート車）
- 400: 一般的な通勤電車、地下鉄
価格 (price)

FreeTrain EX Av では、経営シミュレーションの整合性を保つため、以下の計算式による設定を推奨します。
- 価格＝基礎運賃 (fare) × 70,000
  - 例：基礎運賃 400 の通勤電車なら 28,000,000 (2800万円)。
  - これは建物価格（現実の1/3スケール）と整合性が取れており、木造アパート（2000万円）より少し高い、という適切な経済バランスになります。
移動距離 (triprange)

乗客がどの程度の距離までこの列車を利用し続けるかを設定します。
- short: 各駅停車、山手線などの短距離輸送。
- middle: 快速、湘南新宿ラインなどの中距離輸送。
- long: 有料特急、長距離鈍行、寝台列車。
速度 (speed)

マップ上での移動速度を定義します。(FreeTrain EX Av ver.2の場合) キーワードによる指定のほか、数値を直接指定することでより細かな調整が可能です。
- superb: 超高速 (1分間に1ボクセル走行 = 1)
- fast: 高速 (2分間に1ボクセル走行 = 2)
- medium: 中速 (3分間に1ボクセル走行 = 3)
- slow: 低速 (4分間に1ボクセル走行 = 4)
- 数値指定: 「1ボクセル進むのに要する時間（分）」を整数で直接指定できます。
  - 例: <speed>8</speed> と指定すると、slow の半分の速度（超低速）になります。
  - この「分」はゲーム内時間です。

編成パターンの詳細

自由編成型 (ParamTrainImpl)

先頭・中間・後尾を指定し、プレイヤーが購入時に長さを自由に変更できるタイプです。
- <head>, <tail> は省略可能です。省略すると <body> の車両が代用されます。
個別指定型 (PatternTrainImpl)

編成を実車通りに固定したい場合に使用します。
```
<class name="freetrain.contributions.train.PatternTrainImpl"/>
<config>
  
  <car char="先" ref="{GUID-HEAD}"/>
  <car char="中" ref="{GUID-BODY}"/>
  <car char="後" ref="{GUID-TAIL}"/>
  
  
  <composition>先後</composition>
  <composition>先中後</composition>
  <composition>先中中後</composition>
</config>
```
プレイヤーはここで定義された編成パターンしか購入できなくなります。

同じ長さ（車両数）の編成パターンを複数定義することはできません（例：2両編成として「先後」と「先先」の両方を記述するなど）。同じ長さの定義が重複している場合、プラグインのロード時にエラーが発生します。

3.2.3 道路

道路を定義します。<style> タグによって、その道路の規模、歩道の有無、車線数を設定します。これらの値は、駅周辺の発展アルゴリズムや画面上の表示名称に影響します。

<contribution type="road" id="{GUID-ROAD-001}">
  <class name="freetrain.contributions.road.StandardRoadContribution" />
  <name>街路/二車線/街灯あり</name>
  <description>歩道が整備された二車線の街路です。</description>
  
  <!-- スタイル設定 -->
  <style name="street" sidewalk="pavement" lanes="2"/>
  
  <!-- 道路の場合、picture タグに size（1パターンあたりの画像サイズ。通常は 32,32）と offset（垂直オフセット）属性が必須です -->
  <picture src="road.bmp" size="32,32" offset="16">
    <override when="night" src="road_night.bmp"/>
  </picture>
</contribution>

道路配置クラス (class)

道路の接続の仕組みと画像の切り出し方法を決定します。

freetrain.contributions.road.StandardRoadContribution

現在の標準的なクラスです。接続状態（直線、カーブ、三差路、十字路など）に応じて15種類の画像を使い分けます。道路として自然な見た目を実現するためには、このクラスに合わせて15パターンを用意するのが基本です。
freetrain.contributions.road.A3RoadContribution

『A列車で行こう3』の仕様に基づいた簡略化クラスで、以下の3種類の画像（各32x32ピクセル）を横に並べた画像を使用します。
1. 東西直線、2. 南北直線、3. 交差点・その他
本来はA3の道路を再現するためのものですが、現在では「バラスト（敷石）」「芝生」「広場」など、15パターンの描き分けを必要としないテクスチャ的な表現において、画像作成コストを抑えるために広く活用されています。

スタイル属性値のリファレンス

name 属性

道路の基本的な種別を指定します。
- unknown (または未指定): 道路ではないもの（水面など）。
- footpath: 小道、農道、遊歩道など。
- street: 一般的な車道、生活道路。
- highway: 高速道路、自動車専用道路。
- railballast: 線路敷石（道路として認識されません）。
sidewalk 属性

歩道の形式を指定します（name が street または highway の場合のみ有効）。
- none (または未指定): 歩道なし。
- shoulder: 路側帯（人が通行可能な程度の幅員）。
- pavement: 構造的に分離・整備された歩道。
lanes 属性

車線数を数値で指定します。表示名称に「n車線」として反映されます。

属性の組み合わせと表示名称

設定された属性の組み合わせにより、ゲーム中では以下の7種類のいずれかとして扱われ、表示されます。

name	sidewalk	lanes	画面表示の例
`unknown`	(任意)	(任意)	未定義
`footpath`	(任意)	(任意)	小道
`street`	`none` / `shoulder`	n	n車線街路
`street`	`pavement`	n	歩道付きn車線街路
`highway`	`none` / `shoulder`	n	n車線高速道
`highway`	`pavement`	n	歩道付きn車線高速道
`railballast`	(任意)	(任意)	線路敷石

3.2.4 ダミー自動車

道路上に配置する、動かない自動車（アクセサリー）を定義します。 variations タグを使用することで、1つの定義で複数の色違いを一括して登録できます。

<contribution type="DummyCar" id="{GUID-DUMMYCAR-001}">
  <name>乗用車A</name>
  <sprite origin="0,0" offset="8">
    <picture src="car_patterns.bmp"/>
    <!-- 色違いのバリエーション定義 -->
    <variations>
       <colorVariation>
          <spriteType name="colorMapped">
            <map from="255,0,0" to="0,0,255" /> <!-- 赤を青に置換 -->
         </spriteType>
       </colorVariation>
       <colorVariation>
         <spriteType name="colorMapped">
          <map from="255,0,0" to="0,255,0" /> <!-- 赤を緑に置換 -->
         </spriteType>
       </colorVariation>
    </variations>
  </sprite>
</contribution>

画像形式: origin で指定した座標から、横方向に2つのパターン（各32px）が並んでいる必要があります。
1. 東西方向（左下⇔右上）: 画面の左下（西）から右上（東）へ延びる道路用の画像。
2. 南北方向（右下⇔左上）: 画面の右下（南）から左上（北）へ延びる道路用の画像。
サイズ: 幅32px (1ボクセル分)、高さは 16 + offset px です。

3.2.5 道路アクセサリ

標識、信号機、横断歩道など、道路に付随する施設を定義します。

<contribution type="roadAccessory" id="{GUID-ROADACC-001}">
 <name>速度制限標示</name>
  <sprite>
       <picture src="road_sign.bmp"/>
  </sprite>
</contribution>

画像構造: 128x32ピクセルの画像で、左から32x32ピクセルの画像が4つ並んだ構造をしています。
1. 東西方向（左下⇔右上）・奥側: 道路の奥側に描画されます。
2. 南北方向（右下⇔左上）・奥側: 道路の奥側に描画されます。
3. 東西方向（左下⇔右上）・手前側: 道路の手前側（車両より前）に描画されます。
4. 南北方向（右下⇔左上）・手前側: 道路の手前側（車両より前）に描画されます。
※この並び順（東西・南北・東西・南北）は架線柱 (electricPole) と共通の仕様です。

3.2.6 発車ベル

列車が駅から発車する際に鳴るベル音（メロディ）を定義します。ホームのプロパティから選択できるようになります。

<contribution type="trainDepartureBell" id="{GUID-BELL-001}">
  <name>発車ベルA</name>
  <!-- WAVE形式のファイルを指定。効果音(SE)として再生されるため、BGMとは異なりMP3等はサポートされません -->
  <sound href="departure_bell.wav" />
</contribution>

3.3 建物・構造物

3.3.1 建物総合

従来の commercial (高さ固定) と varHeightBuilding (高さ可変) を統合し、さらに色替えやカテゴリ分類機能を強化した形式です。現在のFreeTrain EX Avで建物を追加する場合、原則としてこの形式を使用してください。

高さ固定

高さが固定された一般的な建物の定義です。

<contribution type="GenericStructure" id="{GUID-GENERIC-BLDG-001}">
  <name>新しいオフィスビル</name>
  <price>150000000</price>
  <size>1,1</size>
  <height>4</height>
  
  <population>
    <class name="freetrain.contributions.population.OfficePopulation"/>
    <base>100</base>
  </population>
  
  <structure>
    <category byname="オフィスビル"/>
  </structure>

  <!-- 色替え定義 (spriteの兄弟要素として記述する) -->
  <spriteType name="hueTransform">
     <map from="*,0,0" to="166,189,203"/>
  </spriteType>

  <!-- 画像定義: 必ず ref で参照する -->
  <sprite origin="0,0" offset="40">
    <picture ref="{GUID-PICTURE-DEF}"/>
  </sprite>
</contribution>

高さ可変

高さを範囲内で自由に設定できる建物の定義です。<sprite> の代わりに <pictures> タグを使用します。画像は top (上層部)、middle (中層部)、bottom (下層部) の3パーツに分けて指定します。topとbottomは複数記述できます（plugins\jp.co.tripod.chiname.structure.hotelを参照）。

<contribution type="GenericStructure" id="{GUID-GENERIC-VAR-001}">
  <name>伸縮マンション</name>
  <price>20000000</price>
  <size>3,4</size>
  <minHeight>4</minHeight> <!-- 最小高さ -->
  <maxHeight>11</maxHeight> <!-- 最大高さ -->
  
  <population>
    <class name="freetrain.contributions.population.ResidentialPopulation"/>
    <base>180</base>
  </population>
  
  <structure>
    <category byname="集合住宅"/>
  </structure>

  <!-- 画像定義 (高さ可変) -->
  <pictures>
    <!-- top: 上層部 (1回だけ描画) -->
    <top origin="0, 0" offset="32">
      <picture ref="{GUID-PICTURE-DEF}"/>
    </top>
    <!-- middle: 中層部 (高さに応じて繰り返し描画) -->
    <!-- 中間層の画像は高さ16px（1ボクセル分）を1単位として作成します -->
    <middle origin="0, 64" offset="32">
      <picture ref="{GUID-PICTURE-DEF}"/>
    </middle>
    <!-- bottom: 下層部 (複数定義することで2階層以上の下層部を作ることも可能) -->
    <!-- 複数定義した場合、XMLで上に記述したものが上階、下に記述したものが地面側（最下層）になります -->
    <bottom origin="0, 128" offset="32">
      <picture ref="{GUID-PICTURE-DEF}"/>
    </bottom>
  </pictures>
  
  <!-- 方向違い（90度回転） -->
  <pictures opposite="true">
    <top origin="112, 10" offset="30">
       <picture ref="{GUID-PICTURE-DEF}"/>
    </top>
    <middle origin="112, 66" offset="38">
       <picture ref="{GUID-PICTURE-DEF}"/>
    </middle>
    <bottom origin="112, 128" offset="40">
       <picture ref="{GUID-PICTURE-DEF}"/>
    </bottom>
  </pictures>
</contribution>

詳細パラメータ説明

方向定義 (opposite)
- opposite="true": この属性を <sprite> (または <pictures>) タグに付与すると、その画像は <size> タグで指定した寸法を縦横入れ替えて解釈されます。
  - 例：<size>2,3</size> と定義された建物の場合、opposite="true" が付いた画像は 3x2 のサイズとして扱われます。これにより、長方形の建物の回転した状態を正しく定義できます。
カテゴリ (category) と非表示 (hide)
- byname: 建物類別を指定します。指定可能な名称については、付録 7.3 建物カテゴリ一覧を参照してください。
- hide="true": 複数のカテゴリを指定した際、特定のカテゴリのメニュー一覧には表示させたくない場合に使用します。
  - 将来的な検索や自動発展アルゴリズムでの利用を想定し、その建物が持つ属性としてデータは持たせたいが、メニューを煩雑にしたくない場合に有用です。

重要な制約事項

GenericStructureを使用する際は、以下のルールを厳守してください。守らない場合、色変換が機能しなかったり、エラーが発生したりします。

画像は ref で参照する: <sprite> や <pictures> タグ内で src 属性を使って画像を直接指定することはできません（仕様上の制限）。必ず picture コントリビューションとして画像を個別に定義し、それを ref 属性で参照してください。
spriteType は sprite の外に記述する: 色替えを定義する <spriteType> タグは、<sprite> (または <pictures>) タグの兄弟要素として記述してください。子要素として中に書いてはいけません。 ※これはGenericStructure独自のパースルールの制約です。システム内部では最終的に <sprite> の子要素として結合されますが、XMLの記述段階では外側に置く必要があります。

旧来のCommercialからの変換

古い形式 (commercial) で作られたプラグインを、ソースコードを変更せずにGenericStructureとして「建物総合」メニューに表示させるためのテクニックとして、変換プラグインの作成があります。既存の画像や定義を再利用しGenericStructureとして再定義します。

例: 古いプラグイン (ID: {OLD-GUID}) を GenericStructure 化する

<?xml version="1.0" encoding="Shift_JIS" ?>
<plug-in>
  <title>変換プラグインのタイトル</title>
  <!-- 元のプラグインに依存 -->
  <depend on="original.plugin.id" />

  <!-- 手順1: 画像の参照
       元のプラグインフォルダ内の画像を直接指定するか、
       元のプラグインが <picture> コントリビューションを公開していればそれを参照する
  -->
  <contribution type="picture" id="{NEW-GUID-PICT}">
    <!-- 相対パスで元のプラグインの画像を参照する例 -->
    <picture src="../original.plugin.folder/building.bmp" />
  </contribution>
  
  <!-- 手順2: GenericStructureとして定義 -->
  <contribution type="GenericStructure" id="{NEW-GUID-GS}">
    <name>変換された建物</name>
    <price>50000000</price>
    <size>4,7</size>
    <height>2</height>
    
    <!-- 元の画像定義を使用 -->
    <sprite origin="0,0" offset="37">
      <picture ref="{NEW-GUID-PICT}" />
    </sprite>
    
    <!-- 新しいカテゴリ定義 -->
    <structure>
      <category byname="公共施設" />
      <category byname="展示場" />
    </structure>
    
    <computerCannotBuild/>
  </contribution>
</plug-in>

この方法を使えば、過去の資産を活かしつつ、最新のUI環境に適応させることができます。

3.3.2 半ボクセル建築

1ボクセルを半分に分割して配置できる、小さな建物やオブジェクトを定義します。「工事」＞「半ボクセル建築」メニューに追加されます。

<contribution type="HalfVoxelStructure" id="{GUID-HALFVOXEL-001}">
   <group>半ボクセル建築</group>
   <subgroup>住宅</subgroup> <!-- ドロップダウンに表示されるサブグループ -->
   <name>小さな家</name>
   <price>100</price>
   <height>1</height>
   <population>
       <class name="freetrain.contributions.population.ResidentialPopulation"/>
       <base>3</base>
   </population>
   <sprite>
       <picture ref="{GUID-PICTURE-REF}"/>
       <!-- カラーライブラリを使用した色置換 -->
       <map from="0,*,0" to="{COLORLIB-PASTEL}"/>
       
       <!-- 各方向の画像定義
            direction: north (北), south (南), east (東), west (西)
            side: either (両面共通), fore (手前半分), back (奥半分)
            origin: 画像内の切り出し開始位置 (x,y)
       -->
       <pattern direction="west" side="either" origin="0,0"/>
       <pattern direction="south" side="either" origin="24,0"/>
       <pattern direction="east" side="either" origin="48,0"/>
       <pattern direction="north" side="either" origin="72,0"/>
   </sprite>
</contribution>

pattern: 方向ごとの画像の切り出し位置を指定します。
- direction: カメラから見た建物の向き（north, south, east, west）。4方向すべて定義する必要があります（同じ画像を使っても可）。
- side: ボクセル内の配置位置。fore（手前）、back（奥）、either（どちらでも同じ画像）を指定します。foreを指定した場合は対になるbackも定義する必要があります。
- origin: 画像ファイル内の左上座標。
カラーライブラリ: {COLORLIB-STONES}, {COLORLIB-WOODS}, {COLORLIB-PASTEL} などを指定することで、ユーザーが設置時に色を選択できるようになります。3.1.5 カラーライブラリを参照してください。
通常の色置換との違い: map タグの to 属性には、具体的な色コードではなく、カラーライブラリのIDを指定します。これにより、ライブラリに含まれる複数の色が選択候補となります。

3.3.3 鉄道施設

鉄道に関連する施設（駅舎、アクセサリ、信号、架線柱）の定義です。

駅舎 (station)

ゲーム内で設置できる駅舎（駅の建物）を定義します。駅工事ウィンドウから設置可能です。

<contribution type="station" id="{GUID-STATION-001}">
  <name>木造駅舎</name>
  <group>田舎の駅</group>
  <price>50000</price>      <!-- 建設費 -->
  <size>1,1</size>          <!-- 幅, 奥行 -->
  <height>1</height>        <!-- 高さ -->
  <operationCost>100</operationCost> <!-- 1日あたりの運営費用 -->
  
  <sprite origin="0,0">
    <picture src="station.bmp"/>
  </sprite>
</contribution>

operationCost: 駅を1日運営するごとに発生する費用を指定します。
group: 指定すると、複数の建物をまとめて1つのグループとしてメニューに表示します。

鉄道アクセサリ (railStationary)

高架橋の橋脚、詰所、車止めなど、機能を持たない景観用の施設です。定義方法は一般建築物 (commercial) とほぼ同じです。

<contribution type="railStationary" id="{GUID-RAILSTAT-001}">
  <group>高架橋</group>
  <name>コンクリート橋脚</name>
  <price>1000</price>
  <size>1,1</size>
  <height>1</height>
  <sprite origin="0,0">
    <picture src="pier.bmp" />
  </sprite>
</contribution>

信号機 (railSignal)

鉄道信号機を定義します。
※この機能を使用するには、org.kohsuke.freetrain.rail.signal プラグインへの依存定義が必要です。

<plug-in>
  ...
  <depend on="org.kohsuke.freetrain.rail.signal" />
  
  <contribution type="railSignal" id="{GUID-SIGNAL-001}">
    <name>3灯式信号機</name>
    <!-- side: left (進行方向左側) または right (右側) -->
    <side>left</side>
    <picture src="signal.bmp"/>
  </contribution>
</plug-in>

架線柱 (electricPole)

架線柱を定義します。
※この機能を使用するには、org.kohsuke.freetrain.rail.electricPole プラグインへの依存定義が必要です。

<plug-in>
  ...
  <depend on="org.kohsuke.freetrain.rail.electricPole" />

  <contribution type="electricPole" id="{GUID-POLE-001}">
    <name>鉄骨架線柱</name>
    <sprite>
       <picture src="pole.bmp" />
    </sprite>
  </contribution>
</plug-in>

画像形式: 画像は128x32ピクセルで、左から32x32ピクセルの画像が4つ並んだ構造をしています。
1. 東西方向（左下⇔右上）の線路用（奥側）: 線路や列車の後ろに描画されます。
2. 南北方向（右下⇔左上）の線路用（奥側）: 線路や列車の後ろに描画されます。
3. 東西方向（左下⇔右上）の線路用（手前側）: 線路や列車の前に描画されます。1番の画像とペアで使われます。
4. 南北方向（右下⇔左上）の線路用（手前側）: 線路や列車の前に描画されます。2番の画像とペアで使われます。
ゲーム内では、[1, 2] → [線路・列車] → [3, 4] の順で描画され、立体感を表現します。

3.3.4 一般建築物【非推奨】

※この機能は互換性のために残されていますが、新規プラグインでは GenericStructure（建物総合）の使用が推奨されます。

商業ビル、住宅、工場などの一般的な建物を定義します。

<contribution type="commercial" id="{GUID-BLDG-001}">
  <group>中層ビル</group>      <!-- グループ名（メニューでの分類） -->
  <name>雑居ビルA</name>
  <price>20000</price>         <!-- 建設費 -->
  <size>1,1</size>             <!-- サイズ (幅, 奥行) -->
  <height>4</height>           <!-- 高さ (ブロック単位) -->
  
  <!-- CPUによる自動建設を禁止する場合 -->
  <computerCannotBuild />
  
  <!-- 人口定義 -->
  <population>
    <class name="freetrain.contributions.population.OfficePopulation" />
    <base>150</base> <!-- 基礎人口 -->
  </population>

  <!-- 画像定義 -->
  <sprite origin="0,0" offset="40">
    <picture src="building.bmp" />
  </sprite>
</contribution>

3.3.5 高さ可変ビル【非推奨】

※この機能は互換性のために残されていますが、新規プラグインでは GenericStructure（建物総合）の使用が推奨されます。

高さを可変（指定範囲内）にできるビルを定義します。

<contribution type="varHeightBuilding" id="{GUID-VARBLDG-001}">
  <group>貸しビル</group>
  <name>伸縮ビル</name>
  <price>10000</price>
  <size>1,1</size>
  <minHeight>2</minHeight>
  <maxHeight>10</maxHeight>
  
  <pictures>
    <top>
      <!-- 上層部の画像定義 (spriteタグと同様) -->
      <picture src="top.bmp" />
    </top>
    <middle>
      <!-- 中層部の画像定義 -->
      <picture src="middle.bmp" />
    </middle>
    <bottom>
      <!-- 下層部の画像定義 -->
      <picture src="bottom.bmp" />
    </bottom>
  </pictures>
  <population>
    <class name="freetrain.contributions.population.OfficePopulation"/>
    <base>50</base>
  </population>
</contribution>

minHeight, maxHeight: 建設可能な高さの範囲（ボクセル単位）。
pictures: <top>, <middle>, <bottom> タグで各部分の画像を定義します。<top> と <bottom> は複数記述でき、それぞれ上から順、下から順に積み重ねられます。

画像構成

高さ可変ビルでは、画像を以下の3つの部分に分けて定義する必要があります。

top (上層部): 常に最上部に描画される。
middle (中層部): 建物の高さに応じて繰り返し描画される。
bottom (下層部): 常に最下部に描画される。

middleは16px（1ボクセル分）の高さで作成することで、階数を増減させることができます。