座標系と方角

FreeTrainはクォータービュー（等角投影図法）を採用しており、画面上の見た目と内部座標系（X, Y, Z）は以下のように対応しています。

描画順序

画像は、ペインタアルゴリズム（奥にあるものから順に重ね書きする手法）で描画されます。

1. 全体の走査順序: 画面の上（奥）から下（手前）へ向かって描画が進みます。
   • 起点は画面の最上部（北東の角、内部座標 X と Y が共に最小の地点）です。
   • 同じ水平ライン上では、左から右へと描画されます。
2. 高さ方向の重なり: 同じ地点（X, Y座標）においては、下（地面側）から上（空側）へ向かって積み重ねるように描画されます。
3. 同一ボクセル内の優先順位: 同じ高さ（Z座標）に複数の要素が存在する場合、以下の優先順位で重なり順が固定されています。
   • （奥・下） 地面 ＞ 道路 ＞ 線路 ＞ 建物 ＞ 車両 ＞ アクセサリ（架線柱・信号等） （手前・上）

このルールにより、手前の建物が奥の建物を隠し、車両が線路の上を走っているように見えるといった、正しい前後関係が表現されます。画像を作成する際は、この重なり順を意識してスプライトの境界やはみ出しを設計してください。

このルールにより、手前の建物が奥の建物を隠すといった前後関係が正しく表現されます。

ボクセルのサイズ

ゲーム内の最小単位である「1ボクセル」は、画面上では以下のサイズとして扱われます。

• 底面: 32x16ピクセルの菱形
• 高さ: 16ピクセル（1段階につき）

サポートされる画像形式

FreeTrainは .NET Framework の標準機能を使用して画像を読み込んでいるため、以下の形式が使用可能です。

• BMP (推奨): 256色（8bit）パレットモードのBMPが、メモリ効率が最も良くFreeTrainの標準として推奨されます。
• PNG: ファイルサイズを小さくできますが、ゲーム内でのメモリ使用量（VRAM）はBMPと同じです。
• GIF: 使用可能ですが、パレットの扱いに注意が必要です。
• JPEG (非推奨): 圧縮ノイズにより透過色が正しく判定されない場合があるため、使用は避けてください。

256色（8bit）パレットモードの推奨: フルカラー（24bit/32bit）の画像も使用可能ですが、256色モードに比べてメモリ使用量が多くなります。現代のハードウェアでは単体での影響は軽微ですが、FreeTrainのように数百〜数千のプラグインを同時に読み込む環境では、この蓄積がパフォーマンスや安定性に影響を与える可能性があります。特別な理由がない限り、画像は256色パレットモードで作成することを推奨します。

透過色と画像作成の注意点

• 透過色: 画像ファイル（BMP/PNG等）の左上隅（座標 0,0）のピクセルの色が、その画像の透過色として自動的に設定されます。
  通常はマゼンタ（RGB: 255, 0, 255）などがよく使われます。
  • 重要: アルファチャンネル（半透明）による透過はサポートされていません。PNG等を使用する場合も、必ず左上隅の色を透過色として塗ってください。
• パレットと256色モード: 256色パレットモードの画像を使用する場合、透過色として指定した色はパレットの何番目にあっても構いません。システムはパレット番号ではなく「(0,0)のピクセルの色と同じ色」をすべて透過処理します。
• 推奨ツールの選択: 減色やパレット操作を行う際、Windows付属の「ペイント」は使用しないでください。パレット情報が意図せず変更されたり、透過色の扱いが不正確になる場合があります。GIMP、Photoshop、あるいはドット絵エディタEDGEなど、パレットを正確に制御できるツールの使用を推奨します。

特殊な発光色（夜間モード）

夜間モードにおいて、特定のRGB値を持つピクセルは「明かり」として特別に処理されます。

※ これら以外の色でも、<override> タグを使って夜専用の画像を用意することで、より自由な夜景表現が可能です。

パラメータ詳細

• origin (起点): BMP画像内でのスプライトの切り出し開始位置（左上隅）の座標。
• offset (垂直オフセット): 画像内の「ボクセルの底面」が画像の上端（origin.Y）から何ピクセル下にあるかを指定します。
  • 建物の場合、地面に接する位置を指定する重要なパラメータです。
• opposite (反転・回転): true に設定すると、X軸とY軸のサイズを入れ替え、画像を左右反転させて描画します。対称な建物の向き違いを作成する際に便利です。

画像座標とオフセットの計算ガイド

画像を正しく表示させるためには、origin（画像の切り出し位置）と offset（基準位置の調整）を正確に設定する必要があります。

