# MSX2版『ファイナルファンタジー』Say DOS ファイルシステム 統合動作仕様書

本書は、MSX2版『ファイナルファンタジー』（マイクロキャビン移植）で採用されている独自ファイルシステム「Say DOS（Ver 1.A0）」のバイナリデータ構造、および再構築ツール・編集エンジンに求められる動作仕様を網羅した技術仕様書である。

---

## 1. ディスク基本諸元

| 項目               | 規格・諸元                                  | 備考                                                |
| :----------------- | :------------------------------------------ | :-------------------------------------------------- |
| **メディア形式**   | 3.5インチ 2DD                               | MSX標準フロッピーディスク                           |
| **総容量**         | 737,280 バイト（`0xB4000` バイト / 720 KB） | 未使用領域は `0xFF` で初期化                        |
| **総セクタ数**     | 1,440 セクタ（`0x05A0` セクタ）             | 絶対セクタ番号: `0x0000` ～ `0x059F`                |
| **セクタ長**       | 512 バイト（`0x0200` バイト）               | 全データの基本配置単位                              |
| **バイトオーダー** | リトルエンディアン                          | Z80 CPUの標準規則                                   |
| **対象メディア**   | Disk 1（Game Disk）                         | 本作は2枚組。Disk 2（User Disk/セーブ専用）は対象外 |

---

## 2. ディスク上の全体セクタマップ

```text
絶対セクタ番号 (HEX)      占有長       用途・格納データ
+----------------------+-----------+--------------------------------------------------------+
| 0x0000 - 0x0009      |  10セクタ | システム領域（IPL / MBR / ブートコード / 5,120B）      |
+----------------------+-----------+--------------------------------------------------------+
| 0x000A - 0x0063      |  90セクタ | ルートディレクトリ領域（46,080B / 2,880エントリ分）    |
+----------------------+-----------+--------------------------------------------------------+
| 0x0064 - (可変)      |  可変長   | 通常ファイルデータ領域（COM, PIC, MAP, BGM, MSG等）    |
+----------------------+-----------+--------------------------------------------------------+
| 0x044C - 0x0540 ※   | 245セクタ | 【特殊領域】戦闘システム・グラフィックデータ（122.5KB）|
+----------------------+-----------+--------------------------------------------------------+
| (データ末尾 - 0x059F)|  可変長   | ディスク終端の未使用領域（0xFF 埋め）                  |
+----------------------+-----------+--------------------------------------------------------+
※ 戦闘データのセクタ番号はオリジナルディスクの初期値。間詰め再配置（コンパクション）時は変動する。
```

---

## 3. ルートディレクトリ構造

ディレクトリ領域は **セクタ `0x000A` ～ `0x0063`（90セクタ分＝46,080バイト）** に固定されている。  
エントリ長は **16バイト（`0x10` バイト）固定** であり、領域全体で **ジャスト2,880エントリ** を保持する。

### 3.1 エントリの内部レイアウト（16バイト固定）

|  オフセット   |  サイズ  | 型 / 形式 | フィールド名  | 仕様・制約                                                          |
| :-----------: | :------: | :-------: | :------------ | :------------------------------------------------------------------ |
| `0x00 - 0x07` | 8 バイト |   ASCII   | `FileName`    | 8文字未満は空白（`0x20`）パディング。                               |
| `0x08 - 0x0B` | 4 バイト |   ASCII   | `FileExt`     | **先頭にピリオドを含む最大4文字**（例: `".COM"`）。空白パディング。 |
| `0x0C - 0x0D` | 2 バイト | uint16_le | `StartSector` | ファイル先頭の絶対セクタ番号。                                      |
| `0x0E - 0x0F` | 2 バイト | uint16_le | `EndSector`   | ファイル末尾の絶対セクタ番号（**両端を含む閉区間**）。              |

#### 計算規則

