# MSX2版『ファイナルファンタジー』PICファイル 技術仕様書

## 1. はじめに

本仕様書は、MSX2版『ファイナルファンタジー』（マイクロキャビン移植）で使用されている画像アーカイブ形式（拡張子 `.PIC`）のデータ構造、展開・圧縮アルゴリズムの仕様、および操作ツール `FFPicTool` の実装仕様を定義するものである。

---

## 2. データ形式の仕様

ファイルは **固定48バイト（`0x30`）のヘッダ** と、それに続く **可変長の圧縮ピクセルストリーム** で構成される。

``` text
+0x00       +0x10                   +0x30                                      終端
+------------+----------------------+------------------------------------+--------+
| 制御ヘッダ | パレットデータ       | RLE圧縮ピクセルストリーム          |Padding |
| (16バイト) | (32バイト: 16色×2B) | (可変長)                           |(0x00)  |
+------------+----------------------+------------------------------------+--------+
|<------------------------------- 512バイト境界 --------------------------------->|
```

### 2.1 制御ヘッダ構造（`0x00`〜`0x0F`：16バイト）

MSX2のVDP（V9938）のグラフィックレジスタおよび矩形転送コマンド（HMMC等）に直結したパラメータ群である。数値はすべてリトルエンディアンで格納される。

| オフセット       | サイズ  | フィールド名      | 内容・解説                                                                                                                                               |
| :--------------- | :------ | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `+0x00`〜`+0x01` | 2バイト | `ScreenMode`      | 画面モード指定。全ファイル共通で `0x0005`（MSX SCREEN 5: 256×212ドット、16色）。                                                                        |
| `+0x02`〜`+0x03` | 2バイト | `DX`              | 転送先VRAM X座標（ドット位置）。全データ共通で `0x0000`（X=0）。                                                                                         |
| `+0x04`〜`+0x05` | 2バイト | `DY`              | 転送先VRAM Y走査線番号（0〜255）。                                                                                                                       |
| `+0x06`〜`+0x07` | 2バイト | `NX` (`rowSize`)  | 転送幅（**バイト数**）。ピクセル数はこの2倍。<br>・画面全幅: `0x0080`（128バイト ＝ 256ピクセル）<br>・差分メニュー: `0x0058`（88バイト ＝ 176ピクセル） |
| `+0x08`〜`+0x09` | 2バイト | `NY` (`rowCount`) | 転送高さ（**ライン数**）。実ライン数がそのまま格納される（0オリジンではなく実数）。                                                                      |
| `+0x0A`〜`+0x0F` | 6バイト | `Reserved`        | 予約領域。**内容未定義（不定値）**。当時の開発環境におけるRAMバッファの残骸データがそのまま出力されており、実機の描画ルーチンでは参照されない。          |

#### VRAM展開先アドレスの算出式（SCREEN 5）

SCREEN 5における1走査線のサイズは128バイト（`0x80`）である。ヘッダの `DY` からVRAM物理オフセットが一意に定まる。
$$\text{VRAM物理アドレス} = \text{VRAMページベース} + (DY \times 128) + (DX \div 2)$$

- **実例（FONT.PIC）**:
  - `DY` = 200 (`0x00C8`)
  - MSX2の裏画面 Page 3（ベース `0x18000`）へ展開される場合：
    $$0x18000 + (200 \times 128) = 0x18000 + 0x6400 = \mathbf{0x0001E400}$$

#### 既存グラフィックの配置パラメータ実測値

| ファイル名 | DX (X) | DY (Y)       | NX (幅)                  | NY (高)       | 用途と配置意図                                 |
| :--------- | :----- | :----------- | :----------------------- | :------------ | :--------------------------------------------- |
| `MENU_L1`  | 0      | 0   (`0x00`) | 88バイト （176ピクセル） | 72行 (`0x48`) | メニュー画面パーツ1。クラスチェンジ前のキャラ  |
| `MENU_L2`  | 0      | 0   (`0x00`) | 128バイト（256ピクセル） | 72行 (`0x48`) | メニュー画面パーツ2。クラスチェンジ後のキャラ  |
| `JOBS_L1`  | 0      | 192 (`0xC0`) | 128バイト（256ピクセル） | 48行 (`0x30`) | ジョブ別16×16歩行キャラ。クラスチェンジ前     |
| `JOBS_L2`  | 0      | 192 (`0xC0`) | 128バイト（256ピクセル） | 48行 (`0x30`) | ジョブ別16×16歩行キャラ。クラスチェンジ後     |
| `FONT`     | 0      | 200 (`0xC8`) | 128バイト（256ピクセル） | 40行 (`0x28`) | 8×8フォント（文字・記号・枠線）通常           |
| `FONT2`    | 0      | 128 (`0x80`) | 128バイト（256ピクセル） | 40行 (`0x28`) | 8×8フォント（文字・記号・枠線）アルファベット |

