wonderfultoolchain / awesome-wsdev

A curated list of WonderSwan development resources.

Awesome WonderSwan Development

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

Contents

• Introduction
• Documentation
  • Datasheets
  • WonderSwan hardware
  • Other documentation
• Emulators
• Accuracy test ROMs
• Software development
  • Libraries
    • Music drivers
  • Tools
    • Graphics utilities
• Source code
  • Boilerplate
  • Demos
  • Games
  • Other programs
  • Miscellaneous
• WonderWitch
  • WW documentation
  • WW open-source homebrew
• Hardware development
  • Cartridges
  • 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. It is the last piece of hardware which the legendary Gunpei Yokoi had a hand in.

It is important to note that WonderWitch development is distinct from bare metal WonderSwan development. The former is specific to the WonderWitch - a special personal use development kit from Qute Corporation which came with its own hardware abstraction layer and toolchain, while the latter focuses on outputting self-contained WonderSwan software. As such, some of the tooling may not be applicable to WonderWitch developers.

Documentation

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.

WonderSwan hardware

• ws.nesdev.org wiki - the most recent and actively developed documentation source, the WSdev wiki!
• STSWS - contains some information not yet on the WSdev wiki.
• WSMan - older documentation source.
• Everything You Never Wanted to Know about the WonderSwan RTC
• Retail cartridges - cartridge logic analyzer and requirement documentation.

Other documentation

• splashbuilder readme - WonderSwan Color custom boot splash format.
• .WSR file format documentation (Japanese) - popular WonderSwan standalone/emulated music file format.

Emulators

Console

• ares (ISC)
• Mednafen (GPL-2.0) - supports WonderWitch and serial port emulation.
• NitroSwan - WonderSwan emulator for Nintendo DSi.
• StoicGoose (MIT) - C#-based WonderSwan emulator.
• WonderDroid Ultra (GPL-2.0) - Mednafen wrapper for Android phones.

Peripherals

• WonderFence (MIT) - MobileWonderGate internet adapter emulator.

Accuracy test ROMs

• WSCPUTest - V30MZ CPU behaviour
• WSHWTest - SoC interrupt/PPU timer handling
• WSTimingTest - V30MZ CPU timing
• ws-test-suite (MIT) - asie's 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

• MiracleMage (GPL-2.0) - limited high-level WonderWitch emulator.
• romwitch (GPL-2.0) - utility to replace executables on "static" WonderWitch software images.
• wonderwitchvc15 - example on using Visual C++ 1.5 for compiling WonderWitch binaries.

WW documentation

• Don Walizer Jr's tutorials (source code).
• wonder/doc/freya - initial Freya internals documentation.

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.

Hardware development

Cartridges

• Bandai2003 (MIT) - Verilog "2003" mapper implementation.
• mbc-unlock (CC0) - VHDL boot handshake implementation.
• nileswan (GPLv3) - Open-source flash cartridge.
• USB WonderSwan Cartridge Utility (MIT) - cartridge dumper and programmer.

Screen capture

• nisetro_wsc (MIT) - FPGA-based screen capture solution.
• swancolorHD - FPGA-based screen capture solution.

Other hardware development

• ExtFriend (GPL-3.0) - WonderSwan EXT<->USB adapter with digital audio capture.
• WonderSwan for MiSTer (GPL-2.0)
• wsheadphone (CC-BY-NC-SA-4.0) - Headphone DAC adapter.
• WSMtool (CC-BY-NC-SA-4.0) - A multitool adapter for the WonderSwan. Headphone, serial and link cable adapter in one.

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.