Development environment

To create homebrew, the following components are necessary:

• the toolchain - a set of tools which allow compiling code for the platform of your choice, as well as libraries which provide commonly used functions; this is essential,
• an IDE - a tool which allows more efficient development of software by providing features such as code completion, code-aware searches and automated refactoring; this is not strictly necessary - many people have written code in Notepad - but can be very useful!
• an emulator - a software implementation of the hardware of the console, which allows testing homebrew software without the laborious process of re-flashing a physical cartridge. Some emulators also include a debugger, allowing tracing and inspection of the program's behaviour.

For the purposes of this guide, we'll be making use of the Wonderful toolchain, which you can install by following the guide at the provided link.

Note that this guide only installs the toolchain - as each supported target can consume hundreds of megabytes in disk space, they are not installed automatically. To install components necessary for WonderSwan development, you should run the following command once you're done installing the toolchain itself:

$ wf-pacman -S target-wswan

The Wonderful toolchain currently recommends using VSCodium (or another fork of VSCode) with the clangd plugin installed.

To install the clangd plugin in VSCodium:

1. Select the “Extensions” tab from the left-hand menu.
2. Type clangd into the search bar at the top.
3. Select the project extension named “clangd” provided by “llvm-vs-code-extensions”.
4. Press the “Install” button and follow any further instructions displayed by the IDE.

The best emulator for doing WonderSwan development is Mesen 2. It provides a fully-featured low-level debugger and high (if not perfect) emulation accuracy.

Other options include:

• Ares - high accuracy, but does not provide a debugger ¹⁾.
• wf-mednafen - medium accuracy, but *does* provide a debugger; a fork of Mednafen.

If you own a WonderSwan, you may wish to test your work on physical hardware. For this, you will require a way to run your own code on the device.

A flash cartridge allows the user to load their own code and run it on physical hardware. There aren't very many options available currently; it is my understanding that this should improve in the medium term.

The WS Flash Masta is a flash cartridge created by Flavor, providing fifteen slots of 64 megabits (8 megabytes) each for flashing your own code, as well as 512 kilobytes of save RAM.

Available for $120-$130 new when in stock, which is not very often.

InsideGadgets sells a compatible flash cartridge. These provide 64 megabits (8 megabytes) for code, 32 KB of save RAM ²⁾ .

Available for $54 new when in stock, though a new customer has to spend an additional $10 for the edge adapter and $30 for the USB flasher device, for a total of $94. If you happen to also be interested in GB/GBC/GBA homebrew, said flasher might be a good investment.

The WonderWitch is an official homebrew solution licensed by Bandai and developed by Qute Corporation. This cartridge provides 512 KB of NOR flash (384 KB user-accessible). However, it is not recommended for Wonderful toolchain development for three reasons.

First of all, it is very expensive on the second-hard market, with bare cartridges going for over $100 and complete boxed sets going for over $250 as of 2024. Remember that if you choose to purchase a bare cartridge, you will still need a serial port adapter to get data to and from the cartridge.

Second of all, the WonderWitch does not run bare WonderSwan ROM images; rather, it provides its own executable format and hardware abstraction libraries. While this is supported by Wonderful via the wwitch subtarget, it is less complete than the wswan subtarget, which is the focus of this guide.

Finally, there is no open source implementation of the Freya abstraction layer available; this means that WonderWitch-exclusive homebrew cannot be ran by non-WonderWitch owners without resorting to copyright infringement.

This is not a critique of the platform itself; it does feature a large library of freely available homebrew software from back in the day; it is a great option for a video game collector, for instance. However, nowadays, over 20 years after Bandai abandoned the device, there are more homebrew-friendly options available.

The MobileWonderGate web browser supports downloading and launching small homebrew binaries with the `application/wondergate` MIME type.

This option is more limited than the WonderWitch, with a small binary size limit - and you still need a serial port adapter. WonderGate cartridges can be found inexpensively at times, but recent developments have increased collector interest in them.

These options are no longer available for sale, but are nonetheless listed in case you run into them:

• WonderDog - available in 64 megabit (8MB), 32 megabit (4MB) and 4 megabit (512KB) variants.
• WonderMagic Color - the only unofficial flash cartridge for the system contemporary to its lifespan; very dated by today's standards. In case you run into one, a copy of the PC flashing software is archived here.

A serial port adapter allows the user to communicate with the WonderSwan using a PC. These are not necessary (unless you're working with the WonderWitch OS), but can make debugging and data transfer more convenient.

The ExtFriend is a firmware for the Raspberry Pi Pico (and other RP2040-based) board which acts as an USB serial port adapter for the WonderSwan. In addition, it allows USB digital audio capture of the WonderSwan's headphone output.

Unfortunately, no sellers of this device are currently known to exist - some DIY is required. For the adventurous, Japanese guide to using an HDMI breakout board is provided here.

The WonderWitch comes with an RS-232 serial port adapter.

The RetroOnyx USB Link Cable is a high-end modern solution, with custom-designed connectors instead of HDMI ports and an integrated USB-serial adapter. However, it does ask for $85 in return.