﻿============================================================
MICRO CABIN MUSIC PLAYER Ver 0.20
============================================================

マイクロキャビンのゲームの曲を、MSX の ROM カートリッジ（メガロム）にまとめて聴くためのツールです。
曲は、それぞれのゲーム自身のサウンドドライバと音色で鳴らします。

この配布物には、曲・ドライバ・ゲームの画面などのマイクロキャビンのデータは入っていません。
ご自分で持っているゲームのディスクイメージから曲とドライバを取り出して、ROM を作ります。

■ 対応しているゲーム

  フォルダ  ゲーム                  ディスク
  --------  ----------------------  --------
  XAK       Xak                     3 枚
  XAKII     Xak II                  6 枚
  FRAY_M2   FRAY（MSX2 版）         4 枚
  FRAY_TR   FRAY（MSX turboR 版）   5 枚
  GAZZEL    ガゼルの塔              4 枚
  ILLUSION  幻影都市                8 枚
  FFANTASY  ファイナルファンタジー  1 枚
  RISK2     キャンペーン版大戦略II  2 枚
  PMAKER    プリンセスメーカー      7 枚
  CABIN     The Tower of Cabin      3 枚

持っていないゲームは飛ばして構いません（持っているゲームの曲だけで ROM を作ります）。

■ 必要なもの

- Python 3.8 以降と Pillow（pip install pillow）
- ゲームのディスクイメージ（.dsk）
- アセンブラ sjasmplus は不要です（組み立て済みの player/player.bin を使います。player/player.asm を直したときだけ必要）

■ ROM の作り方

この README のあるフォルダで、次のように実行します。

1. ディスクイメージを入れるフォルダを作る

      python tools/extract_disks.py

   disk_image の下にゲームごとのフォルダができます。
2. それぞれのフォルダに、そのゲームのディスクイメージ（.dsk）を入れる
   - ディスクの番号はファイル名の順です（「Disk 1 of 3」のような名前ならそのままで構いません）。
3. 曲を取り出す（もう一度同じコマンド）

      python tools/extract_disks.py

   - data/ゲームのフォルダ/ に曲（.MCM）ができます。FM 音源を使う曲と、データベースに登録した PSG の曲だけを取り出します。
   - player/playlist.txt（プレイリスト）と extract_log.txt（取り出した曲の一覧）ができます。
4. ROM を作る

      cd player
      python build_rom.py

   player/MCPLAYER.ROM（1MB、ASCII16 マッパー）ができます。

◆ オプション（build_rom.py）

  オプション      内容
  --------------  -----------------------------------------------------------
  --autoplay      自動再生（下を参照）
  --loops 3       ループ回数の既定値（既定 2）
  --lang en / ja  表示を英語 / 日本語に固定（既定は本体の文字セットで決める）
  --size auto     ROM の大きさを必要最小限にする（既定 1024KB）
  -o 名前.rom     出力するファイル名
  リスト.txt      別のプレイリストを使う

--autoplay で作った ROM は、起動時の曲が終わったら（起動時の曲がなければ起動してすぐ）リストの先頭の曲から順に鳴らし続けます。キーボードのない環境（1chipMSX など）向けです。途中でキーを押せば、ふだんどおり操作できます。

■ 動かし方

- MSX のメガロムカートリッジ（ASCII16）として動かします。エミュレータでは ROM の種類（マッパー）に ASCII16 を指定してください。ASCII16 以外（ESERAMair などを 8KB バンクにしたままなど）で起動すると、「The ROM is not in ASCII16 mode.」と表示して止まります（暴走はしません）。
- MSX1 / MSX2 / MSX2+ / turboR で動きます。RAM 32KB 以上が必要です（ファイナルファンタジーの曲は 64KB。ページ1の RAM でドライバを動かすため）。
- FM 音源（内蔵の MSX-MUSIC か FM-PAC）を自動で見つけます。FM 音源がないときは、FM 音源用の曲データのうち PSG のパートだけが鳴ります（ゲームが FM 音源のないときに使う PSG 用の曲データは使いません）。
- CG（ゲームの絵）は MSX2 以降で表示します。V9990（GFX9000）か、I/O 88h の VDP（V9968 カートリッジなど）があるときは、CG は常にそちらにだけ表示し、内蔵 VDP 側は曲選択の画面（リスト）だけになります（MSX1 でも CG を表示できます。両方あるときは V9990）。
- 本体に V9968 を内蔵した機種（VDP が I/O 98h にあるもの）は、V9958 の MSX2+ と同じに動きます。外付けの V9990 もあれば、内蔵の V9968 で曲選択の画面、V9990 で CG を表示します。

◆ キー操作

  キー   動作
  -----  ----------------------------------------------------------------------------------
  ↑ ↓  曲を選ぶ（SHIFT で 10 曲ずつ）
  ← →  ゲームを選ぶ
  SPACE  選んだ曲を鳴らす / 鳴っている曲を止める
  E      再生の範囲（ALL / GAME / ONE）
  R      リピート（REPEAT / ONCE）
  V      CG とリストを切り替える（MSX2 以降、CG があるとき）
  H      ヘルプ（起動時の CG の表示中に押すと、曲を止めずに曲選択の画面にしてヘルプを出す）

テンキーの 8・2・4・6 でも ↑↓←→ と同じ操作ができます。

■ プレイリストを直す