* **ファイル占有セクタ数**: `SizeInSectors = EndSector - StartSector + 1`
* **ファイル実データ長**: `SizeInSectors * 512` バイト（ファイルサイズはセクタ単位で切り上げられ、末尾の余白はパディングされる）。

### 3.2 ゲーム内アクセスとファイルID（通し番号）

本作のゲーム本体プログラム（Z80マシン語）は、ファイル名文字列ではなく **ディレクトリエントリテーブル上の通し番号（ファイルID: 0 〜 2,879）をインデックスとして直接参照・ロード** する。
このため、メタデータ（`root_directory.json`）には各エントリの通し番号を `FileId`（10進整数）および `FileIdHex`（16進文字列、例: `"0x0000"`）として明示的に記録し、逆アセンブル解析やスクリプト連携時の視認性を担保する。

### 3.3 空エントリおよびカテゴリ区切り（セパレータ）

* **同一値判定**: 16バイトの全バイトが先頭バイトと一致している場合、非ファイルエントリ（空または区切り）と判定する。
* **`0x00` 充填（エントリ 0 〜 179）**: 主にプログラム、BGM、画像、マップが並ぶ前半領域の未使用スロット。
* **`0x40` 充填（エントリ 180 〜 2879）**: メッセージ、データテーブル、スプライトが並ぶ中盤から終端にかけての未使用スロット。ASCIIコードの `'@'`（`0x40`）が並ぶエントリは、開発者が意図的に配置した **カテゴリ間の論理セパレータ（暗黙のフォルダ区切り）** として機能している。

### 3.4 再構築時におけるディレクトリ領域の固定長保証

ディレクトリ領域は90セクタ（2,880エントリ＝46,080バイト）の物理サイズが厳密に定められている。  
外部編集等により `root_directory.json` 内の空エントリが間引かれ2,880件未満になっていた場合でも、再構築ツールは末尾を自動的に空エントリ（`0x00` 埋め）で補完し、**後続の通常ファイル群が開始セクタ `0x0064`（セクタ100）より手前に前詰め配置される物理配置ズレを完全に防止** しなければならない（2,880件を超過した場合はエラー中断）。

---

## 4. ファイナルファンタジー固有の特殊仕様と注意点

本作には一般的なファイルシステムの仕様から外れた構造的トラップが存在する。

### ① ディレクトリ未登録セクタ（戦闘グラフィック・システム領域）

* **該当セクタ**: 初期配置では `0x044C` ～ `0x0540`（計245セクタ / 125,440 バイト＝約122.5 KB）。
* **仕様**:  
  この巨大なデータ領域は、**ルートディレクトリの2,880エントリ中に一切登録されていない**。通常のディレクトリスキャンによるファイル抽出を行うだけでは完全に欠落し、戦闘シーンでゲームが確実にハングアップする。
* **設計方針**:  
  本領域を **`BATTLE_DATA.BIN`** という仮想ファイルとして集約抽出し、再構築時にも同ファイルから後続へ書き戻す設計とする。

### ② `BATTLE.COM` 内のハードコードポインタ自動パッチ

* **仕様**:  
  戦闘モジュール `BATTLE.COM` の先頭から **`+0x0F6C`** バイト目の位置に、上記戦闘データの開始セクタ番号（2バイト、リトルエンディアン）が直接ハードコードされている。
* **ダンプ時の開始セクタ自動検出**:  
  オリジナルディスク（`0x044C`）だけでなく、再配置済みのディスクからも正しく戦闘データを抽出できるよう、ダンプ処理時は `BATTLE.COM` の `+0x0F6C` を参照して実際の開始セクタを自動検出する。検出不能時や特殊なディスク構成への予備動作として初期値 `0x044C` を用いる（CLIオプションによる手動指定も可能）。
* **再構築時のポインタ更新**:  
  ファイルを間詰めして再配置（コンパクション）した場合、通常ファイル群の総セクタ数に応じて戦闘データの開始セクタ番号が変動する。再構築時は、新しく割り当てられた戦闘データの絶対セクタ番号を上記アドレスへ自動で上書きする。

