====== WonderWitch FAQ ======

===== Users =====

==== What is the WonderWitch? ====

The WonderWitch is a personal software development kit developed by Qute Corporation for the WonderSwan and released in July 2000. It allowed users to create and publish their own independent WonderWitch-compatible games and applications.

==== What items do I need to use a WonderWitch? ====

These items are necessary to use the WonderWitch environment:

  * A WonderSwan console.
  * A WonderWitch cartridge. All cartridges are identical hardware-wise, no matter if they come from a retail box, a Player box, or loose.
  * A serial port cable. If you didn't receive one with the cartridge, you can build your own or buy a compatible cable online - see below.

These items are useful, but not mandatory, to use the WonderWitch environment:

  * A WonderWitch CD. Some proprietary files are contained on it which cannot be found online; this is of particular value if your goal is to develop, rather than only use, WonderWitch software. While open source toolchains for the WonderWitch exist, they are not as complete as the official kit and don't yet have as good documentation.

Note that a PDF copy of the WonderWitch manual is provided on the CD, so you don't need to own it physically to have all the included material.

==== Where can I acquire a PC serial port adapter for the WonderSwan? ====

  * The easiest and cheaper way to acquire a serial port adapter is to build one.
    * [[https://github.com/WonderfulToolchain/ws-extfriend|ExtFriend]] is an implementation of the serial port adapter for the Raspberry Pi Pico, allowing one to be built for under 20 USD using an HDMI connector in place of the official EXT connector. [[https://x.com/peca_port0/status/1631569109912817667|Port Zero]] wrote a tutorial on how to do so (in Japanese).
  * [[https://www.retroonyx.com/product-page/wonderswan-usb-link-cable|RetroOnyx]] sells ready-built USB link cables for 85 USD each.
 
==== My WonderWitch cartridge's version of FreyaOS is outdated. Where can I download the latest version? ====

If you own a licensed WonderWitch cartridge, you may download the FreyaOS 1.2.0 update package on [[http://wonderwitch.qute.co.jp/index_wwp.html|Qute's WonderWitch Player website]]. While the site is intended for WonderWitch Player owners only, this file also was available for registered WonderWitch owners via an FTP server; however, that server is no longer online.
==== Some games depend on external IL libraries like sound.il. Where can I download them? ====

Typically, these libraries were available on the WonderWitch and WonderWitch Player CD-ROMs, as well as on the WonderWitch registered user portal. While permission has been granted to redistribute some of them as part of games, many older releases do not include these libraries. Links to online copies of commonly required libraries are provided below:

  * sound.il (1.02): [[http://wwgp.qute.co.jp/2002/entry/00058/rave/sound102.il]]
  * bmpsaver.il (2.01): This library is used for development purposes only, but some games may accidentally depend on it. While the binary is not available online, source code can be used to compile it and is provided here [[http://wwgp.qute.co.jp/2001/entry/00152/BMPSaverWWGP]]. Note that the latest version of the library is 2.03.

===== Developers =====

==== What programming languages are supported by WonderWitch? ====

Officially, assembly and C are supported for direct compliation; however, the community has enabled the use of other programming languages, like (old) C++ for direct compilation (via Turbo C++) or BASIC for interpretation (via WonBe).

==== Which compilers can be used with WonderWitch? ====

The following compilers had official libraries provided for them by Qute Corporation on the WonderWitch CD:

  * LSI C-86 3.5.12 for WonderWitch - developed by LSI JAPAN CO., LTD; bundled on the CD, the default and most popular choice. Note that the WonderWitch package only comes with **non-commercial** use rights for this compiler. Back in the day, it was possible to purchase commercial use rights for WonderWitch separately, but this is no longer possible, and the compiler itself is also no longer available commercially.
  * Turbo C 2.01 - developed by Borland International, Inc.; bundled on the CD.
  * Digital Mars C++ - later versions of the CD came with start-up and build files for this compiler.

The following compilers were adapted for the community for use with Qute Corporation's official WonderWitch libraries:

  * Turbo C++ 1.01, which was offered by Borland as a free download under the "antique/museum" program. It is compatible with Qute's Turbo C libraries, while also offering proper DS != SS support with the ''-ms!'' compile flag and ''_ss'' pointer address space.
  * [[https://github.com/autumn009/wonderwitchvc15|Visual C++ 1.5]]

The following compilers can be used with unofficial, community-made libraries:

  * [[https://wonderful.asie.pl/wiki/doku.php?id=wswan:index|GCC 6.3.0 / Wonderful]]

==== Can any 8086 compiler be used with WonderWitch? ====

No. To support the WonderWitch architecture, a compiler must:

  - not assume that **DS == SS** (under Freya, the data and stack segments are placed in different locations - data in SRAM, stack in IRAM). This is not a very common combination, as typically DOS applications used the same segment for near data and stack contents;
  - support arbitrary **CS** (code segment) locations without relying on relocation - this, in practice, usually prohibits use of far code memory models.

The typical memory model used for WonderWitch software is **small** with the **DS != SS** assumption. It may also be possible, in some cases, to adapt **compact** memory model compilers.