player/playlist.txt は 1 行に 1 曲のファイルを書いたリストです。行の順に曲が並びます。

      @game Xak
      ../data/XAK/XAK101.MCM	# オープニング１
      ../data/XAK/XAK102.MCM	# ...

- 曲を外すには、行を消すか行頭に # を付けます。並べ替えは行を入れ替えるだけです。
- 曲名・英語の曲名・ループ回数は、ROM を作るときにデータベース（tools/mcm_db.csv）から引きます。行末の # の後ろはメモなので、直しても ROM には反映されません。
- 曲のドライバと音色は、曲ファイルのフォルダのゲームのものになります（@game の行は表示するゲーム名だけ）。同じ曲を何度入れても、ROM に入る曲データは 1 つです。
- @game ゲーム名: それ以降の曲のゲーム名（@game ゲーム名 | English name で英語の名前も）
- @cg 画像（@game の後）: そのゲームの CG
- @song_cg 画像（曲の行の次の行）: その曲を鳴らしている間だけ替える CG
- @startup 曲ファイル: 起動時に鳴らす曲 / @startup_cg 画像: 起動時の CG（なければ標準の CG）
- CG は各自で用意してください（使える画像は下の「CG に使える画像」を参照）。
- もう一度 extract_disks.py を実行すると、今の playlist.txt は残し、新しいリストを playlist_new.txt に書きます。

◆ CG に使える画像

ゲームの画面でなくても、好きな画像を表示できます。ただし次の制限があります。

- ファイル: PNG・JPEG・BMP・GIF など（Pillow で読めるもの）と、BSAVE 形式の .SC5 / .SC8。透明な部分は黒になります。
- 大きさ:
  - 256×212 はそのまま、256×192 は下を黒で埋めます。512×212 は横 512 ドットの画面（16 色）になります。
  - 320×240 と 640×480 はエミュレータのスクリーンショットとみなして、周りの枠を切り取ります。
  - それ以外の大きさは 256×212 に引き伸ばします（縦横比は保たれません）。ネットの画像などは、あらかじめ 256×212 に切り抜いて縮小しておいてください。
- 縦横比: 画像の 1 ピクセルが MSX の 1 ドットになりますが、MSX のドットは正方形ではありません。実機（NTSC のテレビ・モニター）では 1 ドットが約 1.14:1 の横長なので、正方形のピクセルの画像は約 14% 横に伸びて見えます。4:3 の画像なら、縦横比を気にせず 256×212 にそのまま縮小すると、実機でほぼ 4:3 に見えます。PAL の本体ではドットがさらに横長（約 1.37:1）になり、ゲームの絵も含めて横に広く見えます。エミュレータでは、設定によってドットが正方形のまま表示されることがあります。
- 色:
  - MSX2 の 512 色に直して 16 色以下なら、色はそのまま（SCREEN 5）です。
  - それより多い画像（写真など）は、決まった 256 色（SCREEN 8）に減らすので、色が粗くなります。横 512 ドットの画像は 16 色に減らします。
- 容量: CG は圧縮して ROM に入れますが、写真のような絵はあまり縮まず（1 枚最大約 53KB）、表示にも 1〜2 秒かかります。ROM の容量（既定 1MB）が足りないときは --size 2048 などで大きくできます（最大 4MB）。
- 表示中は、一番下の行に曲名を重ねて表示します。
- ゲームの画面は、エミュレータのスクリーンショット（openMSX なら screenshot -raw）から作るのが確実です。スキャンラインやぼかしを入れた画像は色が増えて SCREEN 8 になってしまいます。

◆ 曲名を直す

extract_log.txt で曲の id（S0001 など）を調べ、tools/mcm_db.csv（UTF-8。Excel でも開けます）のその行の曲名（title / title_en）を直して、ROM を作り直してください。同じ曲がほかのゲームにもあるときは、ゲームごとに行があります。

■ フォルダの中身

  場所                                         内容
  -------------------------------------------  ----------------------------------------------------------------
  tools/extract_disks.py                       ディスクイメージから曲を取り出し、プレイリストを作る
  tools/mcm_db.csv                             曲のデータベース（曲名・英語の曲名・並び・ループ回数・除外など）
  tools/mcm_db.py ほか                         データベースと MCM を扱うモジュール
  player/build_rom.py                          ROM を作る
  player/player.asm / player.bin / player.sym  プレーヤーのプログラム（ソースと組み立て済みのもの）
  player/drivers.json                          使えるドライバの版の情報（番地と照合用の値だけ）
  player/default_cg.png                        標準の起動時の CG（make_default_cg.py で描いたもの）
  player/TECHNICAL.md / TECHNICAL_en.md        技術的な説明（ドライバの扱い、ROM の構成など）
  font/                                        フォント（k8x12、k6x8）

■ クレジット

- Thanks: Manuel Pazos（MCDRV.COM、Windows 版 PCPLAYER）、Patriek Lesparre
- ドライバの逆アセンブル: Roberto Vargas
  - ドライバの番地などは、Roberto Vargas さんによる幻影都市のドライバの逆アセンブル（Manuel Pazos さんのサイトで公開されている mcdrv.asm）と命令列を突き合わせて求めました。
- フォント: 門真 なむ氏の「k8x12」「k6x8」（自由に利用・改変・再配布できるフォントです。font/ の中の説明を参照）
- 曲・ドライバ・ゲームの画面の著作権はマイクロキャビンにあります。作った ROM は個人で楽しむ範囲で使い、配布しないでください。

All music (C) MICRO CABIN Corp. Thank you for the wonderful music!