### ③ オリジナルディスクのセクタ間ギャップ（パディング配置）

オリジナルディスクでは、実行プログラム（`.COM`）の開始セクタが `0x0064`, `0x0084`, `0x00A4`, `0x00C4`, `0x00E4`, `0x0104`, `0x0124` と、**32セクタ（`0x20`＝16KB）刻みの境界** に整列配置されており、ファイルの末尾と次ファイルの開始位置の間に未使用の空きセクタ（ギャップ）が存在する。  
また、ディレクトリエントリの並び順と物理セクタの配置順が一部食い違っている（例: `ORANYO.BIN` や一部の `.PIC` ファイル）。

---

## 5. コア・アーキテクチャ設計（インターフェース仕様）

ディスク管理ツール `FFSayDosTool` を構築する場合、およびPIC画像解凍・圧縮ツール `FFPicTool` 等の関連ツールや上位スクリプトとのパイプライン連携を想定し、**ディスクイメージをオンメモリで操作する抽象化エンジン（コア層）** を最下層に置き、一括ダンプ／書き出し機能は上位のユーティリティとして設計する。

```text
[ アプリケーション層 ]
  ├── FFPicTool CLI (PIC画像の解凍・圧縮・PNG/BMPプレビュー生成)
  └── FFSayDosTool CLI (一括Dump / 一括Write / 検証 / セクタ出力オプション)
        │
        ▼
[ サービス層（再配置・整合性管理・セクタマッピング解析） ]
  ├── ギャップ維持モード (オリジナル配置・衝突判定)
  ├── コンパクターモード (間詰め再配置・ポインタ自動パッチ)
  └── セクタ解析エンジン (未登録・未特定セクタの検出とブロック分類)
        │
        ▼
[ コア層（オンメモリ・ファイルシステムエンジン） ]
  ├── イメージのロード / エクスポート (720KBバッファ)
  ├── ディレクトリ走査 (ファイル一覧・メタデータ取得)
  ├── ファイル名指定アクセス (ReadFile / WriteFile)
  ├── 特殊データ指定アクセス (ReadBattleData / WriteBattleData)
  └── 生セクタ指定アクセス (ReadSector / WriteSector)
```

### コア層（ファイルシステムエンジン）API仕様

#### 1. イメージ管理

* **`LoadImage(buffer)`**:  
  720KBのディスクイメージバイナリをメモリに展開し、システム領域、ディレクトリエントリ（2,880個）、全セクタデータを内部構造化。
* **`ExportImage() -> bytes`**:  
  現在のオンメモリ状態から `0xB4000` バイトのディスクイメージバイナリを生成して返却。

#### 2. ディレクトリ・情報取得

* **`GetFileList() -> list[FileInfo]`**:  
  空エントリおよび `0x40` 区切りを除外した、有効なファイル一覧（名前、拡張子、開始セクタ、セクタ長、バイトサイズ、ファイルID）を返却。
* **`GetDirectoryEntries() -> list[DirectoryEntry]`**:  
  空エントリを含む全2,880個のエントリ配列（メタデータ）を返却。
* **`GetSectorMap() -> list[SectorUsage]`**:  
  全1,440セクタの使用状況（システム領域、ディレクトリ、登録ファイル名、戦闘データ、未割り当て領域）を示すマップ情報を返却。

#### 3. ファイル名指定アクセス（In-place更新）

再配置を行わず、現在の割り当てセクタ範囲内でデータを読み書きする。

* **`ReadFile(fileName) -> bytes`**:  
  ファイル名（例: `"MAINBG.PIC"`）を指定し、割り当てセクタからデータを読み出して返却。
