QTeM - QTM TrackerModule eMulator V5.02
----

QTeM is a module that translates most TrackerModule *commands and SWIs into their QTMModule equivalents. This is so that old games written for the TrackerModule can play their music through QTM instead.


Why would someone want to do this?
----------------------------------

As far as I know there are 3 main versions of the TrackerModule in circulation:
1. An old version, which will play music at the wrong speed on newer machines.
2. A new version, that plays music at the correct speed, but doesn't allow other sounds (e.g. sound effects in games) to play at the same time as the music.
3. An inbetween-y version. I don't know much about this version with respect to playing speed and sound effects, but I do know that it's StrongARM (and RiscPC?) incompatible, making it useless for most users.

As you can see there isn't a version that plays music at the correct speed, is StrongARM compatible, *and* allows the playing of sound effects over the music. This is where QTeM comes in, because unlike the TrackerModule, QTMModule supports all of the above.


Supported features
------------------

QTeM duplicates the TrackerModule in the following ways:
* It uses the same module name as the TrackerModule, allowing RMEnsure's to work
* It uses the same SWI base and SWI names, allowing TrackerModule SWI's to work
* It supports the same *commands as TrackerModule. These *commands appear to be the only interface many games use to play their music.

The base set of *commands was taken from TrackerModule 4.09. However some versions of the module have extra or different *commands; ones supported by QTeM are:
*PlayInit (from version 2.08 "With some additions by BANDiT of ARMageddon")
*PlayKill (from version 2.08 "With some additions by BANDiT of ARMageddon")
*SetPlayPos (from version 2.08 "With some additions by BANDiT of ARMageddon")


Unsupported features and caveats
--------------------------------

Not all SWIs will behave exactly as they should. Not all SWIs or *commands have been implemented. In particular, the following are unimplemented, and will return an error:

*PlayStatus
*PlaySamples
*PlaySpeed
*PlayStereo
Tracker_Stereo
Tracker_SoundInfo
Tracker_ReadSampleTable
Tracker_Lock
Tracker_Unlock
Tracker_MuteChannel
Tracker_RestoreChannel
Tracker_Speed
Tracker_WriteSampleTable
Tracker_TranslateVolume
Tracker_UpdateData
Tracker_WorkspacePtr
Tracker_RepeatState
Tracker_Sequence
Tracker_DecodeNote
Tracker_PatternInfo
Tracker_ReadState
Tracker_WriteState
Tracker_ReadHardwareAdr

These SWIs are fairly advanced, and are unlikely to be used in any games.

The module is also not 32bit compatible, since there are currently no 32bit compatible versions of QTM.


So, how do I use it?
--------------------

Just copy QTeM over the tracker module for your chosen game, and ensure you have a copy of QTMModule in your !System directory. You will need QTM version 1.22 or above for the transparent sound system to work (to allow you to hear sound effects over the music). You can get a copy from the QTM website at http://www.listen.to/qtm

Some games use Tracker formats that aren't supported by QTM, so you'll have to use a program such as !TrackConv to convert them. You can get a copy of !TrackConv from the QTM website. I'm not entirely sure what the best output
format is, but SoundTracker seems to do the job for the games I've tried.


Game compatibility
------------------

So far, the following games have been tested. The location of the trackermodule to replace has also been listed. Remember to keep backups of your original files, just in case there's some incompatibility that I've missed. Games that use different music modules to TrackerModule haven't been listed.

Game        Status           Notes
----        ------           -----
Cycloids    Incompatible     Game appears to use a compressed copy of
                             TrackerModule, along with compressed music files.
DinoSaw     Compatible       TrackerModule is !DinoSaw.Music.PlayerMod.
FRED     Compatible       TrackerModule is !FRED.Modules.Player_Mod. Music
                             requires conversion using TrackConv.
Fyarena     Compatible       TrackerModule is !Fyarena.PM. Music requires
                             conversion using TrackConv.
Hamsters    Compatible       TrackerModule is !Hamsters.Music.PlayerMod. Music
                             requires conversion using TrackConv.
Ixion       Compatible       TrackerModule is !Ixion.Code.PlayerMod. However the
                             game never appears to play music and sound effects
                             at the same time, so there's little point in using
                             QTeM.
Lemings     Compatible       TrackerModule is !Lemings.Musix.PlayerMOD
Splodge     Compatible       TrackerModule is !Splodge.PM. Music requires
(David Johnston)             conversion using TrackConv. The game has no sound
                             effects though, so there's little point using QTeM.
Staka       Compatible       TrackerModule is !Staka.!S/Tracker.PM. The game has
                             no sound effects though, so there's little point
                             in using QTeM.
Styx        Unrequired       There's a copy of Styx on www.acornarcade.com that
                             uses the QTMModule instead.
Wavelength  Semi-compatible  TrackerModule is !WaveLgth.Music.PlayerMod. Music
                             works fine, but no sound effects are heard. Perhaps
                             a game limitation?


The future
----------

There are a few other music modules that QTeM could be expanded to support, e.g. MusMod/TeqMod (as used by Krisalis), Coconizer, and StasisMod. These would most likely be done in the form of extra QTeM modules, one per module being emulated.

There is also the possibility of improving QTMModule to be 32bit compatible, and to use the SharedSound system. This is certainly something I'll be looking into, as well as how hard it would be to add support for extra file formats (To prevent the user from using TrackConv on some files).


History
-------

V5.02 - 21/3/08
 * Fixed *PlayPos and *SetPlayPos to work correctly. This fixes problems with games such as Hamsters that use *PlayPos to set control tracker files containing multiple looping songs.
V5.01 - 15/1/06
 * Improved 'Unimplemented QTeM operation' error messages to include *command name/SWI index
 * Implemented *PlayPos (Although it won't report the highest sequence number)
 * Implemented *PlayInit, *PlayKill, *SetPlayPos, as found in a TrackerModule version supplied in !FRED
V5.00 - 12/1/06
 * First version
 * Version number is 5.00 to account for the fact that TrackerModule versions go up to (at least) 4.09
 * Tried it with DinoSaw. It works!
 * Tried it with some other games. It didn't work!


Written by Jeffrey Lee, me@phlamethrower.co.uk
http://www.quote-egnufeb-quote-greaterthan-colon-hash-comma-underscore-at.info/