Star Trek(tm): Starship Creator Add On Pack Writing, Version 2.0 --------------------------------------------------------------- WRITING YOUR OWN MISSIONS To enjoy the program, it is not required for you to write original missions. But if want to expand your mission library, and you're willing to do some programming, read on... Contents: 1. Starship Mission Language Glossary 2. Mission Script Structure 3. Map Tags 4. Overlays 5. Importing Your Mission Created by Imergy(r) for Simon & Schuster Interactive. Copyright 1998 All Rights Reserved. SSML Author: Laurence Tietz Director for Imergy: Peter Mackey Executive Producer for Simon & Schuster Interactive: Liz Braswell ___________________________________________________________ BEFORE YOU BEGIN Knowing that the possibilities in the Star Trek universe are infinite, we wanted to give intrepid aficionados access to the programming language we created for the mission simulator portion of Starship Creator. Using these instructions, and the IMPORT MISSION feature on the FLEET screen, you can expand your library of missions to include many different scenarios. Of course, you will encounter a few limitations to what is possible, but with a bit of imagination and creative writing you should discover many interesting possibilities. As with all programming languages, exact precision is essential. One misplaced comma can cause anything from a temporal anomaly to a frozen interface. Don't worry, you can't "break" anything with a typo, but if your script isn't formatted exactly the way the program expects it to be, the outcome may vary from what you intended. Just follow the rule all software developers use and save any open files before you test-run a new script. We hope this information gives anyone interested in making the effort the power to create their own simulations. If you develop a mission you'd like to share with others (or with us!) please do so. ___________________________________________________________ StarShip Mission Language 1. GLOSSARY A StarShip Mission command consists of 2 parts. #symbol, message, The #symbol triggers an event in the simulator. The message for most symbols can be: A simple text "log entry" which will show up on the screen. OR A "message tag" ( example: MSG07 ) which refers to text in a separate "message table", which can contain log entries and-or map tags. OR A hyphen " - " (used like this: #symbol,-, ) which indicates you want no message to accompany the event. For symbols shown below with ,-, you may replace the hyphen with simple text or a MSG code. Although for clarity the hyphens are surrounded by commas, in practice no spaces are used. Certain #symbols require special messages, which contain information needed for the #symbol to be interpreted fully. You cannot attach text messages or tags to those symbols. Where you see pairs of 000 000, a point coordinate is expected, indicating a location in space. (The map is 2000 wide by 1000 high, with 0 0 in the upper left corner. Note this differs from Cartesian space.) The first number is the horizontal coordinate, the second the vertical, separated by a space, with a few exceptions noted below. Also, certain #symbols may be followed by a then/else sequence, explained below. (also see the examples) And, a few #symbols require particular supporting symbols to follow them immediately in the command sequence. All these special cases are indicated below. ___________________________________________________________ --** Power Generators #impulsePwrOff, - , #impulsePwrOn, - , #warpPwrOff, - , #warpPwrOn, - , --** Propulsion (you normally don't have to specify these, they are executed within the simulator as part of larger operations) #engageStrucInteField, - , #disengageStrucIntegField, - , #engageNavDeflector, - , #disengageNavDeflector, - , #disengageImpulseEng, - , (disengage engines and disengage StrucIntegField) #engageImpulseEng, - , (engage engines and EngageStrucIntegField and SetCourse) #engageWarpEng, - , [then/else] adjusts warp speed to the strength of the struc integ fld (else, occurs when no SI field is present, or the SI field is too weak for even warp 1) #disengageWarpEng, - , #useMainPwrSupply, - , [then/else] available for certain specialized scripting cases where you want to vary the dialog depending on the shipÕs power status #useAuxPwrSupply, - , [then/else] available for certain specialized scripting cases where you want to vary the dialog depending on the shipÕs power status --** general ship cmds #waitAbit, - , simple delay #hover, - , (disengageImpulseEng and disengageWarpEng) #dock, - , (disengageWarpEng, disengageNavDeflector, lowerShields, a delay, then disengageImpulseEng) #unDock, - , (impulsePwrOn, warpPwrOn, engageImpulseEng, sets velocity) #departArea, - , (engageImpulseEng) #gotoWarp, - , (disengageImpulseEng and engageWarpEng) #plotNewCoords, 0000:0000, #returnStarBase, 0000:0000, similar commands, require a pair of map coordinates in the message portion (notice that unlike all other coordinates, these are separated by a ":" and not a space) #testManeuverability, - , [then/else] ship classes defined as more maneuverable will return positive #testHitTarget , - , use this "-" for this command, don't attach text watches progress of the ship until it reaches the destination usually placed immedaitely after #goToWarp #testHome , - , like #testhittarget but only used after #returnStarBase --** Command and Control System #UseInternalCommSys, - , [then/else] #UseRFTransciver, - , [then/else] #UseSubSpaceRadio, - , [then/else] #UseUTranslator, - , [then/else] --** Tactical #raiseShields, - , #lowerShields, - , #cloak, - , [then/else] if installed, activating the DefiantÕs cloaking device guarantees that #evadeDetection will always be successful #unCloak, - , [then/else] --** Events #blackHole, - , #asteroid, - , #wearNTear, - , #fireDrill, - , nothing particular happens with these except #asteroid automatically triggers an "insert" animation these are placed in the time and location event overlays where you may attach appropriate messages #damageIncident, 00000 aSystem, replace the 00000 with a number from 1 to 50000 indicating damage aSystem must be one of these terms: crew science transportation powerPlant propulsion weapons commandControl structureSystem navigation sickBay supportSystems --** Science CMDs #longRangeScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #1 to succeed #freqScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #1 to succeed #partSpectraScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #1 to succeed #gravimetrScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #2 to succeed #protspectScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #2 to succeed #lifeFormScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #3 to succeed #subSpaceScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #4 to succeed #opticalScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #5 to succeed #gravitonScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #5 to succeed #gammaScan, 0000 0000, [then/else] replace the 0000s with a point coordinate (see "scan overlays") requires sensor palette #6 to succeed #infraRedScan, 0000 0000, replace the 0000s with a point coordinate (see "scan overlays") [then/else] requires sensor palette #6 to succeed #partclMapScan, 0000 0000, replace the 0000s with a point coordinate (see "scan overlays") [then/else] requires sensor palette #6 to succeed #launchProbe, 0000 0000 aPurpose, [then/else] replace the 0000s with a point coordinate of the target of the probe aPurpose must be one of these: CulturalAnalysis, SampleRecovery, LongTermObservation, SpectralData, EnergyData, GeologicalData, GravimetricData, CommBeacon, MessageProbe, CommBeacon, special case: inside the "then" branch, you can call #getProbeData (The mission waits until the probe reaches its target.) #getProbeData, - , [then/else] only makes sense inside the "then" branch of #launchProbe gives a positive "then" result if the probe was able to read info from the probe data overlay (see explanation of "overlays") To accomplish each task, at least one of these classes of probes must be installed... CulturalAnalysis: Class 7, 8, or 9 SampleRecovery: Class 3, or 5 LongTermObservation: Class 5, or 7 SpectralData: Class 1, 2, or 4 EnergyData: Class 1, 2, or 4 GeologicalData: Class 3 GravimetricData: Class 1, 2, 8, or 9 CommBeacon: Class 6, 8, or 9 MessageProbe: Class 8, or 9 #useLab, aLab, aLab is one of these: Cartography Cybernetics CulturalAnthropology PlanetaryScience Exobiology [then/else] --**Transport #beamAwayTeam, - , #crewComp, 0 0 0 0 0 0, these two commands must go together the 0s are the number of crewmembers being transported, in this order: command engineers civillians scientists support tactical [then/else] #beamCargo, - , #loadData, 1, these two commands must go together loadData is presumed to be tons of cargo (we suggest using 1 for now) [then/else] #engageTractorbeams, - , [then/else] #disengageTractorbeams, - , #launchShuttleCraft, 0000 0000 aType , [then/else] 0000s are a point coordinate of the destination aType must be one of: Defense Impulse Cargo Passengers Warp Thrusters ("Thrusters" is how you use the Sphinx Workpod) (The mission waits until the shuttle reaches its target relative to the shipÕs current location.) --**Crew #testCaptainSkill, - , [then/else] #testChiefEngSkill, - , [then/else] #testFirstOfcrSkill, - , [then/else] #testCommsOfcrSkill, - , [then/else] #testChMedOfcrSkill, - , [then/else] #testScienceOfcrSkill, - , [then/else] #testSecurityOfcrSkill, - , [then/else] #testCounsellorSkill, - , [then/else] --** Facilities #useSalon, - , [then/else] #useHoloDeck, - , [then/else] #useLounge, - , [then/else] #useArboretum, - , [then/else] --** Weapons and Battle #evadeDetection, - , [then/else] #encounterAlien, - , triggers conflict (see "conflict overlay" explanation) the command sequence doesn't return to the command following this one until the conflict is over __discrete firing events (such as as targets or nonbattle events) #fireAnyTorpedo,-, attempts to automatically issue a #fireQuantumTorpedo command if your vessel is not so equipped (and only Defiant and Sovereign can be), then a #firePhotonTorpedo command is given instead #firePhotonTorpedo, - , [then/else] #firePhaser, - , [then/else] #fireQuantumTorpedo, - , [then/else] --** Messages and Report CMDs __use any of these as a medium to pass log messages and map tags: #getGenMessage, - , #reportStatus, - , (these commands also force a brief delay into the simulation): #captainSpeaks, - , #otherSpeaks, - , #getAwayTeamReport, - , #getMedicalTeamReport, - , --** Command Flow #setGoals,MSG00, expects the MSG00 tag to look exactly like this: if you have one goal: if you have more than one goal: (This can be any MSG number, not only 00.) #goalXachieved, - , where X is actually the goal number listed in your #setGoals tag, example #goal2achieved, - , #executePhase, - , normally comes at the end of the Initial Phase sequence (the tag REQUIRED to move the command sequence to the next group of commands labelled , the Execute Phase. #closeMission, - , normally comes at the end of the Execute Phase sequence (the tag REQUIRED to move the command sequence to the Closing Phase group of commands labelled #linkMission, aScriptName, ! very Special Case : aScriptName is the field name of a new mission script (not implemented for imported scripts) #die, -, triggers #simOver #simOver, - , triggers halt to the mission simulation causes evaluation of the ship's performance and calculation of any cRedits earned (which are proportional to the total number of goals set vs. achieved) [then/else] where indicated, means the command may be followed by a conditional branching structure. This way, you can cause certain commands to be executed only when a command is successful, and others if it is not. (You may omit the then/else structure, otherwise use the then/else as a pair.) sample format (also see examples): ,-, #thenCmd,0, ,-, ...one or more commands you want executed if a positive result #elseCmd,0, ,-, ...one or more commands you want executed if a negative result replace each 0 with the number of commands in each group (this count must be exact or unexpected command sequences will result) -o- StarShip Mission Language 2. MISSION SCRIPT STRUCTURE To create a script which the program interpreter can understand, you need to arrange the commands described in the Glossary into "tags". A script contains a series of "tags" which start with < and end with > . You tell the script interpreter what kind of tag it is by using an identifier code, which looks like WXYZ= . Here are some examples of the kinds of tags the script interpreter understands: As you can see, each type of tag has a different structure, suited to its purpose. There is also a comment mark // which you can use to insert notes to yourself or other readers of your script but which the interpreter will ignore. (Hint: Do not include the "#" mark inside your comments.) Here is a very basic mission script, with very simple commands, just to help you see the structure. It is full of comments -- those lines starting with // -- to help further explain the sections of the script. Note that the comments are ignored by the program when the file is being read. (For a sample mission script. For a complete version of an importable script and profile, see the "sector8.txt" file in the IMPORT folder inside the ShipMain folder. It has very few comments in it and is thus easier to see the structure.) The indenting and spacing are ignored by the interpreter. //========================================================= // Sample Mission // Launching a Probe //This is the script header tag. _(required)_______________ //After DES you insert your destination and its name. //The rest of this you can leave as it is. //Initial Phase tag_(required)_____________________________ //This is what happens first... //That "executeGoal" command triggers a link to this tag... //Execute Phase tag_(required)______________________________ //That "closeMission" command triggers a link to this tag... //Close Mission tag_(required)_____________________________ // The "message table"_____________________________________ //Notice that simple text messgages with no commas can be put right next to //the commands themselves. Otherwise use this table. > > > > > > > // HQ Alert Dialog list____________________________________ // Use these to trigger "Headquarters Alert" boxes // The following tag must be present in all scripts // Replace the "4" with whatever number of HQ alerts you have defined //Now insert the tags for the various alert boxes // (see the item in "OVERLAYS" for more detail) // Environment Overlays__________________________________________________ // Location event map // Time event map // System failure tag // Scan and Probe Result Overlay_________________________________________ // (most are empty since we are doing no scans in this mission) // Scan types (you must list all of these) // is a long range scan // is a freq (RF) scan // is a Partical Spectrometry scan // is a Gravimetric Scan // is a Proton Spec Scan // is a Life Form Scan // is a Sub-Space Scan // is a Optical Scan // is a Graviton Flux Scan // is a Gamma Radiation Scan // is a InfraRed Scan // is a Particle Map Scan // Probe data overlays for any type of probe look like this... //end //make sure there is a character after the last line of your script That's it. All of the tag identifiers you see above are required, the exception being the MSG table. Those MSG's are only required if you refer to such a MSG in the message part of your commands. Other tags, notably Conflict Resolution, are optional, depending on the mission. Read all about Conflict Resolution overlays below. -o- StarShip Mission Language 3. MAP TAGS As you've seen, the normal structure of a message tag is: 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. > This map tag makes your ship fly toward you past the "CloudyEarthBG" artwork. > 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. Captain! The crew lounge is being infested!>> This map tag plays the animation named "parasites2", temporarily covering the star map. 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 . 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 ___________________________________________________________ Map Tag Dictionary **------------------------------------- "HEAR" Play a music cue Replace aStyle with one of: action link success fail open process **------------------------------------- "NSRT": Insert-shot cutaway animations, star map switches to an animation Replace aAnim with one of: Asteroids beam_algage melt_ice targetRange blackHole Decontaminate locateSurfaceProbes surfaceProbes2 KurlanDig militarySurveillance Minefield1 Minefield2 parasites1 parasites2 WormholeProbe **------------------------------------- "FLYB" Like an "insert", star map temporarily switches to animation of your ship flying thru the frame Replace aBackground with: 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 atuomatically 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" Places an icon on the map Not necessary for your ship, just other icons in the mission Replace anIcon with one of: 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" Removes a previously SPOTted icon **------------------------------------- "SWAP" 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 -o- StarShip Mission Language 4. OVERLAYS "Headquarters Alerts" Example: Format: 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: Format: 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: 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... 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! "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: 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: 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: 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" or How to Pick a Fight... If your starship encounters an alien ship during the execution of a mission (which you trigger with an #encounterAlien 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 durring a conflict. 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 // 2 Enemy is Hostile-- use the #hostile command to trigger #fightEnemy // 3 Enemy Attacks you-- use the #attacked command to trigger #enemyFire #enemyFire causes the enemy to be classified as either Strong, Weak, or Damaged. // if the enemy is Strong, you probably want to continue fighting: // if the enemy is Weak you can declare them destroyed // if the enemy is Damaged you can declare them destroyed too 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.... //targetDestroyed-->conflict ends //targetDisabled-->conflict ends //targetImpacted-->automatically causes #enemyFire //targetTouched or 'dented'-->automatically causes #enemyFire //targetUnaffected-->automatically causes #enemyFire If Phasers arent ready, the sim looks for this tag to see what else it should do: And if Photon Torpedos arent ready, the sim looks for this tag to see what else it should do... Or no Quantum Torpedos... 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. StarShip Mission Language 5. IMPORTING YOUR MISSION An importable mission script needs to start with a Mission Profile, which looks like this... NAME=Take Position in Sector 8 LEVEL=x 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 and Type lines need to be there, but are ignored. Describe in "Keys" what critical systems will be used 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 , then type @, then type another ). Also, double check that if you have a comment line (one that starts with //) at the end of your script, there is a 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