---

### 2.2 パレットデータ構造（`0x10`〜`0x2F`：32バイト）

MSX2 VDP（V9938）のパレットレジスタ（16色 × 各色2バイト）がそのまま格納されている。

- **各色のバイト構成**:
  - **第1バイト**: `0 R2 R1 R0 0 B2 B1 B0`（赤: 3bit、青: 3bit、各0〜7）
  - **第2バイト**: `0 0 0 0 0 G2 G1 G0`（緑: 3bit、0〜7）
- **24bitフルカラーRGB（RGB888）への換算式**:
  各成分（0〜7）を8段階でスケーリングする。
  $$\text{Value}_{8\text{bit}} = \text{Value}_{3\text{bit}} \times 255 \div 7 \quad (\text{または } \text{Value} \times 36)$$

---

### 2.3 RLE圧縮アルゴリズムの仕様

同一バイトの2連続を契機としてラン長を展開する、同値2バイト連続検出型のランレングス圧縮（RLE）である。

#### 展開規則

実機の圧縮データは**走査線単位（1行＝$NX$ バイト）で完結するように圧縮**されており、走査線境界を跨いでランが継続することはない。展開処理は各走査線ごとに独立して実行する。

各走査線（行）について、行内出力カウンタ（`rowBytes`）を `0` に初期化して以下を行う。

1. データを1バイト読み込み出力する（`Byte1`）。`rowBytes` を `+1` する。
2. `rowBytes` が行幅（$NX$）に達した場合、その行の展開を完了して次の行の処理へ進む（ストリームの次のバイトは次行の先頭バイトとして処理される）。
3. 次の1バイト（`Byte2`）を参照する。
   - `Byte2 != Byte1` の場合：`Byte1` は単独バイトとして確定（すでに1バイト出力済み）。`Byte2` は消費せず、次のループの `Byte1` として扱う。
   - `Byte2 == Byte1` の場合：**ランモードへ移行**。`Byte2` をストリームから消費し、続く3バイト目から **ラン長（`count`）** を読み込む。
4. すでに1バイトは出力済みのため、同一バイト（`Byte1`）を **残り `count - 1` 回** 繰り返し出力する（`rowBytes` をその分加算する）。
5. `rowBytes` が行幅（$NX$）に達するまで 1. 〜 4. を繰り返す。
6. 全 $NY$ 行の展開が完了した時点で処理を終了する。

#### ラン長上限（0x6B）の仕様

- 実機（Z80）側のバッファ溢れ防止およびオリジナルバイナリとの互換性を担保するため、1つのランとして出力できる連続バイト数（ラン長）の上限は **`0x6B`（107バイト）** とする。
- 同一値の連続が上限値の `0x6B`（107バイト）を超える場合は、一度 `0x6B` でランを打ち切り、残余分は後続のデータとして改めてエンコードする（残余が2バイト以上なら再度ランを形成し、1バイトなら単独バイトとして出力する）。
- 同一値が 2 バイトのみ連続する場合であっても、展開ルーチンが「同一値が2回並んだ直後は無条件でラン長が格納されている」と判定する仕様であるため、必ずラン長バイトを付加して出力する（例: `AA AA 02`）。

---

### 2.4 セクタパディング（512バイトアライメント）

- MSXのFDC（フロッピーディスクコントローラ）およびBIOSコール（`DSKIO`）は、すべてセクタ単位（512バイト＝`0x200`）で入出力を行う。
- ゲーム実行時はディスクから直接VRAMやバッファへセクタ単位の転送を行うため、圧縮ファイルの終端は必ず `0x200` の倍数まで `0x00` でパディングされる。

