GTA3 Mission Assembler 0.2.1
---------------------------------

This is a project that was initially developed to help us figure out op codes,
but it has turned into a quite complete assembler which we think it will be 
possible for dedicated moders to create new missions with. As the program  name
implies it uses a rather assembler like source code format so it's not a tool 
for beginner programmers or people with a weak heart. Especially since there is
no complete language reference to the op codes so often you have to "guess" what
parameters are used for.

Anyway, first of there are a few things you need. This assembler, a copy of
Grand Theft Auto 3 (PC version). You also need CyQ's disassembler specially 
designed to disassemble the original main.scm file into the source format we can
use. (it can be found in the zip file dissc.zip) Remember to edit disscm.ini, 
and make sure it's destination directory exists before decompiling.

Another "must have" thing is gequinns GUI for this assembler, which can be 
downloaded at his homepage (http://members.lycos.co.uk/gequinn).

dElAvA has started to work on a referece for the op codes, not that he uses
an "old" format of the scm.ini so you might have to look up opcodes by number
rather than by name. His page can be found at:
http://www.ref3.gta.mendelsohn.de/mainscm_index.html 

If you are serious about mission writing and have any questions then you should
ask them in the forums at www.game-editing.net/forum/ but for the love of god,
no requests! And if you are really really serious about this then you should
send me an email at <dan@game-editing.net> and I'll hook you up with the IRC
info to the room where the "main.scm team" spends it's days :)


How to use it?
---------------------------------

There are a few things you must configure for the assembler to work. First open
the GTA3Asm.ini file and you should see something like this:

  [paths]
  ide=D:\Spel\GTAIII\data\default.ide
  op=D:\Dev\GTA3\scm_special.ini

ide= is the default ide file that you will find in your "gta3\data" directory,
it contains alot of different object definitions. The assembler needs this to 
determine which objects are global and which should be compiled into the 
main.scm file.

op= is the special ini file that we have created to hold information about all
the op codes. Their numeric value, their names and how many parameters they 
take.

Ok, done with that part. This is something that you only have to do the first 
time you download the assembler (unless you move some files, of course).


To assemble a main.scm file you pass a project file as the parameter to the
assembler. I.E "gta3asm.exe c:\my_main.txt". So let's make a sample project file 
shall we?

  [script]
  main_thread=D:\Dev\GTA3\Main\main.gsr
  output=D:\Spel\GTAIII\data\main.scm
  mission_dir=D:\Dev\GTA3\Main\
  
That's it. An ini-styled text file. main_thread points to the source file 
containing the main code for your project. output= is just where the assembled 
file will be saved. And mission_dir= is the directory that holds all the mission
thread files, preferably the same dir as you keep the main code but it's really 
up to you.


Language reference
---------------------------------

  %foo = Objects (Max 24 characters)

  "foo" = string, max 7 characters

  $foo = variable

  @foo = label (must be on it's own line) or label reference when passed as an 
  argument to an op code
  
  #mission <mission name>  compiler directive to include a mission in the scm

  &MISSIONNAME is used where you have to use the mission index as a parameter 
  to an opcode. I.E start_mission &INTRO

  fixed point values MUST have a decimal. Even if it's zero you have to have a 
  decimal. I.E .0 or 0.0

  !opcode = NOT opcode

  !0000-!000f local variables/thread parameters (only used in threads other 
  then main)

  !0010 and !0011 = timers

  ; comment
  

History
---------------------------------

  Version 0.2.1
  - Some people reported that parts of their assembled SCM's contained random
    data from the memory. This have been fixed now.

  Version 0.2.0
  - Fixed error when you had "," as the decimal separator in windows
  - A little more error checking.
  - 3 doubble variables was renamed. (for disscm).

  Version 0.1.9
  - First public release
  - Added support for &, objects, #
  - Cleaned up the project format.
  - About 50% faster than previous version

  Version 0.1.8
  - Unreleased

  Version 0.1.7
  - Can rebuild the original main.scm (using the source generated by CyQ's 
    dissasembler) 
  - Added support for relative jumps 
  - Fixed a bug that would skip op codes without parameters 
  - Some minor things 

  Version 0.1.6
  - Private beta release 
  - Removed case sensitivity for lables 
  - Should pick up bad opcodes (names only) better 
  - Some other crap 

  Version 0.1.5
  - Private beta release 
  
  Version 0.1.4
  - Private beta release

  
  
Credits
--------------------------------- 

Written by Dan Strandberg <dan@game-editing.net>
  
Thanks to gequinn and CyQ for help tracking down bugs and gequinn, CyQ, Xentor, 
dElAvA, charlieC, galax, CtlAltDel, The_Sphere, iidle and the rest of the 
main.scm team.
  
  
  www.game-editing.net
  www.game-editing.net/forum/


Happy modding!

Dan
September, Friday 13th 2002