+---------------------------------------------------------------------------+
|                                                                           |
|  X-Wing Briefing Assembler Kit                                            |
|                                                                           |
|                 Written by Tim Scott (tscott@plains.nodak.edu)            |
|                                                                           |
|                                                                8/29/93    |
+---------------------------------------------------------------------------+

xbrfasm is freeware.  It can be freely distributed as long as this file
accompanies it and the executable is not modified in any way.

Using the X-Wing briefing assembler kit (xbrfasm) it is possible to create
mission BRIEFINGS for the LucasArts game from scratch.  I downloaded the
X-Wing design kit from wuarchive.wustl.edu and saw how limited it
was and how toasted the briefings became after 'editing' them when I
decided to come up with my own development kit.  This is the first part
of a set of tools I plan to create to use for modifying X-Wing.
Future tools will include a disassembler for stock mission briefings and an
assembler/disassembler for the missions themselves.

If you have any comments or suggestions for xbrfasm feel to drop a line
to the author at the address given above.

** IN ORDER TO USE THIS PROGRAM YOU **MUST** READ THE INSTRUCTIONS. **

In order to create a briefing you must learn the assembler's commands
and variable assignments.  Failure to do so will not only result in
no briefing but most likely in frustration at not understanding what
is going on.

Disclaimer: Use this program at your own risk.  I've tried to make it as
safe and non-destructive as possible.  If it screws up any of your data
don't blame me.

'Nuff said.  Onto the program's description.

1. PROGRAM EXECUTION:  In order to create a briefing, you must first have
a briefing listing in the form of a text file.  This file contains all
the commands and parameters according to how you want your mission
briefing set up.  Any old DOS editor should work provided it sticks in
newline characters at the end of each line.  I personally use JOVE 4.14
for DOS which allows me to indent and all that.

This text file must be in the form "filename.b" (without the quotation
marks, course.)  I chose the ".b" extension to signify that the file
is a Briefing listing.  When run, the assembler will simply add the
letters "RF" to the name of the file thus creating the name of the
assembled briefing (therefore, "defect.b" generates the assembled
briefing file "defect.brf".)

To assemble, simply type:

	xbrfasm filename.b

at the DOS prompt.

This program will not overwrite mission briefings that already exist!
If your briefing text file is named "WAZOO.B" and "WAZOO.BRF" exists
in the directory you are currently in, the assembler will exit without
writing.

2. ASSEMBLER COMMANDS:  The assembler has several commands (each described
in detail below) the guide it's operation.  These commands are:

	:dump_data			Display a basic dump of the data read in from
						the briefing file.

	:setup,:esetup		Begin/end setup section of the briefing file.

	:object_data,		Begin/end object_data section of the briefing.
		:eobject_data

	:briefing_setup,	Begin/end setup section of the briefing.
		:ebriefing_setup

	:page_data,			Begin/end page_data section of the briefing.
		:epage_data

	:tag_data,			Begin/end tag_data section of the briefing.
		:tag_data

	:text_data,			Begin/end text_data section of the briefing.
		:etext_data

	:efile				End of briefing file.

Note that each command is immediately preceded by a colon ":" and
is to be on a line by itself.

Of all the commands, :setup,:esetup should come before the other
data definition commands and :efile must be the final command in
the file.  I suggest using the above order to create a sort of
standard if you ever decide to share you briefing sources with
others.

2.1 :dump_data COMMAND:  The :dump_data command dumps all the information
given in the briefing file after it has been successfully read (ie. the
assembler encounters no problems in the reading of the file.)  This
lets the programmer check to see where his/her data is being placed and
if it is being read correctly.

2.2 :setup COMMAND:  The :setup command allows the programmer to set
an initial variable and a variable that really doesn't belong anywhere
else.  These variables are:

	number_of_coordinate_sets
	minutes

The :esetup command must be used to end the setup section.

