I don't have the FAQ online anymore, but here is the text. This FAQ was put together from posts in the scripting forums on the old Taldren boards in the days before Dave Wessel's excellent site, which contains most of this information verbatim.
Star Fleet Command 2: The Mission Scripting API FAQ
Last updated (mm/dd/yyyy): 08/15/2001
This Frequently Asked Questions list is a conglomeration of as many questions and answers on the Taldren scripting forum as I could locate. I only included a question that seemed to have a more or less definitive answer (from user experience or from a Taldren programmer). The FAQ is broken down into 4 sections: General, Errors, Scripting, and Tips.
General:
Q. Will the API be included on the standard CDs, or will it be on the preorder only?
A. Yes, the API is included on the standard CD
Q. Will the API be available for download?
A. At the time of the FAQ?s creation, it is not.
Q. Is there any documentation, or user manual type information for the API?
A. Not as such. However, the source is peppered with detailed comments which should show you how things work.
Q. Are there any tutorials for the API?
A. Cam78 has posted 3 parts of a tutorial creating a skirmish mission. A few others have threatened to write tutorials, but haven?t found the time yet.
Q. Is the source code for any of the missions for sfc2 included as examples?
A. Mission source was not included on the SFC cd with the api, however, the source for several missions is available.
Peace in Our Times / Dilithium Dance Source Code ~ Taldren
http://216.203.248.212/ubb/Forum12/HTML/000066.htmlBonus Mission Source Code (1st Sulu Mission) ~ Taldren
http://216.203.248.212/ubb/Forum12/HTML/000093.htmlDynaverse (SP) Campaign Source Example ~ SFCVixen
http://216.203.248.212/ubb/Forum12/HTML/000285.htmlBase Raid, Orion Random Encounter Source ~ MagnumMan_iCoP
http://www.orionscripts.com/Relay Station Raid ~ Cam78
http://sciborg.uwaterloo.ca/~cmalloy/script/sfcv2/met_relay_v132.zip Q. Will the SFC2 API still use Microsoft Visual C++ 6.0?
A. Yes, you will need VC++6 with SP4 installed. If you have SP5, you may encounter problems. I was able to successfully compile and run the mission in Cam78?s tutorial under VC++6 SP5, however you may not achieve the same results.
Q. How do I install and configure the API?
A. To setup the API, please follow these steps:
1. Open the Start Menu | Programs | Starfleet Command - Volume II | Scripting API folder, and click on "Browse to the API folder"
2. Copy the files from "SFC2 - API Release 1.2\STL\Include" and "SFC2 - API Release 1.2\STL\LIB" to their respective directories found under the install path of your C++ IDE. These files are updates to Microsoft's Standard Template Library and are necessary in order for the SFC2 scripts to build successfully.
Note: Substitute ?OP API - R2.1? if you are installing the Starfleet Command: Orion Pirates API.
3. Copy the "SFC2 - API Release 1.2\Scripts" directory from the folder to your work folder. Please note the path to which you copy this. For future reference, let us call this path "LocalDir".
Note: Substitute ?OP API - R2.1? if you are installing the Starfleet Command: Orion Pirates API.
4. Run your Windows registry. To do this, Click Start | Run. Type, "regedit". Once in the Windows registry editor, you will need to make a some keys and a string value in the following manner: HKEY_LOCAL_MACHINE/SOFTWARE/Taldren/VCScriptAddins/Settings/ScriptRootPath=X, where X="LocalDir\SFC2 - API Release 1.2\Scripts\"
Note: Substitute ?OP API - R2.1? if you are installing the Starfleet Command: Orion Pirates API.
5. Once you have successfully installed the API, open the API workspace found at: "LocalDir\SFC2 - API Release 1.2\Scripts\SFC2_Script_API.dsw"
Note: This file is not included in the OP API. If you did not previously have the SFC2:EAW API installed, you can download the needed files from
http://roguejedi.brinkster.net/sfc/sfc2apiworkspace.zip. Unzip the files into the working scripts folder that you copied the API into in step 3.
6. Click Tools | Customize | Add-ins and Macro Files | Browse. Browse for "CreateScript.dll" and make certain that the check box is checked next to the newly loaded Addin. Repeat for the second macro, "ScriptObjectWizardAddin.dll".
7. Staying in the Customize dialog, click on Commands | Category | Add-ins. You should now see two buttons. Drag these buttons to the toolbar of your choice and name them as you see fit. One addin is for creating a new script. The other is for adding a new SFC2 object.
Q. Ok, now that I have the API set up how do I create a script?
A. From the API readme.txt file:
1. Click on the CreateScript | Script Type. Choose a Script Type. For instance, if you were to create an ISC single player campaign script, you would likely select "ISC"; although, any type will function.
2. Click Script Name and complete the name of this new script.
3. Next, choose the type of template you would like to use. By not choosing either checkbox, the CreateScript Addin will use Tem_Standard.
Note: For the OP API it appears that you must select the single-player check box, else you will get linking errors.
4. Scripts Root Directory should automatically pick up on the path that you had set earlier in the registry editor during installation. If not, fill this in.
5. You should now notice a new project added to the workspace. This project is not yet functional. Do not use this project. Instead, close the workspace (File | Close Workspace), open Windows Explorer and find the newly created x.dsp file, where x is the name of the script. Delete this x.dsp file and rename the x.dsp.new file to x.dsp. Now reopen the SFC2 API workspace. You should now see an updated version of the new script.
6. Now you are ready to script. View all of the files. Throughout each file you will find comments prefaced by the text, "HELPER NOTE". These Helper Notes are actually the documentation interspersed in the appropriate places within the code.
7. Let's say that you wanted to add a new ship to a script. Well, how would you do this? You could either manually create a new .cpp and .h file OR you could use the ScriptObjectWizardAddin Addin. Click on this Addin. Next, click on Ship|Next. Type in the name of the new ship in "Ship Name", then choose "tShipInfo" as the "Parent Ship". Next, click Finish. A pair of newly added files will appear in your current project.
8. Finally, once you are finished writing the custom script, you should build the script. Before you do this, make certain that Run-Time Type Information is set for your project. If you are not certain, click Project | Settings | C/C++ | Category | C++ Language. Then, select the name of your project from the list box on the left. Verify that RTTI is enabled on this dialog. Now build the script. The export file should be the name of your script + .scr and it should be found in "LocalDir\SFC2 - API Release 1.2\Scripts".
9. Update: After the SFC2 2.0.0.5 patch was released there was a change in the API. Before you start scripting, you need to remove the files ?Draw.h? and Draw.cpp? from your project. You will also need to remove the following code from ?<missionName>.h?:
virtual void mInitializeDraw( const int32 MapPicked );
You will also need to remove the following code from ?<missionName>.cpp?:
#include "Draw.h?
and
void tMyMission::mInitializeDraw( const int32 MapPicked )
{
gDraw.mDefineDrawObjects();
}
Note: Replace <missionName> and ?tMyMision? with the name of your mission. I.e ?his_mySkrimish.h?
Note: This step is not necessary for the OP API.
Q. I?ve made the script, now how do I run it?
A. From the API readme.txt file:
1. Go to the directory where SFC2 was installed. Take the newly created .scr file and place it in "Assets\Scripts".
2. For scripts that were created for Dynaverse II, make your way to "Assets\Scripts\Campaigns" and create yourself a new .mct file. Replace the names of the scripts with the name of your newly created .scr file. Change other variables as you see fit. Make certain that the trigger prestige is set to 0 and that the trigger mission is the title of your new script.
3. Now run SFC2. You should now see your single player campaign scripts show up as missions on the mission selector in Dynaverse II and you should see your multiplayer scripts show up on the list under the multiplayer setup screen.
Errors:
Q. I get the following error message when trying to build my script:
Linking...
LINK : fatal error LNK1104: cannot open file "dmp3D_MSVCD.lib"
Error executing link.exe
A. Any time you get a linking error make sure you are building a release version of the script. Taldren did not include the debug code for the API, so trying to build with a debug configuration will not work. To change this click Build | Set Active Configuration? then select <missionName> - Win32 Release and click OK.
Note: Replace <missionName> with the name of your mission.
Q. When I click on 'Create Script!' I get an error that says "The workspace file could not be written. Changes made to the workspace will not be saved" (I recieve this message twice)
A. Check that your workspace file does not have the read-only attribute set. To check this, in Windows Explorer, go to the directory you installed the API into and right click on the workspace file (it will have a .dsw extension) and click on Properties. At the bottom of the properties dialog make sure there is not a checkmark next to ?Read-only?.
Q. I do not get anything in the ClassView in VC++6. Why?
A. You will need to go into the directory you installed the API into and remove the ?Read-only? attribute from all the files and subdirectories there.
Scripting Issues:
Q. How do I set the BPV of enemy ships based on the BPV of the player?s ship(s)?
A: You can set a variable in the <some>Team.cpp file that will have a value assigned to it, and pass that to the MCreateShip method. For example, from the source code to the ?Peace in our Times? mission (EAW, comments were added by me):
void tNPC1Team::mCreateShipsForTeam()
{
tTeamInfo* playerTeam = fMissionInfo->mGetTeamHandle( static_cast< eTeamID >( kPlayerTeam ) );
int32 playerBPV = playerTeam->mGetCombatBPV();
int32 diffLevel = fMissionInfo->mGetDifficultyLevel();
int32 nPCBPV;if( diffLevel == 0 )
{
nPCBPV = playerBPV * 1.5; }
else if( diffLevel == 1 )
{
nPCBPV = playerBPV * 1.25;}
else if( diffLevel == 2 )
{
nPCBPV = playerBPV * 1.2; }
mCreateShip(typeid( tNPCTeamShip ),
nPCBPV,
kClassFrigate,
kClassHeavyBattlecruiser,
0,
kStartPosition_H,
-1, 0, 0, -1, -1,
NULL,
kDefaultShipOptions )
}
Q. What are the place holders for things like the player?s name and rank in the API?
A. There are many placeholders. In your script?s missiontext.cpp, or where ever else you?ve put in-game messages, put the placeholder in your text like this: ?[PLAYER_NAME], you are the greatest starship Captain ever!?. Here?s the list of placeholders in the API:
"PLAYER_NAME",
"PLAYER_RANK",
"PLAYER_RACE",
"PLAYER_RACE_PLURAL",
"PLAYER_SHIP_NAME",
"PLAYER_SHIP_HULL",
"PLAYER_WEAPONS_OFFICER",
"PLAYER_ENGINEERING_OFFICER",
"PLAYER_SCIENCE_OFFICER",
"PLAYER_COMM_OFFICER",
"PLAYER_HELM_OFFICER",
"PLAYER_SECURITY_OFFICER",
"TEAM1_RACE",
"TEAM1_RACE_PLURAL",
"TEAM1_EMPIRE",
"TEAM2_RACE",
"TEAM2_RACE_PLURAL",
"TEAM2_EMPIRE",
"TEAM3_RACE",
"TEAM3_RACE_PLURAL",
"TEAM3_EMPIRE",
"TEAM4_RACE",
"TEAM4_RACE_PLURAL",
"TEAM4_EMPIRE",
"TEAM5_RACE",
"TEAM5_RACE_PLURAL",
"TEAM5_EMPIRE",
"TEAM6_RACE",
"TEAM6_RACE_PLURAL",
"TEAM6_EMPIRE",
"TEAM7_RACE",
"TEAM7_RACE_PLURAL",
"TEAM7_EMPIRE",
"TEAM8_RACE",
"TEAM8_RACE_PLURAL",
"TEAM8_EMPIRE",
"TEAM9_RACE",
"TEAM9_RACE_PLURAL",
"TEAM9_EMPIRE",
"TEAM10_RACE",
"TEAM10_RACE_PLURAL",
"TEAM10_EMPIRE",
"TEAM11_RACE",
"TEAM11_RACE_PLURAL",
"TEAM11_EMPIRE",
"TEAM12_RACE",
"TEAM12_RACE_PLURAL",
"TEAM12_EMPIRE",
"TEAM13_RACE",
"TEAM13_RACE_PLURAL",
"TEAM13_EMPIRE",
"TEAM14_RACE",
"TEAM14_RACE_PLURAL",
"TEAM14_EMPIRE",
"TEAM15_RACE",
"TEAM15_RACE_PLURAL",
"TEAM15_EMPIRE",
"TEAM16_RACE",
"TEAM16_RACE_PLURAL",
"TEAM16_EMPIRE",
"TEAM17_RACE",
"TEAM17_RACE_PLURAL",
"TEAM17_EMPIRE",
"TEAM18_RACE",
"TEAM18_RACE_PLURAL",
"TEAM18_EMPIRE",
"TEAM19_RACE",
"TEAM19_RACE_PLURAL",
"TEAM19_EMPIRE",
"TEAM20_RACE",
"TEAM20_RACE_PLURAL",
"TEAM20_EMPIRE",
"SYSTEM_NAME",
"PREVIOUS_SYSTEM_NAME",
"STARDATE",
Tips:
Reducing script complexity:
In a number of scripts you may find yourself adding ships to the script that do not need any customized behavior. You can greatly simplify your script when this is true by changing the typeid() used to create the ship in mCreateShip for each team.
For example, in the Orion: Base Raid script, there are 2 to 3 (depending on difficulty) defense platforms. These platforms do not need any customized code. They use standard loadouts. Nothing special happens when they are destroyed. Therefore, in the call to mCreateShip I used typeid( tShipInfo ). By using the default ship code without customizations, the size and complexity of your script is greatly reduced. This also means you don't need to make a ship class or a ship base state class for this ship - reducing the time it takes to compile your script.
You can also reuse a team class for multiple users... this is especially true in multiplayer scripts. Normally the script wizard makes you a multiplayer script with 6 teams - each team has it's own folder with its own team class, base state, and victory. In most cases, where all human players are treated equally, you can simply delete all those individual team classes and make a single one - HumanTeam. Then in the script initialization code where teams are created, you can replace the typeid( tTeam1 ) through typeid( tTeam6 ) with typeid( tHumanTeam ). Then when you make a code change to one team, it automatically applies to all players.
Calculating Victory:
One of the easiest ways to calculate victory conditions is to use a global routine that runs through all the teams and totals up how many ships belong to each tag. (Teams with the same tag are allied; to find out other allies you need to consult the table with "AI", "WD", etc. in the script initialization file.)
When running through the list of ships per team, here is something very, very useful to note. Just because a ship is inside a team does NOT mean it belongs to that team. This can cause some confusion to people (as it did to me). Why is this? When a ship is captured by another team, the SHIP is updated so that when you call capturedShip->mGetTeam() it returns the team ID of the team that captured it. Unfortunately, the ship is not physically moved into the capturing team's team ship list.
Before capture:
Team 1
Ship1->mGetTeam == kTeam1
Ship2->mGetTeam == kTeam1
Team 2
Ship3->mGetTeam == kTeam2
Ship4->mGetTeam == kTeam2
Now what you would expect if team 2 captures ship 2 is this:
Team 1
Ship1->mGetTeam == kTeam1
Team 2
Ship2->mGetTeam == kTeam2
Ship3->mGetTeam == kTeam2
Ship4->mGetTeam == kTeam2
However the game ACTUALLY does this:
Team 1
Ship1->mGetTeam == kTeam1
Ship2->mGetTeam == kTeam2 <-- See?
Team 2
Ship3->mGetTeam == kTeam2
Ship4->mGetTeam == kTeam2
So in your logic to check all teams for ships and determine a winner, you need to add extra code to determine the "true" or "current" owner of a given ship. Simply using a tShipIterator on each team is not sufficient.
Topic: Help with MissionText.cpp (Read 5893 times)