ILLUSION CITY - MSX TRANSLATIONS
Translation 1.0.5 / ROM 0.5 - RELEASED
Release date: 15 November 2026

This package upgrades the original September 2025 English release.
Choose ONE route below. Both produce exactly the same 4 MiB ROM 0.5.
No game ROM or disk images are included.

ORIGINAL RELEASE INCLUDED
original/IC100ENG.ZIP is the complete, unchanged September 2025 release.
It contains the original disk IPS patches, manuals, RCD tools and extras.
Extract that ZIP into a separate folder to keep its older tools separate.
Its release text and ROM instructions describe version 1.0.0 / ROM 0.3.
Use the current instructions below when creating ROM 0.5.

REQUIREMENTS
MSX2, MSX2+ or Turbo-R; 256 KB memory-mapper RAM; MSX-MUSIC or FM-PAC.
Supported Turbo-R/Panasonic MSX2+ turbo modes are enabled automatically.
FM works with 256 KB. MIDI retains its 512 KB and compatible hardware
requirements.
For openMSX, select ASCII16-X to use FlashROM saves.

FLASH CARTRIDGE INFORMATION
IC105ENG.TXT retains the original release's MegaFlashROM SCC+SD / OPFXSD,
Carnivore 2 / C2 utilities, and ASCII16-X / ASCIIXF instructions.
IC.RCP is included in this package, unchanged from the original release.
For Carnivore 2, copy the patched ROM to your MSX media as IC.ROM and put IC.RCP
in the same folder. Load IC.ROM with C2MAN and accept the matching RCP preset
when prompted. Keep your original patched ROM for the Windows launchers.
Cartridge utilities and firmware are available from
https://github.com/RBSC/Carnivore2
The historical hardware-test notes are retained from the original release;
they do not claim new ROM 0.5 tests on those cartridges.

ORIGINAL DISK VERSION FROM SD
For the original English disk version, see "RUNNING DISK IMAGES FROM SD" in
IC105ENG.TXT. It covers concatenating the eight disks, SofaRun / SofaRunIt
saving and disk switching, and Sharksym MMC/SD's MMCSD.COM /D2 method.
These disk instructions are separate from the ROM update routes below;
the disk version retains its original Turbo-R requirements.

ROUTE A - ROM 0.3 TO ROM 0.5 (IPS)
1. Start with the original, unmodified 4 MiB ROM 0.3. Back it up first.
2. Check its SHA-256 against the value below. IPS itself does not check hashes.
3. Apply ips/illusion_city_rom_0.3_to_0.5.ips with your usual IPS patcher.
4. Save as illusion_city_v0.5.rom and verify the resulting SHA-256 below.
Do not apply this IPS to disks, Japanese ROMs, or another development build.

ROUTE B - ENGLISH DISKS TO ROM 0.5 (RCD)
Starting with Japanese disks? Extract original/IC100ENG.ZIP separately and
follow its IC100ENG.TXT to patch disks 1-8 with ips/IC100EN1.IPS through
ips/IC100EN8.IPS. Use copies of your disks and keep them free of save writes.
Then return to THIS package's rcd folder and use icrom_0.5.rcd as shown below.
You do not need to build ROM 0.3 or apply the ROM IPS when using this route.

Use the eight English disks patched by the ORIGINAL 1.0.0 IC100EN1..8.IPS files.
The exact accepted disk hashes are below and embedded in the RCD.
Use pristine release disks: modified/save-written disks will fail strict checks.

From the rcd folder (replace D1.DSK ... D8.DSK with actual paths):
Join these three printed lines with spaces and enter them as one command:
  python rcd_apply.py icrom_0.5.rcd
    D1.DSK D2.DSK D3.DSK D4.DSK D5.DSK D6.DSK D7.DSK D8.DSK
    -o illusion_city_v0.5.rom --strict --delete-on-mismatch
Use py on Windows or python3 on macOS/Linux as appropriate. Python 3 is
required.
Windows users can also run build_rom.bat with eight disk paths as arguments.
The input disks are read-only; the tool creates a separate ROM file.

PLAYING WITH OPENMSX ON WINDOWS
Extract the entire release package into a writable folder.
The emulator and system ROMs are not included.

RECOMMENDED OPENMSX BUILD
For emulator play, use Max Iwamoto's openMSX build on GitHub:
https://github.com/maxiwamoto/openMSX/releases/tag/rom-dev-2026.10.28

Download openmsx-rom-dev-2026.10.28-windows-x64.zip from Assets. This is our
unofficial Windows x64 build based on openMSX 22.0. Extract the complete
package, including share and the DLLs, into C:\Program Files\openMSX for the
supplied game launchers. Provide your own machine system ROMs and FM-PAC ROM.

