Awesome WonderSwan Development

A curated list of awesome WonderSwan/WonderSwan Color development resources and tools. Inspired by the awesome list.

Contents

• Introduction
  • Getting started
• Documentation
  • Datasheets
  • Other documentation
• Emulators
  • Peripheral emulators
  • Test ROMs
• Software development
  • Libraries
    • Music drivers
  • Tools
    • Graphics utilities
• Source code
  • Boilerplate
  • Demos
  • Games
  • Other programs
  • Miscellaneous
• WonderWitch
  • WW tools
  • WW documentation
  • WW open-source homebrew
• Open source hardware
  • Cartridges
  • Peripherals
  • Screen capture
  • Other hardware development
• Historical

Introduction

The Bandai WonderSwan is a handheld game console released and supported by Bandai from 1999 to 2003 in Japan, with later follow-ups in the form of the 2000 WonderSwan Color and 2002 SwanCrystal. It is the last piece of hardware with design input from the legendary Gunpei Yokoi, as well as Asuka Langley's handheld of choice.

While this list focuses on "bare metal" WonderSwan development (cartridge ROM as output), note that there exists an official homebrew SDK for the console called the WonderWitch created by Qute Corporation, which requires different targetting (custom .fx file format, FreyaBIOS hardware abstraction layer, FreyaOS libraries, more restrictive IRAM/SRAM layout). Tools and examples for the WonderWitch are present in their own section; however, many other entries (such as hardware documentation or graphics converters) are applicable to both environments.

Getting started

For native WonderSwan development, I personally recommend the following sources:

• Wonderful Toolchain Wiki - documentation for the open-source WonderSwan/WonderWitch homebrew toolchain,
• WSdev Wiki - hardware documentation.

For native WonderSwan and WonderWitch development alike, you may find a serial port adapter useful. The ConsoleMods Wiki provides a list of both purchaseable adapters and DIY building projects.

Documentation

• WSdev Wiki - the most recent and actively developed documentation source, hosted by nesdev.org.
• STSWS - contains some information not yet on the WSdev wiki.
• WSMan - older documentation source.

Datasheets

NEC V30MZ CPU

The NEC V30MZ is an 80186-compatible CPU for low-power platforms with an efficient pipeline design. It should not be confused with the NEC V20/V30 line of CPUs, which provide additional opcodes and features on top of the 8086 architecture.

For a variety of reasons, NEC's documentation (and some WonderSwan documentation) uses unique NEC opcode names, while other sources and assemblers typically use Intel opcode names. A translation map between the two is available as part of STSWS.

• NEC V30MZ Preliminary User's Manual

Other

• Seiko S-3511A - cartridge RTC.
• Fujitsu MBM29DL400TC - WonderWitch NOR flash.

Other documentation

• Everything You Never Wanted to Know about the WonderSwan RTC
• Retail cartridges - cartridge logic analyzer and requirement documentation.
• splashbuilder readme - WonderSwan Color custom boot splash format.
• .WSR file format documentation (Japanese) - popular WonderSwan standalone/emulated music file format.

Emulators

• Mesen 2 (GPL-3.0) - high accuracy, extensive built-in debugger and profiler, recommended for development.
• ares (ISC) - high accuracy.
• Mednafen (GPL-2.0) - serial port emulation, built-in debugger.
  • BizHawk - WonderSwan core based on Mednafen, features Lua scripting and rewind/movie support.
  • wf-mednafen - fork of Mednafen with emulation fixes and debugger UI/UX improvements, based on mednafenPceDev's work.
  • WonderDroid Ultra - fork of Mednafen, Android port.
• NitroSwan - WonderSwan emulator for Nintendo DS/DSi, user friendly WonderWitch support.
  • SwanGBA - GBA version of the above, does not run at full speed.
• StoicGoose (MIT) - C# WonderSwan emulator.
• Oswan (GPL-2.0) - legacy WonderSwan emulator with a built-in debugger.

Peripheral emulators

These emulators are currently only supported by Mednafen by editing its wswan.excomm configuration option.

• WonderFence (MIT) - MobileWonderGate internet adapter emulator.

Test ROMs

• WSCPUTest - V30MZ CPU behaviour
• WSHWTest - SoC interrupt/PPU timer handling
• WSTimingTest - V30MZ CPU timing
• ws-test-suite (MIT) - assorted hardware tests and testing tools
• rtctest - "2003 mapper + S-3511" RTC protocol and behaviour
• Robert Peip's test ROMs - sprite priority/window testing tool

