
Contents:
- Hatari and EmuTOS
- What is EmuTOS
- EmuTOS usage
- EmuTOS compatibility
- Debugging issues with EmuTOS
- EmuTOS compatibility lists
  - Working free/shareware Atari ST demos and games
  - Non-working free/shareware GEM/mono Atari ST games
  - Working free/shareware Atari STE programs
  - "Almost" working color STE games
  - Working free/shareware Falcon demos, games and applications


Hatari and EmuTOS
=================

To run the emulator a TOS ROM image is needed.  EmuTOS, a free
implementation of TOS, is shipped with the official releases of
Hatari.

This tos.img ROM image is identical to the official binary package of
EmuTOS, which is available at the SourceForge website of EmuTOS.  For
downloading other versions or the source code of EmuTOS, please visit
the EmuTOS website.


What is EmuTOS
==============

EmuTOS is a single-user single-tasking operating system for the 32-bit
Atari computers and emulators.  It can be used as a replacement for
the TOS images typically needed today for using emulators and it is
also running on some real hardware, like the Atari Mega STE.  All the
source code is open and free, licensed under the GNU General Public
License (GPL).  A copy of the GNU GPL can be found in the gpl.txt
file.

EmuTOS has its home at SourceForge:
       http://sourceforge.net/projects/emutos


EmuTOS usage
============

There are various reasons for using EmuTOS instead of a real TOS ROM
image:

* Users who don't have Atari HW or other legal means to obtain the
  original Atari TOS ROMs (for all of the Hatari supported Atari
  versions: ST/STE/TT/Falcon), but would like to try out Hatari and
  see what kind of software Atari ST had.  EmuTOS gives them a way to
  test Hatari with free demos, games etc.

* Users who want to continue using Atari compatible operating systems
  and need a open source replacement of TOS for modifications. Beside
  EmuTOS they typically alse use FreeMiNT, XaAES and fVDI as operating
  system replacements/improvements.

* EmuTOS allows also using ACSI disk images with Hatari TT/Falcon
  emulation, whereas TOS 3 & 4 support only IDE and SCSI disks (which
  Hatari doesn't currently support).  Hard disk images are needed for
  running MiNT and some other programs.


EmuTOS compatibility
====================

Many commercial games and applications work fine with EmuTOS. This is
because games (like Bombjack, Nebulus, Oids, Super Hang-On, Turrican,
Xenon...) use directly the hardware which Hatari emulates just fine
and applications use the correct higher level APIs (AES/VDI) for which
EmuTOS has implementations.

EmuTOS AES support is somewhat buggy (mouse dragging and window &
dialog background drawing in larger 4-bit modes) and VDI support
is slowish. Anybody wanting proper AES/VDI support should install
replacement for these, either the free XaAES + fVDI, or the earlier
commercial solutions like NVDI.

Free games have the issue that they often use the Line-A functionality
which is not supported by EmuTOS[1] unlike AES/VDI.  This is partly a
problem with the tools that they've been done with (for example older
STOS and GFA basic version liked to use Line-A for graphics). There
are also many demos which use it for convenience.

[1] EmuTOS has some old partial implementations for some of the Line-A
    functionality, but these are so buggy that they aren't enabled in
    EmuTOS releases except for mouse on/off functionality.

Joystick doesn't work in some (STOS) games that access it through some
other means than XBIOS function Kbdvbase() or by hooking into the IKBD
interrupt vector.   They probably uses some unofficial system variables
which location depends on the TOS version.


Debugging issues with EmuTOS
============================

To debug problems with EmuTOS, you have to download its source code and
recompile it. Enable the MIDI debug output in the config.h header file,
then you can start Hatari with the "--midi /dev/stderr" option. You will
then see the EmuTOS debug output like calls to missing Line-A functions.

To debug EmuTOS panics, you need to compile EmuTOS and create a disassembly
of the ROM image.  You can then look up the program counter value given in
panic message from the disassembly to see where the crash happens.


EmuTOS compatibility lists
==========================

The compatibility lists below cater for users who don't have Atari HW
and therefore won't have (legal) version of commercial Atari software
and most likely lack motivation to investigate applications very
deeply (Linux offers better alternatives nowadays for most of that).
I.e. the list skips commercial software and concentrates on EmuTOS
compatibility of freely available games and demos.

