+-Version 0.60 +Version 0.80
-project initiator and main developer of Hatari: Thomas Huth <thothy@users.sourceforge.net>
-manual by Matthias Arndt <marndt@asmsoftware.de>
+Project initiator and main developer of Hatari: Thomas Huth
+
+Manual written by: Matthias Arndt
-Hatari on the WWW: http://hatari.sourceforge.net/ +Hatari on the WWW: http://hatari.sourceforge.net/
-Hatari is an Atari ST emulator for Linux, FreeBSD, BeOS and other Systems which are supported by the SDL library. -See Appendix B for details on emulation in general. +The emulator is open source software and is distributed under the terms of the +GNU General Public License (GPL). +
+The Atari ST was a 16/32 bit computer system which was first released by Atari -in 1985. Using the Motorola 68000 CPU, it was quite a popular computer having -quite a lot of CPU power at that time. +in 1985. Using the Motorola 68000 CPU, it was a very popular computer having +quite a lot of CPU power at that time. See Appendix B for details on emulation +in general.
-Hatari started as an adaption of the free -WinSTon source code -to Linux (WinSTon is a ST emulator for Windows). -But since WinSTon's CPU core was written in i86 assembler, it was not possible -to use it for Hatari as Hatari is intended to be platform independent. -So the CPU core of UAE -was used for Hatari instead, because this CPU core has been written in -portable C and also has some nice features like 68040 and FPU support. +Unlike many other Atari ST emulators which try to give you a good +environment for running GEM applications, Hatari tries to emulate the hardware +of a ST as close as possible so that it is able to run most of the old ST games +and demos. Of course you can run normal GEM applications with Hatari, too.
-At the time of this writing there is neither a complete MMU emulation -nor support for STE specific features. +nor support for TT or Falcon specific features.
-Hatari currently has the following system requirements:
+Certain versions of Hatari have successfully been tested by various people on +the following systems: +
First, you need the SDL library, you can get it at: http://www.libsdl.org/. Most distributions already ship a suitable version. @@ -183,7 +263,9 @@ If all works fine, you'll get the executable hatari in the src/ subdirectory.
-Then you'll have to copy a TOS ROM to the data directory (the data directory is specified in the configuration file Makefile.cnf) and @@ -191,25 +273,26 @@ rename it to t --tos command line option to tell Hatari where to find a TOS ROM. Hatari needs a TOS ROM image because this contains the operating system -of the emulated Atari. Sorry, it is not possible to ship an image with -the Hatari package since these images are still copyrighted. But you -can -easily create an image with a real ST and one of those various -ROM-image programs for the ST. Or search the internet, but don't ask -the Hatari team -where to find one. -
-Another solution is EmuTOS, which is an open-source -TOS clone. You can find EmuTOS at: http://emutos.sourceforge.net/. -It's -not the best solution for playing games or running other old software -due to compatibility issues, but it's free and officially compatible -with Hatari!
+of the emulated Atari. +Sorry, it is not possible to ship an original ROM +image with the Hatari package since these images are still copyrighted. +But you can easily create an image with a real ST and one of those various +ROM-image programs for the ST (search for "TOSDUMP" with your +favourite internet search engine). If your old ST does not work anymore, you +can also try to search the internet directly for corresponding TOS ROM image, +but don't ask the Hatari team where to get one.
+Another solution is EmuTOS, which is also shipped with the official +release versions of Hatari. EmuTOS is an open-source TOS clone. You can find +it at: +http://emutos.sourceforge.net/. +It is not the best solution for playing games or running other old software +due to compatibility issues, but it's free and compatible with Hatari.
If you do not specify a TOS image on the commandline nor can Hatari find a suitable TOS image in the default dir, you'll get the chance to select a TOS image file from the GUI.
-Type make install as root to do a systemwide installation. In this case it is recommended to set the DATADIR variable in Makefile.cnf to a proper value. /usr/local/share/hatari @@ -219,7 +302,9 @@ anywhere.
When you finally have got a TOS image, try starting Hatari with the option --help to find out more about its command line parameters.
-Now type hatari to run the emulator for the first time. If all goes well, you should now be presented with a window showing you the @@ -228,7 +313,9 @@ little green desktop of the Atari ST. Pr to turn on the GUI to configure Hatari to suit your needs, press F11 to toggle windowed and fullscreen mode.
-Hatari ofcourse understands several command line options.
Type hatari --help to list them all.
@@ -297,7 +384,7 @@ games and demos work)Once you've started Hatari succesfully, you can use the emulator as an allmost complete Atari ST computer system.
-Press F12 to enter the GUI. Navigate it with the mouse. The GUI is rather self explanatory.
+ +
+From the main menu, you can reach the other setup dialogs by clicking on +the appropriate buttons.
+ +You can load the current settings from a configuration file by clicking +on the button and you can save the +current settings to a configuration file with the button.
+Click to go back to the emulated -ST. All checked options will be applied.
+ST. All changed options will be applied.Check the option if you want -the emulated ST to perform a soft reset. This should be equal to -pressing the reset button on your ST. +the emulated ST to perform a cold reset. This is equal to +switching the power off and on again on a real ST.
Click to terminate Hatari and return to the host OS.
Click to abandon any changes -made.
-Check the CPU type to use here, enable prefetch mode and if the -Blitter should be active.
-For best Atari ST compatibility choose plain 68000 here.
-The Timer-D patch changes the Timer-D initialization from TOS. TOS -uses Timer-D as a baudrate generator for RS232. -The TOS default slows the emulation down so the patch gives you a -faster emulation. -
-You can disable the Timer-D patch if games or demos require the -original TOS setting.
+that you have made. + +
+Select the CPU type to use here. For best Atari ST compatibility choose a + plain 68000.
+Choose whether you want to emulate a normal ST or an STE. + Note: STE emulation is very incomplete. It may not work very well.
+For STE emulation a STE compatible TOS image, e.q. version 1.06, 1.62 or 2.x, is strongly recommended.
+Select the CPU clock you want to use. 8Mhz is ST standard and the most + compatible, 16MHz is for Mega STE emulation.
+With the "Slower but more compatible CPU" option, you can enable + the emulation of 68k address errors and the CPU prefetch buffer. This is needed + for best compatibility, but it slows down emulation a little bit so you can + disable it if you don't need it.
+You can also enable/disable Blitter emulation here. The Blitter is a custom + chip that accelerates some graphical operations. This switch only toggles the + Blitter in plain ST mode. In STE mode, the Blitter is always enabled (since all + STEs have been sold with a Blitter chip).
+If you enable the "Real time clock emulation" switch, a RTC will + be emulated based on the time of the host computer. Note that you need at least + TOS 1.02 for proper RTC emulation, TOS 1.00 does not support this.
+The Timer-D patch changes the Timer-D initialization from TOS. TOS uses + the MFP timer D as a baudrate generator for RS232. However, the TOS default + value slows down the emulation. The patch gives you a better performance. + It is normally save to enable the patch, but if you encounter a program that + does not work, you can try to disable the patch to see if it works then.
+Select if you want to use slow FDC emulation. Slow is more compatible esp. + with games and demos that use custom loaders.
NOTE: These parameters are very sensitive to the emulated ST and it is strongly recommended to reset the emulated ST after changing these options.
-
+Use the upper dialog to choose which floppy disks should be emulated in the disk drives.
+You can use most standard Atari ST disk image files. See the chapter "Floppy disk images" for details.
Click on the button next to the A: and B: option to go to the fileselector. You may select and browse zipped disk images as well.
+ ++The fileselector looks like this: +
+ +
+Click on to eject a disk image from the emulated drive. The emulated ST will act as if had no floppy disk in its drive.
@@ -418,6 +565,8 @@ with .st or .msa.Hatari can currently create plain .ST and .MSA disk images exclusively.
+You can choose if you want Hatari to writeprotect your disks. Atari ST virii can spread on disk images too so it is ok to +enable the write protection option. However you can't save highscores or games to your disk images then.
Use the lower dialog to change the harddisk settings.
You can select a harddrive image for harddrive emulation via image file here or you may select @@ -427,7 +576,13 @@ harddrive.
on the harddrive. This option is checked by default if you specify a harddrive image or a directory via the command line. -
+You can select the amount of RAM for the emulated ST here. Only amounts that were valid on a real unmodified STFM can be selected.
Note: This option is critical and you are strongly advised @@ -443,30 +598,64 @@ restored.
different versions of Hatari. E.q. if you compile a newer Hatari, you cannot load your old memory snapshots back. -
+Here you can select the TOS image to use. Click on to select it via the fileselector.
+ class="button">Browse to select it via the fileselector. You can also select an optional cartridge image to use. Click on to select one via the fileselector. Keep -in mind that any custom cartridge image will not work together with -GEMDOS harddisc emulation or the VDI extended resolution emulation + class="button">Browse to select one via the fileselector. Click on to disconnect the custom cartridge image. + +Keep in mind that any custom cartridge image will not work together with
+GEMDOS hard disk emulation or the VDI extended resolution emulation
since some additional driver code will be used in the cartridge memory
space for these emulations.
Note: These options are critical and you are strongly advised to reset the emulated ST when changing one of these option.
-Here you can select which joystick you want to emulate via the -cursor keys.
+ +
+In this dialog, you can configure the emulated joysticks. +With the upper two arrows, you can choose the joystick which you want to +configure.
Joystick 1 is the normal ST joystick port and 99.9% of all ST games -use this port, Joystick 0 -emulates a joystick plugged into the ST mouse port allowing you to play -2 player games.
-If no joystick is checked here, joystick emulation is done via a -connected PC joystick.
-See the chapter "Emulated Joystick" for details.
+use this port. +Joystick 0 emulates a joystick plugged into the ST mouse port +and is often used in games for two players. +With STE joypad A and B, you can enable the emulation of Jaguar joypads +which are plugged in the enhanced joystick ports of the Atari STE. +Only very few STE games support these joypads, so you often won't need this.
+Finally, Hatari also emulates joysticks which were plugged on the parallel +port with a special adapter on a real ST. These were used in some few +multi-player games like "Gauntlet 2".
+For each ST joystick, choose whether you want to disable it, +use the keyboard for emulation or use a real PC joystick.
+For keyboard emulation, you can select the keys by pressing the + button. You will be prompted to press +the keys for up, down, left, right and fire.
+If you want to use a real PC joystick for the emulation, you should connect +it to your PC before you start Hatari. Then you can choose the joystick with +the two lower arrows.
+Check the "Enable autofire" option if you are too lazy to pound +on the fire button in shoot'em-up games. However, this option only works with +certain games. In some other games, it gets worse if you enable this option.
+See also the chapter "Emulated Joystick" for details.
+ +
+Here you control the video output of the emulated ST.
Check "Fullscreen" to run Hatari fullscreen, default is windowed.
Check "Interleaved mode" if you wish to have that old TV feeling in @@ -504,16 +693,37 @@ screenshot in .BMP format to the current screenshots. You can opt to only record new movie frames when the screen content really changed.
-Here you can select the keyboard mapping to use.
-Two different mappings called "Symbolic" and "Scancode" are -predefined.
-You can also load a custom keymapping file here if you wish. Please -note that selecting to use a custom keyboard mapping will -use the "symbolic" mapping for all keys not defined by your map file. -See the supplied example mapfile on how to build your -own keyboard mapping.
-
+Here you can select the keyboard mapping to use. Two different mappings + called "Symbolic" and "Scancode" are predefined.
+"Symbolic" tries to map the symbolic values of your PC keys + to the ST keys. It should be working pretty good on all systems as long + as your keyboard layout looks close to the standard english keyboard + layout. However, you might experience some problems with special keys like + brackets etc.
+"Scancode" uses the scancode values of your PC keys for keyboard + mapping. This only works on certain architectures like Linux where the + scancodes are similar to the ST scancodes (e.g. it does not work on Mac OS X). + If it works on your system, this often gives better results than the symbolic + mapping. Note that you also need a TOS version with the right language + (e.g. use a French TOS if you are using a French keyboard).
+You can also load a custom keyboard mapping file here if you wish. Please + note that the custom keyboard mapping will use the "symbolic" mapping + for all keys that are not defined by your map file. Have a look at the supplied + example mapfile to see how to create your own keyboard mapping.
+ +
+Here you can control the sound subsystem.
Check if you want emulated sound at all. Emulation is faster if sound emulation is turned off.
@@ -523,9 +733,16 @@ Medium quality will work ok in most caseYou can select to record a piece of sound here. Check which format to use and click the button. It is a toggle button so you will need to return to the GUI to switch sound recording off again.
-Check here if you want to enable experimental printer support. See the chapter "Emulated printer" for details.
+ +
+As Hatari currently only supports printing to file, click on to select the file to print to. You can enter a new filename as well.
@@ -552,7 +769,9 @@ MIDI device file for output.NOTE: RS232 and MIDI emulation are very experimental, too. Don't enable them unless you really need them!
-While the emulator is running, you can activate or toggle various features via the following keyboard shortcuts.
| enable/disable sound recording | |||
| F11 | +ALTGR+f or F11 | toggles fullscreen and windowed mode | |
| F12 | -
- activate the GUI -You may need to hold SHIFT down -while in windowed mode. - |
+ ALTGR+o or F12 | +activate the GUI |
| PAUSE | -will go to the debugger if it was activated at -compile time | +will go to the debugger if Hatari was started with + the -D option |
All other keys on the keyboard act as the normal Atari ST keys so pressing SPACE on your PC will result in an emulated press of the SPACE key on the ST. The following keys have special meanings:
@@ -662,16 +879,17 @@ key on the ST. The following keys have s -ALTGR will act as ALTERNATE as well as -long as you do not press it -together with a Hatari hotkey combination.
-The right CTRL key is used as the fire -button of the emulated -joystick when you turn on joystick emulation via keyboard.
-The cursor keys will act as the cursor keys on the Atari ST as long -as joystick emulation -via keyboard has been turned off.
-The right CTRL key is used by default as the +fire button of the emulated joystick when you turn on joystick emulation +via keyboard.
+The cursor keys will be used by default as the emulated ST joystick, +unless you are using joystick emulation via a real joystick or have disabled +joystick emulation completely. Then the cursor keys will act as the cursor +keys of the emulated Atari ST, of course.
+ +For obvious reasons your PC mouse will act as the emulated Atari ST mouse. In fullscreen mode it will act as expected, directly controlling the ST mouse pointer.
@@ -681,7 +899,9 @@ the Hatari window. Do this by pressing t hotkey combination. Press it again to go back to normal mouse behaviour which allows you to work in other X11 windows while Hatari is up and running. -The Atari ST joysticks are emulated ofcourse allowing you to play your favourite games with Hatari.
The default mode is to use a connected PC joystick. You can use any @@ -703,7 +923,9 @@ as the joystick directions, the right CT firebutton. You can still use the cursor keys as the ST's cursorkeys in this mode as long as you press SHIFT along with the cursorkeys.
-Hatari by default only handles ST modes, ST-LOW, ST-MED and ST-HIGH.
Overscan effects and socalled "Border Removal" are possible too.
Due to the fact that these effects are achieved by using quirks and @@ -719,7 +941,9 @@ GEM-compliant applications and they are into your Mega ST.
Make sure to disable extended VDI modes for playing games as 99% of all ST games will not be able to make use of higher resolutions.
-Due to the fact that printer handling is very different between Unix style machines and the Atari ST, emulation of the printer is achieved by writing all printer output to a file.
@@ -737,7 +961,9 @@ you may set up a GDOS printer with a Pos Atari and set your printer device file as Hatari's printer output.Serial communications in Hatari is designed to directly use a serial port on your PC.
Communications parameters are set automatically upon the settings of @@ -745,7 +971,9 @@ the emulated ST. This means all you do i the communication parameters like baudrate from your ST communications software. Hatari will do the rest and handle the serial input and output for you.
-Hatari does not use floppy disks directly but disk images due to differences between the floppy disk controllers of the ST and the PC. Three types of disk images are currently supported: The raw "ST" type, @@ -813,7 +1041,9 @@ net as long as the archive contains a di so your highscores and savegames are lost if you load the game from such a zipped disk image.
-Hatari supports two ways of emulating a ST hard drive: The low-level ACSI hard disk emulation and a GEMDOS based drive emulation.
To use the ACSI hard disk emulation, you need a hard disk image file @@ -846,8 +1076,11 @@ GEMDOS drive emulation.
the emulated Atari since it is not possible to switch the hard disk while the emulator is running.May the fun without the price to be with you ;-) !
-This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -857,16 +1090,19 @@ option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General -Public -License for more details.
-You should have received a copy of the GNU General Public License -along with this program; if not, write to Free Software Foundation, -Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+Public License for more details. ++You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software Foundation, +Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA +
The GNU Project and the Free Software Foundation | The GNU General Public License
-Emulation via software is an art and Hatari is an example of this.
Emulation is to make a computer behave like a (probably) completely different machine on the lowest possible niveau. @@ -901,10 +1137,17 @@ emulation of the various custom chips an parts of the emulated system is much trickier.
-This is a little compilation of what Atari software does work in Hatari. It is by no means finished.
+First is listed software (games, demos and applications) that work +on normal STs, after them is listed STE only software that has been +tested with the current STE hardware emulation.
+ +| Wings Of Death | yes | - | + | works in STE mode too |
| Toki | @@ -1036,7 +1279,7 @@ Hatari. It is by no means finished.
| Does not work with cartridge / HD emulation | +|||
| Virtual Escape (by Equinox) | +yes | ++ | + |
| Posh (by Checkpoint) | +yes | ++ | + |
| Flipo (by Oxygene) | +yes | ++ | + |
| Syntax Terror (by DeltaForce) | +yes | ++ | + |
| Sweety (by DHS) | +yes | ++ | Does not work with HD emulation | +
| B.I.G-demo (musicdemo by Exceptions) | +partially | ++ | Flickers and colors in 3 of the screens don't look right | +
| SoWatt (by CareBears) | +partially | ++ | Colors and scrolling in the main menu are broken | +
| Punish your machine | +partially | ++ | Colors and scrolling in the main menu are broken | +
| Froggies over the Fence Oh no more Froggies |
+ No | ++ | Stop when the main menu loads | +
| Working | Comment | +||
| Programming | +|||
| DevPac 2.2 | yes | @@ -1097,7 +1397,7 @@ Hatari. It is by no means finished.||
| Turbo Assembler | yes | -+ | Due to a bug you need to have a proper disk image inserted into drive A. Works otherwise! |
| GFABASIC 3.6TT | @@ -1111,6 +1411,19 @@ compiling.|||
| Orcs Resource editor | +yes | ++ | |
| Graphics | +|||
| Mgif | +yes | ++ | |
| Neochrome | yes | rasters sometimes unstable | @@ -1122,50 +1435,436 @@ compiling. with disk images|
| Speed Of Light | +yes | ++ | |
| Sound | +|||
| SidSound Designer | +yes | ++ | |
| MusicMon 2 | +yes | ++ | |
| Protracker | +yes | ++ | |
| Accompanist (Henry Cosh Sequencer) |
+ yes | +Program works, but couldn't get Hatari midi output to work | +|
| Sequencer One | +yes | +Program and sample sounds work, but couldn't get Hatari midi + output to work | +|
| Cubase Lite | +yes | +Program works, but couldn't get Hatari midi output to work | +|
| Text Editors | +|||
| Tempus | yes | ||
| Sagrotan | +Qed editor | yes | |
| SidSound Designer | +Everest editor | yes | |
| Business applications | +|||
| MusicMon 2 | +Opus spreadsheet | yes | |
| Protracker | +SBase database | +yes | ++ |
| Communications | +|||
| CAB browser | yes | ||
| Teradesk | +Kivi QWK Reader | yes | |
| Desktops | +|||
| Qed | +Teradesk desktop | yes | |
| Everest | +Thing desktop | yes | |
| Others | +|||
| Speed Of Light | +ST-Guide | +yes | ++ |
| Sagrotan viruskiller | +yes | ++ | |
First are some STE games that do work with the STE features +in Hatari. Most of these games work only on STE, but here are also some +games which work (or have a version that works) also on ST, i.e. they +are just STE enhanced. These are marked with '*'.
+| Title | +Working | +Sound | +Comment | +
| Alien Blast | +yes | ++ | + |
| Astrodia* | +yes | ++ | Blitter support doesn't work with EmuTOS, only real STE TOS | +
| Battletris+ | +yes | ++ | + |
| Blat! | +yes | ++ | + |
| Bombaman | +yes | ++ | + |
| Breakdance | +yes | ++ | THE ultimate scene game | +
| ChuChu Rocket | +yes | ++ | needs to be run from disk image | +
| Dynabusters+ | +yes | ++ | + |
| H.E.R.O. 2 | +yes | ++ | Requires 4MB RAM | +
| Manga Puzzle | +yes | ++ | + |
| Penta* | +yes | ++ | Blitter, DMA audio and STE fadings do work properly | +
| No Limit II | +yes | ++ | + |
| Obsession | +yes | ++ | opens top & bottom border, but part from the right is not visible on screen | +
| Operation Garfield | +yes | ++ | + |
| Pacman on E | +yes | ++ | + |
| Power Up* | +yes | ++ | Problems with music, but DMA sound effects work | +
| Roger | +partially | ++ | Blitter timings inaccurate - game is too fast, + needs to be run from disk image | +
| Skulls | +yes | ++ | part from the right border is not visible on screen | +
| Starball* | +yes | ++ | + |
| Stardust | +yes | ++ | + |
| Stupid Balloon game | +yes | ++ | + |
| Substation | +yes | ++ | + |
| TomTar | +yes | ++ | + |
| Utopos | +partially | ++ | screen corrupted | +
| Ultimate Arena | yes | + | |
| Wolfenstein 3D* | +yes | ++ | STE DMA sound does work | +
| Zool | +partially | ++ | screen corrupted, scrolling fails | +
Some tested STE demos and intros
+| Title | +Working | +Sound | +Comment | +
| Aggression: Braindamage | +yes | ++ | Colors in the last 2 screens don't look right | +
| Armada: Armada is Dead | +yes | ++ | bottom border broken | +
| DHS: Tyranny & Massacre | +yes | ++ | + |
| GGN: Alive | +yes | ++ | + |
| Ice: Extacy | +yes | ++ | + |
| Imagina: 1992 X-mas demo | +yes | ++ | flickers without frameskip | +
| MJJ-Prod: 1st Step | +yes | ++ | + |
| New Core: Beyond Deadline | +yes | ++ | + |
| Omega: Grotesque | +yes | ++ | + |
| Paradox: X-mas 1994 demo | +yes | ++ | + |
| Reservoir Gods: Mind Rewind | +yes | ++ | opens all borders | +
| Reservoir Gods: Grimey | +yes | ++ | + |
| Syntax: Reanimation | +yes | ++ | + |
| MJJ-Prod: Tribute To Rainbow Tos | +partially | ++ | screen corrupted, Blittermania does not work but the code does not crash nor lockup | +
| Armada: RGBRuler demo | +partially | ++ | doesn't look right | +
| New Core: Core Flakes | +partially | ++ | doesn't look right | +
| Percy of Light: VGA slideshow | +partially | ++ | doesn't look right | +
Finally some tested STE applications
+| Title | +Working | +Sound | +Comment | +
| Octalyzer | +yes | ++ | part from the right is not visible on screen | +
| Protracker STE | +yes | ++ | garbage at screen bottom, 50KHz replay duff | +