Software development

• Wonderful - gcc-ia16 based C/ASM toolchain for WonderSwan and WonderWitch.
• owswan - OpenWatcom-based WonderSwan toolchain.
• Kyoui - (mirror) tools for compiling WonderSwan binaries using OpenWatcom.
• WSLink (MIT) - NASM linker outputting WonderSwan and WonderWitch compatible binaries.

Libraries

• libws (zlib) - hardware abstraction functions
• libwsx (zlib) - decompressors and other useful functions
• LZSS decompression routine (public domain)

Music drivers

• WonderSwan Total Sound Driver

Tools

• Dekadence WonderSwan Tools (MIT) - assorted Python scripts.
• splashbuilder (BSD-3-Clause) - toolchain for creating custom WonderSwan Color boot splashes.

Graphics utilities

• SuperFamiconv (MIT) - tile/map converter with flexible palette/optimization options and mostly-complete WS/WSC support.
• bmp2swan - simple bitmap converter.

Source code

Boilerplate

• Wonderful template - GCC/GAS-based template.
• wonder/template - NASM-based template.

Demos

• #wonderwitch IRC channel promo (MIT)
• Bad Apple!! for WSwan (MIT)
• HBlank Cylinder Effect

Games

• Inufuto's games - written using a custom C-like toolchain.
• SwanDriving (Mono) - tech demo written with NASM.
• WonderSnake (GPL-3.0) - Snake game written with Borland TASM.

Other programs

• 144p Test Suite for WS (GPL-3.0) - 240p Test Suite-inspired user-side testing tool
• BootFriend (GPL-3.0) - WonderSwan custom "firmware"/splash screen patch - XMODEM software load to RAM and more!
• CartFriend (GPL-3.0) - WonderSwan cartridge menu/launcher
• Chips1 (MIT) - CHIP-8/SuperCHIP emulator.
• ieepview (MIT) - internal EEPROM viewer/editor.
• ws-backup-tool (GPL-3.0) - cartridge backup/restore/flash tool and IPL dumper for BootFriend.
• wsmonitor (MIT) - 80186 debug monitor.

Miscellaneous

• vgmswan (MIT/zlib) - .VGM playback and conversion tools.

WonderWitch

• wonderwitchvc15 - example of using Visual C++ 1.5 for compiling WonderWitch binaries.

WW tools

• MiracleMage (GPL-2.0) - high-level WonderWitch emulator, only supports "mono" software, does not require a WonderWitch ROM.
• romwitch (GPL-2.0) - utility to inject executables into "static" WonderWitch software ROMs.

WW documentation

• Don Walizer Jr's tutorials (source code).
• Wonder Witch Technical Manual
• WSdev Wiki - also contains a WonderWitch section.
• wonder/doc/freya

WW open-source homebrew

• dumpipl (MIT) - WS/WSC initial program loader dumping tool (as "Soft" image).
• HummingCat (MIT) - work-in-progress sound driver.
• vgmwitch (MIT) - SN76489 music player.
• WWTerm (GPL-2.0) - terminal emulator.
• yoppa (BSD-3-Clause) - WWGP 2001 game.

Open source hardware

Cartridges

• Bandai2003 (MIT) - Verilog "2003" mapper implementation.
• mbc-unlock (CC0) - VHDL boot handshake implementation.
• nileswan (GPLv3) - open-source flash cartridge.

Peripherals

• ExtFriend (GPL-3.0) - WonderSwan EXT<->USB adapter with digital audio capture.
• wsheadphone (CC-BY-NC-SA-4.0) - headphone DAC adapter.
• WS-LinkC (CC-BY-NC-SA-4.0) - cheap, DIY-friendly link cable alternative.
• WSMtool (CC-BY-NC-SA-4.0) - multitool adapter for the WonderSwan; headphone, serial and link cable adapter in one.

Screen capture

• nisetro_wsc (MIT) - FPGA-based screen capture solution.
• swancolorHD (GPL-3.0) - FPGA-based screen capture solution.
  • swantroller (GPL-3.0) - WonderSwan Color-based controller PCB for the swancolorHD.

Other hardware development

• USB WonderSwan Cartridge Utility (MIT) - cartridge dumper and programmer.
• WonderSwan for MiSTer (GPL-2.0)

Historical

These are links to files and sources which are noteworthy from a historical perspective, but have been superseded.

• WSTech 2.4 - outdated document, incorrect in places.