---

### 2.5 アーカイブ構造とオフセット指定の必然性

- 本作のディスク管理下（ブート時に `Say DOS Version 1.A0` と表示されるファイルシステム）にある単体ファイル（`FONT.PIC` 等）だけでなく、プログラムバイナリ（`BATTLE.COM` 等）のアセンブラ内にセクタ番号が直接ハードコードされて配置されているグラフィックが存在する。
- 1つの巨大なバイナリ塊やディスクイメージ（DSK）から任意のグラフィックを切り出す必要があったため、ツールには開始オフセット（`address`）を指定する機能を備える。

---

## 3. MSX的な特徴

### 3.1 ヘッダの構造

ヘッダは、MSX2 VDP（V9938）の画面モード（SCREEN 5）、CPU-VRAM間高速矩形転送コマンド（HMMC）の転送先座標・サイズパラメータ、パレットレジスタ設定値で構成されていて、MSXで扱いやすい形になっている。

### 3.2 ピクセルストリームの構造

- ヘッダ内に横幅（`NX`）と高さ（`NY`）が明記されているため、展開データは **$NX \times NY$ バイトのリニア配列** である。
- 実機描画時は、VDPコマンド（HMMC等）のハードウェア機能により、1行（$NX$ バイト）転送ごとに自動で次ラインへ折り返されるため、データ自体に空きドット（128バイト幅へのパディング等）を埋める必要はない。
- FFPicToolが出力する非圧縮状態バイナリデータ（*.bin）は、**「48バイトのヘッダ ＋ $NX \times NY$ バイトの非圧縮ピクセルストリーム」** としている。  
  （※ヘッダに固定値のブランク区間が無く、圧縮・非圧縮を識別する署名を埋め込む余地がないため、拡張子BINとして出力して区別する。）

---

## 4. ツール `FFPicTool` の構成仕様

### 4.1 ツールの役割と対象範囲

本ツールは **「可逆圧縮・展開を行う純粋なアーカイバ」** として設計する。

- 仮想VRAM画面への配置描画やプレビュー表示は本ツールの対象外とし、除外する。
- データの相互変換において、1ピクセル・1ビットの欠落もない可逆性を保証する。

### 4.2 内部データオブジェクト構造

プログラム内部では「制御ヘッダ」「パレット」「ピクセルデータ」の3つの要素に分けられる。データ構造は以下のように定義する。

``` text
[PicAsset Object]
├── Header
│   ├── ScreenMode      : uint16 (0x0005: SCREEN 5)
│   ├── DestX           : uint16 (DX: 通常 0)
│   ├── DestY           : uint16 (DY: VRAM走査線位置)
│   ├── WidthBytes      : uint16 (NX: 1行のバイト幅。ピクセル幅 ＝ NX × 2)
│   ├── HeightLines     : uint16 (NY: ライン数)
│   └── ReservedBytes   : 6バイト (制御ヘッダ生データ維持用)
├── Palette[16]         : 16色の配列
│   ├── Raw             : uint16 (V9938生データ: 0RRR0BBB 00000GGG)
│   ├── RGB333          : [R: 0-7, G: 0-7, B: 0-7]
│   └── RGB888          : [R: 0-255, G: 0-255, B: 0-255]
└── Pixels              : byte[] (サイズ: WidthBytes × HeightLines)
```

### 4.3 展開処理（Decode）の仕様

1. **入力**: PICファイルバイナリ、またはアーカイブ内の開始オフセット。
2. **ヘッダ解析**: 先頭48バイトからパラメータとパレットを抽出。
3. **ピクセル伸長**:
   - 走査線（1行＝$NX$ バイト）単位で独立して展開を行う。
   - 行末（$NX$ バイト到達）でラン判定を必ずリセットし、前行末のバイトと次行頭のバイトを結合してラン長と誤認させないこと。
   - ギャップや余計なパディングは一切挿入せず、純粋に各行 $NX$ バイト、全 $NY$ 行（総計 $NX \times NY$ バイト）に達した時点で即時終了する。