1. 基準ボクセルの考え方

   建物の配置基準となるのは、画面上で見て一番左にある角のボクセルです。ここがローカル座標の (0,0) となります。

   • 幅 (size X): 基準ボクセルから右上（東方向）への広がり。
   • 奥行 (size Y): 基準ボクセルから右下（南方向）への広がり。

2. オフセット (offset) の役割

   offset は、画像内の切り出し開始位置（origin Y）から、基準ボクセルの上面（地面の高さ）までの垂直距離（ピクセル数）を指します。 これにより、建物の絵が地面に対して正しい位置に表示されるように調整します。

3. 必要な画像サイズの計算式

   スプライトとして切り出される領域のサイズは、建物のサイズ (size) と origin、offset から自動的に計算されます。 画像ファイルを作成する際は、以下の計算式で求めたサイズ以上のキャンバスを用意してください。

   • 必要な幅 ＝ origin.X ＋ (幅ボクセル数 ＋ 奥行ボクセル数) × 16
   • 必要な高さ ＝ origin.Y ＋ offset ＋ (1 ＋ 奥行ボクセル数) × 8

   ※用意した画像がこのサイズより小さい場合、右側や下側が欠けて表示されてしまいます。

ボクセル境界の概念

1ボクセル（1x1サイズ）として定義された建物は、基本的にはそのボクセルの底面（菱形）から垂直に伸びる柱状の領域内に収まるように描画されるべきです。

当たり判定（クリック判定）に関する注意

本ゲームのマウスによるクリック判定は、スプライトの見た目（描画されているピクセル）ではなく、ボクセル（32x16ピクセルの菱形）の物理的な境界に基づいて行われます。

• 透明部分の判定: ボクセルの範囲内であれば、たとえ画像が描かれていない（透明な）場所であっても、クリックするとそのボクセルのエンティティ（駅舎のダイアログ表示など）が反応します。
• 画像のはみ出しによる不一致: スプライトが本来のボクセル領域を大きくはみ出して描画されている場合、「建物の絵がある場所をクリックしたのに、実際にはその絵の下に隠れている隣のボクセルがクリックされたと判定される」といった現象が発生します。

画像がはみ出す場合

建物のデザイン上、どうしても画像がボクセル境界を越える場合は、描画の欠けを防ぐだけでなく、この「見た目と操作判定の不一致」を解消するためにも、建物の定義サイズ（size）を絵に合わせて大きく設定する必要があります。 特に、撤去ツールによる操作や、駅などのプロパティダイアログを持つ施設において、この不一致はユーザーの誤操作（隣のボクセルを撤去してしまう、駅のダイアログが開かない等）を招く原因となります。

道路・地面

コンクリート構造物

僅かに赤みがかった灰色を基調とします。

建物の窓

青や水色での塗りつぶしは推奨されません（おもちゃっぽく見えるため）。 昼間は黒に近い色を使用し、夜間は明かりがついている部屋とついていない部屋を混ぜるとリアルになります。

組み込みカラーライブラリの活用

色替え可能なオブジェクト（半ボクセル建築など）を作成する際は、システム側で用意されているカラーライブラリを利用することで、統一感のある色バリエーションを簡単に提供できます。

利用可能な色の詳細については、第3部 3.1.5 カラーライブラリを参照してください。

色置換 (colorMapped)

特定のパレット（色）を別の色に置き換えます。

<spriteType name="colorMapped">
  <!-- RGB(0,255,0) を RGB(255,0,0) に置換 -->
  <map from="0,255,0" to="255,0,0" />
</spriteType>

色相変換 (hueTransform)

特定の色範囲の色相を変更します。* を使用したワイルドカード指定、または色成分のキーワード指定が可能です。

<spriteType name="hueTransform">
  <!-- 赤系統の色範囲(*,0,0) を 青系統に変換 -->
  <map from="*,0,0" to="0,0,255" />
  
  <!-- キーワードを使用した指定も可能 (Red, Green, Blue) -->
  <map from="Red" to="0,0,255" />
</spriteType>

指定方法:

• *,0,0 または Red (R): 赤成分をキーとして変換。
• 0,*,0 または Green (G): 緑成分をキーとして変換。
• 0,0,* または Blue (B): 青成分をキーとして変換。

計算式: 変換元の色範囲指定で *（ワイルドカード）になった成分の値を n (0-255) とすると、変換後の色は以下のように計算されます。 RGB = ( R * (n/255), G * (n/255), B * (n/255) )

この機能により、1枚のグレースケール（または特定色の）画像から、多様なカラーバリエーション（電車のラインカラーなど）を生成できます。