--------------------------------------------
WiiHandy/SDL v0.2 release README
--------------------------------------------

Ported by raz0red 
[http://www.twitchasylum.com]

--------------------------------------------
What is WiiHandy/SDL?
--------------------------------------------

Handy is software dedicated to emulating the Atari Lynx hardware on a standard
PC. The software was originally developed by Keith Wilkins [http://handy.sf.net]
and was released under the GPL on 14th April 2004. 

Handy/SDL is a port of the WIN32 sourcecode so that it can be used with the
GCC compiler and the Simple Directmedia Layer (SDL) library. The Handy/SDL port
was developed by the SDLEMU crew [http://sdlemu.ngemu.com].

WiiHandy/SDL is a port of the Handy/SDL sourcecode to the Wii developed by 
raz0red [http://www.twitchasylum.com].

--------------------------------------------
Installation
--------------------------------------------

To install WiiHandy/SDL, simply extract the zip file that this README was
distributed with directly to your SD card (retain the hierarchical structure
exactly). A lot of people had issues with v0.1 when they tried to rename
directories, or didn't properly create the roms directory. The easiest way
to avoid this is to simply copy the directories from the zip file as-is to 
your SD Card. 

For the emulator to work, you must provide it with the "Atari Lynx boot rom"
(lynxboot.img). This file must be obtained and placed in the WiiHandy/SDL 
"apps" directory (/apps/wiihandysdl).

Roms must be placed in the "roms" directory (/wiihandysdl/roms). Also, confirm
that the "saves" directory exists (/wiihandysdl/saves).

--------------------------------------------
Controls
--------------------------------------------

    Wiimote:
    
        Move      : Directional pad
        A         : 2
        B         : 1
        Option 1  : Plus
        Option 2  : Minus
        Pause     : A
        Exit      : Home
        Power     : Power off the Wii

    Classic controller:
    
        Move      : Directional pad
        A         : A
        B         : B
        Option 1  : Plus
        Option 2  : Minus
        Pause     : L/R
        Exit      : Home

--------------------------------------------
Snapshots
--------------------------------------------

WiiHandy/SDL now provides "snapshot" functionality. Snapshots allow for saving 
and resuming the state of games. Each game may only have a single snapshot 
associated with it (this is something that may change in subsequent versions).
All of the operations related to snapshots are exposed within the 
"Snapshot management" menu of the WiiHandy/SDL menu system. The menu contains 
the following items:

    Snapshot management menu:
    
        Auto load        : When a cartridge is loaded, the snapshot 
                           (if it exists) for the cartridge will be loaded. 
                           (enabled by default)
                     
        Auto save        : When a game is exited, a snapshot is automatically 
                           created (replacing any existing snapshot for the 
                           cartridge). (disabled by default)
                     
        Load snapshot    : When this item is selected, a list of existing 
                           "snapshots" is displayed. You can select one of the 
                           displayed snapshots to load the cartridge with 
                           the selected snapshot.
                                  
        Save snapshot    : This menu item is only visible if you have exited
                           a game while playing (via the Home button). 
                           Selecting this item will save the state of the 
                           current game to the snapshot associated with the 
                           game's cartridge (replacing any existing snapshot).     
        
        Delete snapshot  : This menu item is only visible if you have exited
                           a game while playing (via the Home button) and a
                           snapshot exists for the cartridge. Selecting this 
                           item will delete the snapshot associated with the
                           cartridge.

--------------------------------------------
Rotate screen (Auto) doesn't work
--------------------------------------------

A common complaint from the v0.1 release of WiiHandy/SDL was that the "Rotate
screen: (Auto)" option didn't do anything. 

This option is intended to work with Keith Wilkins' (the author of the original
Handy emulator) rotation utility. The following is quoted from his Handy 0.95
README file:

    "Handy now supports automatic rotation of images on startup via a flag in 
     the LNX header of the cartridge. This new addition is completely 
     compatible with any existing files. One of the spare bytes in the header 
     is now used to indicate whether which way the screen image should be 
     rotated. A utility has been provided (ROTATE.EXE) to allow you to patch 
     any existing files you may have."
     
You can obtain Keith's rotate utility via the Handy Sourceforge project 
[http://sourceforge.net/projects/handy/].

To make things (a bit) simpler, I added the ability to patch cartridges via
WiiHandy/SDL. The somewhat complex process to do this is as follows:

    1.) Load the cartridge that is to have its rotation settings changed via 
        "Load cartridge".
        
    2.) Once loaded, exit the game (Home button).
    
    3.) Select the rotation settings that you want for the cartridge via the
        "Rotate screen" menu item. Choose "None", "Left", or "Right". Do not
        choose "(Auto)".
        
    4.) Now, enter the "Advanced" sub-menu and select the "Write rotation 
        (cartridge header)" option. Again, if you selected "(Auto)" for the 
        "Rotate screen" option, this menu item will not be visible. 
        
        If all goes well, you should see a message stating that the cartridge's 
        header was written successfully.
        
    5.) At this point, you can set the rotation settings back to "(Auto)". 
        When the cartridge is subsequently loaded, it will use the rotation 
        settings found in its header.
        
There are a couple of caveats that need to be mentioned about writing rotation
settings to a cartridge header. First, none of the above tools (via Keith's 
Windows executable or WiiHandy/SDL's advanced menu) support .zip files (I may
fix this in the future).

Second, any existing snapshots associated with the cartridge will no longer 
work. This is due to the fact that changing the cartridge's header changes its
CRC. Existing snapshot loading will fail as they perform CRC checks to ensure 
they are being loaded for the appropriate cartridge. Any snapshots created
after the header has been changed will work as expected.    

--------------------------------------------
WiiHandy/SDL crashes, code dumps, etc.
--------------------------------------------

While v0.1 of WiiHandy/SDL seemed to work well for the majority of people, 
some were experiencing code dumps and various other issues. While it isn't 
clear why these issues were occurring, it does seem that some of them may be 
the result of differences in Wii firmware and IOS versions. WiiHandy/SDL has
been tested with Wii firmware versions 3.2 and 3.4 (IOS36). 

If you are having issues with WiiHandy/SDL, please let me know about it via
one of the following locations:

[http://www.wiibrew.org/wiki/Talk:WiiHandy/SDL]
[http://www.twitchasylum.com/forum/viewtopic.php?t=510]

I would really like to resolve these issues, and it would be great to work 
along with the people who are experiencing them to get them resolved.

--------------------------------------------
Special Thanks
--------------------------------------------

DJ Dynamite  : Testing 
yossi        : Testing
Wilsoff      : For the cool new icon

--------------------------------------------
Change Log
--------------------------------------------

01/28/09 (0.2)
--------------
    - Save/restore game snapshots
    - Resuming a game (after quitting with Home)
    - Resetting a game (after quitting with Home)
    - Fixed a bug causing homebrew games to crash on load (Lode Runner, etc.)
    - Fixed a bug where games would freeze if left idle for about an hour   
    - Fixed a bug where games would not load after file error
    - Fixed minor glitches in frame rate (reworked game loop)
    - Ability to rotate controls w/ game screen
    - Ability to patch Lynx ROMs w/ rotation settings (not supported for .zip)
    - Advanced menu allowing for enabling debug mode, frame rate adjustments
    - Auto-chain detection
    - Reset/power functions (via Wii and Wiimote)
    - Ability to use a custom directory name for application files    

01/18/09 (0.1)
--------------
    - Initial version
    - Sound support
    - Wiimote/Classic controller support
