** existing users: skip directly to the relevant "What's New" section

===========================
Red Alert Mission Annotater  (v 1.3)      (C)opyright David Louisson 1997
===========================

Thanks for taking the time to test drive my Red Alert Mission Annotater
(RAMA). I hope that you find it useful. The program is released as
freeware, so that it can be used and distributed without charge, and is
supplied on an 'as is' basis. As a result, I make no guarantees of
continued support in the future, nor accept any liability for any damage
caused by running the program, correctly or otherwise. You agree to use
it at your own risk.

RAMA is written using an old version of Microsoft QuickBASIC, so there
is no GUI to speak of, but this makes for a small, portable .EXE file.
Moreover, the emphasis is on functionality rather than presentation.
In all, about 40 hours work has gone into its development. Thanks to Andrew
Griffin and Charles Francis Harkins whose research into Single Player
missions made this possible. Trademarks and copyrights of Westwood Studios,
Microsoft, and any other manufacturers or contributors, are similarly
acknowledged.

I haven't yet created any of my own single player missions, so testing
has been restricted to those produced by Westwood and third parties.
No crashes occurred in the 30+ missions that I tested, however. The
accuracy of the output is heavily dependant on my interpretation of
the information in Messrs Griffin & Harkins' comprehensive Single Player
Mission Creation Guide.

Queries and suggestions are welcomed. If you wish to report a bug, or
are otherwise experiencing problems, please include a copy of the mission
(.INI or .MPR) file, along with a FULL description of the problem, so that
I can attempt to reproduce it here. I will endeavour to respond as time
permits. Send any E-mail to:   dave@bsnz.co.nz


Functional Overview
-------------------
The program takes a single player mission file (e.g. SCG01EA.INI) and
decodes any complex strings it finds (e.g. team types, triggers), adding
comments (lines prefixed with a semi-colon ';') underneath each such
string. Output is sent to a .ANN file of the same name, so that the
original mission file remains unchanged. Run-time is less than 5 seconds
on my Pentium-166.

With a little practice, the .ANN file is very readable, and can be used
to debug your own missions, or reverse-engineer those created by
Westwood Studios, or other gamers. It is also useful for developing
missions incrementally, i.e. you create part of the mission, annotate it,
make further additions and changes, annotate it again, and so forth.


RAMA.LIB file
-------------
RAMA is essentially parameter driven, so much of the output is, to a large
extent, customizable. All parameters are stored in the resource library
file RAMA.LIB, which can be easily modified using a text editor. If you do
make changes, however, take care not to disturb the file's format.
RAMA.LIB describes itself - for more information, read the comment lines
in the file.


Files shipped
-------------
README.TXT    - the document that you're curently reading
RAMA.EXE      - executable program
RAMA.LIB      - modifiable parameter resource library
LAST.DAT      - stores your default entries from the last run
SCG01EA.ANN   - sample output from Westwood's first Allied mission
SCU01EA.ANN   - sample output from Westwood's first Soviet mission


Running Instructions
--------------------
The program expects to find the files LAST.DAT and RAMA.LIB in the
directory (folder) from which it is being run. If RAMA.LIB is missing,
it will not run.

If the TUTORIAL.INI file resides in the same directory as the mission
to be annotated, then its text trigger descriptions will be used,
otherwise the defaults in RAMA.LIB will be used.

To run the program, type   RAMA [Enter]

You will be asked to input 5 parameters, before the program runs to
completion. In each case, simply pressing [Enter] accepts the default
value (highlighted in reverse image). These defaults are your entries
from the previous run, and are saved in LAST.DAT from one run to the
next. The 5 parameters are:

1. Path (folder) where the mission file resides.

2. Name of the mission file to be annotated. If you don't enter an
   extension (.xxx), then the default extension .INI will be assumed.
   Note that RAMA is capable of annotating multi-player missions
   (.MPR files) also.

