Creating Scripts

There are 3 kinds of script used in Darwinia.
1: script files - these are the files that contain most of the scripts in the game, and are located in the /scripts/ folder. The use the functions detailed above, with one function on each line.
2: game.txt scripts - these are scripts that are run when certain conditions are met. They can call script files and speach scripts (see below), and have a different format from script files.
3: Speach Scripts - These aren't really scripts as such, but groups of text with the same name structure. You will not be able to create these yourself until a patch that allows you to add your own text is released, but I will cover them anyway.

Script Files



Making a script file is nice and easy. Simply create a text file, add the script functions in the order you want them, and save the file in the /scripts/ folder. Give the file an appropriate name for where it will be used, for example newlevel_intro.txt. At the end of the file, you need to leave a blank line. If you dont do this, the command in your script will be ignored.
Once you've done that, your script is ready to be used in the game (calling scripts will be detailed below).

Example1.

CamMove start 8

Say hub_intro_6
WaitSay
WaitCam

CamReset

This is a simple example. The script will move the camera to the position called 'start', and will take 8 seconds to get there from its current position. The text linked to hub_intro_6 will be displayed at the same time, and then the script will wait for the text to finish, and the camera to reach its position. Once thats done, the Camera will reset and control will be returned to the player.

Example2.

CamLocationFocus generator 60
Say containmentend_5
WaitSay

EnterLocation generator


####################### Bit of text in the Generator

CamMove intro1 20
Say containmentend_generator1
Say containmentend_generator2
WaitSay

CamBuildingFocus 0 300 300
Say containmentend_generator3
WaitSay

Highlight 23
Say containmentend_generator4

WaitSay
ClearHighlights
ExitLocation


######################## Global world again, wrap it up

CamLocationFocus generator 70
Say containmentend_6
Say containmentend_7
WaitSay

Say containmentend_8
StopSound music2
CamReset


Here's a more complicted example from the sequence that plays after you complete the Containment level.
The script starts on the world map, where the camera is moved to the generator level, and the text containmentend_5 is displayed. Once the text is done, the player is moved into the Generator level. Once inside, the camera moves to intro1, and containmentend_generator1 and containmentend_generator2 are displayed. After the text, the camera focuses on building 0 (the main generator in this case) and some more text is displayed. Building 23 is then highlighted with the God Ray (a trunk port), and some more text is displayed. After that, the highlight is cleared off and the player is moved back to the world map. The camera is then focused on generator again, the last of the text is displayed, then the music is stopped and the control is returned to the player.
As you can see, scripts can be as short or as long as you like.
Although it isnt required to have spaces inbetween sections of script, it does make it easier to read it you make a long one, so it is a good idea. And don't forget the blank line at the end, that IS required.

Game.txt Scripts



These scripts work a litte differently from normal scripts, and only have a few commands to them. However, you can use them to call other script files or speach scripts, and to set mission files. Every script you create here will only run once during the game, at the point where its Event becomes true.
All scripts here should go inbetween the Events_StartDefinition and Events_EndDefinition section of game.txt.
These scripts have a little more structure too them than script files, although they are very simple:

Events
Actions
End

Events are the things that must be true before the Actions are done, and the End is the uhh, End.
There are 5 different Events you can use:

AlwaysTrue
BuildingOnline
BuildingOffline
NotInLocation
ResearchOwned

AlwaysTrue
This should only be used once in your Game.txt file. It will automatically run the actions specified when the game is first loaded, and won't do it again after this for that user. This should be used for any introsequences you want your mod to have. It takes no variables.

BuildingOnline:levelname,buildingnum
This Event, as you might have guessed, is true when the specified building is online. Level name is the name of the level that contains the building you want to check, and buildingnum is the ID number of the building in question.
eg.
BuildingOnline:labs,8
This will be true if Building 8 in the Labs level (the trunk port) is online.
Specifying a level or building that doesnt exist has no obvious effect on the game, but the condition will obviously never be true so your script will never run.

BuidlingOffline:levelname,buidlingnum
This works in the exact same way as BuildingOnline, execpt it becomes true if the building is offline instead of online.

NotInLocation
This is true whenever the player is on the world map (ie, Not in a location). It takes no variables.

ResearchOwned:researchname
This will become true when the player has the specified research. If you use research which doesnt exist in the game, it will never be true and your script will never run.
eg.
ResearchOwned:officer
This will become true when the player gets the Officer research.

Creating an Event is very simple. You can have more than one condition in an event. The Event line must start with the word Event, and each condition should be seperated by a space.
eg.
Event BuidlingOnline:labs,8 ResearchOwned:grenade NotInLocation
This would become true when Building 8 in labs is online, the player has the grenade research, and they are on the world map, and this would cause the scripts actions to be executed.

Once you've created the event, you'll need some actions to run when the event is true. There are 2 kinds of Action you can use here, RunScript and SetMission

