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

A tool that builds an MSX MegaROM cartridge (ASCII16) to listen to the music of Micro Cabin games.
Every song is played with the game's own sound driver and instruments.

This package contains no Micro Cabin data (no music, drivers or graphics).
The music and drivers are extracted from your own disk images of the games when you build the ROM.

== Supported games ==

  Folder    Game                                Disks
  --------  ----------------------------------  -----
  XAK       Xak                                 3
  XAKII     Xak II                              6
  FRAY_M2   Fray (MSX2)                         4
  FRAY_TR   Fray (MSX turboR)                   5
  GAZZEL    Tower of Gazzel                     4
  ILLUSION  Illusion City                       8
  FFANTASY  Final Fantasy                       1
  RISK2     Dai Senryaku II (Campaign Version)  2
  PMAKER    Princess Maker                      7
  CABIN     The Tower of Cabin                  3

You can skip the games you don't have.

== Requirements ==

- Python 3.8 or later with Pillow (pip install pillow)
- Disk images (.dsk) of the games
- sjasmplus is not needed (the prebuilt player/player.bin is used; only needed if you change player/player.asm)

== Building the ROM ==

Run in the folder containing this README:

1. python tools/extract_disks.py - creates one folder per game under disk_image.
2. Put the disk images (.dsk) of each game in its folder. Disks are numbered in file name order
   (names like "Disk 1 of 3" are fine as they are).
3. python tools/extract_disks.py again - extracts the songs to data/<folder>/,
   and writes player/playlist.txt and extract_log.txt.
4. cd player and python build_rom.py - writes player/MCPLAYER.ROM (1MB, ASCII16 mapper).

build_rom.py options:

  Option
  --------------  -------------------------------------------------------------------
  --autoplay      Auto play (see below)
  --loops 3       Default loop count (2)
  --lang en / ja  Always English / Japanese (default: by the machine's character set)
  --size auto     Smallest ROM size (default 1024KB)
  -o name.rom     Output file

A ROM built with --autoplay plays the list from the first song after the startup song (or right after boot), forever.
For machines without a keyboard (1chipMSX etc.). You can still use the keys.

== Running ==

- Use it as an ASCII16 MegaROM. In emulators, select the ASCII16 mapper. With another mapper (e.g. an ESERAMair
  left in 8KB bank mode) it shows "The ROM is not in ASCII16 mode." and stops safely.
- Works on MSX1 / MSX2 / MSX2+ / turboR with 32KB RAM or more (64KB for Final Fantasy songs).
- MSX-MUSIC / FM-PAC are detected automatically. Without FM, only the PSG part of the FM song data plays
  (the separate PSG song data the games use without FM is not used).
- Pictures (CG) are shown on MSX2 or later. With a V9990 (GFX9000) or a VDP at I/O 88h (V9968 cartridge etc.),
  pictures are always shown there only, and the built-in VDP shows only the list (pictures are shown even on MSX1;
  the V9990 is used if both are present).
- A machine with a built-in V9968 (as its main VDP at I/O 98h) works the same as a V9958 MSX2+.
  With an external V9990 as well, the built-in V9968 shows the list and the V9990 shows the pictures.

Keys: Up/Down select a track (SHIFT: 10 tracks), Left/Right select a game, SPACE play / stop,
E range (ALL / GAME / ONE), R repeat (REPEAT / ONCE), V picture / list, H help (on the startup picture, H goes to the list with the help without stopping the song).

== Editing the playlist ==

player/playlist.txt lists one song file per line, in play order.
Titles, English titles and loop counts come from the database tools/mcm_db.csv when the ROM is built
(text after # is only a memo). The driver and instruments are those of the game of the song file's folder.

- @game Name | English name - game of the following songs
- @cg picture - picture of the game, @song_cg picture (line after a song) - picture only while that song plays
- @startup song / @startup_cg picture - song and picture at boot (default picture if omitted)
- Pictures: prepare them yourself (see "Pictures" below).

== Pictures ==

Any image can be shown, not only game screens, with these limits:

- Files: PNG, JPEG, BMP, GIF etc. (anything Pillow reads) and BSAVE .SC5 / .SC8. Transparent parts become black.
- Size:
  - 256x212 is used as is; 256x192 is padded with black. 512x212 becomes a 512-dot screen (16 colours).
  - 320x240 and 640x480 are treated as emulator screenshots and their border is cut off.
  - Other sizes are resized to 256x212 (the aspect ratio is not kept). Crop and scale images to 256x212 beforehand.
- Aspect ratio: one image pixel becomes one MSX dot, but MSX dots are not square. On a real NTSC TV / monitor a dot is
  about 1.14:1 (wide), so images with square pixels look about 14% wider. A 4:3 image simply resized to 256x212
  (ignoring the aspect ratio) looks almost 4:3 on real hardware. On PAL machines dots are even wider (about 1.37:1),
  so all pictures, including the games' own, look wider. Emulators may show square dots depending on their settings.
- Colours: 16 colours or less (after conversion to the MSX2 512 colours) are kept exactly (SCREEN 5).
  More colours (photos etc.) are reduced to a fixed 256-colour palette (SCREEN 8) and look coarse.
  512-dot wide images are reduced to 16 colours.
- Size in ROM: pictures are compressed, but photo-like images stay large (up to about 53KB each) and take 1-2 seconds
  to show. If the ROM (1MB by default) is full, use --size 2048 etc. (up to 4MB).
- The bottom line shows the song title over the picture.
- Game screens are best taken from emulator screenshots (openMSX screenshot -raw). Scanlines or blur add colours
  and make the picture SCREEN 8.

== Fixing titles ==

To fix a title, find the song id in extract_log.txt and edit that row of tools/mcm_db.csv.

== Credits ==

- Thanks: Manuel Pazos (MCDRV.COM, PCPLAYER for Windows), Patriek Lesparre.
- Driver disassembly: Roberto Vargas. Driver addresses were found by comparing each driver with Roberto Vargas'
  disassembly of Illusion City's driver (mcdrv.asm, published on Manuel Pazos' website).
- Fonts: "k8x12" and "k6x8" by Num Kadoma (free to use and redistribute; see font/).
- Music, drivers and graphics are (C) MICRO CABIN Corp. Use the ROM you build for your personal enjoyment only and do not distribute it.

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