* **`WriteFile(fileName, data, autoPad=True) -> WriteResult`**:  
  ファイル名を指定してデータを上書き。
  * 現在の割り当てセクタ数（`SizeInSectors`）以内に収まる場合、セクタを上書き（余白は自動パディング）。ディレクトリエントリのセクタ範囲は維持。
  * 割り当てセクタ数を超える場合、上書きを拒否し「容量超過（要コンパクション再配置）」を通知。

#### 4. 特殊領域（戦闘データ）アクセス

* **`ReadBattleData() -> bytes`**:  
  戦闘データ領域（245セクタ＝125,440バイト）を連続バイナリとして返却。
* **`WriteBattleData(data) -> void`**:  
  戦闘データ領域のバイナリを上書き。

#### 5. 生セクタ指定アクセス（RAWセクタ）

再配置を行わない微修正や、IPL・ブートローダーの更新、特定マシン語パッチ用の低レベルインターフェース。

* **`ReadSector(sectorIndex, count=1) -> bytes`**:  
  指定した絶対セクタ番号から生データを読み出し。
* **`WriteSector(sectorIndex, data) -> void`**:  
  指定した絶対セクタ番号へ生データを直接書き込み。

---

## 6. 再配置（サービス層）の動作仕様

単一ファイルの更新ではなく、ディスクイメージ全体を再ビルドする場合の2つのモードである。

### モードA：ギャップ維持モード（オリジナル配置の完全再現）

* **処理内容**:  
  メタデータに記録されたオリジナルの `StartSector` / `EndSector` を完全に維持して各ファイルを書き込む。
* **衝突判定（コリジョンチェック）**:  
  改変後の各ファイルが元の占有セクタ数を超過していないかを事前に検証する。超過が検出された場合はエラーを出力し、後続ファイルやギャップ領域の破壊を防止する。
* **戦闘データ**:  
  元の位置（セクタ `0x044C`）に固定されるため、`BATTLE.COM` へのポインタ修正は不要である。

### モードB：コンパクターモード（最適化・間詰め再配置）

* **処理内容**:  
  ファイルサイズが増加して元の領域に収まらない場合や、新ファイルを追加してディスクを再構築する場合のモードである。
  1. 先頭 `0x0000` ～ `0x0009` に `SYSTEM_BOOT.BIN`（10セクタ / 5,120B）を配置。
  2. セクタ `0x000A` ～ `0x0063` にディレクトリ領域（2,880エントリ / 46,080B）を確保（不足分は空エントリで自動補完）。
  3. セクタ `0x0064` を起点として、メタデータ順に各通常ファイルを隙間なく連続配置。
  4. 各ファイルの配置に合わせてディレクトリエントリの `StartSector` / `EndSector` を再計算。
  5. 通常ファイルの終端直後のセクタへ、`BATTLE_DATA.BIN`（実ファイルサイズに応じたセクタ数）を連結。
  6. `BATTLE_DATA.BIN` の新しい開始セクタ番号（2バイト、リトルエンディアン）を、`BATTLE.COM` の先頭から `+0x0F6C` の位置へ上書きパッチ。
  7. 全体の配置完了後、ディスク容量（`0xB4000` バイト / 720KB）を超過していないかを検証し、残りのディスク末尾を `0xFF` でパディング。

---

## 7. 一括ダンプ時の出力構成と解析漏れ防止オプション

本ファイルシステムはディレクトリ未登録のセクタが存在するなど変則的であり、**「既知の仕様外にあるデータや解析から漏れている未特定領域が存在する可能性」**を常に考慮する必要がある。  
このため、通常のファイル単位抽出を基本としつつ、**解析漏れの防止および未特定データの救済・調査を目的としたセクタダンプおよび未割り当てセクタ抽出オプション**を設ける。各出力の有無は設定フラグまたはCLIオプションで任意に制御可能とする。

### 7.1 ダンプ制御オプション一覧