2.2.1 number_of_coordinate_sets VARIABLE:  X-Wing briefings allow 1 to
2 sets of coordinates for displaying ships in the map grid.  If only 1
set is used, it is numbered "0"; two sets are numbered "0" and "1".

This variable accepts one parameter, that being a '1' or '2'.
(See view_coord_set, coords0, and coords1 variable descriptions below).

2.2.2 minutes VARIABLE:  This is the number of minutes allowed in the
actual mission.  The length of the mission might not work if this variable
doesn't match the one in the mission file.  This variable accepts
one parameter, being the length in minutes.

2.3 :object_data COMMAND:  The :object_data command allows the programmer
to begin his/her creation of briefing objects.  These objects include
everything from mines to planets to ships.  The only commands found "under"
the :object_data command are :object and :eobject which are used for
defining each individual object.  The :eobject_data command must be
used to exit the object_data area.

2.3.1 :object COMMAND:  The :object command is used to begin the definition
of an object.  The variables that are allowed to follow it are:

	name
	cargo
	coords0
	coords1
	reaction
	appearing
	formation
	type

The :eobject command must be used to end the definition of the current
object.  NOTE THAT when creating objects, the first object defined is
referenced as "0", the second as "1", and so on in the briefing.
This information will become important when using variables found
under the :command command.

2.3.1.1 name VARIABLE:  This is the name of the object as used in the
briefing.  It accepts one text parameter up to 16 characters long.
This variable defaults to a string of length 0 (null string).

2.3.1.2 cargo VARIABLE: This is the name of the cargo the object is
carrying (if any).  It accepts one text parameter up to 16 characters
long.  This variable defaults to a null string.

2.3.1.3 coords0 VARIABLE: This is set "0" of the coordinates used in
the briefing.  It accepts 3 integer parameters, each separated by at
least on space, representing the X, Y, and Z coordinates of the
object. (see view_coord_set below for more details on coordinate display.)

2.3.1.4 coords1 VARIABLE: As above, this is set "1" of the coordinates
used in the briefing.  It accepts 3 integer parameters, each separated
by at least on space, representing the X, Y, and Z coordinates of
the object.  If only 1 coordinate set is chosen using the :setup
command then any values places in coords1 will be ignored. (see
view_coord_set below for more details on coordinate display.)