3. Whether you want second level references to be annotated in the output
   file. Type Y or N (upper or lower case are both acceptable). Specifying
   Y means that items such as TeamTypes and Triggers are re-annotated in
   full, every time they are encountered (e.g. when referenced indirectly
   within definitions of Structures, Units, other Triggers, etc).
   Specifying N means that only the original definition of each item is
   annotated. NOTE: if you want the error "referenced item missing" to
   be checked, then this option must be set to Y

4. Whether you want diagnostic ERROR messages to be output. Type Y or N
   (upper or lower case). Although a full syntax check is not performed,
   RAMA is capable of reporting a number of potential errors. Error
   messages in the .ANN file are prefixed with the string !!! so they
   can be located quickly using a text search.

5. Whether you want diagnostic WARNING messages to be output. Type Y or N
   (upper or lower case). A warning message is less likely to cause
   problems than an error - many of the Westwood missions generated
   warnings, for example. Warning messages in the .ANN file are prefixed
   with the string !!

To exit the program at any time, press Ctrl-Break. If you're running from
the DOS prompt, pressing F3 then Enter will re-start from the beginning.

If RAMA crashes, the chances are that there's a bug somewhere in your
mission. Use the partly complete .ANN file to help you track it down.


What's new in Version 1.1
-------------------------
Version 1.1 addresses all of the enhancements outlined in release 1.1 of
the Single Player Mission Creation Guide. These include:
  - the "Ant" units and capabilities made possible by Westwood's
    Counterstrike add-on,
  - some refinements to Trigger and TeamType annotation, and
  - annotations of cell addresses in the [Bases] and [TERRAIN] sections.

RAMA.LIB has been upgraded to accommodate all of this.
WARNING: installing the new RAMA.LIB will overwrite any changes that
you made to your existing version.

The remainder of this document has also been upgraded accordingly.


What's new in Version 1.2
-------------------------
Error reporting functions have been enhanced. See the section "Error
Reporting and Debugging Facilities" below.


What's new in Version 1.3
-------------------------
  *  Unnecessary repetition of 2nd level trigger references in
     [CellTriggers] section has been eliminated.
  *  Warning "p4=0 with action2 present" no longer appears where p3=3.


Contents of the .ANN file
-------------------------
The .ANN file contains everything in the original mission file, plus
comments inserted by the annotater. The sequence of the original file
is maintained, e.g. if your [Waypoints] section occurs before your [Trigs]
section in your mission file, then that will also be the case in the
.ANN file.

Standard references are indented by a single semi-colon, e.g.
;B002: Gun Turret(Greece)  100%  {8021=62,85}  ^South  Trigger='Shelp'

Second level references (if selected) are indented by 5 semi-colons, e.g.
;;;;;T013: "Blight" (GoodGuy)  *Priority=7


The following sections are annotated as described:


[STRUCTURES] section
--------------------
2=Greece,GUN,256,8021,128,Shelp,1,0
;B002: Gun Turret(Greece)  100%  {8021=62,85}  ^South  Trigger='Shelp'
 ||    |          |        |      |    |       |       |
 ||    |          |        |      |    **      |       associated trigger
 ||    |          |        |      |            direction facing
 ||    |          |        |      anchor cell#
 ||    |          |        health condition as a percentage
 ||    |          country owned by
 ||    full description
 |sequence number = 002          ** N-S & E-W cell co-ordinates
 B means 'Building'                 (see "Cell References" section below)

If there is an associated trigger ("Shelp" in this case), and second
level references have been selected, then the trigger is annotated
immediately below, exactly as it is in the [Trigs] section (see below).

Parameter #8 can generate the following annotation:
*Repairable - denotes that the building can be repaired, or rebuilt