| オプション（CLI例）          |  既定値  | 目的・動作                                                                                                                                                                                                                                                                               |
| :--------------------------- | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dump-files`               |  `true`  | 通常ファイル、システム領域、戦闘データを `files/` 配下に集約出力。リソース抽出・ファイル差し替え用。                                                                                                                                                                                     |
| `--dump-sectors`             | `false`  | 全1,440セクタを512バイト個別の生バイナリとして `sectors/` 配下に出力。**ファイルシステム側のパースや現在の解析ロジックから漏れている領域を一切取りこぼさず、セクタ単位で厳密に調査・保全するための安全策。**                                                                             |
| `--dump-unallocated`         | `false`  | ディレクトリ登録ファイル、戦闘領域、システム領域のいずれにも紐付かないセクタ（アライメントギャップ、末尾空き領域、未知のデータブロック）を抽出し `unallocated/` 配下に出力。**ファイルとして出力されていない領域に未知のコードやデータが残留・隠蔽されていないかを検証するための機能。** |
| `--skip-blank-unallocated`   | `false`  | 未割り当てセクタのうち、全バイトが `0xFF` または `0x00` の純粋な空きブロック出力をスキップする。                                                                                                                                                                                         |
| `--battle-start <SEC>`       |  `auto`  | 戦闘データ開始セクタを手動指定（未指定時は `BATTLE.COM` のポインタから自動検出、検出不能時は `0x044C`）。                                                                                                                                                                                 |
| `--battle-sectors <COUNT>`   |  `245`   | 戦闘データのセクタ数を手動指定（既定値: 245セクタ / 125,440B）。                                                                                                                                                                                                                         |
| `--battle-pointer <OFFSET>`  | `0x0F6C` | `BATTLE.COM` 内の戦闘セクタ番号ポインタオフセットを指定（既定値: `0x0F6C`）。                                                                                                                                                                                                            |

### 7.2 ディレクトリ構成（全オプション有効時）

```text
[作業ディレクトリ]
├── root_directory.json          # 全2,880エントリのメタデータ定義 (FileId, FileIdHex, セクタ範囲等)
├── sector_map.json              # 全セクタの使用状況・分類マップおよび戦闘データ解析情報
├── files/                       # 【基本】既知の仕様に基づくファイル出力（--dump-files）
│   ├── SYSTEM_BOOT.BIN         # セクタ 0x0000 - 0x0009（IPL / ブートローダー / 5,120B）
│   ├── BATTLE_DATA.BIN         # 戦闘グラフィック・システム（初期値: 0x044C - 0x0540 / 125,440B）
│   ├── MAIN.COM
│   ├── BATTLE.COM              # (+0x0F6C に戦闘データポインタを内包)
│   ├── MAINBG.PIC              # FFPicToolで解凍・圧縮・PNG画像化の対象となるリソース
│   ├── *.PIC / *.CHR / *.MAP / *.BGM / *.MSG ...
│   └── ...                     # その他バイナリおよびテーブル
│
├── unallocated/                 # 【解析漏れ対策】ファイル非占有セクタ（--dump-unallocated）
│   ├── UNALLOC_0078_0083.BIN   # COM間のギャップ等（開始・終了セクタ付き、4桁HEX表記）
│   ├── UNALLOC_0541_059F.BIN   # 戦闘データ終端からディスク末尾までの領域
│   └── ...                     # 既知領域外にデータが存在する場合に隔離・検出
│
└── sectors/                     # 【完全保全・解析用】全セクタ生データ（--dump-sectors）
    ├── 0000.bin
    ├── 0001.bin
    ├── ...
    └── 1439.bin
