
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 TT specific demos
  - 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 the emulators and it is
also running on some real hardware, like the Atari Mega STE and Atari
ColdFire.  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 the original
TOS ROM images:

* 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 the Atari machines had.  EmuTOS gives
  them a legal 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.

* This includes users of new "Atari" machines like Atari ColdFire project,
  which isn't 100% compatible at HW level to the original Atari machines:
	http://acp.atari.org/

* EmuTOS also allows using ACSI disk images with Hatari TT/Falcon
  emulation, whereas TOS 3 & 4 support only IDE and SCSI disks.
  Hard disk images are needed mainly for running MiNT.


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

These comments apply to EmuTOS v0.8.5.

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 clicks and dragging
doesn't always work properly) 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 old 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
other means than XBIOS function Kbdvbase() or by hooking into the IKBD
interrupt vector.  They probably use some unofficial system variables
which location depends on the TOS version.


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

To debug problems with EmuTOS, you have to recompile it from source
after enabling the MIDI debug output in its config.h header file. Then
start Hatari with the "--midi-out /dev/stderr" optio and you will see
the EmuTOS debug output such as calls to missing Line-A functions.

To inspect EmuTOS issues with the Hatari debugger, you'll need symbols
for the EmuTOS image you're using.  If you've compiled EmuTOS with
AHCC[2], you can get suitable symbols with its "-n" linker flag, or
you can use a script coming with Hatari (ahcc-symbols-convert.sh) to
convert AHCC *.map file to "nm" format supported by the Hatari
debugger.

After loading the symbols to the debugger, disassembling the problematic
address should provide more clues for the problem.  Or you can just look
up the program counter value given in panic message from the AHCC
emutos.map file.

Hatari profiling support (see patches on hatari-devel) can be used to
debug OS freezes.  If EmuTOS gets stuck, just profile it for a while
and then ask debugger for a profile that tells where it's looping and
then disasm that part with symbols directly in Hatari.

[2] AHCC: http://members.chello.nl/h.robbers/


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)
- Outline 2008 invite (by DHS)
- Outline 2010 invite (by Checkpoint)
- Overdose (by Aggression)
- Paradise (by Dune Design)
- Phaleon Gigademo
- Posh (by Checkpoint)
- Rebirth (by MMJ production)
- Save The Earth (by Defence Force)
- Soundtracker (by Equinox)
- Sweety (by DHS)
- Tut! (by Wildfire)
- Two in One (by DHS)
- YmRockerz musicdisks such as Popstars etc.
- Xmas2000 (by Paranoid)

Color games:
- Archon 4KB
- Alien Blockade
- Bellum*
- Bombs Away
- ChuChu Rocket* (Lite version for STFM)
- 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:
- 4 Gewinnt* (Connect four)
- Abalone
- Ballerburg* (bug: mouse-over acts like click)
- Biglife*
- Chess* (works only from floppy)
- Clicks*
- Daleks*
- Dame
- DBWH
- Drachen
- Gem_mind
- Gnuchess
- Isola
- Kensington
- Mars (corewars)
- Mathmaze
- Megaroid*
- Mines*
- Nethack*
- Orb
- Pacman
- Shanghai
- Snake
- Stello*
- ST Concentration*
- Solitair*
- Sudoku*
- Tartan* (chess)
- Thrust
- Tricky yahoo
- Worm farm
- Wator (slow)
- zSudoku

Monochrome games:
- Balloons
- Bounce
- Delta patrol
- Emperor (v1.0 & v1.5)
- Fun Face (playable demo)
- Go UP
- HASCS
- Lasermon (bug: some lines are not drawn)
- MiniGolf* (GFA basic)
- Monkey Business
- Mr Dash
- Poolmono*
- Punssi
- Pyro
- Qix
- Sbreak* (by Mark Overmars)
- Wallball
- Mandala

Text games:
- Advent (Colossal Cave)
- Eliza
- 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 (menus close immediately after opening)
- Checkers
- Dte (mouse gets stuck)
- Fs (panic)
- Gemamigo* (panic or double bus error)
- Invaders* (shots go through buildings/shields)
- Othello
- Patience* (dragging doesn't work, arrowheads drawn wrong)
- Risk* (dragging doesn't work)
- Verrueck (?)
- Yukon* (dragging doesn't work)

Games that mix GEM UI and non-VDI drawing:
- Backgam
- Fishes
- Robugs*

Mono games:
- Columns* (keyboard input issues)
- Crystal Caves*
- Domino
- Lokomotive
- MacPan*
- Midimaze* (joystick doesn't work)
- MineFeld
- Pipeline*
- Pling II
- 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/MJJ Prod)
- 20 years megademo (by Atari scene collective), issues in some screens
- 20 years Atari STE megademo (by Paradox), some screen don't work
- Again (by Paradox)
- Armada is dead (by Aggression)
- Azed/Jungle demo (by Atari)
- Beat Demo (by Frontline)
- Birdie (by Zeal)
- CD-player (by Light)
- Cernit Trandafir (by DHS)
- Core Flakes (by New Core)
- Dynamite (by Unit 17)
- E605 (by Light)
- Ecstacy A (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)
- Realtime (by MJJ Prod)
- Sinfull Sinuses (by Chronicle)
- STE slideshow (by DHS)
- STE Wars (by Tony Barker)
- Sommarhack (by DHS)
- Vision (by POV)
- XiTEC Presentation (by Omega)

Color games:
- Alien Blast (demo)
- Battletris+
- ChuChu Rocket* (full version)
- Dynaplus*
- Frantick
- No Limit II (shareware pinball)
- Obsession* (demo of commercial pinball)
- Operation Garfield
- Pacman on E
- Power Up
- Skulls (shareware "minesweeper")
- Spy 4k
- 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 TT specific demos
-------------------------

- 256mbrot, Glasstro, Orion-B, Yabt (TT/Falcon intros by ray//.tSCc)
- 4getful (by gwEm, 4KB intro TT-version)
- Adebug 3DTT demo (by Brainstorm)
- TT highres slideshow (by .tSCc)
- XiTEC presentation (by Omega)


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

Missing Videl and DSP 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:
- A Rh Positive 4k (by tSSc)
- Alive (by Fun Industries)
- Ascii (by Reservoir Gods)
- ATS (by DHS)
- Birdshow
- Blue & Flu 4k (by New Beat)
- DBA Magazine 14 intro (by Lazer)
- Illusion 64 (by Paranoia)
- Game of Life 4k (by Aggression)
- Snowstorm (by Reservoir Gods)
- Terrorize Your Soul (by tSSc)
  - fonts and colors aren't right on all screens
- ZZ 9 Plural Z Alpha (by tSSc)

Games:
- Aces High (preview)
- Blum
- Columns by Deadheart (demo)*
- Corsair
- DB 4K
- Dry Egg (needs >4MB RAM)
- FalcTron
- Heretic (lower part of screen flickers, I think EmuTOS screen is too high)
- Impulse (Breakout clone)*
- Lamemine (needs "dummy" DSP mode in Hatari)
- Madtris
- Running*
- 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)*

Utilities:
- Cecile hard disk (image) driver

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, doesn't get input
    or input freezes the game
- Motion (unfinished demo by Aggression)
  - only writer screens work
- Nibe:
  - screen is messed, I suspect EmuTOS is missing resolution change function
- Virtual City (needs DSP): city is invisible with EmuTOS


	- Eero