[SHIPS] & [UNITS] sections
--------------------------
0=GoodGuy,ARTY,256,6872,192,Guard,None
;U000: Artillery(GoodGuy)  100%  {6872=53,88}  ^West  Guard
 ||    |         |         |      |    |       |      |
 ||    |         |         |      |    **      |      initial action
 ||    |         |         |      |            direction facing
 ||    |         |         |      starting cell#
 ||    |         |         health condition (%)
 ||    |         country owned by
 ||    full description
 |sequence number = 000            ** N-S & E-W cell co-ordinates
 U means 'Unit', S means 'Ship'       (see "Cell References" section below)

If there is an associated trigger, and second level references have
been selected, then the trigger is annotated immediately below,
exactly as it is in the [Trigs] section (see below).


[INFANTRY] section
------------------
12=USSR,E2,256,11729,3,Guard,0,None
;I012: Grenadier(USSR)  100%  {11729=91,81,d}  ^NW  Guard
 ||    |         |      |      |     |     |   |    |
 ||    |         |      |      |     **    |   |    initial action
 ||    |         |      |      |           |   direction (NW=northest, etc)
 ||    |         |      |      |           sub-cell (a,b,c,d, or e)
 ||    |         |      |      starting cell#           b   c  )  sub cell
 ||    |         |      health condition (%)              a    )  positions
 ||    |         country owned by                       d   e  )
 ||    full description
 |sequence number = 012         ** N-S & E-W cell co-ordinates
 I means 'Infantryman'             (see "Cell References" section below)

If there is an associated trigger, and second level references have
been selected, then the trigger is annotated immediately below,
exactly as it is in the [Trigs] section (see below).


[Basic], [Map], [MapPack], [OverlayPack], [Digest] sections
-----------------------------------------------------------
These sections are not annotated.


[Waypoints], [TERRAIN], [SMUDGE] sections
-----------------------------------------
Cell references are annotated as described in the "Cell References"
section below.


[CellTriggers] section
----------------------
7102=rnf1
;;;;;rnf1=0,1,0,0,1,-1,1,0,-1,0,7,9,-1,-1,0,-1,-1,-1
;;;;;G012: 'rnf1' (Greece)
;;;;;  IF  Entered by(Greece)
;;;;;  THEN  Reinforcement(T009) {@-1}

Cell references are annotated as described in the "Cell References"
section below. The trigger part is annotated only if second level
references have been selected. For information on how Triggers are
annotated, refer to the [Trigs] section (see below).


[Base] section
--------------
The full description of any structure is displayed on the line below.
Cell references are annotated as described in the "Cell References"
section below. Example:

Player=GoodGuy
Count=18
000=POWR,5033
;  Power plant   {5033=39,41}


[Trigs] section
---------------
Brpet2=1,0,3,0,7,-1,0,13,-1,20,4,13,-1,-1,0,-1,-1,-1
;G014: 'Brpet2' (Spain)
;  IF  Destroyed by anybody ||| Elapsed time(2 min)
;  THEN  Create team(T013)   No action
;;;;;Blight=8,0,7,0,0,-1,14,3,E1:5,E3:3,1TNK:1,5,3:1,3:2,3:9,0:7,0:10
;;;;;T013: "Blight" (GoodGuy)  *Priority=7
;;;;;    is   5 x Rifleman   3 x Rocketman   Light Tank
;;;;;    <00>  Move to {@1=6872=53,88}
;;;;;    <01>  Move to {@2=8021=62,85}
;;;;;    <02>  Move to {@9=11729=91,81}
;;;;;    <03>  Attack(Factories)
;;;;;    <04>  Attack(Power Plants)

The above illustrates a trigger, showing a second level reference to a
teamtype. Teamtype annotation is covered in full below. The [Trigs]
entry works as follows:

;G014: 'Brpet2' (Spain)
 ||    |         |
 ||    |         Country referred to in second parameter
 ||    Trigger name (quotes are inserted by the annotater)
 |Trigger sequence number = 014
 G means 'triGGer'