This build improves in-game FlashROM saves: it preserves modified Flash
sectors while loading untouched sectors from the current ROM. This makes
compatible ROM updates easier without discarding your saved games. Select
ASCII16-X; our game launchers already do this. Keep backups: older full-chip
saves can still mask updated ROM data, and save formats must be compatible.

It also adds convenient mouse capture and Makoto / YM2608 support. With an
MSX mouse connected in the Input menu, click the display to capture it; the
first click only captures. Middle-click releases the mouse.

Makoto PC-98 music for Illusion City is coming soon. ROM 0.5 still uses its
FM/MIDI soundtrack; installing this emulator does not change the game's music.
Use the game launchers below for this release; no Makoto extension is needed.
Back up your emulator profile before upgrading. Older emulator builds cannot
read this fork's new .flash format, so keep their profiles separate.

Put illusion_city_v0.5.rom beside these launchers and double-click your choice:
  run_msx2.bat     - Philips NMS 8250, 256 KB RAM and FM-PAC.
  run_msx2plus.bat - Panasonic FS-A1WSX, 256 KB RAM and built-in MSX-MUSIC.
  run_tr.bat       - Panasonic FS-A1GT Turbo-R and built-in MSX-MUSIC.
The ROM enables the supported turbo modes automatically.
The launchers also find the ROM created inside rcd by build_rom.bat.
Alternatively, drag a patched ROM onto any launcher, even if it has another
name.
No Python or development tools are needed to play an already-patched ROM.

Settings and FlashROM saves are kept in .local/openmsx-user inside this release
folder. Keep that folder when moving the game and back it up with your saves.
Close openMSX before switching launchers: all three share this save profile.
To use existing saves from another installation, back up both profiles and
transfer the matching FlashROM persistence files while openMSX is closed.

SAVES
Back up FlashROM persistence files, cartridge saves and disk saves before
updating.
Use the game's Load menu with the new ROM. Old emulator save states contain old
code and are not a reliable way to load the updated game. This package creates
a clean ROM and does not migrate cartridge/emulator flash persistence for you.

INPUT ROM 0.3 SHA-256
36d91d8857e514d751ffd18e98269d0b875d1b4a787f0341eaba120c37df89a7

OUTPUT ROM 0.5 SHA-256
0ae6d6271f972baa79dbd1df1a767a58f321b2564f1fc1887392fc90b0b9e849

ENGLISH DISK SHA-256 (1.0.0 release, NOT Japanese input-disk hashes)
Disk 1: 2ff7136bb3b279e66d918bcf35f02400141c9ffe1332b8d99b66493d0f9a8f15
Disk 2: 5af61eb167d39d157ffdaeecec2e376bd0fc1b79fe8c0ac646b8a5c80c81fe6a
Disk 3: 562332ae762997ea3e7ddc74ca7de65101d5d26f527deb802fdfe8e7ec7ae705
Disk 4: e338a0e641f5c368a9129961583c85dd1c0e4cb1a29ac76dc84ab820441db17d
Disk 5: e43ddc4bb29904212427a4686297246387594a39aaa339f925de044cc6225e58
Disk 6: e769e748a3f3783938468c3c7ea5a938de11cfbdf02651bc4d2428d075a057a0
Disk 7: fa23a425d5112f136ea9e2b0244479c7e910de409ab91cd2c3342de89e3356d2
Disk 8: 98ad9620132be886f811f15d6b039dc5da515fda6ee3e1f78d592ffe830de6e3