Games that are considered good quality & fun, are marked with "*".
All the listed demos are quite OK. Most demos can be downloaded from
http://pouet.net/ .

First are listed ST demos and games, then STE demos, games and music
applications and last Falcon demos, games and (music) applications.


Working free/shareware Atari ST demos and games
-----------------------------------------------

There are so many freely available color games and demos that from
those only the ones found working with EmuTOS are listed. Often the
non-working ones "Panic" EmuTOS.

Demos:
- 4getful (by gwEm, 4KB intro)
- 4kker (by Checkpoint, 4KB intro)
- Anomaly (by MMJ-Prod)
- Breath (by Mystic Bytes)
- Darktrip (by Legend, doesn't work with >2MB of RAM)
- Dark Side of the Spoon (by ULM)
- Death of the Clock Cycles (by Aggression)
- Dimensio (by Condemned)
- Flashback (by Carebears)
- Frenchies (by Frenchies, 96KB intro)
- Hallucinations (by Reservoir Gods)
- Overdose (by Aggression)
- Paradise (Dune Design)
- Phaleon Gigademo
- Posh (by Checkpoint)
- Soundtracker (by Equinox)
- Sweety (by DHS)
- Two in One (by DHS)
- YmRockerz musicdisks such as Popstars etc.

Color games:
- Archon 4KB
- Alien Blockade
- Bellum*
- Bombs Away
- ChuChu Rocket*
- Clogged Up
- Crapman*
- Dave Munsie games (shareware)
- Entombed
- Flip'em* (4KB puzzle)
- Grav*
- Hackman II*
- Hang About (4KB mountain climbing)
- Haywire
- Hector*
- Jetpac
- Nibe 2
- Nova
- Pengy
- Punt II
- Rockfall*
- Robert in the Fire Factory
- Santafly
- Snowball Fight
- Spacewar
- Starball* (shareware)
- Sweeper
- Tankx*
- Teserae*
- Yak (4KB gridrunner)

GEM games:
- Ballerburg*
- Biglife*
- Daleks*
- DBWH
- Drachen
- Gem_mind
- Isola
- Kensington
- Mars (corewars)
- Megaroid*
- Mathmaze
- Nethack*
- Orb
- Pacman
- Shanghai
- ST Concentration*
- Sudoku*
- Thrust
- Worm farm
- Wator (slow)

Monochrome games:
- Balloons
- Delta patrol
- Eliza
- MiniGolf (GFA basic)*
- Monkey Business
- Mr Dash
- Punssi
- Pyro
- Qix
- Sbreak*
- Wallball
- Mandala

Text games:
- Advent (Colossal Cave)
- Hack
- Larn
- Omega


Non-working free/shareware GEM/mono Atari ST games
--------------------------------------------------

Although there are plenty of color demos and games, the number of
(even remotely fun) free GEM or monochrome games and demos is so low
that for those I list here non-working ones.  Unless otherwise stated,
the issues in them are assumed to be Line-A related (graphics don't
show because they use Line-A drawing functions etc).

GEM games:
- Awele
- Backgam
- Checkers
- Dte (mouse gets stuck)
- Emperor
- Fishes
- Fs
- Gemamigo*
- Gnuchess
- Invaders*
- Mines
- Othello
- Patience (dragging doesn't work)
- Risk (dragging doesn't work)*
- Robugs*
- Solitair
- Stello*
- Tricky yahoo
- Verrueck
- Yokon*

Mono games:
- Bounce
- Columns*
- Crystal Caves*
- Domino
- Fun Face
- Go UP (stops at hi-score)
- Lasermon
- Lokomotive
- MacPan*
- Midimaze (joystick doesn't work)*
- MineFeld
- Pipeline*
- Pling II
- Poolmono (mouse gets stuck)*
- Roll X
- Sherlock*
- Space war*


Working free/shareware Atari STE programs
-----------------------------------------

There are not that many freely available or even commercial programs
that would be STE specific (or even STE enhanced):
    http://atari-ste.anvil-soft.com/html/archivapps.htm

Missing blitter support in EmuTOS (XBios function etc) is an additional
reason why some programs/demos (such as Blittermania) don't work with it.
But following STE specific demos, games and apps work (mostly) fine
with EmuTOS.

Demos:
- 1st Step (by Tobe/Mjjprod)
- 20 years megademo (by DHS), display issues in some screens
- Again (by Paradox)
- Armada is dead (by Aggression)
- Azed/Jungle demo (by Atari)
- Beat Demo (by Frontline)
- Birdie (by Zeal)
- CD-player (by Light)
- Core Flakes (by New Core)
- Dynamite (by Unit 17)
- E605 (by Light)
- Extacy (by ICE), breaks at the end
- French Kiss (by DHS)
- Illusion (by Next)
- Gobi Toons (by Dune)
- Grimey (by Reservoir Gods)
- Kick my assembler (by Orion), start doesn't look right
- Madness (by Cream)
- Mathematica (by Aura)
- More or Less Zero (by DHS)
- Maxymizer compo 2006 (by gwem)
- Meshake (by Spice Boys)
- Mind Rewind (by Reservoir Gods)
- MovieSTE (by Tony Barker)
- New Year -94 Intro (by Extream)
- Pacemaker (by Paradox), stops at end-part
- Paracon 6 & 7 remindtros (by Paradox)
- Powerrise (by Light)
- Reanimation (by Syntax)
- Sinfull Sinuses (by Chronicle)
- STE slideshow (by DHS)
- STE Wars (by Tony Barker)
- Vision (by POV)

Color games:
- Alien Blast (demo)
- Battletris+
- Dynaplus*
- Frantick
- No Limit II (shareware pinball)
- Obsession* (demo of commercial pinball)
- Operation Garfield
- Pacman on E
- Power Up
- Skulls (shareware "minesweeper")
- Stardust* (tunnel sequence demo)
- STEtris
- STrEet Fighter II (incomplete)
- Stupid balloon game
- Substation* (demo)
- Tomtar
- Wolfenstein3D v0.8a (a bit unstable)

Music Applications:
- Blipp Blopper
- Desktracker
- MaxYMizer
- Octalyzer
- Paula
- Sirius Player

Most of the non-GEM ST tracker & chip music composer programs
work also with EmuTOS too (not just STe ones).


"Almost" working color STE games
--------------------------------

There are some STE games that would appear otherwise to work perfectly,
but some part of the graphics just don't show.  They are listed in case
someone, someday, starts to fix the EmuTOS line-A things (which I
think are preventing these from working properly).

- Atari Scene Card Battle (card images don't show)
- Blat (main graphics don't show)
- Breakdance (another scene game, game freezes when playing)
- Mr Boomer (all graphics don't show)
- Pooz (all graphics don't show)


Working free/shareware Falcon demos, games and applications
-----------------------------------------------------------

Missing Videl support in EmuTOS is probably the reason why many
of the demos and games get wrong video made and their graphics
look completely broken under EmuTOS.  Following Falcon only
demos, games and apps work (mostly) fine though.

Demos:
- Alive (by Fun Industries)
- Ascii (by Reservoir Gods)
- ATS (by DHS)
- Birdshow
- Blue & Flu 4k (by New Beat)
- Illusion 64 (by Paranoia)
- Game of Life 4k (by Aggression)
- Snowstorm (by Reservoir Gods)
- ZZ 9 Plural Z Alpha (by .tssc)

Games:
- Blum
- Columns by Deadheart (demo)*
- Corsair
- DB 4K
- Dry Egg (needs >4MB RAM)
- FalcTron
- Impulse (Breakout clone)*
- Lamemine (needs "dummy" DSP mode in Hatari)
- Madtris
- Radical Race (demo)*
- Rave (needs "dummy" DSP mode in Hatari)
- SBM v0.8 (Bomberman clone)*
- Spice (Defender clone)*
- Static
- Steinbruch
- Tank Blaster
- Toy Man
- Vertical Mayhem (Columns clone)*
- Willie's Adventure (preview)*

Mostly working applications:
- AceMidi demo (softsynth sounds needs DSP)
- FlaySID (sound needs DSP)
- Fractal Playground (parameter input doesn't work)
- Kronos (benchmark)
- Whip! (virtual light machine)

Almost working demos & games:
- Bugger, Bunion, SkyFall, Switch, Sworm games* by Resorvoir Gods:
  have issues with keyboard input in the main menus
- Heretic: screen is messed
- Nibe: screen is messed
- Virtual City (needs DSP): city is invisible with EmuTOS


	- Eero