RunScript
This Action obviously runs the specified script. The script can either be a normal script file, or a speach script (see below). If you are running a script file, put the name of the file containing the script in . If its a speach script, just put the name of the text variables in.
eg.
RunScript gamestart.txt
This would run the script gamestart.txt, which would be in the /scripts/ directory.
RunScript game_intro
This would run the speach script game_intro, which would be located in english.txt.
If the scriptname you specify doesn't exist, nothing will happen.

SetMission
SetMission works just as before. It will set the mission file you specify to the given level. If the file doesn't exist, the game will crash when you try to load that level.

Unlike Events, each Action line can only have one thing on it. However, you can have as many Action lines as you need.
eg.
Action RunScript gamestart.txt
Action SetMission containment mission_containment_recapture.txt

You can run as many scripts as you like doing this, but I would recommend against running too many. If you want to run more than one, make sure they dont contain any of the same commands. Running 2 scripts at the same time that both want to enter locations, move the camera and display text are going to cause havok with each other. The only instances in the game where more than one script is run at once is when a music script is called at the same time as an intro sequence, which contains only a single TriggerSound line in it. Try and keep this in mind when setting up actions.

After your actions, you need an End. This simply tells the game that this is the end of your script and not to look for anymore actions.
Heres an example of a complete script.

Event BuildingOnline :hub,26 BuildingOnline :hub,27 BuildingOnline :hub,28
Action RunScript hub_reinforced
End

This is nice and simple. When the 3 Buildings in the hub level (one of the levels im working on) are online, the speach script hub_reinforced is run, which displays a couple of lines of text on the screen.
Heres a longer script.

Event NotInLocation BuildingOnline:labs,8 ResearchOwned:grenade
Action SetMission containment mission_containment_enable.txt
Action RunScript labsfinished
End

This is the script that runs once you've finished the lab level.
Once you've activated building 8 (the trunk port) in lab, got the grenade research, and have moved out to the world map, the containment mission file is set, and the labfinished speach script is run.
You can have as many of these scripts in game.txt as you'd like, but be sure to put a blank line between each one, for readabilities sake if nothing else.

Speach Scripts

As I mentioned, speach scripts aren't really scripts at all, I'm just calling them that because they are called with the RunScript command.
Adding text to the game is very simple. All you need is something like the following, placed in a file called strings_default.txt in your mods directory:

text_identifier This is the text that will appear in the game.

text_identifier_1 is the thing that will be called by the Say command, and the text after is what will appear in game as a result.
A speach script is simply several of these, which all have the same name, but a different number at the end of each.
eg.

text_identifier_1 This is the text that will appear in the game.
text_identifier_2 So will this
text_identifier_3 This too
text_identifier_4 And this is the last one.

Thats all there is too it. As long as the name is the same, and they each end with _ and the next number in the sequence, 'Action RunScript text_identifier' will display each of them in sequence.
Make sure you have a blank line at the end of your strings_default.txt file - if you don't, the last line will be ignored and will cause you problems when you try and use it.

The 'ScriptTrigger' entity

One of the Building types in Darwinia is the ScriptTrigger. This is invisible in game, but has area detection for specific units. You can use this to trigger a script when a specific unit type comes into range of the trigger. You can also use the 'Always' type to make it run when you enter the level. A scriptTrigger will only trigger once during the game, when their trigger becomes true, much in the same way as game.txt scripts. Script triggers can use both script files and speach scripts. Using ScriptTriggers, you can create intro sequences when you enter levels (using the 'Always' trigger), have specific text appear when your Darwinians reach a certain point, or maybe enemy units advance to a certain point. One issue however, is that you dont seem to be able to put underscores in using the editor, so if you script name has underscores in, you will need to save your level after placing the trigger, and manually edit the text file to add an underscore.

Adding Mission Objectives

Adding mission objectives to the game is a very simple process. Open up your mission file for your level, and between the PrimaryObjectives_StartDefinition and PrimaryObjectives_EndDefinition sections, add a line like the following:

BuildingOnline :labs,8 objective_capture_trunk

Objectives work in a very similar way to game.txt events. Once the BuildingOnline event is true, the mission is complete. The objective_capture_trunk part specifies the text to display on the mission objective screen (in this case, it would display 'Capture Trunk Port'). At the end of this, you can also add the name of a script file. This is the file that would play when you click the mission in the objective screen, and would normally give you a small sequence detailing the objective.
eg.

BuildingOnline :hub,27 hub_objective_1 hub_primary2.txt

The objective for this mission is to bring building 27 online. hub_objective_1 is the description of the mission ('Reinforce Trunk Port' in this case), and hub_primary2.txt is the script file that will run when you click on the mission objective, which in this case would give you a detailed mission explanation, as well as camera movements showing you the objective.

We're nearing the end of the guide now. Just a few more things and you'll be all set and ready to go!