Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:WonderSwan ROM image

From ReverseEngineering.wiki
Format
Extensions .ws, .wsc
Endianness little
On this wiki Facts · Code · Notes · Topics

Raw cartridge dump of the Bandai WonderSwan and WonderSwan Color (.ws, .wsc): no leading header, the ROM is padded at the front to a power of two and ends with a 16-byte footer whose last 10 bytes (developer, colour flag, cartridge id, ROM size, save type, flags, RTC/mapper, checksum) are the cartridge header.

Layout

The CPU starts at the end of the address space (physical 0xFFFF0, Platform:WonderSwan), so the header is stored at the end of the ROM, and the ROM size is a power of two (minimum 64 KiB; Mesen2 and Beetle WonderSwan both refuse smaller files). If a dump is not a power of two, the loaders pad at the front: Mesen2 inserts zeros before the data, Beetle fills with 0xFF (mednafen/wswan, libretro.c Load).

Footer (last 16 bytes)

Offsets are from the end of the file; -1 is the last byte. Sources: Dox's WSTech document in Beetle WonderSwan (mednafen/wswan/wstech24.txt, section 6, "last 10 bytes"), ares (mia/medium/wonderswan.cpp, reads rom[size-16]) and Mesen2 (Core/WS/WsConsole.cpp).

From end Field
-16 opcode of the start jump (a far JMP EA) followed by 4 bytes offset:segment. Unverified: not read in the sources, only the Detective Conan patch in Beetle writes EA 00 00 00 20 at 0xFFFE8
-10 developer (publisher) id
-9 minimum system: 0 monochrome WonderSwan, 1 WonderSwan Color (Mesen2 tests bit 0)
-8 cartridge id, defined per developer
-7 undocumented in the WSTech document (3 - ??). Unverified: version number
-6 ROM size code (table below)
-5 save type code (table below)
-4 flags: bit 0 = 1 vertical, 0 horizontal orientation; bit 2 = 1 means 16-bit bus (ares); WSTech notes bit 2 "always 1"
-3 RTC present (WSTech, ares: value 1); Mesen2 and ares also read this same byte to choose the mapper (0 = Bandai 2001 / KARNAK, 1 or more = Bandai 2003)
-2, -1 checksum, 16-bit little endian: sum of all ROM bytes except these two

ROM size codes (WSTech; sizes in megabits): 2 = 4 Mbit, 3 = 8 Mbit, 4 = 16 Mbit, 6 = 32 Mbit, 8 = 64 Mbit, 9 = 128 Mbit (1, 5, 7 marked unknown). The emulators ignore this byte and use the file size.

Save type codes: 0x00 none; SRAM 0x01 to 0x05; EEPROM 0x10, 0x20, 0x50. The sources disagree on 0x01: Beetle WonderSwan gives 8 KiB (WSTech: 64 kbit), ares and Mesen2 give 32 KiB. Others agree: 0x02 32 KiB, 0x03 128 KiB, 0x04 256 KiB (WonderWitch), 0x05 512 KiB; EEPROM 0x10 = 128 bytes (1 kbit), 0x20 = 2 KiB (16 kbit), 0x50 = 1 KiB (8 kbit).

WonderWitch

The WonderWitch development cartridge is a 512 KiB flash image holding the FreyaBIOS: ares recognises it by size 0x80000, the text ELISA at 0x70000 and the footer bytes (publisher 0, game id 0, save format 4, mapper 1 at -10, -8, -5, -3).

Related

Platform:WonderSwan.

Code & repositories

  • https://github.com/SourMesen/Mesen2 @ b9fa69ddc6d0a331fb103fdb5eef6904305703c2 · license: GPL-3.0 (declared by the contributor; GitHub's detector did not recognize LICENSE)
    Multi-system emulator with debugger; Core/SMS (Sega mapper, Codemasters), Core/PCE (MPR banking, SF2 mapper, CD-ROM), Core/WS (cart footer parsing)
    Tested on: source read, not run: read the source, not built · checked 2026-10-18
  • https://github.com/libretro/beetle-wswan-libretro @ 4b01295838ea89e3f1355bbe4cb5cf98aa6108cd · license: GPL-2.0 (declared by the contributor; GitHub's detector did not recognize COPYING)
    Mednafen WonderSwan core with Dox's WSTech document (wstech24.txt) describing the ROM header and I/O ports
    Tested on: source read, not run: read the source, not built · checked 2026-10-18
  • https://github.com/ares-emulator/ares @ 9408cb43d4948fc3ea6e152a307a34348df3fe04 · license: ISC (declared by the contributor; GitHub's detector did not recognize LICENSE)
    Multi-system emulator; its cartridge loaders and databases show header layouts, mapper detection and save types.
    Tested on: source read, not run: source read, not run · checked 2026-10-18