```

### 7.3 未割り当てセクタ抽出（`--dump-unallocated`）の動作仕様

* **仕様漏れ・隠蔽データの検出**:  
  本作の戦闘データ（`BATTLE_DATA.BIN`）のように「ディレクトリに登録されずマシン語コードから直参照されている領域」が他にも存在する可能性を想定する。ファイルシステム上の登録外セクタを抽出することで、未解明のデータや消去し忘れた開発時の残存データが存在しないかを特定可能とする。
* **出力形式**:  
  連続する未登録セクタを1つのブロックバイナリとして集約し、`UNALLOC_[開始セクタ]_[終了セクタ].BIN`（4桁16進数大文字表記）として出力する。
* **完全空きセクタのフィルタリング**:  
  単なる未使用パディング（全バイトが `0xFF` または `0x00`）であるセクタブロックについては、ディスク容量節約のためにファイル出力を抑制しメタデータへの記録のみに留めるオプション（`--skip-blank-unallocated`）の併用を可能とする。

---

## 付録：先行ツール（final-fantasy-msx2-say-dos-tool）と FFSayDosTool の差異・互換性メモ

先行のオープンソース実装である `final-fantasy-msx2-say-dos-tool`（C#実装）と、本仕様に基づく `FFSayDosTool` における設計・動作の差異である。

* **ディレクトリエントリ長（16バイト保証）**:  
  `final-fantasy-msx2-say-dos-tool`（`SayDosRootDirectory.cs`）の出力処理では、拡張子フィールドを `FileExt.PadRight(3)` で処理していたため、エントリ長が15バイトに縮退する問題があった。`FFSayDosTool` では「8バイト名 + 4バイト拡張子（ピリオド含む） + 2バイト開始セクタ + 2バイト終了セクタ」の16バイト固定長バイナリを厳密に出力する。
* **ファイルID（通し番号）の保持と可視化**:  
  ゲーム本体のZ80コードがディレクトリエントリのインデックス（通し番号）でファイルを特定・ロードする仕様に基づき、`FFSayDosTool` では `root_directory.json` の各エントリに `FileId`（10進整数）および `FileIdHex`（16進文字列）を出力し、一覧表示（`list`）でも明示する。
* **戦闘システム領域の自動検出と再配置対応**:  
  先行ツールでは戦闘データの開始セクタを `0x044C` 固定として読み込んでいたため、再構築後のディスクを再ダンプした際に位置ズレが発生していた。`FFSayDosTool` では `BATTLE.COM` 内ポインタ（`+0x0F6C`）を参照して実際の開始位置を自動検出し、手動指定オプションも備える。
* **ルートディレクトリ領域（2,880エントリ）の完全補完**:  
  手動編集でJSONから未使用エントリが削除された場合でも、`FFSayDosTool` は90セクタ分（46,080B）に達するまで空エントリで自動補完し、ファイルデータ領域（セクタ `0x0064`）の物理配置ズレによる起動不能を防止する。
* **セクタ端数データのパディング処理**:  
  先行ツールの書き込み（`Write`）処理では、ファイルサイズが512バイトの倍数でない場合に例外終了する仕様であった。`FFSayDosTool` ではリソース差し替え等で端数サイズが発生した場合、オプション指定（`--auto-pad`）により末尾を自動パディングしてセクタ境界（512バイト倍数）へ切り上げて配置できる。
* **セクタダンプの標準運用と任意化**:  
  先行ツールは全セクタを個別の連番ファイル（`0000.bin` ～ `1439.bin`）としてダンプ・参照する構造が必須であった。`FFSayDosTool` では通常の可搬性と管理性を考慮し、ファイル集約型（`SYSTEM_BOOT.BIN`, `BATTLE_DATA.BIN` を含む）を標準とする。ただし、解析から漏れている未知データの存在や仕様外データの取りこぼしを防ぐ目的において、必要に応じて同等形式の全セクタ個別ダンプ（`--dump-sectors`）や未割り当てセクタ抽出（`--dump-unallocated`）を選択・出力できる設計とする。
* **コンパクション時のディスク総容量検証**:  
  `final-fantasy-msx2-say-dos-tool` の間詰め再配置処理を踏襲しつつ、`FFSayDosTool` では全ファイルおよび戦闘データの配置完了時にディスク総容量が `0xB4000` バイト（1,440セクタ / 720KB）を超過していないかの整合性チェック（アサート）を必須とする。