4. **出力形式**:
   展開したデータは、「制御ヘッダ」「パレット」「ピクセルデータ」の各要素を用途に合わせて以下のファイルへ分けて出力する。
   なお、アドレス指定オプション（`-a`）を指定して展開した場合は、ファイル名衝突の防止および抽出元アドレス特定の利便性のため、ベースファイル名末尾に `_0x{0埋め5桁揃え16進数アドレス}` を自動付加する（例: `hoge.pic -a 0x200` の場合、`hoge_0x00200.png`、`hoge_0x00200.json`、`hoge_0x00200.bin` を出力。アドレス値が0であってもオプションが指定された場合は付加する）。

   - **4bppインデックスカラー画像ファイル（PNG / BMP）**（出力内容: パレット、ピクセルデータ）:
     - 幅: $NX \times 2$ ピクセル、高さ: $NY$ ピクセル。
     - **4bpp（16色インデックスカラー）形式** で出力。
     - パレットはヘッダから抽出した16色をそのまま埋め込む。
   - **非圧縮バイナリ（`*.bin`）**（出力内容: 制御ヘッダ、パレット、ピクセルデータ）:
     - 先頭48バイト（制御ヘッダ16バイト ＋ パレット32バイト）をそのまま保持し、後続の圧縮ピクセルストリームのみを展開した非圧縮MSX PICバイナリを出力する。ピクセルデータのみを取り出したファイルではなく、PICファイルの圧縮部分を展開した状態のバイナリとする。
   - **メタデータ（`*.json`）**（出力内容: 制御ヘッダ、パレット）:
     - 座標、パレット等のパラメータ記述ファイル。パレットの各色エントリは `raw`（16進数文字列）、`rgb333: [R, G, B]`（MSX2 V9938パレットレジスタ準拠の3bit値: 0〜7）、`rgb888: [R, G, B]`（24bitカラー換算値: 0〜255）の形式で記述し、各色成分を個別の独立フィールドに細分化せず配列として保持する。
     - パレット一覧の視認性・編集性を担保するため、`rgb333` および `rgb888` などの短い数値配列は要素ごとに改行せず、`[R, G, B]` のように1行（インライン形式）で整形して出力する。

### 4.4 圧縮処理（Encode）の仕様

1. **入力形式と各要素の取得方法**:
   入力するファイルの形式に応じて、「制御ヘッダ」「パレット」「ピクセルデータ」を以下のように取得する。

   - **4bpp画像ファイル（PNG / BMP）を入力とする場合**:
     - **パレット・ピクセルデータ**: 画像ファイルから16色パレット、4bppピクセルデータ、および画像サイズ（$NX$ ＝ 幅 ÷ 2、$NY$ ＝ ライン数）を取得する。
     - **制御ヘッダ情報（DX, DY, Reserved）**: 同名の `*.json`（メタデータ）が存在すればそこから取得する。コマンドライン引数（`-x`, `-y` 等）や `--keep-header` による既存PICファイルまたは非圧縮バイナリからの引継ぎ指定があればそれを最優先で反映する。いずれの指定もない場合は $DX=0, DY=0, Reserved=0x00 \times 6$ で初期化する。
   - **非圧縮PICバイナリ（`*.bin`）を入力とする場合**:
     - 先頭48バイトから「制御ヘッダ情報」および「パレット」を取得し、48バイト以降から「ピクセルデータ」を取得する（引数やJSONによるDX, DY等の上書き指定も可能とする）。
2. **ヘッダの構築**:
   - 取得したパラメータおよび16色パレット（V9938形式: 2バイト×16色）を統合した48バイトヘッダを構築する。
3. **RLEエンコード**:
   - 走査線（1行＝$NX$ バイト）単位で独立してエンコードを行う。**走査線境界（$NX$ バイト）を跨いでランを継続させてはならず、行末で必ずランを完結させる**こと。
   - 行内のピクセルデータを走査し、同一値が2バイト連続した時点でランモードへ移行（`Byte Byte Count`）。
   - **ラン長上限は `0x6B`（107バイト）** とし、連続バイト数がこれを超える場合は一度 `0x6B` でランを打ち切り、残余分を後続のデータとして改めて処理する。
   - 2バイトのみの同一値であっても、必ずラン長 `02` を付加して出力する（`AA AA 02`）。
   - ※オプションとして、上限を撤廃し1バイト最大値（255）まで使用するモード（`-unlimited-run`）を設ける（ただし行境界を跨がない制約は維持する）。