2.3.1.5 reaction VARIABLE: This is the type of reaction the object
has (which determines it's coloring [green or red] on the map grid.)
It accepts one text parameter of "default","foe", or "friend".  This
parameter MUST be in lower case (without the quotation marks.)

2.3.1.6 appearing VARIABLE: This is the number of objects appearing.
It accepts one integer parameter.  This value appears to have no
affect on the mission briefing.

2.3.1.7 formation VARIABLE: This is the formation that the objects
fly in.  It accepts one integer parameter.  This value appears to have
no affect on the mission briefing.

2.3.1.8 type VARIABLE: This is the type (ship, planet, or otherwise) of
object that is displayed.  It accepts one text parameter.  This parameter
may be any one of the following (exactly as shown, all in lower case):

xwing, ywing, awing, tie fighter, tie interceptor, tie bomber, gunboat,
transport, shuttle, tug, container, freighter, cruiser, frigate,
corvette, star destroyer, tie advanced, mine1, mine2, mine3, mine4,
comm sat, nav buoy, probe, asteroid1, asteroid2, asteroid3, asteroid4,
asteroid5, asteroid6, asteroid7, asteroid8, planet1, planet2, planet3,
planet4, planet5, planet6, planet7, planet8, planet9, planet10, planet11,
planet12, planet13, planet14, death star.

2.4 :briefing_setup COMMAND: The :briefing_setup command sets up the
way that the text and map fields in the briefing are used.  The
programmer is allowed to change the size of the map grid, the number of
rows in the main body of text displayed when the map grid is displayed,
etc.  The top left corner of the display window (the entire area containing
the map grid and text areas) is defined as (X=0,Y=0) and the bottom
left is defined as (X=0, Y=138) although a much larger section can
be defined (but in this case, text will "disappear" by going out of the
range of window.)  The variables used in the briefing_setup section
are:

	map_top
	map_bot
	map_set
	full_top
	full_bot
	clock_period
	map_style

The :ebriefing_setup command must be used to exit the briefing setup
section.

2.4.1 map_top VARIABLE: This variable defines the top, or heading, of the
of the display window when the map grid appears on the screen.  It accepts
three integer parameters corresponding to the X and Y coordinates and
bottom Y coordinate.  For instance, in most of the stock briefings
map_top is defined as "0 0 12".  This means put the blue background starting
at the top left corner of the display window and extend it down 12.  This
allows for a one-line header.

2.4.2 map_bot VARIABLE: This variable defines the bottom, or sub-heading,
of the display window when the map grid appears on the screen.  It accepts
three integer parameters corresponding to the X and Y coordinates and
bottom Y coordinate.  For most stock briefings, this is two lines long.

2.4.3 map_set VARIABLE: This variable defines the area of the display
window taken up by the map grid.  It accepts three integer parameters
corresponding to the X and Y coordinates and bottom Y coordinate.  The
top Y coordinate usually equals the bottom Y coordinate of map_top
and the bottom Y coordinate usually equals the top Y coordinate of
map_bot (it's basically "sandwiched" between those two variables.)

2.4.4 full_top VARIABLE: This variable defines the top, or heading, of
the display window when the game player is viewing the full text of
explanation of the briefing.  It accepts three integer parameters
corresponding to the X and Y coordinates and bottom Y coordinate.

2.4.5 full_bot VARIABLE:  This variable defines the main section of
display window taken up by the full text description explanation of
the briefing.  It accepts three integer parameters corresponding to
the X and Y coordinates and bottom Y coordinate.

2.4.6 clock_period VARIABLE:  This variable defines the clock period,
or number of time segments, used by the briefing.  It accepts one
integer parameter valued from 0 to 9999.

During the map grid display (and as long as the STOP button hasn't
been "pressed") actions take place.  For instance, an identification
box (or id as I call it) may drop down on several (actually it's as
many as four) different objects.  The briefing uses timed events to
either drop the ids separated by a few seconds (as in DEFECT.BRF's id'ing
of the Imperial FRTs) or at the same time (as in DEFECT.BRF's id'ing
of the Y-Wing fighters.)  The clock_period is the value at which
all events end.  (see :commands command for more information.)

2.4.7 map_style VARIABLE: This variable defines the style of the
map grid.  It accepts one text parameter entered as "space" or
"surface" (note that the paramter must be entered in lower case
without the quotation marks.)  If "space" is chosen, the color of
the map grid is black.  If "surface" is chosen, the color of the
map grid will be light blue/gray signifying the surface of the
Death Star.

2.5 :page_data COMMAND:  This command denotes the beginning of page
definitions.  The commands that can be used under it are:

	:page
	:epage

The :epage_data command must be used to exit the page data definition
section.

2.5.1 :page COMMAND:  This command is used to define a page.  A page
corresponds to each page of the briefing (for example, in DEFECT.BRF,
there are 3 pages - the 1st page has a map grid and has the general
overview of the mission, the 2nd and 3rd pages are full text descriptions
of the mission.)  The variable and commands that can be used under
:page are:

	view_coord_set
	:commands
	:ecommands

The :epage command must be used to end the definition of a page.  Note
that the first page definition will use the values in map_top,
map_bot, and map_set to define the display window while subsequent
page definitions will use the values in full_top and full_bot to
define the display window.

2.5.1.1 view_coord_set VARIABLE: This variable defines which set of
object coordinates are viewed for the page.  It accepts one integer
parameter of either a "0" or a "1" depending on the set that is
to be displayed.  If "0" is chosen, the values from the objects variable
coords0 are used.  If "1" is chosen, the values from the objects variable
coords1 are used.

2.5.1.2 :commands COMMAND:  The :commands command is used to begin
definition of a command list that is executed by the briefing.  The
variables (or command directives) that can be used under :commands
are:

	header
	main
	center
	zoom
	a_tag
	b_tag
	c_tag
	d_tag
	a_id
	b_id
	c_id
	d_id
	clear_text
	clear_tags
	clear_ids
	end_cmds

The :ecommands command must be used to exit the command list definition.

2.5.1.2.1 header VARIABLE:  This defines which text string is placed in
the area as defined by the values in map_top or full_top.  It accepts
two integer parameters, the first of which is the time segment it is
executed at and the second of which is the id number of the text string
(see the :text_data command below) to be displayed.

2.5.1.2.2 main VARIABLE: This defines which text string is placed in
the area as defined by the values in map_bot or full_bot.  It accepts
two integer parameters, the first of which is the time segment it is
executed at and the second of which is the id number of the text string
(see the :text_data command below) to be displayed.

2.5.1.2.3 center VARIABLE: This defines where to place the center
position of the map grid.  It accepts three integer parameters:
time segment of execution, X coordinate, and Y coordinate.  Changing
the center of the map grid creates the panning effect found in many
of the briefings.

2.5.1.2.4 zoom VARIABLE: This defines the zooming in and out of the
map grid.  It accepts three integer parameters: time segment of
execution, X zoom factor, and Y zoom factor.  X and Y zoom factors
of 8 cause the map grid to have no subdivisions.  Numbers greater
than 8 zoom in; numbers less than 8 zoom out.  Factors of 0
cause X-Wing to crash.

2.5.1.2.5 a_tag through d_tag VARIABLES:  These display map tags (see
:tag_data below) on the map grid.  They accept four integer parameters:
time segment of execution, tag number, X coordinate, and Y coordinate.
Note that only a total of four tags may be displayed at a time on the
map grid (thus the a_tag, b_tag, c_tag, and d_tag differentiation.)  The
letters that precede these variables are for clarification purposes only.
In order to display more tags, the clear_tags variable/command directive
must be issued to get rid of the current tags.

2.5.1.2.6 a_id through d_id VARIABLES:  These place an identification
box on the specified object.  They accept two integer parameters:
time segment of execution and object identification number (see
:object_data for more information.)  The letters that precede these
variables are for clarification purposes only and do not in any way
correspond to the variables in 2.5.1.2.5.  A total of 4 id's are
allowed displayed.  To display more id's, the clear_ids variable/command
directive must be issued to get rid of the current ids.

2.5.1.2.7 clear_text VARIABLE: This variable clears the text areas of
the display window (ie. the heading and main body).  It accepts
one integer parameter corresponding to the time segment of execution.
This command must be issued before any new text can displayed.  It
is generally followed by a heading variable/command directive and
main variable/command directive.

2.5.1.2.8 clear_ids VARIABLE: This variable clears the identification
boxes from the map grid.  It accepts one integer parameter corresponding
to the time segment of execution.  This command must be used if there
are currently four ids being displayed and the programmer wishes to
make more ids.

2.5.1.2.9 clear_tags VARIABLE: This variable clears the tags from
the map grid.  It accepts one integer parameter corresponding
to the time segment of execution.  This command must be used if there
are currently four tags being displayed and the programmer wishes to
display more tags.

2.5.1.2.10 end_cmds VARIABLE: This is a REQUIRED variable for the end of each
page definition.  It accepts one integer parameter corresponding
to the time segment of execution.  Even though in stock briefings
the clock period isn't as large as 9999, this is what has been used
and what I advise programmers to use "to be on the safe side."  I
haven't done any bounds testing with this variable/command directive
so I don't know what happens if it isn't set to 9999.

2.6 :tag_data COMMAND: This command denotes the beginning of the
definitions of tags that are displayed on the map grid.  One
variable can be used under it (but this one variable can be used a
number of times):

	tag

The :etag_data command must be used to exit the tag data definition
section.

2.6.1 tag VARIABLE: This variable defines a string of text that is
used by the :commands variables/command directives a_tag through
d_tag.  It accepts one text parameter.  Any newline characters found
after the definition are erased.  Each time this variable is used a
new tag is created without destroying any previous tags.  The first
tag definition is referenced as "0", the second definition is
referenced as "1", and so on.  These references are used in the
:commands sections.

2.7 :text_data COMMAND: This command denotes the beginning of the
definitions of text strings that are displayed in the blue text
areas of the display window.  One variable can be used under it (but
this one variable can be used a number of times to create several
text strings):

	text

The :etext_data command must be used to exit the text data definition
section.

2.7.1 text VARIABLE: This variable defines a block of text that is used
by the :commands variables/command directives main and header.  It
accepts one text parameter.  A blank line signifies the end of the
text definition.  Any newline characters found in the definition
lines are erased.  A greater-than sign ">" will cause subsequent
text to be printed in yellow in the briefing (used almost exclusively
for headers) -- the briefing interprets this.  Green highlighting can be
turned on/off by using the carat symbol "^".  For example, if the text string
desired is "Look out for Darth Vader's Star Destroyer" and the programmer
wants "Darth Vader's" to be highlighted in green, he/she would enter the
string as "Look out for ^Darth Vader's^ Star Destroyer".  The assembler
will create the appropriate highlighting and discard the "^"s before
creating the briefing file.

The first text string defined is referenced as "1", the second is
referenced as "2" and so on.  Note that this is different from how
tags are referenced and pages are referenced (both starting at
"0" rather than "1").

2.8 :efile COMMAND: This command denotes the end of the file and
causes the assembler to begin dumping data (if requested) and
writing/creating the briefing file.

3.0 BRIEFING INFORMATION:  In order to use your briefing -- back up a
briefing and rename your briefing to the briefing you just backed up.

Here is a list of Tours of Duty and Historical Missions file names:
(Thanks to Henry Chang for supplying this with his X-Wing Design Kit)

Tour Of Duty 1		Tour Of Duty 2		Tour of Duty 3
Op. Name			Op.	Name			Op.	Name
1	DEFECT			1	STARSNDB		1	DEFEND2
2	ID-RECON		2	RESCUE1			2	YRAID
3	WXRGARD1		3	YSTRIKE5		3	MAX14
4	WXPROT2			4	WYCAPT2			4	MAX17
5	ATTACKXY		5	MAX9			5	WYRESC3
6	MAX13			6	CRNDRFT1		6	LARRY1
7	MAX10			7	MAX18			7	LARRY2
8	ATTACK3			8	MAX1			8	LARRY3
9	SULLUST			9	STD1			9	ASSAULT2
10	ACK-HARD		10	STD2			10	MAX19
11	CYGNUS			11	LEIA			11	DEFEND1
12	MAX20			12	INTCEP1			12	DSTAR1
										13	DSTAR2
										14	DSTAR3

Historical Missions
XWING			YWING			AWING
1	WAISTEM		1	YWASTEM		1	AWAISTEM
2	MAX4		2	YWAISTEM	2	WAAGGR1
3	SATLIT1		3	HELLO		3	MAX2
4	MAX5		4	MAX7		4	CONVOY2
5	HALLEY		5	WYRESC2		5	MAX15
6	KEYAN		6	ACKBAR		6	WARECON1

3.1 I have included in this package the "DEFECT.B" which, when assembled,
performs similar, if not exactly the same as, the DEFECT.BRF briefing
included with X-Wing.  View it as an example on how to set up your own
briefings.

Have fun, and may the force be with you!

--tim