;  IF  Destroyed by anybody ||| Elapsed time(2 min)
   |   |                    |   |
   |   |                    |   Description of trigger event #2
   |   |                    |      and its parameters
   |   |                    Event connector (AND, OR or |||=both)
   |   Description of trigger event #1 and its parameters
   IF denotes trigger EVENTS annotation

;  THEN  Create team(T013)   No action
   |     |                   |
   |     |                   Description of trigger action #2
   |     |                      and its parameters
   |     Description of trigger action #1 and its parameters
   |        (in this case TeamType #13 is the parameter)
   THEN denotes trigger ACTIONS annotation

Parameter #1 can generate the following annotations:
*OnceOnly - the trigger is fired only once
*Repeat - repeats, after trigger event has occurred to all attached items
*FreeRepeat - will continue to repeat whenever its trigger event is true


[TeamTypes] section
-------------------
Bclear=8,0,7,0,1,-1,8,1,2TNK:5,8,3:15,3:21,3:20,3:19,5:10,3:18,5:10,6:3
;T010: "Bclear" (GoodGuy)  *Priority=7   *MaxOccur=1   Trigger=G008
;    is   5 x Medium Tank
;    <00>  Move to {@15=4405=34,53}
;    <01>  Move to {@21=4682=36,74}
;    <02>  Move to {@20=4828=37,92}
;    <03>  Move to {@19=7125=55,85 Greek Base}
;    <04>  Guard area(1 min)
;    <05>  Move to {@18=6980=54,68}
;    <06>  Guard area(1 min)
;    <07>  Repeat from <03>
;;;;;Bagain=1,8,0,0,7,-1,0,0,-1,0,4,10,-1,-1,0,-1,-1,-1
;;;;;G008: 'Bagain' (GoodGuy)
;;;;;  IF  Destroyed by anybody
;;;;;  THEN  Create team(T010)

The above illustrates a [TeamTypes] annotation, showing a second
level reference to a Trigger (explained above). The [TeamTypes]
annotation works as follows:

;T010: "Bclear" (GoodGuy)  *Priority=7  *MaxOccur=1  Trigger=G008
 ||     |        |         |            |            |
 ||     |        |         |            |            attached trigger
 ||     |        |         |            max# of instances of the teamtype
 ||     |        |         priority (parameter #3)
 ||     |        country that owns the teamtype
 ||     Teamtype name (quotes are inserted by the annotater)
 |Teamtype sequence number = 010
 T means 'TeamType'

;    is   5 x Medium Tank
     |
     This lists the members of the teamtype (5 medium tanks)

;    <00>  Move to {@15=4405=34,53}
     |     |       |
     |     |       Parameter associated with team action
     |     Team action description
     Action sequence number

Parameter #2 can generate the following annotations:
*Replace - destroyed members of the team type are replaced
*Surplus - inactive duplicate of the team is produced
*AutoCreate - team is subject to the autocreate facility
*Direct - team moves directly to its target without engaging enemy on route
*Evade - team attempts to evade enemy units


Cell References
---------------
Absolute cell references are enclosed in curly braces. Also shown is
the vertical (N-S) and horizontal (E-W) co-ordinates, thus:

   {3403=26,75}
    |    |  |
    |    |  horiz (E-W) component
    |    vertical (N-S) component
    cell address

i.e. 3403 = (26 x 128) + 75

Waypoints are similarly referenced, thus:
                                    
{@19=7125=55,85 Greek Base}
 |   |    |  |  |
 |   |    |  |  Any comment (;) appended to a Waypoint definition
 |   |    |  |     (in the [Waypoints] section) is included
 |   |    |  horiz (E-W) component
 |   |    vertical (N-S) component
 |   Refers to absolute cell reference 7125
 Waypoint number 19


Notation Conventions
--------------------
To make locating item types easy using text searches, the following
system of notation has been adopted:

  Gnnn   - Trigger sequence numbers
  'xxxx' - Single quotes enclose Trigger names
  Tnnn   - TeamType sequence numbers
  "xxxx" - Double quotes enclose TeamType names
  Unnn   - Unit (vehicle) sequence numbers
  Bnnn   - Building (structure) sequence numbers
  Innn   - Infantry sequence numbers
  Snnn   - Ship sequence numbers
  {n}    - Cell address number
  {@nn=  - Waypoint number
  #n     - Global switch number
  <nn>   - Action step numbers (in [TeamTypes] section)
  (xxx)  - Parameter for event or action
  !!!    - Error message follows
  !!     - Warning message follows


Error Reporting and Debugging Facilities
----------------------------------------
As an aid to debugging your missions, RAMA now reports more than 30
different error types. Messages fall into two categories: errors
(will likely cause crashes or unpredictable results) and warnings
(possible error, or definition may not work exactly as intended).
The  !!!  string is used to highlight an error message, the  !!  string
highlights a warning message. These are contingent upon the 'display
errors' and 'display warnings' options being set on.

Performing a text search for !! is recommended, before attempting to
run your mission.

The full list of messages is as follows:

!!! ERROR: Invalid .INI statement: '=' missing
!!! ERROR: Invalid country: (misspelt country name)
!!! ERROR: Invalid section header: (misspelt section name)
!!! ERROR: Invalid item name: (misspelt unit/structure/ship/infantry name)
!!! ERROR: Invalid command type: (misspelt command for unit etc)
!!! ERROR: invalid units/actions list (check your parameter sequence)
!!! ERROR: Incorrect 'Count=' value or numbering (error in [Base] section)
!!! ERROR: Duplicate label (label name) found in section
!!! ERROR: referenced item missing: (name of undefined trigger, team, etc)
!!! ERROR: Country# p2>19 (invalid country# in trigger)
!!! ERROR: p3<0 or p3>3 (invalid value in trigger parameter 3)
!!! ERROR: p4<0 or p4>1 (invalid value in trigger parameter 4)
!!! ERROR: T1 p5<0 or p5>32 (first trigger event number out of range)
!!! ERROR: T1 p8<0 or p8>32 (second trigger event number out of range)
!!! ERROR: R1 p11<0 or p11>36 (first trigger action number out of range)
!!! ERROR: R1 p15<0 or p15>36 (second trigger action number out of range)
!!! ERROR: Country# p1>19 (invalid country# in team type, unit, etc)
!!! ERROR: p2<0 or p2>31 (invalid team type parameter value)
!!! ERROR: Health p3>256 (invalid health for unit, structure, etc)
!!! ERROR: Direction p5>256 (invalid direction for unit, structure, ship)
!!! ERROR: Direction p7>256 (invalid direction for infantryman)
!!! ERROR: Sub-cell p5>4 (sub-cell for infantryman must be 0,1,2,3 or 4)
!!! ERROR: Human player assigned non-zero IQ value

!! WARNING: Credits = 100 x nnnnn (multiplier probably forgotten)
!! WARNING: Tech Level not in range 1..16
!! WARNING: IQ Level not in range 1..5
!! WARNING: p3=0 with event2 present  )
!! WARNING: p3>0 with event2 absent   ) incompatibililty between flags
!! WARNING: p4=0 with action2 present )   and trigger events/actions
!! WARNING: p4>0 with action2 absent  )
!! WARNING: Credits = nnnnn (trigger event 12, multiplier doesn't apply)
!! WARNING: Global switch #n not initialized (set or clear trigger missing)
!! WARNING: Location lies outside defined map boundaries
!! WARNING: Item's map location possibly overlaps with xxxx

Thanks to Jaakko Nenonen who contributed ideas to this section.


Meantime, happy mission creation!  There are already several original
and challenging missions available on the 'Net and I look forward to
downloading and playing many more of them.


Cheers

David Louisson,
Hamilton, New Zealand
E-mail: dave@bsnz.co.nz

28-June-1997



                     ======= END OF DOCUMENT ======

