This is intented for people with some 68000 assembler knowledge, Atari ST(E), TT, Falcon, TOS knowledge.
There is people interested about subject, so I will try my best to explain things and make it less hard - because it is not easy for sure. Will start from simplest case :  singleparted game, which uses not TOS calls.

  The goal is to make adaptation (some call it patch) of game, originally distributed on floppy(es) , which will run from regular Atari format hard disk (or some Flash card), on any regular TOS version, and any Atari ST(E), Falcon, TT .  Additionally, we want gamestate saving option at any moment during gameplay - what means that can continue at point where saved, by few mouse clicks. Plus simple exit from game to Desktop. Of course, some trainer options may be added.

   What is HAGA ?
HAGA is just abbrev. of  'hard disk gaming  Atari' .  In fact it is special file, containing  functions requred for our goal, described above. So, there is HW test function, which detects machine type, RAM size , TOS version . Function to set RAM usage, function for reading/writing from/to hard disk - what is intended to replace game's floppy access. And more ...
Basically, it is same concept as Amiga WHDLoad. HAGA would be master, and launcher would be slave. Difference is that HAGA is completely free and source of it will be published soon - after some cleaning of source file and solving multiple pexec calls. What is not in VHDLoad  is usage of PMMU of 68030 for faster disk access, and so called GOS - TOS 1.04 in RAM for TOS calling games. And statesaves . TOS 1.04 in RAM solves TOS compatibility problems, and more important: RAM usage problems, etc.

 Requred SW, Tools:
You need some assembler, of course. Source files are made for Devpac 3, so best that you get it. May work in some other too, but I don't know, and will not make versions for other assemblers. Devpac 3 assembles correctly 68030 PMMU instructions for instance, what is not case by most assemblers.  
Steem Debugger is a must - to analyse game code, to do tests.
For high-color screens displayed before game start you need to prepare BMP format pic. with some SW. I use Paint Shop Pro 9.  Format is unpacked BMP, 320x228-273 px. 16 million colors. And need BMP 320x240 , 256 colors for Falcon, TT .
SW for converting in HST format is supplied (thanx to Cyg for making it so good).
Packer into C3 format is included.

For start, simplest case: singleparted game. Template is for game Botics. You need to correct some things for your game. Most of it is easy. What is hard is to find place in game code, which reads keyboard pressings, to add exit to Desktop and savestate.
I do it in Steem Debugger by setting monitoring of read from address $FFFC02 - when game runs . Then press / on NumPad - Steem Debugger (SD in further text) will stop, with code $66 readen from IKBD. Press OK, and will stop again with code $E6. We need later, because it is for released key / . That prevents some possible problems.  In game code after that come usually some tests, necessary to filter mouse, joystick and keyboard commands. Of course, we need keyboard command, so to put branch little later. Usually there is something like :  cmpi.b #$F6,d0 ; bcc  label . Keypress code is always below $F6, so after that we may put jmp to gamex label. It may be short absolute jump if we can place our code in low 32KB of RAM. Of course, what is overwritten with that jump must be executed at exit of our gamex code - see source code.
Codes are not ASCI codes, but Atari's keyboard scan codes.
When everything is done, you need to test it - first in SD, of course. If it is OK, it will 99% work well on some ST, STE.

  Work on Falcon, TT:
This is hard part, and if you don't have those machines for testing, can not be sure will it work or not. Most common problem is stackframe, what is different by 68030. Fortunatelly, there is modded version of SD to catch such errors. But other errors are possible, and they may be timer and other related - pretty hard to determine and fix.
For TT, which has much faster CPU, what can not set to lower clock slowdown may be needed with some games to be playable.  More about later ..

Template for singleparted games, not using TOS calls, with some tools:  Download  SP_LA
It includes launcher source template SPNOG.S (Botics) , OVSSH.S - put in include DIR of Devpac 3.   higheSTcolor17.exe - converter from BMP to HST format (Windows),  do.bat is for easier usage of converter.  STPACKER.exe (Windows) for packing into C3 format - on ST it would be very slow.


Second template, for singleparted game, using TOS calls, with regular TOS relocatible executable.
By such games we use TOS 1.04 part without AES, modded for our purposes, and running in high RAM. Still no disk access after start.
I just finished adapt. of game Conqueror , and it is good as template and for learning some things:
Conqueror has actually 2 TOS executables - first is intro, second is game self. Intro runs game executable via pexec function, and part of intro remains in RAM during play too. Only thing what it does then is checking copy protection. As I removed it, no need to keep any part of intro in RAM when game part starts, so can use special way to run game from same RAM location as intro - see in source COLA.S .  Because that, we can consider this as singleparted.  However, some tricks were needed to make it work - to avoid delete of packed data, what is loaded in low 512KB - by pexec.  I lowered Phystop to $40000 before running GOS (TOS 1.04 in RAM). There is no enough space in 1MB machines to load 220KB data in upper 512KB, because there goes TOS save, GOS, HAGA . Better solution would be to use start with fastload flag on, but it is not set in current HAGA version.

After solving protection removal we have 2 executables - intro and main game - and main can run without intro part in RAM. Need to pack both with C3 packer.
 For TOS executables we need  2 launchers :  first is for starting from regular Desktop, and is very similar to launcher for non-TOS games,.  Second launcher is regular TOS executable, what virtually AUTO starts in GOS, and in lower RAM area than possible without GOS - address is normally $AB52  . In second launcher we depack game's executable(s), again to same location.  All code can be placed in, by AUTO run wasted space between $611C and $A84E . Only Dungeon Master uses that space from games I examined (and it is not low count) . 
