StarShip Mission Language
Continued from "Scripting Part One"
This file is optional and only for use in manually editing or revising your 
mission scripts.
It contains notes about...
3. Map Tags
4. Overlays
5. Importing Handwritten Missions

3.
MAP TAGS

As you've seen, the normal structure of a message tag is:
<MSG23 = Captain, what shall we do now?>
This presents the text message as a log entry on the screen.

You may also insert into such a message tag another tag for triggering map 
events and music cues. We call these "Map Tags".

Here are some examples, followed by the dictionary of map events you can 
trigger.


<MSG36 = Engage.<FLYB=CloudyEarthBG;ByOut>>
This map tag makes your ship fly toward you past the "CloudyEarthBG" artwork.

<MSG01 = Let's get under way. <SWAP=Target;BluePlanet_icon@HEAR=action>>
This map tag makes the Target icon, which is normally an orange bracket, become 
a Blue Planet. This tag also causes the program to select an "action" style 
music cue and play it.

<MSG32 = <NSRT=parasites2> Captain! The crew lounge is being infested!>>
This map tag plays the animation named "parasites2", temporarily covering the 
star map.

<MSG26 = <SPOT=romulan;754;470> We've encountered a Romulan border patrol. 
Shields up!>
This map tag places a new icon, the "romulan" symbol, onto the map at 
coordinates 754x470. It will stay there until another tag elsewhere in the 
script is encountered saying <CANC=romulan>.


Notice that you *nest* a map tag inside the MSG tag.
The number of opening brackets and closing brackets must match.
Only one map tag per MSG tag is possible. Use the @ symbol if you want more than 
one. No extra spaces please.

Other map tag examples
<SWAP=Target;XYZ123_icon@SWAP=active_ship;icon> 
<SPOT=romulan;754;470>
<FLYB=EarthBG;ByOut>
<SWAP=Target;DestMark_icon>
<HEAR=action>


___________________________________________________________
Map Tag Dictionary

ее-------------------------------------
"HEAR" <HEAR=aStyle>
Play a music cue 
Replace aStyle with one of:
	action  link  success  fail  open  process 

ее-------------------------------------
"NSRT": <NSRT=aAnim>
Insert-shot cutaway animations, star map switches to an animation 
Replace aAnim with one of the types of animations avaliable, such as:
	Asteroids   beam_algage  melt_ice   targetRange   blackHole
	Decontaminate   locateSurfaceProbes   surfaceProbes2
	KurlanDig   militarySurveillance   Minefield1   Minefield2
	parasites1   parasites2   WormholeProbe
 

ее-------------------------------------
"FLYB"  <FLYB=aBackground;aMove>
Like an "insert", star map temporarily switches to animation of your ship flying 
thru the frame 

Replace aBackground with one of the types of backgrounds avaliable, such as:
   DeadMoonBG     BluJupiterBG   SunBG    EarthBG
   BluePlntBG     CloudyEarthBG   SmStarbaseBG    HotSunBG
   BlueCircNebBG  BluCloudBG     PinkNebBG   StarfieldBG
   GreenNebBG     orangeNebBG    pinkFlowerBG
(If your ship is not at starbase and you have specified smStarbaseBG, the 
program will automatically use the generic StarfieldBG instead.)

Replace aMove with:
	#ByOut  (ship moves out of the distance toward you, L to R)
	#warp  (ship moves from the R foreground into the distance)


ее-------------------------------------
"SPOT"  <SPOT=anIcon;000;000>
Places an icon on the map
Not necessary for your ship, just other icons in the mission
Replace anIcon with one of the types of icons avaliable, such as:
	DestMark	the standard generic target (its ID is Target)
	Federation
	XYZ123	a prometheus ship
	DeepS9 	space station
	HotRed 	planet or star
	Earth 	planet
	GasGiant 	planet (jupiter)
	RedPlanet 	planet (mars)
	BluePlanet 	planet
	Romulan	these are symbols of the various races
	Borg
	Bajoran
	Cardassian
	Dominion
	Ferengi
	Kazon
	Klingon
	Maquis

ее-------------------------------------
"CANC" <CANC=romulan>
Removes a previously SPOTted icon

ее-------------------------------------
"SWAP"  <SWAP=aIDname;aState>
 Changes the state of an existing Icon

	example: Target;XYZ123_icon OR activeShip;icon

	1st item   aIDname:   needs to be an established id name 
	  eg Target, Romulan, activeShip, CTN324 
	  (may use activeShip generically to indicate 
	   whichever shipID is "foreground" at the moment)
	  ("Target" is automatically assigned to the destination
	   location, and the "DestMark" icon - the orange 
	   bracket - is automatically placed. But you can change it.)
          
	2nd item   aState:  new art to use, either:
	    name_type ...selects any given art
	              eg Romulan_boom
	OR  type      ...selects type version of the IDname art
	     "icon" resets to base version of IDname art
	     "scan" shows the scan version of the IDname art (ships only)

	 if you dont use the "_" character the program will assume you just want 