4. **セクタ境界アライメント**:
   - 出力全体のサイズが512バイト（`0x200`）の倍数になるよう、末尾を `0x00` でパディングする。

### 4.5 4bpp（16色インデックスカラー）形式採用の意義

- MSX SCREEN 5 は 4bpp（1バイト＝2ピクセル、上位4bitが左、下位4bitが右）である。
- PNGやBMPを4bppインデックスカラーで扱うことにより、24bit/32bitカラーへの展開に伴う減色誤差やアンチエイリアス混入のリスクを根本から遮断する。
- 外部グラフィックツール（Aseprite、Photoshop、EDGE等）で編集後、カラーインデックス（0〜15）を1対1で保ったまま確実にMSXデータへ再圧縮することが可能となる。

---

## 付録（Appendix）：C#版「FF MSX GFX」における既知の不具合と解析メモ

既存の C# 版ツール「FF MSX GFX」（`final-fantasy-msx2-de-compressor`）における実装上の不具合および動作解析をメモにまとめた。

### A.1 展開時におけるメタデータの欠落

C#版の `DumpAllGeneral` では、解凍処理 `FFMSXFont.Decompress` の戻り値（ピクセルバイト配列のみ）をそのままファイルに書き出していた。これにより、先頭48バイトに存在した「サイズ（NX, NY）」「VRAM配置座標（DX, DY）」「パレット」がすべて破棄され、展開後の `.bin` ファイルから元の画像構成を再現することが不可能になっていた。

### A.2 行末パディング処理の誤謬とアンダーフロー不具合

C#版の `Decompress` ルーチンでは、実機の仕様通り行内カウンタ `d = rowSize` を用いて走査線境界を管理していた。しかし、幅が128バイト未満のデータに対して画面全幅（128バイト）へ引き伸ばそうとする空ループ（`for (int i = rowSize; i < maxRowSize; i++) decompSize++;`）を誤って挿入していた。
さらに、RLE展開ループ（`do { output.Add(a); decompSize++; d--; b--; } while (b > 0);`）の内部で行内カウンタ `d` のゼロ判定を行っていなかったため、もしデータ内で行境界を跨ぐようなランが存在した場合に `d` がアンダーフロー（`0 -> 255`）を起こす構造的欠陥を抱えていた。その結果、行末判定がスキップされてループの歩進が狂い、展開処理が規定サイズで停止せずファイル末尾を突き抜けて肥大化したゴミデータを出力していた。

### A.3 終了判定の誤認によるオーバーラン（rowCount + 1問題）

C#版では展開終了サイズの算出に `(rowCount + 0x1) * maxRowSize` を用いており、ヘッダのライン数に対して意図的に 1 行多くループを回していた。
さらにラン展開ループ内に総サイズ超過判定がなかったため、最後のランが展開された際に規定サイズを突き抜け、例えば 40 ラインのデータ（`FONT.PIC`: 本来 5,120 バイト）に対して 42 ライン分（5,376 バイト）まで余計に出力されていた。

### A.4 圧縮時における連続数算出ループ（totalFill）の条件文不具合

C#版 `Compress` ルーチンの 122 行目付近にある連続バイト数算出処理において、ループ終了判定が以下のように記述されていた。

```csharp
if (j+1 < uncompressed.Length || uncompressed[j] != uncompressed[j+1]) break;
```

条件が `||`（OR）で結合されていたため、1 回目のループ（`j+1 < uncompressed.Length` が真）で必ず `break` してしまい、変数 `totalFill` は常に `1` となっていた。このため、直後に記述されていた端数調整式 `(totalFill % 0x6a == fillLength)` は一切機能せず、実質的には `fillLength == 0x6b` の強制ブレークのみによってラン分割が行われていた。

### A.5 圧縮処理における元ファイルヘッダ依存

C#版の `Compress(uncompressed, destBytes)` は、第2引数として既存の圧縮ファイル（`destBytes`）を要求し、その先頭48バイトをそのままコピーして使い回していた。このため、画像サイズの変更やパレットの編集、新規グラフィックの作成をツール単体で行うことができなかった。