In Conqueror own code is used to read keyboard, so again need to examine it with SD (see above). But GOS has support for intercepting key pressings - if it goes in game via TOS - then it is really easy to solve Desktop exit and statesaves. Hopefully in next template (example) we will deal with such game.
Download SP_GOS


One more template with singleparted game, with Hi-Score load/save on hard disk :
Game is Yolanda, which does not use TOS calls, except few XBIOS calls by loading. It loads in 6 sections, but can be singleparted, because after last load no more disk access while playing.  Only disk access then is highscore save to floppy.
Of course, we want it on hard disk. So, need to perform some jumps on proper locations to our code, which will do it on hard disk, + loading from hard disk during start. See source.  May see how copy protection is fooled  too.
Download SP_HIS


Template for multiparted game, using TOS calls, with regular file load via Trap #1 functions:
Game is Pixie & Dixie - it uses regular TOS executable, and there are some 75 data files with total size about 550KB - and most is ICE packed. Game works with 512KB RAM. So, it must load some files during play. This concrete title is not copy protected, and could be fixed for hard disk run by simple editing of executable, by removing all  'a:'  before filenames with dir. But we want statesaves too, so will use HAGA and GOS . Launcher is very similar to singleparted, using TOS calls. Difference is in GOS launcher file - there are filesystem functions for RAMdisk, like open file, read bytes from file, close file, and related. Why we need RAMdisk ? Because of HAGA concept, which uses installed hard disk driver. It is located somewhere in low RAM, about location $10000 . But that space is space where most of games runs too. So, we perform RAM swap between game and TOS with installed hard disk driver when some disk access is needed. It is little slow, so to avoid slow work with lot of files, file chunks, we use RAM as some kind of cache, RAMdisk. Even with 1MB machines we can have 200KB allocated for that purpose. If RAMdisk is larger than it, we use it as read-ahead cache.  So, we need to make RAMdisk with all files, which may loading during game. In zip is short proggy, which will create it. You need to copy all files in freshly created DIR, if possible in order how they will read in game, and as last copy file ZZ.TOS . Then run it, and will get file FSRD which contain CAT of filenames and ther locations in RAMdisk, and RAMdisk self. Need to cut 2 parts from.
 In this concrete case we have actually 3 sections, as there are 3 subdirectories on floppy, but joined in one file. May see in source how code accessing proper section by looking first letter, what is first letter of DIR containing files. By most of games no separated subdirectories. There are some simplifications in compare to real FAT16 filesystem. Only 8 characters of filename are considered, without extension - because we have no same ones. If there are same filenames, with different extension, need code which compares whole filename + extension.
Only 1 file handle is used, because no more than 1 file opened at once. Otherwise need code which stores file position for each opened file.
And considering statesaves and exit to Desktop, all you need to do is to put 1 for label gxIkbg in file PIXHA1.TOS .Then it will use GOS keyboard code for them.   If default keys  / and * are not OK for game, or your taste, may change them at part:
   IFNE   gxIkbg
    move.w    #$E6E5,$6130.w
   ENDC
Need to enter scancodes for released keys (scancode + $80).
Download MP_GOS
And this is category (type) of Atari ST game, what is most used, with some smaller variations, of course. Instead TOS relocatible executable may be executable for concrete RAM address, and it is usually pretty low set - like $CC00 - what means that you can not run such games from hard disk just like that, because game will destroy hard disk driver. This is why we need GOS and HAGA.

Template for multiparted game, not using TOS calls, with custom, direct FDC access code:
Game is The Untouchables - and it is good example - it is on 3 floppies, so need to find game's floppy change/detection code and serving data from proper floppy image, without need that user do anything about it. 
The hard part with custom floppy access code is to find and understand floppy reading rutine. It will be certainly hard without experience, but no other way . Usually, there is some subrutine, which reads from floppy area to destination RAM location, which gets parameters in CPU registers, or in some memory block. In this case in a0 is destination address,  d0 holds sector count for load, d1 holds start sector (it starts by 1 on floppies)   and  d2 holds track # . Because floppies are with 10 sectors/track we need to multiply d2 with $1400, adding  (SS-1)*$200  etc ... Because with 1MB machines no enough space to hold whole floppy image (400KB), we use read-ahead cache, what loads currently needed data from hard disk into cache if it is not in RAM. If there is some file longer than cache size, it must be loaded directly from hard disk - but that's not much present.
  In case of Untouchables we have additional problem - every level is with own code, so we need to find keyboard reading in all of them, and insert link in all.
  There is a lot of things to correct, and many links. And it is not all what I did - some corrections were inserted directly in floppy images - like changing level skip key combinations, then removing writings to Video freq. register in all levels, otherwise will lose video on TT and Falcon.
Download MP_DFA


With this, I covered most present Atari ST game types. Dealing with copy protections is topic for self, I will not go in this, at least not without some demand. Using cracks as base for hard disk adaptations may seem as good idea, but I avoid it. The reasons are: there are many bad, incomplete cracks around. Then, it is often easier to understand original's code than cracker's, then there are diverse packing systems, usually slow depacking, so need to repack, what is another complication, etc. Removing copy protection with Steem Debugger is not so hard as it is on real HW, and there is a lot of STX images available. There is SW for converting STX to ST format - if floppy is with regulat sectors. Then copy protection data is of course lost in most of cases, but we lose it for sure, as running from hard drive. ST image is good for our purpose - and it means less work than extracting all files separately.
If game has some unusual floppy format - like trackwise data, without sectors, or special sectors then is best to use game's floppy code to make image.



    PP , Oktober  2013.


  Questions, suggestions please in e-mail or in forum(s) .

Send mail with suggestions, questions, critic etc. to site maintainer: Before it enter name of animal on small picture:

Menu Properties Quick Reference