to change the version of the current art


ее-------------------------------------
"AIMAT" <AIMAT=anIcon;anotherIcon>
Point the icon "anIcon" at "anotherIcon" 
See explanation for the "SPOT" tag in the original WRITING file.
To refer to the icon for the ship running the mission, 
say "activeShip".

ее-------------------------------------
"HIDE" <HIDE=anIcon>
"SHOW" <SHOW=anIcon>
Makes it invisible/or visible, but keeps it "on the map."
Use the "CANC" tag to free up that channel.
NOTE: There are now ten possible "sprite channels" for icons (the ships and 
planets).




4.
OVERLAYS


"Headquarters Alerts"

Example:
<MO_HQ_EV3 = What are our orders?,
            #otherSpeaks,-,Return to base., #simOver,-,Stay there., #HQCmd3,>

Format:
<MO_HQ_EVn = Text in the alert area,
            #aCommand,optionalmessage,Text for the first button, 
#aCommand,optionalmessage,Text for the second button, #HQCmdn,>

where n is the arbitrary yet sequential number of this tag. Note that it appears 
in 2 places. (eg: MO_HQ_EV3 and #HQCmdn) You use the #HQCmd3 in the script 
somewhere to trigger the appearance of this box.

If you want only one button to appear make the "Text for the button" space void, 
ie, just the two commas. MO_HQ_EV4 in the sample above does this.



"Environments"

The Location Event tag is used to define a set of up to 10 events 
that will be triggered by the ship crossing a specific point on the map

Example:
<LEVTMAP = #blackHole,30,50,Black hole in area, #asteroid,80,100,Asteroid 
field,>

Format:
<LEVTMAP = #aCommand,horizCoord,vertCoord,Text message,>

A valid horizCoord is 0 to 2000. A valid vertCoord is 0 to 1000.


This Time Event tag is used to define a set of up to 10 events 
that will be triggered at specific times relative to the start of a mission. 
Time is expressed in ticks (60 ticks / sec)

Example:
<TEVTMAP = #disengageWarpEng,9999,For some reason we just dropped out of warp!,>
The format for this tag is similar to the Location Event tag, except the 
numerical value expected here is ticks, not a rectangle in space.



"Other Event Tags"

Unrecoverable failures. The System Failure tag is triggered by the simulator 
when it senses that the engineering staff is unable to repair anything. 
Typically used to trigger an alert box...

<MO_CO_SYSFAIL = #HQCmd3,-,>


The Shields Malfunction response tag is triggered by the simulator when it 
senses that the shields are no longer able to protect the ship from externally-
inflicted damage. This usually happens during a conflict. This example assumes 
that. If you have a script with no enemies, it is advisable to leave out the 
"fightEnemy" command in here!

<MO_CO_SMF = #otherSpeaks,The shields are going down. Keep fighting 
anyway.,#fightEnemy,-,>




"Scans and Probes"

When you send a command to launch a probe or try a scan, such commands include 
parameters that specify points in space. These overlays "catch" those points and 
determine what if any feedback is given.

Example:
<MO_SN_IR = 180,70,220,450,#something,Thermal emissions detected.;>

The command symbol #something will cause a positive result to be fed back. If 
you place a #nothing command there then the feedback is false. You may also use 
#debris, #interstellarDust, or #distortion to partially obscure the signal 
(debris has the least interfering effect distortion the most).

Example of that:
<MO_SN_LR = 0400,0600,0500,0700,#interstellarDust,A cloud of microparticles is 
obscuring the signal.; 0400,0600,0500,0700,#something,Long range scan picks up a 
possible stellar fragment.;>
If the ship's installed equipment is sensitive enough it will read "through" the 
layer of dust to see "something". Notice how the rectangles are identical.

The format for an scan-environment tag is:

<MO_SN_aa = L1,T1,R1,B1,cmd1,"dsp text1";L2,T2,R2,B2,cmd2,"dsp text 
2;....;Ln,Tn,Rn,Bn,cmdn,"dsp testn>

where L=Left, T=Top, R=Right, B=Bottom which define a rectangle target

Only the tags that will be triggered by a scan request cmd that you have
included within the main script need to be defined with specific data.
For the ones that you are not using just place a null Rect (0,0,0,0) with 
#nothing cmd and blank message data.



"Conflict Resolution" overlays
<an alternate method of managing conflict>
(This is superceded by the simpler #encounterAdversary command used in Mission 
Creator.)

If your starship encounters an alien ship during the execution of a mission 
(which you trigger with an #EngageAlien command) it will make use of a set of 
tags associated with conflict resolution. You will need to define these tags so 
that the starship will "know" how to conduct itself during a conflict. These 

These tags may be omitted if your ship will never encounter an alien ship. 

The following is a set of suggested commands for each of the Mission Overlay 
Conflict Resolution tags. This set will produce a battle between the star ship 
and the enemy ship. (The MSGxx's are here as examples.)

Notice how each group of tags is read by the simulator in response to a 
particular command. Depending on conditions, one of the group of tags is 
selected by the simulator for execution.


#encounterAlien evokes one of 3 possible response tags:

// 1 Enemy is Friendly
<MO_CR_FC = #executeGoal,MSG39,>

// 2 Enemy is Hostile-- use the #hostile command to trigger #fightEnemy
<MO_CR_HC = #otherSpeaks,MSG40,#hostile,-,>

// 3 Enemy Attacks you-- use the #attacked command to trigger #enemyFire
<MO_CR_AC = #otherSpeaks,MSG41,#attacked,-,>



#enemyFire causes the enemy to be classified as either 
Strong, Weak, or Damaged.

// if the enemy is Strong, you probably want to continue fighting:
<MO_CR_SNG = #fightEnemy,MSG46,>

// if the enemy is Weak you can declare them destroyed
<MO_CR_WEK = #targetDestroyed,MSG42,#goal1achieved,-,#closeMission,-,>

// if the enemy is Damaged you can declare them destroyed too
<MO_CR_DMG = #targetDestroyed,MSG42,#goal1achieved,-,#closeMission,-,>

When the sim gets the #targetDestroyed command, the conflict ends.



#fightEnemy causes an attempt to #firePhasers
If successful, one of these tags is selected:

//target is deemed Invincible.... 
<MO_CR_INV =  #enemyFire,MSG47,> 

//targetDestroyed-->conflict ends
<MO_CR_TD = #targetDestroyed,We have vaporized the invading vessel.,>

//targetDisabled-->conflict ends
<MO_CR_TDA = #targetDisabled,The invading vessel is disabled and no longer a 
threat.,>

//targetImpacted-->automatically causes #enemyFire
<MO_CR_TIP = #targetImpacted,We've done some damage to them.,>

//targetTouched or 'dented'-->automatically causes #enemyFire
<MO_CR_TDNT = #targetTouched,Invading vessel barely felt that one.,>

//targetUnaffected-->automatically causes #enemyFire
<MO_CR_TUNE = #targetUnaffected,Our firepower is having no effect.,>


If Phasers arent ready, the sim looks for this tag to see what else it should 
do:
<MO_CR_NOPHS = #firePhotonTorpedo, Phasers not online. Try a photon torpedo.,>

And if Photon Torpedos arent ready, the sim looks for this tag to see what else 
it should do...
<MO_CR_NOPTP  =  #otherSpeaks,Torpedos not firing!,>

Or no Quantum Torpedos...
<MO_CR_NOQTP  =  #otherSpeaks,Quantum torpedos offline.,>


The core of a battle sequence is the exchange of #enemyFire and #fightEnemy 
commands. That happens automatically when the conflict resolution tags are 
written this way.




5.
IMPORTING HANDWRITTEN MISSIONS

An importable mission script needs to start with a Mission Profile, which looks 
like this...

NAME=Take Position in Sector 8
LEVEL=5000
ERA=x
TYPE=Sample
KEYS=Basic Equipment
DESC=
Fly to Sector 8 and request further instructions. Your mission will be 
successful if you can make it there.
@

The labels in capitals, followed by the =, must be in the file just as shown, as 
lines of their own. The number following "Level" is the maximum possible credits 
for this mission. The Era line needs to be in there, but is ignored. It is 
helpful to others who may see your Mission to describe in "Keys" what critical 
systems will be use during the mission. 

Please do not use the @ character anywhere in your document except as the 
separator symbol, as described next.

Note how, in the "Sector8.txt" sample file in the Import folder, the mission 
profile text preceeds the actual script, separated by a lone @ on a line by 
itself (that is, type a <return>, then type @, then type another <return>).

Also, double check that if you have a comment line (one that starts with //) at 
the end of your script, there is a <return> following it.

The program expects to read a Plain Text document. Be sure you have saved it 
this way.

We recommended that the file be put in the Import folder that is in the same 
folder (ShipMain) as Starship Creator. (That is not essential however as a 
dialog box will prompt for the file's location.)  Once imported, the file is not 
needed by the program, so you can remove it from the Import folder, but keep it 
somewhere as a backup.

Adding the new script to your list of available missions happens on the FLEET 
screen. Use the Import Mission button.


9/27/1998, rev 07/99, rev 03/00