NEW IN THIS VERSION

 [ Hardware compatibility ]

 - The ROM now runs on MSX2 and MSX2+ with 256 KB of memory-mapper RAM and
   built-in MSX-MUSIC or an FM-PAC, as well as on Turbo-R.
 - Removed the Turbo-R-only startup restriction and adapted the FM driver for
   Z80 machines without the Turbo-R timer hardware.
 - Automatically enables R800 mode on Turbo-R and the supported Panasonic
   MSX2+ turbo mode.
 - Protected the FM driver against overlapping interrupts while preserving
   music, sound effects and screen interrupts. FM needs 256 KB; MIDI retains
   its 512 KB RAM and compatible MIDI hardware requirements.

 [ Faster maps, battles and windows ]

 - Cached unchanged field and battle map buffers instead of expanding the same
   map data repeatedly.
 - Reused unchanged tile and layer composition on both display pages, while
   retaining repairs for moving characters, targeting and damage animations.
 - Reduced repeated work in tile comparison and clean-tile scans, skipped
   unchanged columns, and reused overlapping map strips during scrolling.
 - Cached animation lookups and tracked exactly which visible tiles depend on
   each animation. Offscreen animation changes no longer force unnecessary
   full map checks.
 - Tracked battle animation dependencies separately for each layer and skipped
   unchanged battle columns. All scenery layers, animation steps and the
   original game-area size remain enabled by default.
 - Fixed cache invalidation after loading a save, so ordinary resource reads
   no longer discard reusable map and composition data.
 - Restored the interface from an expanded ROM copy instead of repeatedly
   decompressing it during conversations, elevator transitions and menu
   changes.
 - In matched tests, the MSX2 tile comparison/composition pass fell from 78.2
   ms to 11.3 ms, and an MSX2+ apartment redraw after loading fell from 279 ms
   to 125 ms. These are specific workloads, not a universal or cumulative
   speed multiplier.
 - Added an experimental F1 foreground ON/OFF switch for field maps, including
   Downtown signs. Ground and other scenery layers remain visible; battles
   keep all layers. The setting is not saved.

 [ Battle and magic fixes ]

 - Restored the moving attack animation for the SHIVA Guard Robots using the
   newer archived engine behaviour, with correct targeting and damage.
 - Fixed the target-candidate overwrite that could make Tian Ren less likely
   to be attacked. The original random selection, distance and status rules
   are preserved.
 - Consuming Nectar of the Gods now clears its revival effect from both the
   battle and persistent character records, preventing it from becoming armed
   again when the battle record is rebuilt.
 - Made HP/MP effects safely skip empty target-list entries, complementing the
   translation's existing target-count correction.
 - Corrected Headgear paralysis protection: it now blocks paralysis instead of
   blocking its cure, and recovery works while Headgear is equipped.
 - A confused character's failed attack without ammunition now ends the turn,
   without repeated retries or a free attack. Normal attacks and ammunition
   handling are preserved.
 - Fixed Zhuo Shi Kai's free field magic overwriting Tian Ren's MP by
   restoring the correct caster pointer. Zhuo's zero MP cost and normal spell
   costs remain intact.
 - Instantaneous Return with no valid destination now displays an English
   barrier message and returns to the caster menu instead of repeatedly
   casting and reopening the error. Valid destinations retain their normal
   behaviour.

 [ Menus and mouse controls ]

 - Known spells now appear consecutively in the Magic list, without large
   empty category gaps. The list is rebuilt from the character's progression,
   preserving spell identities, their order and spells learned later.
 - Fixed damaged selection frames and copied cursor fragments in the battle
   Items and Magic lists by preserving cursor state and alignment during arrow
   redraw.
 - Aligned the right-side scroll arrows with their mouse click areas and kept
   them visible through window refreshes. Buy pages restore their arrows, and
   the BGM menu keeps responding after changing songs.
 - Repaired screen restoration when closing Debug and when returning from Save
   Anywhere or its cancelled Save menu.
 - Cleared selection-outline residue when returning from refused or empty Sell
   selections, while retaining normal cancellation.
 - Added English explanations for protected-item discard, unusable items,
   equipment restrictions, a full inventory when removing equipment, and
   insufficient MP. Empty slots and cancelled actions remain silent.
 - Pressing Space in Speed Adjustment no longer disables Left/Right. Keyboard
   and mouse adjustments continue to work after confirmation.
 - Using the last copy of an item now returns to the list without an incorrect
   error sound. Empty slots return silently, while genuinely unusable items
   retain their error feedback.
 - Fixed the shifted mouse arrow after portrait conversations, including
   Discuss after Instantaneous Return to Kai. Portrait palette switching now
   retains the correct 8x8 sprite mode.

 [ Startup artwork and release tools ]

 - Added the new 512 x 424 interlaced SCREEN 7 MSX Translations logo with
   palette fade-in/out.
 - Added the new 256 x 192 SCREEN 8 title picture after the translation logo,
   replacing the old SCREEN 12 startup artwork.
 - The startup images use CBS Cruncher v5.5 streams with a rolling 16 KB
   buffer, retaining each image field or picture as one continuous compressed
   stream.
 - Included Windows openMSX launchers for MSX2, MSX2+ and Turbo-R. Place the
   patched ROM beside the launchers, or drag it onto one to play. Settings and
   FlashROM saves are kept in the release folder.
 - Included an IPS update from the original ROM 0.3 and an RCD conversion from
   the eight English disks of translation 1.0.0. Both routes produce the same
   ROM 0.5.
 - Included the complete original 1.0.0 release archive, unchanged, with disk
   translation patches, manuals and extras. Translate Japanese disks with
   those patches, then convert directly to ROM 0.5 with the new RCD.
 - For emulator play, use Max Iwamoto's openMSX build from GitHub for easier
   FlashROM saves across compatible ROM updates, convenient mouse capture and
   Makoto / YM2608 support. Makoto PC-98 music for Illusion City is coming
   soon; ROM 0.5 retains its FM/MIDI soundtrack.

The original FM/MIDI player is retained; streamed-music research is not
included.
