The level of detail included here will increase as I get time - many of the actual scripting sections are just outlines at this point. What I'll likely do is fill in the examples of step-by-step instructions to build a complete working mission, then go back and add to the general guidelines. If you see errors or omissions, or if I'm just plain doing something stupid somewhere, please let me know: my email address is dwessels@telus.net
Keep in mind that, as we're simply talking about C++ programming, the number of ways to achieve the same effect is essentially infinite. The descriptions I have provided simply follow some of the informal standards the mission scripting community has adopted, plus (naturally) a few of my own habits and styles.
I've tried to get the path names correct, but typos are likely so please notify me if you spot any errors. I've focused this on EAW, but have tried to include comparable file and folder information for OP as well.
Note on MS Visual C++:
To make full use of this requires MS VC++ 6.0, preferably running service pack 4.
(In fact, I'm running pack 5 and haven't encountered problems yet.)
The (free) introductory versions of VC++ 6.0 will allow you
to create and compile the scripts as described below, but will not allow
you to actually run them with the game. I'm guessing the academic version would
allow you full use, but I haven't tried it.
The versions from "Standard" up all fully support the script use.
Throughout this document I assume you have a basic understanding of C++ and object oriented programming. If you don't, there are a ton of good books and websites, but I might as well include a shameless plug for my own material on the topic (don't worry, it's all free). Here are links to my introductory C++ course and followup C++ course.
If you don't have VC++, all is not lost! There is a good mission script editor produced by the folks at EagleEye. It's called FMSE and there is a patch that goes along with it. This editor will allow you to select teams, ships, terrain, victory conditions, and briefing messages (pretty much the only thing it doesn't let you do is scheduling sequences of actions or events).
The mission scripters have adopted a few conventions with regards to naming and data types that are worth mentioning here:
- Enumerated types are prefixed with the letter e (e.g. eRaceName) and the enumerated values are prefixed with the letter k (e.g. kFederation, kKlingon, etc)
- Classes are prefixed with the letter t (e.g. tMissionInfo), their methods with m (e.g. mDisplayMessage(...)), and their fields are prefixed with the letter f (e.g. fPos)
- Global variables are prefixed with the letter g (e.g. gEventMrg)
- There are a couple of types replacing traditional types, e.g. int32 is used to represent integers (32 bit), and iTruth is used for Boolean data types. Both char* and string are used for strings in various places
The instructions below assume that you are working on EAW - if you
are working on OP then replace
Taldren\Starfleet Command II\API\SFC2-API Release 2\
with the OP version:
Taldren Software Inc\Starfleet Command Orion Pirates\OP API - R2.1
- copy all files from the API include folder:
C:\Program Files\Taldren\Starfleet Command II\API\SFC2-API Release 2\Stl\include
to the VC++ include folder:
C:\Program Files\Microsoft Visual Studio\VC98\include
(This may overwrite one or more older VC++ files.) - copy all files from the API lib folder:
C:\Program Files\Taldren\Starfleet Command II\API\SFC2-API Release 2\Stl\lib
to the VC++ lib folder:
C:\Program Files\Microsoft Visual Studio\VC98\lib (again, this may overwrite one or more older VC++ files.) - You need a working directory (i.e. a folder) to store your new VC++ script projects,
below I'm assuming this working directory is C:\SFCDEV, but you can
replace this with whatever you like.
Into your working directory, copy the folder (and all its contents)
C:\Program Files\Taldren\Starfleet Command II\API\SFC2 - API Release 1.2
i.e., it should now appear in your working folder:
C:SFCDEV\SFC2 - API Release 1.2 or (for OP) C:\SFCDEV\OP API R2.1\ - You must perform some editing of your registry,
so from start/run, fire up REGEDIT, then:
- select HKEY_LOCAL_MACHINE/SOFTWARE/Taldren
- right click Taldren and create a new key: VCScriptAddins
- right click this new key, and create a new key: Settings
- right click this new key, and create a string variable: ScriptRootPath
- double-click this variable (right window) and set its value to C:\SFCDEV\SFC2 - API Release 1.2\Scripts\ or to C:\SFCDEV\OP API - R2.1\Scripts\ (for OP)
- Now we will start up VC++ and customize the working environment
for compatibility with our mission scripting. First,
go to folder C:\SFCDEV\SFC2 - API Release 1.2\Scripts
and double-click SFC2_Script_API.dsw
Another exception for the OP user: the specified file wasn't included in the OP API release. You can download it here courtesy of RogueJedi.
- Next, select Tools|Customize|Addins and
Macro Files|Browse.
Click to show .dll files, and select CreateScript.dll.
When it appears, make sure the check box beside it is checked.
- Next, select Tools|Customize|Addins and
Macro Files|Browse again.
Still show .dll files, and select ScriptObjectWizardAddin.dll.
When it appears, make sure the check box beside it is checked.
- Drag the two new icons (#1 is the object wizard,
#2 is the CreateScript wizard)
to one of the top toolbars and remember these - you'll be
using these two icons every time you create a new script.
-
As Kziti Kat points out, you must do this from Tools|Customize|Commands|Category Drop Down:Addins
That completes the API initialization, you are now set up to create as many scripts as you like.
- Go to C:\SFCDEV\SFC2 - API Release 1.2\Scripts and double click SFC2_Script_API.dsw
- Click on the CreateScript icon (#2 on the toolbar)
- Select a race (for campaign) or type of mission
- Fill in the name field
- Choose an option (the default option uses the bare bones Tem_Standard template, the single player option uses the Tem_Single template, and the multiplayer option uses the Tem_Multi template).
- Click the Create box
- Close VC++
- Go to the appropriate directory (based on race or mission type of your script) in the Scripts folder in your working space.
- Go to the folder with your new mission's name
- Remove the file your_script_name.dsp and rename your_script_name.dsp.new to your_script_name.dsp
- Reopen VC++ with your_script_name.dsw
(it seems to find it/create it even if it isn't originally visible)
-
Actually, as RogueJedi points out, all
you have to do is close the workspace (File | Close workspace, click yes when it asks you
to save changes to the workspace),
rename the project files, and then re-open the workspace.
- Click on the File View tab on left side, click your_script_name and in the Project menu select Set As Active Project
- Go to Projects | Settings | C/C++
Select C++ Language in the drop down menu and make sure the RTTI checkbox is checked
Close the display box - Go to Build | Set Active Configuration
and choose your_script_name - Win 32 Release
The next set of steps are needed to remove some elements that were eliminated from the API in an earlier patch
- Go to your project, and using the file view (on left-hand side), expand to view files, and remove the files Draw.h and Draw.cpp
- In the left hand window, double-click your_script_name.h,
and remove the declaration
virtual void mIniitializeDraw(const int32 MapPicked); - Double-click your_script_name.cpp, and remove
the following two code segments:
#include "Draw.h"
andvoid tyour_script_name::mInitializeDraw(.....) { ..... }
Actually, unless you are using multiple maps within a single mission, the MissionMap.h file can probably be left unchanged.
The MissionMap.cpp file contains an array of strings, the first two of which are titles/comments for the map and the rest of which actually define the map. E.g.:
const char* MapLines[]=
{
"YOUR_MISSION_NAME",
"// YOUR_MISSION_NAME Map",
" +____1____2____3+",
" |...............|",
" |...............|",
" |...............|",
" |........*......|",
"1|...............|",
" |...............|",
" |....G..........|",
" |...............|",
" |...............|",
"3|........g......|",
" |...............|",
" |...............|",
" |...@...........|",
" |...............|",
"3|...............|",
" +---------------+",
"///",
0
};
Each character represents a 10-unit block on the game map, so the above map is
30 by 30 hexes (a region of space 30000k by 30000k).
Each hex (i.e. each character in the string representation of the map) can start of with one feature, and different kinds of features are indicated using different characters:
- Ship positions are indicated with uppercase letters G through Z
- Ship facings are indicated with lowercase letters g through z (i.e. a ship at the uppercase G faces towards the lowercase g)
- Planets are indicated with digits 0..9 (different digits represent
different kinds of planets). The placement indicates the center of the planet,
but the larger planets may be more than 1 hex wide so don't place them too close together.
1 = Earth-like planet 5 = Dark Earth-like 8 = Fire planet 2 = Ringed-earth 6 = Saturn-like 9 = Ice planet 3 = Mars-like 7 = Night city planet 0 = Gas planet 4 = Jupiter-like
- Other celestial bodies are represented with various punctuation marks.
Again, these bodies (especially the suns) might be more than a hex wide.
Also, the nebula are area effects, covering the entire map.
@ = Moon & = Nebula1 : = Small black hole [ = Small asteroid # = Corpse ( = Sun1 ? = Nebula2 , = Large black hole ] = Large asteroid ^ = Organian ) = Sun2 < = Light dust cloud % = Wormhole * = Ice asteroid ! = Sun3 > = Heavy dust cloud $ = Fissure ~ = Pulsar
We can set up multiple maps for a mission, each with different terrain and ship starting points, and allow the dynaverse to automatically pick the most appropriate one.
To do this, we must create all the maps (in the MissionMap.cpp file) and add a terrain selection method in the Met_ScriptName.cpp file (and an appropriate method description in the Met_ScriptName.h file).
The selection routine must be named mAssignMapTerrainTypes, taking one integer parameter, and this will automatically be called by the dynaverse to select the most appropriate of your maps.
Here is an example of the routine:
tMapTerrain tMet_ScriptName::mAssignMapTerrainTypes(int32 Map)
{
/*
* For each map, describe which kinds of terrain it is appropriate for
* This is done using calls to the tMapTerrain constructor,
* supplying it with three parameters:
* iTerrainTypes TerrainType = kTerrainAnyTerrain,
* iPlanetTypes PlanetType = kPlanetAnyPlanet,
* iBaseTypes BaseType = kBaseAnyBase
*
* The valid types for iTerrainTypes are
* kTerrainNone
* kTerrainSpace = kTerrainSpace1 | kTerrainSpace2 | kTerrainSpace3 |
* kTerrainSpace4 | kTerrainSpace5 | kTerrainSpace6,
* kTerrainAsteroids = kTerrainAsteroids1 | kTerrainAsteroids2 | kTerrainAsteroids3 |
* kTerrainAsteroids4 | kTerrainAsteroids5 | kTerrainAsteroids6,
* kTerrainNebula = kTerrainNebula1 | kTerrainNebula2 | kTerrainNebula3 |
* kTerrainNebula4 | kTerrainNebula5 | kTerrainNebula6,
* kTerrainBlackholes = kTerrainBlackHole1 | kTerrainBlackHole2 |
* kTerrainBlackHole3 | kTerrainBlackHole4 |
* kTerrainBlackHole5 | kTerrainBlackHole6,
* kTerrainAnyTerrain = kTerrainSpace | kTerrainAsteroids | kTerrainNebula | kTerrainBlackholes |
* kTerrainDustclouds | kTerrainShippingLane,
*
* The valid types for iPlanetTypes are
* kPlanetNone
* kPlanetHomeWorld = kPlanetHomeWorld1 | kPlanetHomeWorld2 | kPlanetHomeWorld3,
* kPlanetCoreWorld = kPlanetCoreWorld1 | kPlanetCoreWorld2 | kPlanetCoreWorld3,
* kPlanetColony = kPlanetColony1 | kPlanetColony2 | kPlanetColony3,
* kPlanetAsteroidBase = kPlanetAsteroidBase1 | kPlanetAsteroidBase2 | kPlanetAsteroidBase3,
* kPlanetAnyPlanet = kPlanetHomeWorld | kPlanetCoreWorld | kPlanetColony | kPlanetAsteroidBase,
*
* The valid types for iBaseTypes are
* kBaseNone
* kBaseAnyBase = kBaseStarbase | kBaseBattleStation | kBaseBaseStation |
* kBaseWeaponsPlatform | kBaseListeningPost,
*/
switch ( Map )
{
case 0: return tMapTerrain (kTerrainSpace, kPlanetNone, kBaseNone);
case 1: return tMapTerrain (kTerrainAnyTerrain, kPlanetNone, kBaseAnyBase);
case 2: return tMapTerrain (kTerrainAnyTerrain, kPlanetAnyPlanet, kBaseNone);
case 3: return tMapTerrain (kTerrainAnyTerrain, kPlanetAnyPlanet, kBaseAnyBase);
case 4: return tMapTerrain (kTerrainSpace, kPlanetNone, kBaseNone);
case 5: return tMapTerrain (kTerrainAsteroids, kPlanetNone, kBaseNone);
case 6: return tMapTerrain (kTerrainNebula, kPlanetNone, kBaseNone);
case 7: return tMapTerrain (kTerrainBlackholes, kPlanetNone, kBaseNone);
default: break;
}
return tMapTerrain();
}
Now, in our MissionMap.cpp file we need to have a map which corresponds to each of the cases
which could get selected above. I've abbreviated the maps themselves below,
otherwise here is an example of the file setup:
int32 TotalMaps = 8;
const char* MapTypes[] = { "Met_ScriptName Map",
"Met_ScriptNameBase Map",
"Met_ScriptNamePlanet Map",
"Met_ScriptNameBoth Map",
"Met_ScriptNameEmpty Map",
"Met_ScriptNameAsteroid Map",
"Met_ScriptNameNebula Map"
"Met_ScriptNameBlackHole Map",
};
const char* MapLines[]=
{
"Met_ScriptName",
"// Met_ScriptName Map",
" +____1____2____3____4____5____6____7____8+",
" |........................................|",
" |........................................|",
// most of the map itself deleted here
" |........................................|",
"8|........................................|",
" +----------------------------------------+",
" 1 2 3 4 5 6 7 8",
"///",
"// Met_ScriptNameBase Map",
" +____1____2____3____4____5____6____7____8+",
" |........................................|",
" |........................................|",
// again, deleted most of the map
"8|........................................|",
" +----------------------------------------+",
" 1 2 3 4 5 6 7 8",
"///",
"// Met_ScriptNamePlanet Map",
" +____1____2____3____4____5____6____7____8+",
" |........................................|",
" |........................................|",
//
// etc etc etc for all 8 maps
//
" |........................................|",
"8|........................................|",
" +----------------------------------------+",
" 1 2 3 4 5 6 7 8",
"///",
0
};
In MissionText.h we establish an enumerated type, TextMessages, with a unique value for each different kind of message that can be displayed. E.g. kMissionTitle_msg, kDescription_msg, ....
In MissionText.cpp we find the actual strings for these text messages, inside std::string Messages[] =.... The order of the messages in MissionText.cpp must exactly match the order of the ids in MissionText.h, otherwise you'll get the wrong messages popping up in the wrong places.
There are a handful of predefined message types:
- kMissionTitle_msg - the mission title in the mission screen
- kDescription_msg - the description given to the player at the start of the mission
- kBriefing_msg - the mission briefing in the communication panel
- kStart_msg - the start of mission message
- kAstoundingVictory_msg, kVictory_msg, kDraw_msg, kDefeat_msg, kDevestatingDefeat_msg, kLeftEarly_msg - the messages given to the player at the end of the mission, depending on how well or how poorly they did
You can also add as many other messages as you like, just give each a unique identifier in the enumerated type in MissionText.h and (in the matching spot) put the string of text in MissionText.cpp.
To display the added messages during the mission, add the following code
within one of the event handling routines:
fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kTHEMESSAGEID_msg);
This sends the message with enumerated value kTHEMESSAGEID_msg to the
player team (kPlayerTeam is an enumerated value specifying the player team,
declared in the CommonDefs.h file).
When creating the strings, there are a number of variables we can insert such as:
- [STARDATE] - the current dynaverse date
- [PLAYER_NAME] - the name of the player
- [PLAYER_RANK] - the player's current campaign rank
- [SYSTEM_NAME] - the current dynaverse hex (the mission is being played in)
For example, "[STARDATE]: [PLAYER_RANK] [PLAYER_NAME] commanding. At coordinates [SYSTEM_NAME] ..." might appear on the screen as "2269.3: Captain Nuclear Wessels commanding. At coordinates 32x,17y ...".
There are also several other forms of communication discussed in other segments of the document:
- Setting up briefing messages and the briefing map: section 6.3
- Setting up debugging messages and debriefing messages: section 11.1.1.5
- Setting up communication buttons: section 11.2.6
Just as an aside, there are a handful of arrays declared in Race.h that come in handy if you want to grab a string representing the race name, based on a race type. Two of the handy ones are: gRaceNames[] and gFullRaceNames[]
if you use anything else then you'll have to make appropriate translations.
enum eTeamTypes
{
kPlayerTeam = kTeam1, // this will be the primary (drafting) player
kPlayerNPCTeam = kTeam2, // this will be their AI ally team
kEnemyTeam = kTeam3, // this will be the primary opponent (drafted) player
kNPC1Team = kTeam4, // this will be some additional AI team (pirates, monsters, another race, whatever)
};
- 6.1.1 Setting up the mission options, in mScriptSpecs Each of these options is established by assigning a value to a field in the Specs object, e.g. Specs->fPlayerRace = ... or Specs->fMinDate = .... Below are a list of the fields, what they're for, and what options are available.
- Mission title: this is the title displayed when selecting the mission,
we can set this from one of the enumerated messages in the MissionText.h and .cpp files,
for example:
Specs->fMissionTitle = Messages[kMissionTitle_msg];- Mission description: similarly, this sets the description of the mission, and is also set using the enumerated messages in the MissionText files, e.g.:
Specs->fMissionDescription = Messages[kDescription_msg];- Mission type: we can establish a mission by assigning either kTutorialMission for a tutorial mission, kHistoricalMission for skirmish missions, kCampaignMission for dyna/metaverse missions, or kMultiplayerMission for (surprise) multiplayer missions. Whoops, there is also kUniqueCampaignMission for the scripted one-time-only campaign missions. Example:
Specs->fMissionType = kCampaignMission;- Mission location: for campaign missions, we can describe where a mission can be offered in the dyna/metaverse. We can supply a list of categories of "whose territory" the mission can be offered in, and also a list of what kind of nearby terrain is required. Furthermore, we can specify how far away a valid hex can be located for us to run a mission in the current hex (range 0 means the current hex must match the criteria, range 1 means the current hex or any adjacent one, etc). For example, if the mission can be offered in enemy or neutral territory, and the player must actually be in an asteroid or dust cloud hex, we could specify:
Specs->fMetaLocationSpec(0, kEnemyRace|kNeutralRace, kAsteroidHex|kDustCloudHex);
The race and terrain options are controlled by bitmasks, so you can use logical or (|) to create combinations like the above.Note that bases, planets, and terrain are considered separate categories: i.e. in a hex with a base and a planet you could get base missions, planet missions, or empty space missions.
- NOTE: These settings are really treated as recommendations by the dynaverse - there are
settings in the server .gf file that determine how much weight it really assigns to the
specifications you make here. For more details on those file settings see section
17.1.
The available race options are: kPlayerRaceHex, kEnemyRaceHex, kAlliedRaceHex, kNeutralRaceHex, kAnyRaceHex, kFederationRaceHex, kKlingonRaceHex, kISCRaceHex, kRomulanRaceHex, kGornRaceHex, kLyranRaceHex, kHydranRaceHex, kMirakRaceHex
The available terrain options are: kAnyTerrainHex, kEmptySpaceHex, kAnyBaseHex, kAnyPlanetHex, kAsteroidHex, kDustCloudHex, kBlackHoleHex, kShippingLaneHex, kCoreWorldHex, kHomeWorldHex, kColonyHex, kAsteroidBaseHex, kBaseStationHex, kBattleStationHex, kStarbaseHex, kBaseListeningPostHex, kBaseWeaponsPlatformHex .- Mission date: we can specify that a mission can only be offered in a specific time period in the dyna/metaverse, to do so we specify the earliest and latest date. For example, to specify that the mission could only be offered in the earliest 10 years of a campaign, we would use:
Specs->fMinDate = kMinDate; Specs->fMaxDate = kMinDate + 10;
A value of 0 corresponds to 2263, 10 to 2273, etc. kMinDate = 0, kMaxDate = 60.- BPV range: theoreticall we can specify a mission can only be offered to a player whose ships falls in a specific BPV range, e.g.
Specs->fMinBPV = 80; Specs->fMaxBPV = 140; Later, in section 6.1.4 we can set restrictions on the strengths of each individual ship in each team.- Player race (primary, or drafting, player): we can specify that the mission can only be offered to players from certain races, again with a bitmask set up to allow selection of multiple races. The options are kSpecFed, kSpecLyran, kSpecKling, kSpecRomulan, kSpecGorn, kSpecISC, kSpecHydran, kSpecMirak, kSpecNonPirateRace, e.g.:
Specs->fPlayerRace = kSpecLyran | kSpecKling;- Ship numbers: we can specify that the mission only be offered to fleets with certain numbers of ships: kMissSpecNoShip, kMissSpecOneShip, kMissSpecTwoShip, kMissSpecThreeShip, kMissSpecAllShips, for example to specify that the player needs either two or three ships:
Specs->fNumShips = kMissSpecTwoShip | kMissSpecThreeShip;- Menu options: for skirmish and multiplayer missions we can enable or disable some of the menu buttons the player can use: kNoMenuButtons, kEnableSupplyDock, kDisableCustomSkirmish, kDisableAI, kDisableTagA, ..., kDisableTagF, kDisableAllTags, kDisableAll. An example preventing custom selection of ships in a skirmish mission would be
Specs->fMenuStates = kDisableCustomSkirmish;- Bandwidth options: to be honest, I don't know what the hell this does, but the options are kNumClientsMask, kForgotClientInitialization, k0Client, ..., k5Client, kHostBandwidthMask, kForgotHostInitialization, k1Band, ..., k6Band, kThirdBand, kHalfBand, kAllBand and an example is
Specs->fBandwidthPart = kAllBand; - Mission description: similarly, this sets the description of the mission, and is also set using the enumerated messages in the MissionText files, e.g.:
- 6.1.2 Setting up the teams in mScriptSpecs
- For each team we will use the mCreateTeamSpec method to set the basic parameters/options
for the team. This method expects to receive the value for each option, in the correct order. The options are as
follows:
- The team name: a string used to name the team, e.g. "Player Team", "Pirate Team", "Rescue Team", whatever.
- The team ID, e.g. kPlayerTeam, kEnemyTeam, etc. This is usually cast to type eTeamID.
- The chance the team should be used (a value in the range 0-1). For example, the primary player team is required, so would be set to 1.0, whereas you may have an NPC team that only comes into play half the time, so this may be set to 0.5.
- Is the team required or not?, if the mission requires that this particular team be present, then set this to kTrue, otherwise it can be set to kFalse
- The type of team - there are four types:
kNPCTeam, //Only run by the AI kPlayableTeam, // Can be played by player or AI kPrimaryTeam, //e.g. the drafter kPrimaryOpponentTeam, // e.g. an enemy draftee
- The chance the team can be played by the AI instead of a human player, again this can be any value between 0 and 1.
- The valid races for the team, chosen from a combination of kSpecFed, kSpecKling, kSpecRomulan, kSpecLyran, kSpecHydran, kSpecGorn, kSpecTholian, kSpecISC, kSpecMirak, kSpecLDR, kSpecWYN, kSpecJindarian, kSpecOrion, = 1 << kOrion, kSpecMonster, kSpecAnyRace, kSpecNonPirateRace, kSpecPlayableRace
- Race modifying criteria, chosen from a combination of kSameAs, kAnyEnemyOf, kWorstEnemyOf, kAnyAllyOf, kBestAllyOf, kAnyRace, kDifferentThan
- The type of team allocation used, used by applying typeid to the team's class, e.g. typeid(tPlayerTeam) or typeid(tEnemyTeam), etc. (Discussion of team classes takes place in section 6.2.)
- The tag for the team, use kNoTeamTag unless this is a multiplayer mission. For multiplayer, the other options are: kTagA, kTagB, ... , kTagZ (though only A through F are valid for human players).
- The mission title used for that team, e.g. "Data Recovery" versus "Holding Action", depending on which side of the mission you're on.
const tTeamSpec& team1 = mCreateTeamSpec( "Player Team", static_cast< eTeamID >( kPlayerTeam ), kMaxChance, kTrue, kPrimaryTeam, kMinChance, kSpecPlayableRace, kAnyRace, typeid( tPlayerTeam ), kNoTeamTag, Messages[kMissionTitle_msg] ); const tTeamSpec& team2 = mCreateTeamSpec( "Enemy Team", static_cast< eTeamID >( kEnemyTeam ), kMaxChance, kTrue, kPrimaryOpponentTeam, kMaxChance, kSpecPlayableRace, kAnyEnemyOf | kPlayerTeam, typeid( tEnemyTeam ), kNoTeamTag, Messages[kMissionTitle_msg] ); const tTeamSpec& team3 = mCreateTeamSpec( "Pirate Team", static_cast< eTeamID >( kNPC1Team ), kMaxChance, kTrue, kNPCTeam, kMaxChance, kSpecOrion, kAnyRace, typeid( tNPC1Team ) );
Once we've established the teams, we must set them up, so follow our team creation code with the setup calls, e.g.:Specs->mSetupTeam( team1 ); Specs->mSetupTeam( team2 ); Specs->mSetupTeam( team3 );
- 6.1.3 Setting up team goals and relations in mStartMission
- Here we will create a twodimensional character array specifying how each team relates to one another,
and what each team's goal is with respect to each other team. The possible goals, relationships, and representative
characters are shown below:
Goals Relationships Notes - Ignore (self) - Self Cannot fire on allies I Ignore (other) A Allied Hostile AI ships will not fire until fired upon C Cripple F Friendly At war AI ships will actively seek out enemies X Capture N Neutral D Destroy H Hostile W War P PassiveAs noted above, the relations have an impact on how teams can interact, but they also have an impact on how AI teams will respond to commands. For example, an AI team that is set to HI will stop dead in space until given a command to follow, defend, or whatever. Sometimes to get an AI command to work it is necessary to change the relationships between teams, but doing so runs the risk of also changing the behaviour of other ships on the team.To set up the relationships, we need to set the number of teams in kRelationsCount, create the 2D character array, and then call mSetTeamRelations to actually set the relationships. For example:
void tMet_PigInTheMiddle::mStartMission() { tScript::mStartMission(); const int kRelationsCount = 3; int32 teamList[kRelationsCount] = { kPlayerTeam, kEnemyTeam, kNPC1Team, }; std::string relationships[kRelationsCount][kRelationsCount] = { //Plyr = kPlayerTeam, //Nme = kEnemyTeam, //NPC1 = kNPC1Team, // Plyr Nme NPC1 /*Plyr*/ "--", "WI", "WX", /*Nme */ "WI", "--", "WX", /*NPC1*/ "HI", "HI", "--", }; fMissionInfo->mSetTeamRelations( teamList, (std::string*)relationships, kRelationsCount); } - 6.1.4 Setting up the team strengths in mDefineTeamShipStrengths
- Earlier we defined the overall BPV restrictions for mission to be offered to the primary player.
Here we set up specific strength limitations for each of the
individual ships
in a team (up to 3 ships per team) for example:
void tMet_PigInTheMiddle::mDefineTeamShipStrengths( void ) { mSetTeamShipStrength( kPlayerTeam, kClassFrigate, kClassHeavyBattlecruiser, kMinBPV, 250 ); mSetTeamShipStrength( kPlayerTeam, kClassFrigate, kClassNewHeavyCruiser, kMinBPV, 180 ); mSetTeamShipStrength( kPlayerTeam, kClassFrigate, kClassHeavyCruiser, kMinBPV, 120 ); mSetTeamShipStrength( kEnemyTeam, kClassDestroyer, kClassNewHeavyCruiser, 80, 180 ); mSetTeamShipStrength( kEnemyTeam, kClassFrigate, kClassHeavyCruiser, 50, 140 ); mSetTeamShipStrength( kEnemyTeam, kClassFrigate, kClassLightCruiser, kMinBPV, 120 ); }If I understand things correctly, in D2 the mission matcher actually goes through your TeamShipStrength declarations to identify the appropriate team slots - this takes place *before* a list of missions is actually offered to the player, then actual drafting etc takes place if and when the player actually chooses that mission.The available ship categories are kClassShuttle, kClassPseudoFighter, kClassFreighter, kClassFrigate, kClassDestroyer, kClassWarDestroyer, kClassLightCruiser, kClassHeavyCruiser, kClassNewHeavyCruiser, kClassHeavyBattlecruiser, kClassCarrier, kClassDreadnought, kClassBattleship
The single player template sets up four teams, the PlayerTeam, EnemyTeam, PlayerNPCTeam, and the NPC1Team. For each team, it will create a Team.h and Team.cpp file, plus a TeamBaseState.h and TeamBaseState.cpp file. In addition, it will create a PlayerShip.h and PlayerShip.cpp file, and a PlayerShipBaseState.h and PlayerShipBaseState.cpp file.
The Team.h and Team.cpp files are used to set up team ships, victory conditions, and mission scheduling.
The Ship.h and Ship.cpp files are used to control a specific team's ships.
The TeamBaseState.h and TeamBaseState.cpp files are used for event handling for events relevant to that specific team.
Similarly, the ShipBaseState.h and ShipBaseState.cpp files are used for event handling for events relevant to a particular team's ships.
Each of these files creates and defines a particular class, so at the outset we have the following classes by default:
- tPlayerTeam, tPlayerTeamBaseState, tPlayerShip, tPlayerShipBaseState
- tEnemyTeam, tEnemyTeamBaseState,
- tPlayerNPCTeam, tPlayerNPCTeamBaseState,
- tNPC1Team, tNPC1TeamBaseState,
If we want to change the name of a team, e.g. use Pirate instead of NPC1, then we should change the name of the class for that team, and the name of the files, and the name of the identifier for the team, and (here's the ugly part) all the references to the class/file/identifier. This means going through the .cpp files and changing all instances of tNPC1Team to tPirateTeam, for instance. It improves readability, but it's a pain in the butt if you go to do it manually. When you do this, be sure you update the #include statements at the tops of the files as well.
Now, suppose we want to add specialized event handling for the enemy team's ship ... we don't have tEnemyShip, tEnemyShipBaseState, or any files for them. Here's a solution:
- Make copies of PlayerShip.h, PlayerShip.cpp, PlayerShipBaseState.h, and PlayerShipBaseState.cpp, and name them EnemyShip.h, EnemyShip.cpp, etc.
- Go through the new copies, changing each instance of Player to Enemy, again make sure you catch the #include statements as well.
- Add the new files to the C++ project. (Go to
Project | Add to Project | Files, and select the file you want to add. It should appear in the list of files in the left hand window, then make sure you drag it to the desired directory - use the structure for the player team and ships as an example if you have any doubts.)
Fortunately in VC++ you can also automate this process: details to be posted shortly.
Example include layout: if you want to lay out the files and includes from scratch, here is what it looks like:
For each team, we can specify a different briefing message based on which race they are. This is done in the your_mission_name.cpp file, in the mDefineBriefings routine, for example:
void tMet_YourScriptName::mDefineBriefings( void )
{
// the enemy player gets the same briefing no matter what
for ( int32 i = kFederation; i <= kMirak; i++ )
{
fBriefingIndex[kEnemyTeam][i] = kEnemyBriefing_msg;
}
// the main player gets a different message if they're playing
// Mirak than if they're playing anything else:
for ( int32 i = kFederation; i < kMirak; i++ )
{
fBriefingIndex[kPlayerTeam][i] = kBriefing_msg;
}
fBriefingIndex[kPlayerTeam][kMirak] = kMirakBriefing_msg;
}
We can also dictate what is shown on the briefing map for the player, in the
mASCIIOverrides method (also in your_mission_name.cpp. For example:
void tMet_YourScriptName::mASCIIOverrides( tMapOverrides* Map )
{
tScript::mASCIIOverrides( Map );
Map->fTacticalMapIcon['G'] = kObjectPlayerShip; // show the player ship at map location G
Map->fTacticalMapIcon['H'] = kObjectEnemyShip; // show the enemy ship at map location H
Map->fTacticalMapIcon['I'] = kObjectEnemyShip;
}
Valid display objects include kObjectEmptySpace, kObjectNebula, kObjectBlackHole, kObjectFissure, kObjectOrganian,
kObjectPulsar, kObjectWormHole, kObjectSun, kObjectPlanet, kObjectAsteroid,
kObjectDustCloud, kObjectCorpse, kObjectEnemyBase, kObjectPlayerBase, kObjectEnemyShip,
kObjectAlliedShip, kObjectPlayerShip
.
In the PlayerTeam.cpp file, in the mScheduleNextMission method, we will include instructions to the dyna/metaverse on what it should do with the results of this mission.
This is done by setting a number of values in fMissionScheduler, I'll try to outline the values and settings below:
- fMissionScheduler.fVictoryLevel the victory level the player should be awarded, e.g.
- fMissionScheduler.fPrestige the amount of prestige the player should be awarded, e.g.
- fMissionScheduler.fBonusPrestige the amount of bonus prestige the player should be awarded, e.g.
- fMissionScheduler.fNextMissionScore I think this is the number of the next mission to be played, e.g. if you've got two missions that should be played back-to-back depending on results. (In single player campaigns, if you go to your Assets/Scripts/Campaigns folder, you'll find a .mct file for each type of campaign, which includes the list of missions, numbers (scores?) associated with each, prestige triggers, etc.)
- fMissionScheduler.fNextMissionTitle As above, only you're supplying the actual title of the mission you're recommending should be scheduled next. (I do think the dyna/metaverse only takes this as a recommendation.)
- fMissionScheduler.fMedal You can recommend a medal for the player, or update medal status, based on the mission results. Possible values for this (set bitwise it appears) include kNoMedals, kMedalRankOne, kMedalRankTwo, kMedalRankThree, kMedalRankFour, kMedalRankFive, kMedalMissionOne, kMedalMissionTwo, kMedalMissionThree, kMedalMissionFour, kMedalSpecialOne, kMedalSpecialTwo, kMedalSpecialThree, kMedalSpecialFour
- fMissionScheduler.fCampaignEvent: there are 3 kinds of campaign event: kLost, kRetire, kNone.
void tPlayerTeam::mScheduleNextMission( tVictoryCondition* VictoryCondition )
{
fMissionScheduler.fVictoryLevel = VictoryCondition->mCalcVictoryStatus( mGetTeam() );
fMissionScheduler.fPrestige = VictoryCondition->mGetPrestigePoints( fMissionScheduler.fVictoryLevel );
fMissionScheduler.fBonusPrestige = VictoryCondition->mGetBonusPrestige(); // player added bonus calculation routine
fMissionScheduler.fNextMissionScore = 0;
fMissionScheduler.fNextMissionTitle = "";
fMissionScheduler.fMedal = kNoMedals;
fMissionScheduler.fCampaignEvent = tTeamInfo::tMissionScheduler::kNone;
}
In the appropriate Team.h file (e.g. PlayerTeam.h) we establish identifiers for the possible ships on that team, e.g.
// in file PlayerTeam.h in file EnemyTeam.h
enum eCustomPlayerIDs enum eCustomEnemyIDs
{ {
kPlayerShip1 = 100, kEnemyShip1 = 200,
kPlayerShip2 = 101, kEnemyShip2 = 201,
kPlayerShip3 = 103, kEnemyShip3 = 202,
}; };
Ships for a team are created in the appropriate Team.cpp file, e.g. PlayerTeam.cpp for
primary player ships, EnemyTeam.cpp for primary opponent ships, etc.
The actual creation is carried out in mCreateShipsForTeam (options discussed below), and if the ship is human controlled we need to set that up in mTeamSetupComplete:
void tPlayerTeam::mTeamSetupComplete()
{
tTeamInfo::mTeamSetupComplete();
// this sets the first ship in the list to be the one the player
// starts out controlling
tShipIterator ship = mGetFirstShip();
Assert( *ship != NULL );
if ( *ship != NULL )
{
if ( mIsTeamHumanControlled() )
{
ship->mSetShipPlayerControlled();
}
}
}
The mCreateShip method expects the following fields:
- The (project) class type, apply typeid to the ship class, e.g. typeid(tPlayerShip)
- The kind of ship, e.g. "L-CC" to hardcode a Lyran command cruiser, or
shipScriptDescription.fClassName.c_str(), to extract a type from a dyna/metaverse ship - The map starting position for the ship, e.g. kStartPostion_I
- The MetaShipId, used to indentify the ship to the dyna/metaverse. kNoMetaShipID specifies that the ship is NOT to be left as a persistant ship in the metaverse once the mission ends.
- The ship id, e.g. kPlayerShip1
- The starting X, Y map coordinates of the ship
- The X, Y map coordinates the ship is facing towards at the mission start
- The name of the ship
- The available options for the type and nature of the ship, selected (bitmask) from amongst: kNoShipOptions, kStartPositionCanBeOffset, kStartPositionOffsetMask, kStartPositionBitAlignment, kNumStartPositionOffsets, kStartPositionOffsetE, kStartPositionOffsetW, kStartPositionOffsetSE, kStartPositionOffsetSW, kStartPositionOffsetS, kStartPositionOffsetN, kStartPositionOffsetNE, kStartPositionOffsetNW, kStartPositionOffsetOrigin, kCanAddToFleetUponCapture, kDeathUponCapture, kDeathUponDisengage, kCanBeRestricted, kCanBeCarrier, kCanBeEscort, kCanBeSublight, kCanBeScout, kCanBeMarine, kCanBeTournament, kCanBeSmallQShip, kCanBeLargeQShip, kPlaceHolderForNextConstant, kDefaultShipOptions = ( kCanAddToFleetUponCapture | kStartPositionCanBeOffset )
mCreateShip(typeid( tPlayerShip ), "L-CC", kStartPosition_G, // which map letter matches this ship kNoMetaShipID, // tells D2 not to leave this as a persistent ship kPlayerShip1, // id for the ship 0, 0, -1, -1, //x0, y0, are coordinates of ship // x1, y1 are coordinates it is pointing towards "Tikka Terror", // ship name kNoShipOptions ); // no ship options available
Rather than creating a ship just for this mission, in campaigns we usually want to use whatever ship or ships a player is currently flying in the campaign.
For example, the following extracts an opposing ship from the dyna/metaverse:
mCreateShip( typeid( tEnemyShip ), // draft the enemy team's ships from the dyna/metaverse
shipScriptDescription.fClassName.c_str(), // use whatever kind of ship is specified there
kStartPosition_H, // starting position
shipScriptDescription.fMetaDatabaseID, // dyna/metaverse ID for the ship
kEnemyShip1, // mission id for the ship
0, 0, // coordinates relative to the start position above
-1, -1, // facing relative to the start position above
shipScriptDescription.fCustomName.c_str(), // use the player's name for the ship
static_cast< eShipOptions >( kDefaultShipOptions | kCanBeCarrier ) ); // restrictions on what can be drafted
As mentioned, the mCreateShip method is invoked within the mCreateShipsForTeam method in the appropriate XTeam.cpp file.
If we want to give the player extra ships (either hardcoding a fleet, or temporarily adding to the player's current dyna/metaverse fleet) then we simply use multiple calls to mCreateShip.
For example, the following gives the player his dyna/metaverse fleet, plus control of a neutral base station:
mCreateShip( typeid( tPlayerShip ),
shipScriptDescription.fClassName.c_str(),
kStartPosition_H,
shipScriptDescription.fMetaDatabaseID,
kPlayerShip1,
0, 0,
-1, -1,
shipScriptDescription.fCustomName.c_str(),
static_cast< eShipOptions >( kDefaultShipOptions | kCanBeCarrier ) );
mCreateShip(typeid( tPlayerShip ),
"N-BS",
kStartPosition_G, // which map letter matches this ship
kNoMetaShipID, // tells D2 not to leave this as a persistent ship
kPlayerShip2, // id for the ship
0, 0, -1, -1, //x0, y0, are coordinates of ship relative to position G
// x1, y1 are coordinates it is pointing towards
"R and R stop", // base name
kNoShipOptions ); // no ship options available
We also have the ability to randomly generate a ship of a specific BPV, from a range of ship sizes. However THIS IS NOT TO BE USED FOR A METAVERSE CAMPAIGN. (I suspect this is because of the lack of a metaverse ship id ... this might wind up leaving lots of extra persistant ships on the map that can't be drafted.)
mCreateShip(typeid( tPlayerNPC1 ), // class type 85, // ship BPV kClassFrigate, // smallest hull size kClassDestroyer, // largest hull size 0.2, // allowable % variation from the specified BPV kStartPosition_Z, // start position kPlayerNPC1 ); // team idWe can even generate a ship later in the mission. To do so, when the appropriate event occurs (e.g. a timer goes off N turns into the mission) use the call fChildActor->mCreateShip (plus the usual collection of parameters) to spawn the new ship at whatever location you like. To go along with this, we should be able to make use of methods to manipulate which ships are on which teams:
iTruth mAddShipToTeamList( tCreateShipInfo& Info ); void mRemoveShipFromTeamList( tShipInfo* Ship );
It is also possible to duplicate an existing ship, with a call to mDuplicateShip. I've outlined the parameter list below
mDuplicateShip(PtrToShipToBeCopied,
MapPosition,
StartX, StartY,
FacingX, FacingY,
ShipName,
ShipOptions );
Finally, we can randomly generate a fleet in much the same way as we would randomly generate a single ship,
mCreateFleet(ShipClass,
TotalShips,
TotalBPV,
SmallestHullSize,
LargestHullSize,
VariantPercent,
MapPosition,
CustomID,
StartX, StartY,
FacingX, FacingY,
CustomName,
ShipOptions,
FleetRace );
OK, after a bit of experimenting it turns out we can bring a metaverse ship into a mission on a "delayed entry" basis. This means that the player can't do anything, and just sees a blank screen until their ship arrives in the mission. (Can't see a good reason for doing this in single player, but it has all sorts of nasty implications in online missions.)
As far as I can tell, the only place we can capture the information for a player's metaverse ship is inside the mCreateNewShip routine, which we can do thusly:
void tPlayerTeam::mCreateNewShip( const tShipScriptDescription& shipScriptDescription )
{
// store the settings from the player's metaverse ship
// so we can generate it later
SetPlayerShipDescription(shipScriptDescription.fMetaDatabaseID,
shipScriptDescription.fClassName.c_str(),
shipScriptDescription.fCustomName.c_str());
}
You'll note this involves the use of a new function, SetPlayerShipDescription. This is because
we need to store the player ship information until we decide to use it. In this example, I placed the access
routines in CommonDefs.cpp:
#includeThis also requires declarations in CommonDefs.h of course:int32 gPlayerShipMetaID; char *gPlayerShipType; char *gPlayerShipName; void SetPlayerShipDescription(int32 id, const char *type, const char *name) { // store the player ship's metaverse id gPlayerShipMetaID = id; // store the type of the player's metaverse ship int len = strlen(type) + 1; gPlayerShipType = new char[len]; strcpy(gPlayerShipType, type); // store the name of the player's metaverse ship len = strlen(name) + 1; gPlayerShipName = new char[len]; strcpy(gPlayerShipName, name); } int32 GetPlayerShipMetaID() { return gPlayerShipMetaID; } char *GetPlayerShipType() { return gPlayerShipType; } char *GetPlayerShipName() { return gPlayerShipName; }
void SetPlayerShipDescription(int32 id, const char *type, const char *name); int32 GetPlayerShipMetaID(); char *GetPlayerShipType(); char *GetPlayerShipName();Finally, somewhere along the line we need to actually bring the player's ship into the mission. In this example, it's done with a timer event:
void tPlayerTeamBaseState::mOnTimedInterval( int32 timerID )
{
static int count = 0;
if (timerID == kPlayerShipArrives) {
if (count > 0) return;
count = 1;
mGeneratePlayerShip(GetPlayerShipMetaID(), GetPlayerShipType(), GetPlayerShipName());
}
}
void tPlayerTeamBaseState::mGeneratePlayerShip(int32 id, const char *type, const char *name)
{
// get a handle for the team
tTeamInfo* playerteam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
// get the player's latest ship
playerteam->mCreateShip( typeid( tPlayerShip ),
type,
kStartPosition_I,
id,
tPlayerTeam::kPlayerShip2,
0, 0,
-1, -1,
name,
static_cast<eShipOptions>(kDefaultShipOptions|kCanBeCarrier));
}
Remember to add void mGeneratePlayerShip(int32 id, const char *type, const char *name) into
the PlayerTeamBaseState.h for this, and of course set up the timer itself.
All of this relies on setting up variables to remember what (of interest) has happened so far, telling the system to watch for specific kinds of events, and when those events occur adjust the appropriate variable values and set up other kinds of events.
What you can do is really only limited by your imagination and the amount of time you are willing to spend coding and debugging.
The specific events that are available, how to set them up, and how to handle them when they occur are listed in section 11.2, while the routines available to help you observe or change the conditions of specific teams or ships are listed in section 11.1.
I will, hopefully shortly, use this section to include a number of different examples along the lines of "I want this to happen, how do I make it so?".
We will need to:
- In a setup state, randomly generate the number of turns before the sabotage takes effect and start a timer for each case of sabotage (to go off in said number of turns). To do this, in the mBeginState method we can use the mRandomInt32 and mSetTimedInterval routines.
- When the timer goes off, we need to randomly select the effect and apply the event. Again we'll be using mRandomInt32, plus mSetSystemHealthFromOrig or mSetSystemHealthFromCurr, plus we'll set up a message to tell the player why their ship just deteriorated.
How to do it? I'll post the explanation soon, or you can look at the code in BaseVictoryState.h and BaseVictoryState.cpp for the simple campaign mission shown in section 13.
Here the goal is to get the AI to adapt, at least a little bit, to changing conditions.
Here's the rundown:
- Every second turn, the AI team will re-evaluate how the battle is going
- If the enemy team is significantly stronger (more BPV, less damage) than the player team, then it's goal will be to go for a capture
- If the enemy team is significantly weaker than the player team, then it's goal will be to run for the border and disengage
- For anything else, the team will take a normal combat attitude to the player team
To achieve this, in the enemy team's base state we'll check and see if it's an AI team. If so, we'll set up the timer that indicates when we should re-evaluate strategy:
void tEnemyTeamBaseState::mBeginState()
{
// if the team is AI controlled, then every second turn
// re-evaluate how the battle is going
tTeamInfo *enemyteam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
if (!enemyteam) return;
if (enemyteam->mIsTeamHumanControlled() == kFalse)
mSetTimedInterval(kTimerTurnsSet, kEvaluateAIStrategy, 2.0f);
}
To set the timer up, in our .h file we must set up an ID for the timer, i.e.:
enum eCustomTimerIDs
{
kEvaluateAIStrategy,
}
Now, when the timer goes off, we need to get the BPV of the current ships for both teams,
and the damage status of the current ships for both teams.
We will then use that to create a rating of the team strengths, and use the ratio of the
AI team's strength versus the player team's strength to decide what to do next.
void tEnemyTeamBaseState::mOnTimedInterval( int32 timerID )
{
if (timerID == kEvaluateAIStrategy) {
// time to reevaluate the AI's strategy for the team
// decide whether to destroy, capture, or disengage,
// and decide which ship is the key target for now
// first, get the BPV for the team,
// multiplied by (1 minus the damage percent) for the team
tTeamInfo *enemyteam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
if (!enemyteam) return;
// Note: both team->mGetCombatBPV and team->mGetTotalDamagePercent are based
// only on the ships currently in play
float EnemyStrength = enemyteam->mGetCombatBPV() * (100.0 - (enemyteam->mGetTotalDamagePercent()));
int32 enemyshipcount = enemyteam->mShipsCurrentlyControlled();
tShipInfo *ship;
// next, do the same thing for the player team
tTeamInfo *playerteam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
if (!playerteam) return;
float PlayerStrength = playerteam->mGetCombatBPV() * (100.0 - (playerteam->mGetTotalDamagePercent()));
// assess the relative strengths
float StrengthAssessment = EnemyStrength / PlayerStrength;
// if the player team is in much worse state than this team,
// then consider trying a capture
// if this team is in much worse shape than the player team
// then consider disengaging
// otherwise just treat is as normal combat
if (StrengthAssessment > 2.0) { // go for capture
fMissionInfo->mSetTeamRelations(static_cast<eTeamID>(kEnemyTeam), static_cast<eTeamID>(kPlayerTeam), kTeamAtWar, kGoalCapture, 1.0, kFalse);
} else if (StrengthAssessment < 0.75) { // run away, everyone scatter for the nearest border
for (int32 i = 0; i < enemyshipcount; i++) {
ship = enemyteam->mGetThisShip(i);
if (ship != NULL) ship->mDisengage(kByMapEdge, kVeryHighPriority);
}
} else { // continue normal play (aim to destroy the player ships)
fMissionInfo->mSetTeamRelations(static_cast<eTeamID>(kEnemyTeam), static_cast<eTeamID>(kPlayerTeam), kTeamAtWar, kGoalDestroy, 1.0, kFalse);
}
// set the timer to go off again in another two turns
mSetTimedInterval(kTimerTurnsSet, kEvaluateAIStrategy, 2.0f);
}
}
Whoops, change of plan - for the moment I've moved this into section 7.5 above.
There are lots of points to consider. First, ask yourself
- Who is going to be playing this?
Just me
My friends and I
Whoever is on the server I put this on
Whoever chooses to download it - Where are they going to be playing this?
Single player skirmish
Single player campaign
Online campaign
Multiplayer skirmish - How often are they going to play it?
Once per campaign
Repeatedly in a campaign
Whenever they select it (single/multiplayer skirmish)
The answers to those three questions tell you a lot about what your mission should address.
If the mission is once per campaign then you can afford to throw in as many specialized plot twists as you like - they'll play it rarely enough that the twists are still interesting. If it comes up repeatedly, however, or if it is a skirmish mission, then having a narrowly-focused plotline is only interesting until the player figures out the right sequence of choices. It might still be challenging from a technical point of view, but the plot is no longer the interesting part.
If the mission is something that occurs repeatedly then you need some way to keep the player off balance. The random ship generation can do that to a degree in skirmish missions, as can the semi-random process of drawing in other ships from the dyna/metaverse. However, it is rarely enough to keep the long term interest of an avid player (look at the online campaigns, many players routinely complete fifty or a hundred missions every week ...).
Pseudo-random ship placement can help somewhat, as can the inclusion of some random events (e.g. sometimes there's a third or fourth team generated, sometimes there isn't ... sometimes that team is your ally, sometimes it isn't).
Beefing up the AI teams can also help. If left to its own devices, the AI in most missions is quite predictable. However, you can set timers to explicitly check conditions, and if it seems appropriate change the AI orders and priorities. Oh, let's say have the player's AI allies suddenly panic and disengage at a critical time, or suddenly have several enemy ships suddenly ordered to try a high-priority capture on a crippled player ship. Dig through the AI commands and priority system, you CAN create a better AI!
Keep the difficulty settings in mind - if someone is flying on the beginner levels they shouldn't be hammered with an impossible mission, the game is hard enough on beginners as it is. On the other hand, if someone is flying at admiral level, then why not make 'em work for it? (evil grin)
On a similar note, the mission should be challenging but not insane - if the player has to read your mind to have any chance of surviving then it isn't a good mission (IMO). If there is something particularly unusual the player must do, then there should be some reasonable hint about it.
Getting the victory conditions and prestige awards right is also a biggie - overly large prestige awards or penalties can dramatically unbalance a campaign, but overly small ones can discourage the player. (I'd lean more to the latter than the former, but then I like long campaigns.) On the victory conditions - organize your conditions carefully and comprehensively ... there's nothing worse than coming up with an innovative solution to a difficult mission and then getting hammered by incorrect victory conditions because it was something the mission designer hadn't thought of or tested.
Test your campaigns before you turn them loose on the public!
Many scripters are pretty good at this, but there are a few who release missions
buggy enough to be Microsoft products.
Get ideas anyplace you can - look at all the missions posted for SFC, EAW, and OP, as well as any from other games that look relevant. "Borrow" ideas from TV shows, movies, real life, your latest dream/nightmare, whatever works!
Other than that, HAVE FUN!!!! Let the creative juices flow, and have a helluva good time with it. If the debugging gets you down, then walk away from it for a bit and go play! Hey - go get on SFC2.net's server, see what BBJones, Skull, Articfires, and Tantalus have dreamed up for us this week!
And, on behalf of everyone who plays this game, thanks for trying to come up with new ideas and new challenges!
I tend to do all my storage and computation of victory conditions in BaseVictoryState.h and BaseVictoryState.cpp, but I note that a more common practice seems to be to carry this out in states associated with the individual teams. Again, it's programming - you can do it any way that works and makes sense to you when you come back to modify (fix) it later.
There are two big issues in calculating victory conditions:
- Identifying all the possible combinations of results, and assigning a reasonable victory condition based on the specific combination.
- Accurately updating the combinations as each relevant event takes place.
The simplest case is just a "last team standing" scenario - if your team runs away, gets captured, or gets destroyed then you lose, otherwise you win.
This is a little dull for a custom scripted mission however.
You may want to alter the level of victory based on the relative damage between the teams, the number of ships which were captured, as opposed to destroyed, and the number which were destroyed as opposed to disengaging.
You may also want to alter the victory levels based on how long it took the player to achieve them.
There may also be very mission specific goals, e.g. delivering something to a planet, stealing something from another ship, successfully negotiating a deal with some other team, etc etc. These may far outweigh the combat considerations in the calculation of victory.
In terms of rewarding (or penalizing) a player, there are three primary means:
- prestige points (positive or negative)
- bonus prestige (positive or negative, though a negative bonus has always irked me)
- victory level
The victory levels available are kAstoundingVictory, kVictory, kDraw, kDefeat, kDevastatingDefeat, while the prestige awards can be almost any integer value. (If it is a campaign mission, however, keep in mind how unbalancing huge awards or penalties can be.)
The routine used to compute victory status is mCalcVictoryStatus, and I tend to write a custom routine which it in turn calls, e.g.:
eVictoryLevels tBaseVictoryState::mCalcVictoryStatus( eTeamID ID )
// Assumes there are two human teams, the player team and the enemy team
// The victory status for the enemy team is simply assigned as the
// opposite of the status for the player team
{
switch (fChildActor->mGetPlayerResults(kPlayerTeam))
{
case kPlayerAstVictory:
if (ID == kPlayerTeam) return kAstoundingVictory;
else return kDevastatingDefeat;
break;
case kPlayerVictory:
if (ID == kPlayerTeam) return kVictory;
else return kDefeat;
break;
case kPlayerDefeat:
if (ID == kPlayerTeam) return kDefeat;
else return kVictory;
break;
case kPlayerDevDefeat:
if (ID == kPlayerTeam) return kDevastatingDefeat;
else return kAstoundingVictory;
break;
default:
return kDraw;
}
}
This is a fairly simple case - if there are more than two teams then the results will
be more complicated to compute.
The mGetPlayerResults routine examines variables I store in BaseVictoryState.h, e.g. counting the number of ships on each team which disengage, or are destroyed or captured, tracking which specific objectives were met or not, etc. That is the topic of the next section.
The biggest trick is making sure that during the mission you track all the events that change the victory status for each team in the mission.
In the event handling routines I update these conditions. The absolutely crucial events to consider are the capture, destruction, and departure of ships on each team. The event handlers for each of these must identify changes in the overall victory status and must figure out if it is time for a mission to end. (Otherwise, one winds up in one of those endless Alt-F4 missions.)
Here are examples of handlers for those three events, also kept in BaseVictoryState.cpp:
void tBaseVictoryState::mOnDeath( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// get a handle for each team
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
tTeamInfo* pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kNPC1Team));
// see which team originally owned the dead ship and which one
// owned it just before it died
eTeamID NewOwners = static_cast<eTeamID>(ship->mGetTeam());
eTeamID FirstOwners = static_cast<eTeamID>(ship->mGetOriginalTeam());
// see how many ships each team has left
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
int32 pirateshipcount = pirateTeam->mShipsCurrentlyControlled();
if (FirstOwners == kNPC1Team) { // the pirate ship was destroyed
fChildActor->mSetTeamStatus(kNPC1Team, kTeamDestroyed);
} else if (FirstOwners == kPlayerTeam) { // one of the player team's ships was destroyed
if (playershipcount == 0)
fChildActor->mSetTeamStatus(kPlayerTeam, kTeamDestroyed);
} else { // one of the enemy team's ships was destroyed
if (enemyshipcount == 0)
fChildActor->mSetTeamStatus(kEnemyTeam, kTeamDestroyed);
}
// figure out if the scenario should end now
if (playershipcount == 0)
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses );
else if ((pirateshipcount + enemyshipcount) == 0)
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins );
}
void tBaseVictoryState::mOnCapture( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// get a handle for each team
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
tTeamInfo* pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kNPC1Team));
// see which team originally owned the captured ship,
// and which team owns it now
eTeamID NewOwners = static_cast<eTeamID>(ship->mGetTeam());
eTeamID FirstOwners = static_cast<eTeamID>(ship->mGetOriginalTeam());
// see how many ships each team has left
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
int32 pirateshipcount = pirateTeam->mShipsCurrentlyControlled();
if (FirstOwners == kNPC1Team) { // the pirate ship was captured
if (NewOwners == kPlayerTeam)
fChildActor->mSetTeamStatus(kNPC1Team, kCapturedByPlayer);
else if (NewOwners == kEnemyTeam)
fChildActor->mSetTeamStatus(kNPC1Team, kCapturedByEnemy);
} else if (FirstOwners == kPlayerTeam) { // one of the player team's ships was captured
if ((NewOwners != kPlayerTeam) && (playershipcount == 0))
fChildActor->mSetTeamStatus(kPlayerTeam, kCapturedByEnemy);
} else { // one of the enemy team's ships was captured
if ((NewOwners != kEnemyTeam) && (enemyshipcount == 0))
fChildActor->mSetTeamStatus(kEnemyTeam, kCapturedByPlayer);
}
if (FirstOwners == NewOwners)
fChildActor->mSetTeamStatus(static_cast<eTeamTypes>(NewOwners), kSurviving);
// figure out if the scenario should end now,
// i.e. has all of one side or the other left
if (playershipcount == 0)
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses );
else if ((pirateshipcount + enemyshipcount) == 0)
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins );
}
void tBaseVictoryState::mOnDisengaged( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// see which team originally owned the departed ship and which one
// owned it just before it left
eTeamID NewOwners = static_cast<eTeamID>(ship->mGetTeam());
eTeamID FirstOwners = static_cast<eTeamID>(ship->mGetOriginalTeam());
// get a handle for each team
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
tTeamInfo* pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kNPC1Team));
// see how many ships each team has left
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
int32 pirateshipcount = pirateTeam->mShipsCurrentlyControlled();
// update the status of the team that left,
// if that was the last ship on the team
switch (NewOwners)
{
case kPlayerTeam:
if (playershipcount == 0)
fChildActor->mSetTeamStatus(kPlayerTeam, kTeamDisengaged);
break;
case kEnemyTeam:
if (enemyshipcount == 0)
fChildActor->mSetTeamStatus(kEnemyTeam, kTeamDisengaged);
break;
default:
if (pirateshipcount == 0)
fChildActor->mSetTeamStatus(kNPC1Team, kTeamDisengaged);
break;
}
// if all the player ships are gone, or all the other ships are gone,
// then whether the player won or lost depends purely on whether or
// not the player got the pirate
if (fChildActor->mGetTeamStatus(kNPC1Team) == kCapturedByPlayer)
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins );
else
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses );
}
This routine sends the team id and the team results back, with the following bitmask (i.e. any combination) options for the results: kGameInProgress, kEnemyCaptured, kEnemyDestroyed, kEnemyDisengaged kPlayerWins, kPlayerDisengaged, kAllyDestroyed, kAllyCaptured, kAllyDisengaged, kPlayerLoses, kMissionFailed, kPlayerDestroyed, kPlayerCaptured, kLeftEarly, kExpellFromElite, kCampaignCompleted, kWinMission, kLoseMission
OK, that's victory conditions, what about prestige and bonus prestige?
The easiest way to set prestige is simply to tie it to the victory level, this is done in file BaseVictory.cpp in method mSetupState, e.g.:
void tBaseVictory::mSetupState()
{
tBaseVictoryState* baseVictoryState = new tBaseVictoryState( 300, 200, 50, -50, -100 );
mRegisterState( baseVictoryState );
mGotoState( typeid( tBaseVictoryState ) );
}
The numbers reflect the base prestige award/penalty for astounding victory down through devastating defeat.
When we're examining various events, we can also manipulate team prestige and bonus awards through various victory state access methods:
mGetPrestigePoints( eVictoryLevels Level ); mGetBonusPrestige(); mLookupPrestigeValue( eVictoryLevels Level ); mAddToPrestige( int32 X ); mAddToPrestige( eVictoryLevels Level, int32 X ); mAddToBonusPrestige( int32 X );
Now, suppose we decide that we want to scale the prestige awards based on the relative strengths of the teams involved. Let's try the following:
- We'll have very minimal standard awards, say (100, 50, 10, -10, 50)
- Everything else will be recorded as bonus prestige points
- Every time a player ship is destroyed, the player is penalized 100% of it's BPV, but scaled by the relative strength of the two sides. Similarly if an enemy ship is destroyed the player is awarded 100% of its BPV, also scaled by the relative strength of the two sides.
- For captured ships, the award/penalty will be 150% of the ship BPV (scaled again)
- For ships which disengage, the award/penalty will be 25% of the ship BPV (scaled again)
float tBaseVictoryState::mGetStrengthRatio()
{
// get the current relative strength ratios of the two teams
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle( static_cast< eTeamID >( kEnemyTeam ) );
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle( static_cast< eTeamID >( kPlayerTeam ) );
return (((float)(playerTeam->mGetCombatBPV())) / ((float)(enemyTeam->mGetCombatBPV())));
}
Now we'll update each of the death, destruction, and capture events in BaseVictoryState.cpp to
compute the relevant bonus prestige:
void tBaseVictoryState::mOnDeath( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// see which team owned the dead ship
eTeamID Owners = static_cast<eTeamID>(ship->mGetTeam());
if (Owners == kPlayerTeam) { // player ship was destroyed
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
mAddToBonusPrestige(0 - (ship->mGetShipBPV() * (mGetStrengthRatio())));
if (playershipcount == 0) {
mSetVictoryStatus(kPlayerDestroyed);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kLoseMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
} else // enemy ship was destroyed
{
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
mAddToBonusPrestige(ship->mGetShipBPV() * (mGetStrengthRatio()));
if (enemyshipcount == 0) {
mSetVictoryStatus(kEnemyDestroyed);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kWinMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
}
}
void tBaseVictoryState::mOnCapture( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// see which team owned the captured ship
eTeamID Owners = static_cast<eTeamID>(ship->mGetOriginalTeam());
if (Owners == kPlayerTeam) { // player ship was captured
// give the player a penalty for being captured
mAddToBonusPrestige(0 - (1.5 * ship->mGetShipBPV() * (mGetStrengthRatio())));
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
if (playershipcount == 0) {
mSetVictoryStatus(kPlayerCaptured);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kLoseMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
} else if (Owners == kEnemyTeam) // enemy ship was captured
{
// give the player a 75 point bonus for capturing the enemy
mAddToBonusPrestige(1.5 * ship->mGetShipBPV() * (mGetStrengthRatio()));
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
if (enemyshipcount == 0) {
mSetVictoryStatus(kEnemyCaptured);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kWinMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
}
}
void tBaseVictoryState::mOnDisengaged( tShipInfo* ship )
{
// check for null pointer
if ( !ship ) return;
// see which team owned the deaparted ship
eTeamID Owners = static_cast<eTeamID>(ship->mGetTeam());
if (Owners == kPlayerTeam) { // player ship disengaged
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam));
int32 playershipcount = playerTeam->mShipsCurrentlyControlled();
mAddToBonusPrestige(0 - (0.25 * ship->mGetShipBPV() * (mGetStrengthRatio())));
if (playershipcount == 0) {
mSetVictoryStatus(kPlayerDisengaged);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kLoseMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
} else if (Owners == kEnemyTeam) // enemy ship disengaged
{
tTeamInfo* enemyTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam));
int32 enemyshipcount = enemyTeam->mShipsCurrentlyControlled();
mAddToBonusPrestige(0.25 * ship->mGetShipBPV() * (mGetStrengthRatio()));
if (enemyshipcount == 0) {
mSetVictoryStatus(kEnemyDisengaged);
gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kWinMission );
fMissionInfo->mInvokeGameStatus(kTrue, kNoTeam);
}
}
}
In this section I have, for now, generally ignored routines used in initially setting up the mission, teams, and ships, since those are covered elsewhere. This section is mostly to catch everything not covered by sections 4 through 10.
During the mission, we may be interested in getting and/or setting information values relevant to the mission overall, a specific team, or a specific ship. In this section we'll give an overview to all three parts.
- 11.1.1 Getting/setting mission information via fMissionInfo
- 11.1.1.1: Team information/settings
- The first information we will look at (since it is needed for many other methods) is how to
get pointers to the teams in a mission. We use the mGetTeamHandle method, and as a parameter we
supply the team identifier (from the list created in CommonDefs.h).
An example is shown below.
// first we'll establish pointers to the two teams TeamInfo *pirateTeam, *playerTeam; pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam)); playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam)); - We can get the relations between two teams:
fMissionInfo->mGetTeamRelations(kPlayerTeam, kEnemyTeam); - We can alter the relations between one team and another using mSetTeamRelations and providing the two
teams, the new relationship, the new goal, an EPVfactor, and a boolean variable declaring whether or not the
relationships are supposed to be mutual (otherwise you are only altering one team's views towards the other).
The most common relationships are kTeamAllied, kTeamFriendly, kTeamNeutral, kTeamHostile, kTeamAtWar
and the goals are kGoalIgnore, kGoalCripple, kGoalCapture, kGoalDestroy. I'm not sure what the EPVfactor
is for, but using a value of 1.0 seems to work ok! E.g.
// set two teams as mutually hostile but ignoring ... fMissionInfo->mSetTeamRelations(kPlayerTeam, kEnemyTeam, kTeamHostile, kGoalIgnore, 1.0, kTrue);
- 11.1.1.2: Ship information/settings
- Get the target of a ship: mGetShipTarget: we pass the pointer to one ship as a parameter and get a pointer to the target back as the return value
- 11.1.1.3: Hex/D2 information/settings
- We can get the current difficulty settings, I assume 0 = lowest, 2 = highest as with the .ini and .gf settings
int32 setting = fMissionInfo->mGetDifficultyLevel() - Get the type of D2 hex the mission is located in: mGetHexType: I believe we create
a (class) variable of type tMetaLocationSpec and for this variable we create an expression
describing the type of hex we're interested in. We then pass the variable as a parameter to
mGetHexType, and we get back a boolean (iTruth) value saying yay or nay, is
the current hex of that type. The details on the tMetaLocationSpec class and related types
are in MissionMatchLocation.h. Here's a hypothetical example, I haven't tried it yet:
tMetaLocationSpec location( 5, kPlayerRaceHex, kAnyBase|kAnyPlanet ); if (fMissionInfo->mGetHexType(location)) { .... }The tMetalocationSpec constructor is used in campaign missions to specify what D2 hexes the mission can be generated in, e.g.
tMetaLocationSpec(1, kEnemyRaceHex, kDustCloudHex|kAsteroidHex) indicates the mission can be located in any hex where you are within 1 hex of an enemy hex and within 1 hex of either a dust cloud hex or an asteroid hex.The available options for specifying the race restrictions are:kPlayerRaceHex, kEnemyRaceHex, kAlliedRaceHex, kNeutralRaceHex, kAnyRaceHex, kFederationRaceHex, kKlingonRaceHex, kISCRaceHex, kRomulanRaceHex, kGornRaceHex, kLyranRaceHex, kHydranRaceHex, kMirakRaceHex, while the available terrain options are:kAnyTerrainHex, kEmptySpaceHex, kAnyBaseHex, kAnyPlanetHex, kAsteroidHex, kDustCloudHex, kBlackHoleHex, kShippingLaneHex, kCoreWorldHex, kHomeWorldHex, kColonyHex, kAsteroidBaseHex, kBaseStationHex, kBattleStationHex, kStarbaseHex, kBaseListeningPostHex, kBaseWeaponsPlatformHex .
- 11.1.1.4: Map information/settings
- We can get the map dimensions: mGetMapDimensions: we pass pointers to ints for the maximum X and Y coordinates, the values are set by the method
- We can set a goal indicator for teams or ships, and the indicator can be
either to a map location or another ship. Examples:
// here we assume playership and enemyship have type tShipInfo*, // toggle has value either kTrue or kFalse (toggle the indicator on/off) // x/ycoord are coordinates at which the indicator should appear // whichteam has team id's, such as kPlayerTeam, kEnemyTeam, etc fMissionInfo->mSetGoalIndicator(whichteam, enemyship); fMissionInfo->mSetGoalIndicator(whichteam, toggle, xcoord, ycoord); fMissionInfo->mSetGoalIndicator(playership, enemyship); fMissionInfo->mSetGoalIndicator(playership, toggle, xcoord, ycoord);
- We can generate a new map object, using its coordinates and the corresponding character symbol
from MissionMaps.cpp, e.g. creating a moon at coordinates 32,17:
fMissionInfo->mCreateMapObject('@', 32, 17);
Similarly we can add an icon to the map, e.g. fMissionInfo->mAddMapIcon(objecttype, xcoord, ycoord, subtype); where the object types are enumerated in MapObject.h and include things such as kObjectSun, kObjectPlanet, etc. I'm not sure where the subtypes are enumerated, will try to remember to look this up later.
- 11.1.1.5: Message information/settings
- We can display a message for a particular team/ship. The team id is from CommonDefs.h,
the message id is from MissionText.h, the ship ptr is NULL by default but you can specify
an individual ship, and the message type defaults to kMissionScriptMessage but can be
set to any of the following: kEngineerScriptMessage, kMissionScriptMessage, kScienceScriptMessage,
kFleetScriptMessage, kNonCommScriptMessage. E.g.:
fMissionInfo->mDisplayMessage(static_cast<eTeamID>(teamid), msgid, msgtype, shipptr); - We can add specific messages to the debriefings, e.g.
fMissionInfo->mAddToDebriefingList(kPlayerTeam, "you really sucked that time"); - We can add debugging messages to appear during the mission, e.g.:
fMissionInfo->mDebugMessage("This is what seems to be going on...");
- 11.1.1.6: Other misc. information/settings
- We can generate a random integer in a specified range:
int32 newnumber = fMissionInfo->mRandomInt32(lowvalue, highvalue); - We can make a button start or stop flashing on the player control panel using
mStartFlashingButton and mStopFlashingButton, supplying the appropriate string
for the button identifier.
Note that if the player actually pushes the flashing button, we can detect that and respond to it, see the events section 11.2.7 for details.
- The first information we will look at (since it is needed for many other methods) is how to
get pointers to the teams in a mission. We use the mGetTeamHandle method, and as a parameter we
supply the team identifier (from the list created in CommonDefs.h).
An example is shown below.
- 11.1.2 Getting/setting mission information via tTeamInfo pointers
- 11.1.2.1: Team information/settings
- We can get the id value for the team using mGetTeam, which returns a value which can be matched against the ids from the CommonDefs.h file
- We can get the race of a team using mGetRace, the possible races are kFederation, kKlingon, kRomulan, kLyran, kHydran, kGorn, kISC, kMirak, kOrion, kMonster, kTholian, kLDR, kWYN, kJindarian, kAndro, kNeutralRace, kMirror,
- We can determine if a team is human controlled using mIsTeamHumanControlled (returns kTrue or kFalse) or get a pointer to the ship which is currently controlled using mCurrentlyControlledShip
- We can get the combat BPV of the ships currently in play for a team, mGetCombatBPV()
- We can get the damage rating for the ships currently in play for the team: mGetTotalDamagePercent
This is given as a floating point value in the range 0.0 to 100.0, representing the appropriate percent. - We can assess how much damage was done to another team (hit count I presume) using mAssessDamages(targetteamptr)
- We can get the relationship with another team, e.g. mGetRelations(kEnemyTeam) and we can get the goal with respect to another team, e.g. mGetGoal(kEnemyTeam)
- We can set relations with another team using mSetRelations(teamid, relations, goals, 1.0)
- 11.1.2.2: Ship information/settings
- We can get the number of ships the team currently has in play using mGetShipsInPlayCount
- We can get also get ship counts for the team using:
- number in play: mGetShipsInPlayCount
- number remaining from original team: mShipsRemainingInPlayFromOriginalTeam
- number currently controlled: mShipsCurrentlyControlled - We can get pointers to the ships on a team. An example is shown below.
// establish pointers to the first ship on each of two teams tShipInfo *pirateShip, *playerShip; tShipIterator ship = pirateTeam->mGetFirstShip(); pirateShip = *ship; ship = playerTeam->mGetFirstShip(); playerShip = *ship;
- We can, I think, determine which is the team's flagship using mGetTeamFlag, this should return an index number (e.g. is it ship 1, 2, or 3)
- We can set the currently controlled ship using mSetCurrentlyControlledShip(shipptr), bet this could be used to really drive a player nuts!
- We can get a specific ship from the team by index, e.g. mGetThisShip(1) returns a tShipInfo pointer for the first ship in the list.
- 11.1.2.3: Team command and control information/settings
- We can remove a ship as the team's target using mRemoveShipAsTarget(shipptr)
- We can clear the current list of commands to the AI using mClearCommands
- We can tell a team to defend a particular ship, what to treat as a threat radius, what range to
follow a threat out to, and what defense priority to use via:
mDefendEntity(shipptr, threatradius, followradius, priority).
The AI priority levels are: kNeverPriority, kVeryLowPriority, kLowPriority, kMediumPriority, kHighPriority, kVeryHighPriority, kAbsolutePriority
- 11.1.2.4: Team/game status information/settings
- We can get the current game status using mGetGameStatus, returning values such as kGameInProgress, kEnemyCaptured, kEnemyDestroyed, kEnemyDisengaged, kPlayerWins, kPlayerDisengaged, kAllyDestroyed, kAllyCaptured, kAllyDisengaged, kPlayerLoses, kMissionFailed, kPlayerDestroyed, kPlayerCaptured, kLoseMission, kWinMission, kLeftEarly, kExpellFromElite, kCampaignCompleted. These are set as bitmasks, so combinations are possible.
- We can get the current event status of the team, mGetTeamStatus, this will return a value of type iNotifyEvents, i.e. a list of all the events being monitored for that team
- We can set the game status using mSetGameStatus (see the first list item under "learning things" above for a status list)
- 11.1.3 Getting/setting mission information via tShipInfo pointers
- 11.1.3.1: Team/game information/settings
- We can get the race of a ship: mGetRace
- We can get the current and original teams for the ship: mGetTeam, mGetOriginalTeam
- 11.1.3.2: Ship information/settings
- We can get the class of a ship by type using mGetClassType or by name using mGetClassName
- We can get the percent of damage to the ship so far, mGetDamagePercent
- We can get the BPV of the ship: mGetShipBPV
- We can get the current ship options list using mGetShipOptions. The options are set up in the scriptsdata.h file, and basically cover what special categories of ship are allowable, whether the ship can be captured or not, and where the ship placement can be relative to it's listed map starting position.
- Destroy the ship mDestroyShip or destroy it silently mDestroyShipSilently
- Reset the name of the ship mChangeName(msgid)
- Set the health of a system as a percent (float value between 0 and 1) of its original health, with a true/false flag as to whether
they're allowed to repair it or not:
mSetSystemHealthFromOrig(system, percent, flag). - Set the health of a system as a percent (float value between 0 and 1) of its current health, with a flag to indicate if damage should be
rounded up or not
mSetSystemHealthFromCurr(system, percent, flag)Note: setting the health to 0 destroys the weapon, setting the health to 0.5 stuns it, and setting the health to 1.0 repairs it. For example, ship->mSetSystemHealthFromOrig(kAllShieldsHardPoint, 0.5) destroys all the ship's shields.
Note: damage assigned in this way does NOT appear to be effective once the ship leaves the mission. I.e. if you destroy half the engines using SetSystemHealth, and the enemy destroys another 25%, when the ship leaves the mission only the 25% damage done by the enemy needs to be repaired.
The systems are specified by hardpoints, which is an extremely lengthy list, enumerated in sysbaseenums.h. Oh what the hell, here are most of them: kRandomInternalsHardPoint, kAllEnginesHardPoint, kAllShieldsHardPoint, kAllWeaponsHardPoint, kBridgeHardPoint, kFlagBridgeHardPoint, kEmergencyBridgeHardPoint, kAuxBridgeHardPoint, kSensorGroupHardPoint, kSensorHardPoint, kScannerHardPoint, kHullGroupHardPoint, kForwardHullHardPoint, kAftHullHardPoint, kCenterHullHardPoint, kExcessDamageHardPoint, kTransporterHardPoint, kTractorHardPoint, kMechTractorHardPoint, kShuttleBayHardPoint, kFighterBayHardPoint, kEngineGroupHardPoint, kRightWarpHardPoint, kRightWarpHardPoint, kLeftWarpHardPoint, kCenterWarpHardPoint, kAPRPowerHardPoint, kImpulsePowerHardPoint, kTotalEngineHardPoints, kBatteryHardPoint, kLabHardPoint, kBarracksHardPoint, kCargoHardPoint, kShieldGroupHardPoint, kShieldOneHardPoint, kShieldOneHardPoint, kShieldTwoHardPoint, kShieldThreeHardPoint, kShieldFourHardPoint, kShieldFiveHardPoint, kShieldSixHardPoint, kShieldSixHardPoint, kTotalShieldHardPoints, kShipSystemADD6HardPoint, kShipSystemADD12HardPoint, kShipSystemADD30HardPoint, kArmorHardPoint, kCloakHardPoint, kDamageControlGroupHardPoint, kDamageControlHardPoint, kInternalRepairHardPoint, kOfficerGroupHardPoint, kHelmOfficerHardPoint, kEngineerOfficerHardPoint, kScienceOfficerHardPoint, kWeaponsOfficerHardPoint, kSecurityOfficerHardPoint, kCommOfficerHardPoint, kCaptOfficerHardPoint, kProbeHardPoint, kHeavyWeapon1HardPoint, kNewFirstHeavyWeaponHardPoint=kHeavyWeapon1HardPoint, kHeavyWeapon1HardPoint,..., kHeavyWeapon10HardPoint, kWeapon11HardPoint,..., kWeapon25HardPoint, kNumberOfShipSystemHardPoints, kNewTotalWeaponHardPoints, .
- 11.1.3.3: Control/command information/settings
- We can get the current alert status of a ship, mGetAlertStatus
- Set the current ship alert status, mSetAlertStatus
- Set the deepscan status: mSetDeepScanStatus(OnOffFlag)
- Set the (AI) ship target and priority mSetShipTarget(shipptr, priority)
- Clear the (AI) ship's target list: mRemoveTargets
- Clear the (AI) ship's command list: mClearCommands
- Order an AI ship to disengage, how to disengage, and its priority mDisengage(method, priority): methods are kByAcceleration, kByMapEdge
- Order the AI ship to patrol, supplying a list of patrol points, a detection radius, and a priority: mPatrol(radius, points, priority). The patrol points are described in tmissionmap.h
- Order an AI ship to turn cloak on/off mCloak(flag)
- Order an AI ship to probe another ship mFireProbe(targetship, priority)
- Order an AI ship to defend another ship mDefendEntity(shipptr, threatradius, followradius, priority)
- Order an AI ship to follow another ship mFollowEntity(shipptr, priority)
- Order an AI ship to tractor another ship mTractorEntity(shipptr, xcoord, ycoord, priority) (to a specific x,y coord?)
- Setting the ship thrust and maximum speed mSetShipThrust(power), mSetShipMaxSpeed(speed),
- Set the ship to be player or AI controlled: mSetShipPlayerControlled, mSetShipAIControlled
- 11.1.3.4: Map information/settings
- We can get the start and end coordinates of a ship using mGetStartX, mGetStartY, mGetEndX, and mGetEndY
- We can get the distance between a ship and another ship, map object, or map location using mGetTacticalDistance, giving it as parameters either the X,Y coordinates, or a pointer to a ship, or a map object
- 11.1.3.5: Crew and supply information/settings
- We can get the rank of any of the ship officers using mGetOfficerRank(officer), officer types include kWeaponsOfficer, kEngineeringOfficer, kScienceOfficer, kCommOfficer, kHelmOfficer, kSecurityOfficer, kCaptainOfficer, kMaxOfficers while the ranks include kRookie, kJunior, kSenior, kVeteran, kLegendary,
- Add an item to stores or set the amount of an item to stores
mAddItemToStores(storestype, storesubtype, amount)
mAddItemToStores(storestype, transportertype, amount)
mSetItemInStores(storestype, storesubtype, amount)
mSetItemInStores(storestype, transportertype, amount) - Remove an item from stores, specified by either its ShipStores type or its Transporter item type: mRemoveItemFromStores(type, amount). The ship stores types cover kMissilesTypeI, kMissilesTypeIV, kSpareParts, kMarines, kSmall_Mines, kLarge_Mines, kTransporterItem, whereas the transporter items cover kTransGornEgg, kTransSpareParts, kTransCaptain, kTransBlueStar, kTransDilithiumCrystals, kTransGravTank, kTransMarineDude, kTransHarryMudd, kTransInfiltrator, kTransNovaMine, kTransRomulanAle, kTransTribbles, kTransAlienArtifact, kTransCaptainDude, kTransWeaponSchematic, kTransMedicalSupplies, kTransAwayTeamItem, kTransDiplomat, kTransInjuredDude, kTransMedicineJar, kTransScientists, kTransLifePodDude, kTransDeathPlague, kTransBlackBox, kTransPsionicDisruptor, kTransIonicProjector, kTransEngineers, kTransPrisoner,
- Set an officer name or rank, mSetOfficerRank(rankid), mSetOfficerName(msgid)
Once the team and ship creation has taken place, most of the action is controlled by watching for specific events and invoking special routines when the event takes place. For instance, if a ship reaches a certain area on the map we might want something to occur (get a message from a planet, enemy ships warp into the battle, whatever). Similary if the ship's mission is to deliver medical supplies to the planet, then when the supplies are delivered we might want to end the mission.
Generally speaking, we have to keep track of what has (and what has not) happened so far - i.e. the current state of the game. We can track this on several levels simultaneously: keeping track of the state of a team, the state of a specific ship, and the state of the mission with respect to victory conditions. The code for tracking and modifying the states is kept in various xxxState.h and xxxState.cpp files, along with code for setting up and dealing with (handling) the various events that effect the state. I.e., we want to place the handling in PlayerShipBaseState.h for handling events relevant to player ships, in BaseVictoryState.cpp for events relevant to victory conditions, etc.
For most events, the game does not automatically watch to see if they are taking place (this would create unnecessary processing demands, since many events are not relevant in most missions). As a result, we often need to invoke one routine to tell the system to begin watching for a particular kind of event, and another routine that actually deals with the event if/when it actually occurs.
There are many possible events and results, including things such as:
- Begin and end of event handling
There are typically mBeginState() and mEndState() routines that can be used to set up the events which must be monitored from the start of a mission, and to clean up matters at the end. These routines are automatically called. - 11.2.2 Time-based events
Often we want to schedule one event to take place a certain amount of time into a mission, or a certain amount of time after some other event. For this we have the mOnTimedInterval method. To use this, we specify how to measure time (turns, seconds, etc), give an identifier for the timer we want to have start, and specify how long it should run using the call mSetTimedInterval(timerformat, timerid, amountoftime). The mOnTimedInteval routine receives as a parameter the type of timer which went off so we can handle it appropriately. The available types of timer (borrowed from the scriptsdata.h file) are:kTimerEndGamePause, // use this to adjust the amount of seconds to pause before leaving the tactical game kTimerCountdownSet, // use this to display a countdown timer on the tactical screen kTimerCountdownAdjust, // use this to modify the countdown timer kTimerTurnsSet, // use thses to setup a timer callback using game turn time kTimerSecondsSet, // use these to setup a timer callback using seconds kTimerKillTimer, // used to stop a timer from going off again in the future
- 11.2.3 Events based on ship/system damage
We can track damage events for a ship or system:- mOnDeath is automatically generated when a ship is destroyed, and receives as a parameter a pointer for the ship that died (tShipInfo *)
- mOnCapture is automatically generated when a ship is captured, and also receives as a parameter a pointer for the captured ship. Not that by the time this event is called the ship has changed ownership due to the capture, so be careful when figuring out which team captured it from which other team.
- mOnDamage tracks damage to a ship, but must be turned on first using mSetShipCallbackEvents(kNotifyDamage). The handler recieves as parameters a pointer to the damaged ship, then a pointer to the ship that damaged it, then a specifier for the type of damage taken.
- 11.2.4 Events based on location/proximity
The position of a ship is often relevant to mission goals, so there are a number of available events:- mAtDistance is called when a ship gets within a certain range of a certain map position. To use this, we must specify the range and the position with mTrackTacticalDistance(distance, xcoord, ycoord). The handler receives as a parameter a pointer to the ship which has reached the indicated distance.
- mAtDestination is called when a ship reaches a specific location, which must first be identified with mSetFinalDestination(xcoord, ycoord). This handler also receives as a parameter a pointer to the ship which has reached its destination.
- mOnDisengaged this is automatically called when a ship disengages (leaves the map), and the handler receives as a parameter a pointer to the ship which disengaged.
- mOnBeginOrbit and mOnEndOrbit are called when a ship enters/leaves orbit, but must be set up with calls to mSetShipCallBackEvents(kNotifyBeginOrbit) and mSetShipCallbackEvents(kNotifyEndOrbit) respectively. Both routines receive as a parameter a pointer to the ship which just entered/left orbit.
- 11.2.5 Events based on material/personnel movement
There are a number of events which deal with moving a player, key personnel unit, or key item from one ship (or planet or base) to another.- Players can move from one ship to another, effectively changing their command ship. To handle this, we use mOnChangingShip, which is called automatically and which takes as a parameter a pointer to the ship the player has arrived at.
- We can use transporters to move an item from one ship to another, in which case mOnTransportedItem is the event handler. To set this up we need to call mSetShipCallbackEvents(kNotifyTransportedItem), and the event handler receives as parameters pointers to the target ship, the source ship, and an identifier for the type of item moved.
- There is also an event handler called mOnSpecialTransport - I guess this might come up for things like alien abductions, this handler receives as a parameter just a pointer to the ship affected. To set up this we need to call mSetShipCallbackEvents(kNotifySpecialTransport)
- 11.2.6 Events based on communication and state
During the mission, we can present the player with different communication options: e.g. generate a couple of buttons on the communication screen, and the player can choose to send (or not) a particular message. The messages might be orders for the crew, or communications with non-player ships or teams. When the player presses one of the commication buttons that generates a specific event, and we write the event handler to simulate the reaction of whoever was supposed to receive the message.The setup process is as follows:
- For each button choice, create a value in an enumerated type, e.g. eCommStates in the appopriate XShip.h file
- Register the communication state in the matching XShip.cpp file, e.g.
team->mRegisterCommMessage(kChosenStateId, kNewCommStateId, mGetShipID(), kMatchingButtonMsg_btn);, implying (I think) that if we were in the state corresponding to kChosenStateId and someone pushed the button with label kMatchingButtonMsg_btn then go to the state corresponding to kNewCommStateId - Generate the button when you're handling some other event, e.g. with
team->mGotoCommState(shipid, kChosenStateId); - Insert the code to handle the button press in mOnCommButtonPress, using if (buttonID == kChosenStateId) ....// do whatever
Similarly we can register states, generate a change of state, and handle the change of state using mRegisterState, mGoToState, and mOnStateChange respectively. The states themselves, however, are classes - thus the standard approach is to create a .h and .cpp file for each state, and include all the relevant code. For example, in the PlayerTeam.cpp file we might create the states and pick an initial one:
void tPlayerTeam::mSetupState() { mRegisterState( new tPlayerTeamInitialState( ) ); mRegisterState( new tPlayerTeamAnotherState( ) ); mRegisterState( new tPlayerTeamThirdState( ) ); mGotoState( typeid( tPlayerTeamInitialState ) ); }Then that state could be set up in its own class in PlayerTeamInitialState.h and .cpp, and in the .cpp file we could initialize things in mBeginState method and include handlers for all the events relevant to that state. - 11.2.7 Other assorted events
There are a wide variety of other events, including:- mOnAlertStatusChange notifies us when a ship has changed alert status, and takes as parameters a pointer to the ship and the new alert status. To set this up we need to call mSetShipCallbackEvents(kNotifyAlertStatusChange)
- mOnDeepScan notifies us when a ship has turned deep scan on or off, receiving as a parameter a pointer to the scanning ship and a flag for whether scanning is now off or on. It must be set up using mSetShipCallbackEvents(kNotifyDeepScan)
- mOnProbeLaunch notifies us when a probe has been launched, receiving as a parameter a pointer to the launching ship. It must be set up using mSetShipCallbackEvents(kNotifyProbeLaunch)
- mOnBeginTractor, mOnEndTractor notify us when tractors have been turned on or off, and receive two parameters: pointers to the target and tractoring ship respectively. To initiate the begin tractor event we need to call mSetShipCallbackEvents(kNotifyBeginTractor), and for the termination we can call mTractorEntity with the ship pointer, x/y coordinates, and a priority level. (Haven't tried to puzzle out what the coordinates are for yet, maybe the spot to tow the target ship to?)
- mOnFlashingButtonPressed notifies us when a flashing button has been pressed by the player (e.g. during the tutorials). This can be set up using mStartFlashingButton with a specifier for the button type.
- mOnShipSystemUpdate notifies us of the current value of a particular ship system. The parameters are the ship pointer, type of update (value or percent), system hardpoint, and new system value. For this to be called, the player must have initiated either shipptr->mGetHealthOfSystem(systemtype) or shipptr->mGetMaxHealthOfSystem(systemtype). The list of available system types is quite large, so you can look it up in file sysbaseenums.h, the enumerated type is eSystemHardPoints
- mOnShipStoresUpdate notifies us of a change to a particular kind of stored items in a ship. The parameters are the ship pointer, type of item (out of kMissilesTypeI, kMissilesTypeIV, kSpareParts, kMarines, kSmall_Mines, kLarge_Mines, kTransporterItem ), the subtype of the item (out of any bitmap combination of kStandard, kBig, kSpeed_Med, kSpeed_Fast), and the number in storage. For this to be called the player must have initiated shipptr->mGetAmountOfStore(itemtype) or shipptr->mGetMaxAmountOfStore(itemtype).
- mOnHostChanged notifies us when the mission host has changed, and is on automatically.
- mOnPlayerLeaving notifies us when a player has left, and is on automatically. The player number is received as a parameter.
- There is one player ship, hard-coded to be a Lyran CC
- There is one enemy ship, hard-coded to be an Orion CA-1
- The mission description, briefing, start message, and debriefing messages have been customized.
- We have added a timer which taunts the player if they haven't won after about 12 turns, and then another to taunt the player further if they still haven't won 10 turns later
- The player and the pirate start a lonnnggg way apart, with the pirate location hidden. Once every turn the navigator will tell the player whether they have gotten closer to or farther away from the pirate. This goes on until the player gets within normal scanner range of the pirate.
- The game ends when either ship is destroyed, captured, or disengages
- The player gets an Astounding Victory for capturing the pirate, a Victory for destroying the pirate, a Defeat for letting the pirate get away, and a Devestating Defeat for being captured or destroyed. Any other result is a Draw.
- The pirate is just hanging out by an asteroid, and will ignore the player until attacked.
We will start out creating just the basic skirmish part - setting up teams, relations, ships, victory conditions, and briefing/debriefing messages.
Once that works, we will add the overall game timer and messages to taunt the player if they are too slow working through the mission.
Once that works, we will add the periodic navigator updates - figuring out if we are getting closer to the pirate ship or farther away from it.
By this point, you should have a good idea of how to manipulate a basic mission, and determine/set up some of the information you need for event handling.
We'll go through exact instructions to set up the basic teams, ships, victory conditions, and messages to complete a working script. Once that is done, we'll go back and revise the mission to add some simple timers and in-game messages to torture the player, producing a new complete script. Finally, we'll go back and revise it yet again to add the ability to track our distances from the enemy ship and give the player updates on our progress, producing our final complete version of the script.
- 12.1.1: Getting the basic mission running
Particular thanks to cam78 for his tutorial on setting up missions, I never would have gotten through these steps the first time without it!- I'm assuming that at some point you went through the steps in setting up the API - if you've never done that then go back and do it now.
- Now we want to set up a new skirmish mission, so if you haven't already done so go to the section on setting up a new script, picking Historical as the type of mission (step 3) and giving your mission whatever name you want. In this example, I've used His_TestSkirmish as my mission/script name.
- First, our mission is only going to have two teams: the player's team and an enemy team (the pirate).
The script wizard that created our files actually included basic setup for a couple of additional teams, so the first thing we're going to do is a bunch of cleaning and deleting to get rid of those extra teams.- Open the file CommonDefs.h, and look for the following enumerated type:
enum { kPlayerTeam = kTeam1, kPlayerNPCTeam, kEnemyTeam, kNPC1Team, };This lists all the teams, and we want to get rid of the ones that aren't player or enemy. While we're at it, we'll throw in a name for the enumerated type as well, may save some grief later:enum eTeamTypes { kPlayerTeam = kTeam1, kEnemyTeam, }; - OK, now we've got to do a bunch of deleting in the main script file: His_yourscriptname.cpp,
e.g. mine is His_TestSkirmish.cpp.
First, look for a method called mScriptSpecs, and inside this we want to delete the mCreateTeamSpec calls for the two teams we've eliminated. The two parts we're deleting should look something like:const tTeamSpec& team2 = mCreateTeamSpec("PlayerNPCTeam", static_cast<eTeamID>(kPlayerNPCTeam), kMaxChance, kTrue, kNPCTeam, kMaxChance, kSpecPlayableRace, kAnyRace, typeid(tPlayerNPCTeam));and,const tTeamSpec& team4 = mCreateTeamSpec("NPC1Team", static_cast<eTeamID>(kNPC1Team), kMaxChance, kTrue, kNPCTeam, kMaxChance, kSpecPlayableRace, kAnyRace, typeid(tNPC1Team));Don't worry about what this stuff does right now, just delete it.
OK, now if you look at the two team creations that are left there, the first one is for team 1, the second is for team 3. No good - we want to renumber team 3 as team 2, i.e.
change const tTeamSpec& team3 to const tTeamSpec& team2
We're almost through this part. If you look a little further down the file you'll seeSpecs->mSetupTeam(team1); Specs->mSetupTeam(team2); Specs->mSetupTeam(team3); Specs->mSetupTeam(team4);
Well, we've only got two teams left, so delete those last two lines. - Alrighty, still working in that main .cpp file (e.g. His_TestSkirmish.cpp),
we'll try to clean up the relationships and goals of the two teams.
Look for the method called mStartMission() (a little farther down in the file).
In here, you'll see a line const int kRelationsCount = 4; but we need this to reflect the number of teams actually around, so change the 4 to a 2.
Below it, you'll see a teamList array declaration, we want this to just include our two teams, so change it to look like:int32 teamList[kRelationsCount] = { kPlayerTeam, kEnemyTeam, };Now down below that is a great ugly declaration for a two-dimensional array of strings, where these strings represent the relationships and goals between each possible pair of teams. We've eliminated two of the four teams, so we need to completely rewrite this beastie:std::string relationships[kRelationsCount][kRelationsCount] = { //Plyr = kPlayerTeam, //Nme = kEnemyTeam, // Plyr Nme /*Plyr*/ "--", "WD", /*Nme */ "HI", "--", };The WD means the player is at war with the pirate and the goal is to destroy the pirate (although of course what the player actually does is completely up to them).
The HI means the pirate is hostile to the player and is ignoring the player. The pirate won't do anything unless the player attacks, in which case the pirate will go to a "war" footing and will fight back.
- Open the file CommonDefs.h, and look for the following enumerated type:
- OK, I think we're about done on the cleanup section - now might be a good time to try building the script just so we can check if we've introduced any glitches (probably typos). Go to the Build menu, and try to build your script (probably the second or so option down). If it compiles cleanly great, otherwise errors will be displayed in the build window at the bottom of the screen, read the first error message and double click on it to bring up the point in the code where the error was detected. (Don't worry about the other errors until you fix the first one, often that one error will be the source of many of the other error messages as well.)
- Now, let's set up the mission map. Open the MissionMaps.cpp file, and examine the large text
array it contains. This is essentially an ascii map of the playing area. Each . represents a
10-hex segment of empty space, and we can add terrain by changing specific dots to different characters.
You'll see a complete list of the terrain symbols in comments in the file.
For each ship, we need to specify where it is, and which way it is facing.
To specify a position, we use an uppercase letter in the range G-Z. Let's use G for the player and H for the pirate.
To specify facing, we use the matching lowercase letter. E.g. if we put a small g on the map, the player's ship will face from the uppercase G towards the lowercase g (and similarly for the pirate with H/h).Put the two ships wherever you like, and maybe put a small asteroid (character [ beside the pirate.
In my mission map, I put the two ships a long way apart, but more or less facing each other. - Let's set up the mission messages next. We'll only use the defaults for now, and add others when we do the
next complete version of the script.
Open the MissionText.cpp file, and examine the list of default strings it contains. You can customize these messages by altering the string to be whatever you want, but for now don't add any new strings or delete any existing ones - simply change the contents of the strings that are there. (We'll go into the why's in the creation of the next version of the mission.)
The string names are reasonably self explanatory:
- the kTitle_msg is the mission title that is shown to the player when they're selecting missions
- the kDescription_msg is the description of the mission shown to the player
- the kBriefing_msg is the description which appears when the player checks their mission briefing while performing the mission
- the kAstoundingVictory_msg, kVictory_msg, ... etc are the debriefing messages the player receives after the mission, depending on how well or how poorly they've done.
All these types of messages will (as far as we're concerned) automatically turn up in the right place at the right time.
- OK, lets go back and make sure the mission and team specs are set up correctly.
Open up the main script file (e.g. His_TestSkirmish.cpp) and look for the mScriptSpecs method again. (This is the one where we earlier deleted the lengthy setups for two of the teams.)Here is the version we want for that routine, I've included lots of comments in it to explain what I think is going on:
void tHis_TestSkirmish::mScriptSpecs( tMissionSpec* Specs ) { Specs->fMissionTitle = Messages[kMissionTitle_msg]; // sets mission title from MissionText.h Specs->fMissionDescription = Messages[kDescription_msg]; // sets mission description as above Specs->fMissionType = kHistoricalMission; // see below for the mission types I'm interested in // Tutorial means tutorial, Historical means skirmish, Campaign means D2 Specs->fMetaLocationSpec = tMetaLocationSpec( 1, kAnyRaceHex, kAnyTerrainHex ); // I *think* this determines where in the dynaverse this can occur // - the number is the D2 hex range for the mission // - the second parameter is which racial territory the mission can appear in // (kPlayerRaceHex, kEnemyRaceHex, kAlliedRaceHex, kNeutralRaceHex, kAnyRaceHex, // kFederationRaceHex, kKlingonRaceHex, kRomulanRaceHex, kGornRaceHex, kLyranRaceHex, // kHydranRaceHex, kMirakRaceHex, kISCRaceHex) // - the final parameter is the required terrain to get the mission to appear // (any combination of kAsteroidHex, kNebulaHex, kBlackHoleHex, kShippingLaneHex, // kDustCloudsHex, kEmptySpaceHex, kAnyTerrainHex, kBaseStationHex, kBattleStationHex, // kStarbaseHex, kBaseWeaponsPlatformHex, kBaseListeningPostHex, kAnyBaseHex, // kHomeWorldHex, kCoreWorldHex, kAsteroidBaseHex, kColonyHex, kAnyPlanetHex) Specs->fMinDate = kMinDate; // earliest campaign year the mission can occur in (D2) Specs->fMaxDate = kMaxDate; // latest campaign year the mission can occur in (D2) Specs->fBandwidthPart = kAllBand; Specs->fPlayerRace = kSpecLyran; // makes the mission available to Lyrans only (my preference, deal with it!) // we can choose from Fed, Kling, Romulan, Lyran, Gorn, Hydran, ISC, or Mirak // and join them together with the or operator | (fPlayerRace is evaluated bitwise) // e.g. = kSpecLyran | kSpecFed; Specs->fMenuStates = kDisableCustomSkirmish; // disables player customization buttons // The buttons still LOOK like they're available to the player, but whatever they select // is actually ignored // Having done this, we will need to explicitly choose and assign player and enemy ships // An alternative would be to selectively enable some buttons, using values such as kEnableSupplyDock // create specs for each and every team const tTeamSpec& team1 = mCreateTeamSpec( "Player Team", // team name static_cast< eTeamID >( kPlayerTeam ), // eTeamID kMaxChance, // float, chance team is available kTrue, // true if the team is required, false otherwise kPrimaryTeam, // eTeamType (kNPCTeam, kPlayableTeam, kPrimaryTeam, kPrimaryOpponentTeam) kMinChance, // float, chance team can be playable by AI kSpecPlayableRace, // iMissSpecRace, racial (bitmask) combination selected from // kSpecFed, kSpecKling, kSpecLyran, kSpecHydran, kSpecGorn, kSpecRomulan, kSpecISC, kSpecMirak, // kSpecNoRace, kSpecTholian, kSpecLDR, and a bunch of others kAnyRace, // iRaceCriteria: bitmask, the MissSpecRace list using any combination of // kSameAs, kAnyEnemyOf, kWorstEnemyOf, kAnyAllyOf, kBestAllyOf, kAnyRace, kDifferentThan // e.g. if the iMisSpecRace was kSpecFed and the iRaceCriteria was kAnyEnemyOf then the // combination of the two would describe any race that was an enemy of the Federation typeid( tPlayerTeam ), kNoTeamTag, // eTeamTag - the letter associated with the team in multiplayer Messages[kMissionTitle_msg] ); // team mission title const tTeamSpec& team2 = mCreateTeamSpec( "Enemy Team", static_cast< eTeamID >( kEnemyTeam ), kMaxChance, kTrue, kNPCTeam, kMaxChance, kSpecPlayableRace, kAnyRace, typeid( tEnemyTeam ) ); // given the specs, set up each team Specs->mSetupTeam( team1 ); Specs->mSetupTeam( team2 ); } - We're getting there, but we still need to get ships for the players and figure out victory conditions.
Let's create some ships for the two teams first. There are a TON of ways to do this, I'm going to cop out and
take the easiest one - we'll just hardcode two specific choices.
First let's create the player ship, open up PlayerTeam.cpp and find mCreateShipsForTeam. Let's replace the entire body of this routine so that it looks like:
void tPlayerTeam::mCreateShipsForTeam() { // Here we will explicitly create the player ship as a Lyran CC mCreateShip(typeid( tPlayerShip ), "L-CC", kStartPosition_G, // which map letter matches this ship kNoMetaShipID, // tells D2 not to leave this as a persistent ship kPlayerShip1, // id for the ship 0, 0, -1, -1, //x0, y0, are coordinates of ship // x1, y1 are coordinates it is pointing towards "Tikka Terror", // ship name kNoShipOptions ); // available eShipOptions (bitmask combination) are: // kNoShipOptions, kDefaultShipOptions, kStartPositionCanBeOffset, // kCanAddToFleetUponCapture, kDeathUponCapture, kDeathUponDisengage, // kCanBeRestricted, kCanBeCarrier, kCanBeEscort, kCanBeSublight, // kCanBeScout, kCanBeMarine, kCanBeTournament, kCanBeSmallQShip }The comments are, of course, optional and justmeant to explain what the choices areFollowing a similar path, let's create the enemy ship. Open up EnemyTeam.cpp and find mCreateShipsForTeam and replace it with:
void tEnemyTeam::mCreateShipsForTeam() { mCreateShip( typeid( tShipInfo ), "O-CA+1", kStartPosition_H, kNoMetaShipID, kEnemyShip1, 0, 0, -1, -1, "One poor dead pirate", kNoShipOptions ); }Note, this requires the addition of kEnemyShip1 to our EnemyTeam.h file, just as we must ensure kPlayerShip1 is defined in the PlayerTeam.h file. Add the appropriate types within the tEnemyInfo and tPlayerInfo classes:enum eCustomIDs { kEnemyShip1 = 200, // similarly, kPlayerShip1 in the PlayerTeam.h file }; - Now the tricky bit, let's figure out victory conditions. We have to make sure that if the player runs away, gets
destroyed, or gets captured then the player loses. On the other hand, if the pirate runs away, gets destroyed, or
gets captured then the player loses. Additionally, we would like to distinguish between the levels of win/loss:
Astounding Victory, Victory, Draw, Defeat, Devastating Defeat.
We're going to set it up so that all these things are tracked in the BaseVictory and BaseVictoryState files (.cpp and .h). The way we'll do that is to set up a variable that records how well/poorly the player is doing, and when different game events occur we'll update that variable. When it comes time to end the mission, we'll check the current value of that variable to decide what kind of a result to award.
- First, in BaseVictory.h, we add an enumerated type describing the possible mission results
enum ePlayerWinStatus // define the possible player win/loss states, // to be tracked during the mission { kPlayerAstVictory, kPlayerVictory, kPlayerDraw, kPlayerDefeat, kPlayerDevDefeat, }; - Second, in the tBaseVictory class, also in BaseVictory.h, we add a variable and
access routines to track the current mission status:
class tBaseVictory : public tVictoryCondition { public: tBaseVictory( ); tBaseVictory( tTeamInfo* team ); void mSetupState(); // // Accessors. // // returns current player win/no-win status ePlayerWinStatus mGetPlayerResults(){return fPlayerResults;} // // Modifiers. // // sets current player win/no-win status void mSetPlayerResults(ePlayerWinStatus winstatus) {fPlayerResults = winstatus;} private: // // Victory attributes. // // records current player win/loss status ePlayerWinStatus fPlayerResults; }; - Third, in BaseVictoryState.cpp we specify how victory is calculated using our variable:
eVictoryLevels tBaseVictoryState::mCalcVictoryStatus( eTeamID ID ) { // pretty basic, the variable in this version tells us exactly what kind of victory to return switch(fChildActor->mGetPlayerResults()) { case kPlayerAstVictory: return kAstoundingVictory; case kPlayerVictory: return kVictory; case kPlayerDefeat: return kDefeat; case kPlayerDevDefeat: return kDevastatingDefeat; default: return kDraw; } } - Fourth, also in BaseVictoryState.cpp we specify how to update the variable if a ship is destroyed:
void tBaseVictoryState::mOnDeath( tShipInfo* ship ) { if ( !ship ) return; // determine which team's ship died eTeamID team = ship->mGetTeam(); // in this case, there are only two teams and one ship per team // if the player ship died, set the mission result to a devastating defeat if(team == static_cast< eTeamID >( kPlayerTeam ) ) { //Set this before calling mSetGameStatus fChildActor->mSetPlayerResults(kPlayerDevDefeat); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses ); } // otherwise the enemy ship died, set the mission result to victory else { fChildActor->mSetPlayerResults(kPlayerVictory); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins ); } } - Fifth, still in BaseVictoryState.cpp we specify how to update the variable if a ship disengages:
void tBaseVictoryState::mOnDisengaged( tShipInfo* ship ) { if ( !ship ) return; // determine which team's ship disengaged eTeamID team = ship->mGetTeam(); // in this case, there are only two teams and one ship per team // if the player ship disengaged, set the mission result to a defeat if(team == static_cast< eTeamID >( kPlayerTeam ) ) { //Set this before calling mSetGameStatus fChildActor->mSetPlayerResults(kPlayerDefeat); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses ); } // otherwise the enemy ship disengaged, set the mission result to a draw else { fChildActor->mSetPlayerResults(kPlayerDraw); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins ); } } - Finally, yet again in BaseVictoryState.cpp, we specify how to update the variable if a ship is
captured. We have to be careful here, since by the time this routine gets called the ship has changed hands
(hence if the pirate ship was captured it now shows up as being on the player team).
void tBaseVictoryState::mOnCapture( tShipInfo* ship ) { if ( !ship ) return; // determine which team's ship got captured, note we look for the original team owners of the ship, // because it has just changed hands eTeamID team = ship->mGetOriginalTeam(); // in this case, there are only two teams and one ship per team // if the player ship got captured, set the mission result to a devastating defeat if(team == static_cast< eTeamID >( kPlayerTeam ) ) { //Set this before calling mSetGameStatus fChildActor->mSetPlayerResults(kPlayerDevDefeat); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerLoses ); } // otherwise the enemy ship got captured, set the mission result to astounding victory else { fChildActor->mSetPlayerResults(kPlayerAstVictory); gScriptInterface.mSetGameStatus( static_cast< eTeamID >( kPlayerTeam ), kPlayerWins ); } }
- First, in BaseVictory.h, we add an enumerated type describing the possible mission results
- Now jump to the section on building and incorporating the script so you can try out your new mission! Since this is a skirmish (historical) mission, it'll be under Single player | Skirmish | Lyran.
- 12.1.2: Adding a mission timer and in-game message
OK, let's open up the mission we created above (go into your workspace with explorer and double-click on the .dsw file) and we'll set up a simple timer and when it goes off we'll fire a message to the player.- We'll do this by editing PlayerShipBaseState.h and PlayerShipBaseState.cpp to create a specific kind of timer event, and create a variable to keep track of (in a general sense) how long the mission has taken, and we'll generate and respond to time events.
- First the easy part, we'll create an enumerated data type which specifies the kinds of timers we'll use
(right now there will just be one kind). In PlayerShipBaseState.h add the following:
// create a timer that will be used in tracking total mission time enum eTimeIDs { kMissionTimeID, }; - Now we'll create an enumerated type categorizing how long the mission is taking: we'll start out treating
it as a fast mission, after a while we'll downgrade that to medium, and after a while we'll downgrade that to slow.
Add the following enumerated type to PlayerShipBaseState.h
// create classifiers to define the player's mission speed as fast, medium, or slow enum eMissionSpeed { kFast, // player completes mission in less than 12 turns kMedium, // player completes mission in less than 22 turns kSlow, // player takes at least 22 turns to complete mission }; - Now we're going to add a private variable and two public access routines to the tPlayerShipBaseState class (also in
PlayerShipBaseState.h). These will be used to get and set the rough amount of time the mission has been going on so far.
In the public section of the class, add the following:
// // Routines to get and set the overall mission time // eMissionSpeed mGetMissionSpeed() { return fMissionSpeed; } void mSetMissionSpeed(eMissionSpeed speed) { fMissionSpeed = speed; }In the private section of the class, add the following:// // Variable to track overall mission time // eMissionSpeed fMissionSpeed;
- Hmmm, we're going to want to send a message in a minute, so we better create that now.
To add a new kind of message to the mission, we need to create an identifier for it in MissionText.h, and supply the text of the message in MissionText.cpp. There is a catch, however. The order in which kinds of messages are listed in MissionText.h must EXACTLY match the order in which the associated text is supplied in MissionText.cpp. Similarly, the number of messages described in both files must be identical.
In MissionText.h, look for the section on Event dialog, and add two new message identifiers:
// // Event dialog // kPlayerNotFast_msg, // this message gets sent after about 12 turns kPlayerSlow_msg, // this message gets sent 10 turns later
Now in MissionText.cpp we'll set up the matching text:// // Event dialog // "Hey [PLAYER_NAME], a fast captain would be done by now!", "Geez Captain, can't we pick up the pace a bit? \n The pirate is going to die of boredom at this rate",
The [PLAYER_NAME] will actually insert the player's game name into the message (handy when you feel like taunting someone). - Now we'll go to PlayerShipBaseState.cpp and start a timer ticking: in mBeginState
we'll add code to initialize the mission speed to fast, then start the timer.
// first we'll set the player's current completion rating to fast, // then set a timer to go off after 10 turns, // a fast player will finish the mission before this goes off, // if they don't manage that then their rating will be downgraded // to medium and we'll set things up so that 10 turns later their // rating gets downgraded to slow mSetMissionSpeed(kFast); mSetTimedInterval(kTimerTurnsSet, kMissionTimeID, 11.8f);
- Eventually, if the player doesn't finish the mission first, the timer will go off.
When this happens the mOnTimedInterval routine is called (also in PlayerShipBaseState.cpp.
Within this routine, we must identify which kind of timer went off (actually we only have one kind right now) and include code to respond to it.
Our code will send the kPlayerNotFast_msg to the player, and set another timer. If that timer goes off later we'll send yet another taunt to the player (but won't bother setting things up for a third go-round).
Set up the mOnTimedInterval routine to look as follows:
void tPlayerShipBaseState::mOnTimedInterval( int32 timerID ) { // when the timer goes off we'll figure out if we've moved closer to // or farther from the pirate during the last turn, and display an // appropriate message switch(timerID) { case kMissionTimeID: // downgrade the classification of mission speed if (mGetMissionSpeed() == kFast) { mSetMissionSpeed(kMedium); mSetTimedInterval(kTimerTurnsSet, kMissionTimeID, 10.0f); fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kPlayerNotFast_msg); } else { fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kPlayerSlow_msg); mSetMissionSpeed(kSlow); } break; } }Observe that the mDisplayMessage routine is used to send a specific message to the player team. You can use this routine to send any messages you like, as long as they are properly set up with identifiers (in MissionText.h) and matching text (in MissionText.cpp).Just for the heck of it, let's set up another message to taunt the player if they leave the map, and see if we can determine when it occurs.
We'll add an identifier in MissionText.h
// // Event dialog // kRunaway_msg, kPlayerNotFast_msg, kPlayerSlow_msg,
And we'll add the text in MissionText.cpp// // Event dialog // "When danger reared its ugly head, the Brave Sir Robin turned and fled... \n Way to be a coward [PLAYER_NAME]", "Hey [PLAYER_NAME], a fast captain would be done by now!", "Geez Captain, can't we pick up the pace a bit? \n The pirate is going to die of boredom at this rate",
Now we want to know if the player ship leaves the map. When this happens, the player ship's state is affected, i.e. another event is generated. So let's open up PlayerShipBaseState.cpp again, and look for routine mOnDisengaged. Within that routine we'll add the call to display our new taunt:void tPlayerShipBaseState::mOnDisengaged( tShipInfo* ship ) { // display a taunt if the player disengages fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kRunaway_msg); } - OK, you have timers and messages set up, you can once again build and incorporate your script and go test it out!
- 12.1.3: Tracking the distance between two ships over time
One last time, let's open up the mission we created above and we'll things up so that our navigator can keep track of whether or not we're getting closer to the pirate we're searching for! Of course, this will be kind of useless if the two ships start off within range 100 of each other, since they'll be able to see each other anyway. In your MissionMaps.h file make sure the two ships are separated by more than 13 dots (that way even with deep scanners you can't initially see the pirate).- This time, we need to set up a variable that stores our recorded distance from the pirate ship, and every so often update it. If we've gotten closer then give the captain one message, if we've gotten further away then give a different message.
- First let's set up the messages, open MissionText.h and add the message identifiers:
// // Event dialog // kRunaway_msg, kWarmer_msg, kColder_msg, kPlayerNotFast_msg, kPlayerSlow_msg,
Then open up MissionText.cpp and add the message text:// // Event dialog // "When danger reared its ugly head, the Brave Sir Robin turned and fled... \n Way to be a coward [PLAYER_NAME]", "I believe we have moved somewhat closer to the other ship", "I believe we have moved somewhat away from the other ship", "Hey [PLAYER_NAME], a fast captain would be done by now!", "Geez Captain, can't we pick up the pace a bit? \n The pirate is going to die of boredom at this rate",
- OK, now we'll go back to PlayerShipBaseState.h and set up a variable and access routines
to record the distance from the pirate ship: add the following to the public section of the tPlayerShipBaseState class
// // Routines to get and set the recorded distance from the pirate ship // float mGetLastDistance() { return fLastDistance; } void mSetLastDistance(float distance) { fLastDistance = distance; }And add the following to the private section of the same class:// // Variable to track last recorded distance from the pirate ship // float fLastDistance;
- We'll be adding another kind of timer, so that every turn we can generate an event to update the distance
to the pirate and generate a message. Thus we must expand our set of timer ids in PlayerShipBaseState.h:
// create a timer that will be used to track total mission time // and another that will track time for periodic status updates enum eTimeIDs { kMissionTimeID, kDistanceUpdateID, }; - Now, we will determine our original distance from the pirate ship, and initiate our first timer.
We'll keep resetting the timer every turn untl we get within normal scanner range of the pirate, after that the
captain is on his/her own!
To calculate the distance between the two ships, we use the mGetTacticalDistance routine, but to do so we need a pointer to each ship.
To get this, we use a mission info routine to get pointers to the two teams, then through the teams we get pointers to the first (in this case only) ship on each team.
In PlayerShipBaseState.cpp our resulting mBeginState routine now looks like:
void tPlayerShipBaseState::mBeginState() { // here we'll create two times, one used to track overall mission time, // the other used to create periodic updates on the distance between the // pirate ship and the player ship // first we'll set the player's current completion rating to fast, // then set a timer to go off after 10 turns, // a fast player will finish the mission before this goes off, // if they don't manage that then their rating will be downgraded // to medium and we'll set things up so that 10 turns later their // rating gets downgraded to slow mSetMissionSpeed(kFast); mSetTimedInterval(kTimerTurnsSet, kMissionTimeID, 11.8f); // then we'll set the timer for the periodic distance updates, // this one will involve a bunch of steps // first we'll establish pointers to the two teams tTeamInfo *pirateTeam, *playerTeam; pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam)); playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam)); // then we'll establish pointers to the two ships tShipInfo *pirateShip, *playerShip; tShipIterator ship = pirateTeam->mGetFirstShip(); pirateShip = *ship; ship = playerTeam->mGetFirstShip(); playerShip = *ship; // then find out how far apart the two ships are float separation = playerShip->mGetTacticalDistance(pirateShip); // then we'll record that distance in the class variable we set up // in the .h file (using our access routines) mSetLastDistance(separation); // then we'll turn on the timer we declared in the .h file // setting it to go off after one turn // (every time it goes off we'll let the player know if they're // getting closer to the pirate or farther away) mSetTimedInterval(kTimerTurnsSet, kDistanceUpdateID, 1.0f); } - Finally, we need to update our timer handling routine (also in PlayerShipBaseState.cpp) so that it
handles both different kinds of timers. In it we will also need to go through this process of tracking down pointers
to both ships:
void tPlayerShipBaseState::mOnTimedInterval( int32 timerID ) { // when the timer goes off we'll figure out if we've moved closer to // or farther from the pirate during the last turn, and display an // appropriate message switch(timerID) { case kMissionTimeID: // downgrade the classification of mission speed if (mGetMissionSpeed() == kFast) { mSetMissionSpeed(kMedium); mSetTimedInterval(kTimerTurnsSet, kMissionTimeID, 10.0f); fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kPlayerNotFast_msg); } else { fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kPlayerSlow_msg); mSetMissionSpeed(kSlow); } break; case kDistanceUpdateID: // first we'll establish pointers to the two teams tTeamInfo *pirateTeam, *playerTeam; pirateTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kEnemyTeam)); playerTeam = fMissionInfo->mGetTeamHandle(static_cast<eTeamID>(kPlayerTeam)); // then we'll establish pointers to the two ships tShipInfo *pirateShip, *playerShip; tShipIterator ship = pirateTeam->mGetFirstShip(); pirateShip = *ship; ship = playerTeam->mGetFirstShip(); playerShip = *ship; // remember how far apart the two ships were last turn float oldseparation = mGetLastDistance(); // then find out how far apart the two ships are now float newseparation = playerShip->mGetTacticalDistance(pirateShip); // then we'll record that distance in the class variable we set up // in the .h file (using our access routines) mSetLastDistance(newseparation); // send the warmer/colder message to the player ship if (oldseparation > newseparation) fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kWarmer_msg); else fMissionInfo->mDisplayMessage(static_cast<eTeamID>(kPlayerTeam),kColder_msg); // if we're not within normal scanner range // reset the timer to repeat the process next turn if (newseparation > 100.0) mSetTimedInterval(kTimerTurnsSet, kDistanceUpdateID, 1.0f); break; } } - Let's make one last alteration: if the player runs the mission more than once then s/he knows
where the pirate is, so the seeking part isn't very challenging. Let's create 5 random spots the pirate
could begin the mission in!
First, go to MissionMaps.cpp and add 4 other random starting positions, i.e. add i, I, j, J, k, K, l, L somewhere on the map.
Now open EnemyTeam.cpp to randomly select one of the five positions when the mission starts.
At the beginning of the mCreateShipsForTeam function we will use the mRandomInt32 call with two range parameters, then based on whatever value pops up we select a different starting position.
int32 position = fMissionInfo->mRandomInt32(1, 5); switch (position) { case 1: position = kStartPosition_H; break; case 2: position = kStartPosition_I; break; case 3: position = kStartPosition_J; break; case 4: position = kStartPosition_K; break; default: position = kStartPosition_L; break; }Then in the mCreateShip call we replace the kStartPosition_H we were using earlier with the variable that holds our randomly selected value, i.e. position. - OK, you can once again build and incorporate your script and go test out the final version!
VOILA!
For our simple skirmish, here are the final versions of each of the files we created, the only changes from the code you should have created by following the steps above are in the comments, I've tried to add/clarify explanations in a number of places:
-
- BaseVictoryState.h, BaseVictoryState.cpp
- CommonDefs.h, CommonDefs.cpp
- EnemyTeam.h, EnemyTeam.cpp
- EnemyTeamBaseState.h, EnemyTeamBaseState.cpp
- His_TestSkirmish.h, His_TestSkirmish.cpp
- MissionMaps.h, MissionMaps.cpp
- MissionText.h, MissionText.cpp
- PlayerShip.h, PlayerShip.cpp
- PlayerShipBaseState.h, PlayerShipBaseState.cpp
- PlayerTeam.h, PlayerTeam.cpp
- PlayerTeamBaseState.h, PlayerTeamBaseState.cpp
One of the things that helps in having a deeper understanding of the interaction of the mission components is knowing how the various classes are based on one another.
For the basic skirmish mission we've just discussed, here is the layout of the key classes:
tState
/ \
/ tVictoryState
/ \
tChildActorState tChildActorVictoryState
/ | \ \
/ | \ tBaseVictoryState
/ | \
/ tEnemyTeamBaseState \
/ \
tPlayerTeamBaseState tPlayerShipBaseState
tAllocatedClass
|
tActor----+--------------+
/ | \ \
/ | \ \
/ | \ tVictoryCondition
tTeamInfo tScript \ |
/ | | \ |
tEnemyTeam | tYourScriptName \ tBaseVictory
| \
tPlayerTeam tShipInfo
/ |
/ |
tPlayerShip tEnemyShip
Here we create a simple campaign mission, a one-on-one duel: the player versus an enemy ship, both drawn from the dynaverse, and with the results returned to the dynaverse. We will throw in a twist though: we'll hit the player ship with two random types of sabotage at different points in the mission. The player gets bonus prestige for captures, and bonus prestige for surviving the sabotage attempts. The mission also tries to weight the ship sizes slightly in favour of the player getting sabotaged.
Disclaimer: so far I haven't been able to get the #@$% D2 hex values to update ... someone PLEASE holler if they know the magic incantation.
For our simple campaign mission, here are the final versions of each of the files we created, the only changes from the code you should have created by following the steps above are in the comments, I've tried to add/clarify explanations in a number of places:
-
- BaseVictoryState.h, BaseVictoryState.cpp
- CommonDefs.h, CommonDefs.cpp
- EnemyTeam.h, EnemyTeam.cpp
- EnemyTeamBaseState.h, EnemyTeamBaseState.cpp
- EnemyShip.h, EnemyShip.cpp
- EnemyShipBaseState.h, EnemyShipBaseState.cpp
- Met_OneOnOne.h, Met_OneOnOne.cpp
- MissionMaps.h, MissionMaps.cpp
- MissionText.h, MissionText.cpp
- PlayerShip.h, PlayerShip.cpp
- PlayerShipBaseState.h, PlayerShipBaseState.cpp
- PlayerTeam.h, PlayerTeam.cpp
- PlayerTeamBaseState.h, PlayerTeamBaseState.cpp
Here we create a second campaign mission, this one with three teams, including some late arrivals.
You and an enemy (both pulled from the dynaverse) are each out to capture a pirate who is somewhere between you. It takes a couple of seconds before your navigator nails down the pirate location, then the race is on! A few seconds later, the pirate (realizing how bad the situation is) will try to run to the border to disengage. About 5 turns into the mission an ally of the pirate will appear on the map (near the edge of the border the pirate was running towards) and both pirates will turn to fight. Whoever captures the pirate wins, but anyone who gets destroyed loses.
(Disclaimer about D2 hex value updates still applies)
For our second campaign mission, here are the final versions of each of the files created, the only changes from the code you should have created by following the steps above are in the comments, I've tried to add/clarify explanations in a number of places:
-
- BaseVictoryState.h, BaseVictoryState.cpp
- CommonDefs.h, CommonDefs.cpp
- EnemyTeam.h, EnemyTeam.cpp
- EnemyTeamBaseState.h, EnemyTeamBaseState.cpp
- EnemyShip.h, EnemyShip.cpp
- EnemyShipBaseState.h, EnemyShipBaseState.cpp
- Met_PigInTheMiddle.h, Met_PigInTheMiddle.cpp
- MissionMaps.h, MissionMaps.cpp
- MissionText.h, MissionText.cpp
- NPC1Team.h, NPC1Team.cpp
- NPC1TeamBaseState.h, NPC1TeamBaseState.cpp
- PlayerShip.h, PlayerShip.cpp
- PlayerShipBaseState.h, PlayerShipBaseState.cpp
- PlayerTeam.h, PlayerTeam.cpp
- PlayerTeamBaseState.h, PlayerTeamBaseState.cpp
- (in VC++) select Build and your_script_name.scr
- The resulting script should appear in
C:\SFCDEV\SFC2 - API Release 1.2\source\assets\scripts - Copy the .scr file to folder
C:\Program Files\Taldren\Starfleet Command II\Assets\Scripts - If the script is for use in a campaign, then go to folder
C:\Program Files\Taldren\Starfleet Command II\Assets\Scripts\Campaign
and edit the appropriate .mct file(s) to include the new mission.For example, if the script is to be added to the Lyran vs the ISC campaign, then edit ISC-Lyran.mct, either adding your new mission to the list that file contains, or replacing an existing mission with it. (For instance, the monster missions and plethora of pirates both bug me, so I tend to replace them with other missions in the .mct file.)
Ok, here's the way I understand things working in the Dynaverse. It's highly likely I've got some of that wrong, so please take it all with a grain of salt. Anything here that's actually correct should be credited to clintk, who has done a great job of trying to research this stuff.
- The D2 engine examines each hex on the map and generates AI ships based on the settings in the server .gf files.
- For each hex, the D2 engine determines if missions are required in the hex.
To do this, it must examine each of the available mission scripts, and determine which ones are appropriate. Within each script, it appears to look at a lot of information and settings:- The mission criteria you establish in mScriptSpecs:
- Valid hex terrain for the script (e.g. kColonyHex|kAsteroidHex)
- Valid hex ownership for the script (e.g. kEnemyRaceHex)
- Valid races for the (drafting) player team (e.g. kSpecLyran|kSpecKlingon)
- MinDate and MaxDate (years in the range 0==2263 to 60==2323)
- MinBPV and MaxBPV (I'm still not convinced this is used)
- The available maps specified in your mAssignMapTerrain method, to determine which are most suitable for the hex and mission.
- The team strength definitions in mDefineTeamShipStrengths, to determine appropriate team slots.
- The mission criteria you establish in mScriptSpecs:
- The player selects whichever mission they want (or forfeits, in which case a .gf-selected forfeit penalty is applied).
- The D2 engine drafts other players to fill any appropriate team slots, and (if applicable) creates AI teams to fill some or all of the remaining team slots. (Again, the draft radius is specified in the server .gf files.) At this point the appropriate mission map is also selected.
- The mission happily chugs away, with mission endpoints and results controlled for each team by the mission script. Unfortunately, bugs in the 2013 API are preventing correct results from being returned, so your ship comes back with the appropriate damage and prestige, but the hex defensive values are not updated by player-developed mission scripts at the moment.
Once the mission has begun, somehow we would like to determine what the "outside universe" looks like. I would happily kill for any method of doing this!!!!!!!
The best I can do so far is make up our own information for a variety of pseudo-D2 information: go to your main script .cpp file, e.g. Met_YourScriptName.cpp, and look for the method int32 tMet_YourScriptName::mInitializeStart(tDynaverseInfo& Info). Within this routine, the Info parameter has already been stocked with most of the relevant D2 information.
(As an aside: this routine returns an integer value indicating which map you want used. It appears that if you return 1 then map 0 is used, if you return 2 then map 1 is used, etc.)
Below I provide a list of all the accessible fields and their data types, in the later sections we'll discuss how to use that information.
int32u Info.fMissionDate.fDay; // turn within the current year
int32u Info.fMissionDate.fYear; // current year
std::string Info.fMissionName;
eSectorName Info.fMissionLocation; // things like Romulan Core hex
int32 Info.fCampaignYear; // years since start of campaign
eTeamID Info.fPlayerTeam;
eRaceName Info.fPlayerRace;
eRaceName Info.fAlliedRaces[kNumberOfRaces + 1]; // list of who's your allies (races)
eRaceName Info.fEnemyRaces[kNumberOfRaces + 1]; // list of who's your enemies
eRaceName Info.fPreviousAlliedRace; // ally in last mission
eRaceName Info.fPreviousEnemyRace; // enemy in last mission
eVictoryLevels Info.fPreviousVictoryLevel; // how you did in last mission
int32 Info.fPlayerFleetSize;
tShipInGame Info.fPlayerFleet[3]; // tShipInGame can record nearly everything known about the ship,
// - position, type, name, BPV, human-controlled, meta-id,
// and also has some interesting fields I haven't played with,
// particurly fDisplayOnMap (a Boolean variable...)
iMapPosition Info.fPlayerFleetPosOffset;
int32 Info.fPreferedMap; // the value D2 sets describing the current hex terrain
tTeamScriptDescription Info.fTeams[kMaxTeams];
iTruth Info.fHosting;
eGameStatus Info.fCampaignStatus;
Here's the scoop:
PART I In the mission script, the scripter gets to set restrictions on where/when a mission should be offered, including:
- valid years
- valid BPV ranges
- valid fleet strenghts
- valid fleet sizes
- valid racial territory (e.g. own, enemy, neutral, allied)
- valid terrain (empty space, asteroids, nebula, etc)
- required bases
- required planets
- how far away (in hexes) the specified conditions can exist (e.g offer this mission within 2 hexes of an enemy hex with a black hole in it)
These were the options covered in 6.1.1 Setting up the mission options, in mScriptSpecs
As a mission scripter I thought that was all worthless or buggy, because the missions would appear in all sorts of invalid places anyway. This brings us to:
PART II
The server only treats those rules as advice, not as rules!
The settings in MissionMatching.gf control how much weight the server attaches to each different "area" of script recommendations.
Of course, the .gf settings don't break down into exactly the same categories as the scripter provides, but they're pretty close.
Furthermore, the default settings in that file are utter rubbish - leading to the rules laid down in the mission script being largely bypassed. It looks like they were set up to give a maximum randomness of missions encountered, without real concern as to the implications.
After a helluva lot of fiddling, here are the relevant MissionMatching.gf settings I changed to get missions to appear exactly where their scripts say they should. The original settings appear in comments.
//weight to missions matching based on terrain [TerrainScoring] PlanetTypeScoreForMatching=12000 // 5000 BaseTypeScoreForMatching=8000 // 2500 TerrainTypeScoreForMatching=4000 // 100 //weight to missions matching based on political tensions [PoliticsScoring] // NOTE THE NEGATIVE SIGNS IN THE -10000's // It's important! ;) BonusForExactPoliticalMatch=2000 // 1000 LookingForOwnHexInOwn=2000 // 1000 LookingForOwnHexInAlly=-10000 // 500 LookingForOwnHexInNeutral=-10000 // 0 LookingForOwnHexInEnemy=-10000 LookingForEnemyHexInOwn=-10000 LookingForEnemyHexInAlly=-10000 LookingForEnemyHexInNeutral=-10000 // 0 LookingForEnemyHexInEnemy=1000 LookingForAllyHexInOwn=-10000 // 0 LookingForAllyHexInAlly=1000 LookingForAllyHexInNeutral=-10000 // 0 LookingForAllyHexInEnemy=-10000 //weight to missions matching based on ships available [FleetScoring] GoodBPVScore=1000 TooWeakBPVScore=0 // 300 TooStrongBPV=0 GoodShipCountScore=1000 TooFewShipCountScore=0 // 300 TooManyShipCountScore=0 PlaceBaseMissionScore=50000 BaseScoreBonus=10000 // weights of categories [ScoringWeights] WeightMissionsLastPlayed=0.2 WeightPoliticsScore=1.0 WeightTerrainScore=1.0 WeightFleetScore=1.0 // 0.5 [RelationshipScoring] MaxRelationShipScore=1000 PoorEnemyOfScore=0 // 100 PoorAllyOfScore=0 // 200 DecentWorstEnemyScore=0 // 300 DecentAllyOfScore=0 // 200What it all means
At the very least this means we can now prepare custom missions and get them to appear where they are needed and expected.
It does, however, mean that if you apply this to a stock server then somewhat fewer missions are offered (since it doesn't give all the "wrong" mission opportunities it used to).
This may also turn out to have an important side effect, in that I suspect some of our weird-hex-effects come in as a result of poor misson offering (e.g. a script intended to run in a player's own territory instead gets run in their allies territory, and updates the DV incorrectly as a result). That's still pretty speculative however.
It appears that the relative weighting of planets, bases, terrain, and politics is critical. If bases and planets, or terrain and bases, are too closely weighted then you start getting base or planet missions cropping up in empty space.
- 17.3.1 Primary player
- 17.3.2 Playable allies
- 17.3.3 AI-only allies
- 17.3.4 Playable opponents
- 17.3.5 AI-only allies
- 17.3.6 Adding controllable ships to playable teams