A.SCI, the first Assembler for the Sierra Creative Interpreter




IMPORTANT NOTE:
___________________________
This is not a compiler; basically, it's a disassembler with
an assembler to reverse the process, which allows for minor changes.





OVERVIEW OF THE TOOLS
___________________________

kernels.pre:
Default Kernel call names for SCI 1.1 (16-bit) games. See below.

rdkernel.exe:
Extracts Kernel call names from SIERRA.EXE to standard output.

scasm11.exe:
Assembler for SCI 1.1 (16-bit) scripts (SCH+SCS -> HEP+SCR).

scasm20.exe:
Assembler for SCI 2.x (32-bit) scripts (SCH+SCS -> HEP+SCR).

scdasm11.exe:
Disassembler for SCI 1.1 (16-bit) scripts (HEP+SCR -> SCH+SCS).

scdasm20.exe:
Disassembler for SCI 2.x (32-bit) scripts (HEP+SCR -> SCH+SCS).


The heap sources are saved in a separate source file because I found
that this makes it easier for me to find my way through it, and because
it's easier for the assembler to handle as well. It pays off having a
text editor that can open multiple files, I guess... :)

Old SCI0 and SCI1 games, where heap and code are combined, are not supported.




USAGE
_______________________

Before you can use these programs to modify a game, you should create
some initialization files:

- Copy the game's RESOURCE files to a work directory.

- For 32-bit games, copy the game's SIERRA.EXE to that directory as
well. Execute "RDKERNEL > KERNELS.INI" to create an initialization file
with kernel call names. This is not necessary for 16-bit games, as they
usually store these in 999.voc --- if they don't, SCDASM11 will output
"kernels.ini not found". In this case (and ONLY then), rename
KERNELS.PRE to KERNELS.INI.

- Disassemble scripts 0 ("SCDASM11 0"/"SCDASM20 0") and (64-)994
("SCDASM11 994"/"SCDASM20 64994"). For both 0.scs and 994.scs, look at
which global variables are set up to contain pointers to objects. I.e.:

lofsa LongSong
sag global099

Edit the file GLOBALS.INI (which will be created upon first execution of
the disassembler) to reflect these object names, so that when you
disassemble a game script, "lag global099" is automatically disassembled
as "lag LongSong", making it so much easier to see what's going on.
After you've done editing GLOBALS.INI with known variable names, delete
the disassemblies of scripts 0 and 994, since their global variable
names are now obsolete.



You can now disassemble any script by executing "SCDASMxx <scriptnum>", and
reassemble the modified script sources by executing "SCASMxx <scriptnum>".
SCDASM will extract the script and heap resource, if it's not already
present, by itself from the resource file; if it's present in the
directory, it will use that one instead, ignoring the one in the
RESOURCE.000 file. Therefore, before changing a script, first check if
there's already a patch script on the CD; make sure to copy that one
into your disassembly directory as well, so that the correct script gets
disassembled.

Please note that the assembler does not sort out nested scripts by itself.
However, it should be possible though to do this manually for an easier
reading by inserting additional spaces into the source file:

     pushi     117     ; SetSpeed
     push1
          pushi     55     ; moveSpeed
          push0
          lag     ego
          send     4
     push
     lofsa     object egoFollower
     send     6





KNOWN ISSUES:
_____________________________________________________________________________

- Object overloading (i.e. having both Actor "FreshHound" and Talker
"FreshHound" in the same script) is not supported. Fortunately, I've
never come across a game that needed this.

- Don't do any fancy stuff within strings --- "\n" is supported. OEM
special accented characters are supported, too, but don't try things
like "\0" or "blah\x22\x34". 

- The assembler does not always use the most efficient coding form ---
for example, jumps are ALWAYS 3-byte instructions, even if a 2-byte one
would do the job. This is because the jump distance is only known once
symbol references are resolved, which happens after assembly.

- The LEA instruction is not disassembled into clear text. It is however
reassembled properly. Therefore you shouldn't mess around with it. :)




---------------------
Have fun,
Enrico Rolfi, 2009
