Scripting Functions

This part of the guide was orignally a seperate guide that I wrote during the beta. However, I have decided to incorporate it into the whole modding guide.

First off, here's a list of all the scripting commands availible to you, what they do and how they are used.
They will be in the following format:
FunctionName etc..
All variables are required - if you miss one out, the game will crash when your script runs.
Don't worry, I'll explain how you use these on the next page.


CamCut
Causes the camera to jump instantly to the named camera. The camera is not locked when using this function, however, which means the player will still be able to move around.

CamAnim
I'll add this later on, when I work out how camera animations actually work.

CamMove
CamMove takes 2 variables, the name of the camera you want to move to, and the time in seconds you want to take to get there.
eg.
CamMove intro1 10
This would move the camera from its current location to intro1, and it would take 10 seconds to get there.
The player will be anable to take any action when this is called, until CamReset (see below) is called.

CamBuidlingFocus
CamBuildingFocus make the camera move to the building specified in BuildingID, and pan around it. This can be any building entity in your level. I'm not sure exactly what the 2 numbers do, but they control the pitch and height of the camera. The lower the numbers, the closer to the ground the camera will be.
eg.
CamBuildingFocus 10 300 300
This would move the camera from its current position to building 10, and pan around it at a roughly 45 degree angle.
The player will be anable to take any action when this is called, until CamReset (see below) is called.

CamLocationFocus
CamLocationFocus causes the camera to focus on a location on the world map. LocationName is the name of the location on the world map that you wish to focus on. Im unsure what the second variable does, but its effect seems to be minor. It is required however.
eg.
CamLocationFocus containment 50
This will make the camera focus on the containment level on the map.
Note: This should only be used when the player will be on the World map, or the game will crash.
The player will be anable to take any action when this is called, until CamReset (see below) is called.

CamReset
CamReset stops any current camera movements, and returns camera control to the player. It takes no variables.
Its important to make sure this is called after any camera sequence, or the player will be unable to do anything afterwards.

EnterLocation
This forces the player into the location specified in location name. Once inside the location, your script can continue, and use Building IDs and camera names from that level. You may then either end your script, giving control of the level to the player, or call ExitLocation (see below), forcing them back onto the world map.
eg.
EnterLocation containment
This would force the player onto the containment map.
This should only be used on the world map. It will have no effect if called from inside a level.

ExitLocation
This forces the player out of their current location and back to the world map. It takes no variables.
After calling this, your script may continue using world-map functions, or you can end it and return control to the player.
This should only be used when the player is on a level. It will have no effect if called from the world map.

Say
This will cause a speach box to appear, with the text specified in TextID. More than one of these can be called in sequence, and the text will be seperated by an enter prompt. All TextID's and their corresponding text are stored in a file called userstrings.txt.
eg.
Say containmentend_1
This will cause the text associated with containmentend_1 to be displayed on screen.

WaitSay
Calling this function will make the script wait for all currently queued text to be displayed before continuing. It takes no variables. The script will continue once enter has been pressed on the last piece of text, or the text times out by itself.

WaitCam
This will make the script wait until all camera movement is finished before continuing. It takes no variables.
The script will continue once the camera has reached its destination, or the enter key is pressed.

Highlight
This will cause the God Ray to shine down on the building specified in BuildingID. The God Ray will remain until ClearHighlights (see below) is called.
eg.
Highlight 0
This will cause building 0 to be highlighted by the God Ray.
This should only be used when the player is in a level. It will have no effect if called from the world map.

ClearHighlights
This will clear all current God Ray highlights. It takes no variables.
Calling this from the world map will have no effect.

TriggerSound
Starts the sound indicated by SoundName. Sounds should (presumably) be located in the 'OTHER Script' section of sounds.txt. This won't make much sense to anyone who hasn't read the sound files in Darwinia. I havent develed into sounds much, but I will update this when I do. The only variables you can use at the moment are music1, music2, music3 and music4.
eg.
TriggerSound music1
This would start musci1 playing.

StopSound
Stops the sound SoundName, after starting it with TriggerSound.
eg.
StopSound music1
This would stop music1 playing, assuming it had been started before hand.
This has no effect if SoundName isn't already playing.

DemoGesture
Plays a demo of the gesture indicated by GestureFileName. Gesture Demos must be located in the gesture_demos folder.
eg.
DemoGesture armour.txt
This would given a demo of the gesture needed to create Armour.
If GestureFileName is not a valid file, or is missing altogether, the game will crash.

GiveResearch
This will give the player access to ResearchName, where ResearchName is the name of any unit or weapon in the game. It will default to v1, and currently there is no way to change this.
eg.
GiveResearch Rocket
This would give the player the Rocket weapon to use with their squads.
If the player already has the research you indicate, or you specify something that doesn't exist, nothing will happen.

SetMission
This will set the mission in LevelName to the MissionFile. MissionFiles contain the units, dynamic buildings, mission objectives and cameras for any given level. Using this, it allows you to prevent people from entering your level until the script is run, or re-using the same level with different mission files.
eg.
SetMission garden mission_garden_recapture.txt
This would link the garden level with the mission mission_garden_recapture.txt.
Giving an invalid file name in will not crash the game, however the game WILL crash when you try and load the mission with the invalid file.
Specifying an invalid LevelName will crash the game.
SetMission should only be used in game.txt scripts (see below)

GameOver
This is called when the player completes the original game, and unlocks the account that allows the player to play any level. I would recommend against using this in your own mods at all.

ResetResearch
This sets the level of the Darwinians back to version 1. It currently only effects Darwinians, and was used for the Garden cutscene so that the Darwinians couldnt fight back while the virus was attacking them. Its possible that this will be increased to affect all research levels at a later stage.

RestoreResearch
Restores the Darwinians lasers back to the level they were at before ResetResearch was called.

GodDishActivate
GodDishDeactivate
Activates and Deactivates the god dish glow effect, if you have a god dish on your level. If you dont, these functions have no effect.

GodDishSpawnResearch
Spawns a research item, as used in the Temple intro cutscene. The research isn't a real research item and cannot be used by engineers. No effect if there is no GodDish in the level.

GodDishSpawnSpam
Spawns a Spam from the GodDish ala the Temple intro cutscene. If there is no GodDish, this has no effect.

TriggerSpam
Makes any spam present 'fire'.

Functions added in v1.3

PermitEscape
Means that pressing enter will, instead of skipping the current line of text or waitcam, will instantly exit the script. This means that any setmission lines etc vital to progress WILL BE SKIPPED if they are AFTER this line. ClearHighlight and stopsound are apparently built into this command, which is very annoying.

CamFov
Basically zoomes the camera in and out. The first number is what size the field of view should be. The normal camera has an FOV of 60, in a cutscene where the camera is moving, this is automatically changed to 70. Camreset always returns this to 60. Lower numbers zoomes in and higher numbers zoom out. This isn't really zooming in and out, it basically applies a fish eye effect, and whatever the opposite of that is when zooming in. The second number is basically a flag - you can set it to anything but only 0 and non 0 do anything - 0 means that you will slowly sweep into the new FOV, 1 will make it instant (like camcut)

ShutUp
A handy new command, it makes Dr S shut up, basically clearning any strings he might have been saying. (lines half said will be completed instantly)

WaitRocket # # #
Basically, a special scripting command specificlaly for the escape rocket structure. The first and last operand are apparently unused, with valid 2nd ones being at least 'Countdown' and 'exploding', as used in demo2

ShowDarwinLogo
Shows the logo shown at the start of demo2

WaitPlayerNotBusy
Fairly self explanitory - will wait until the player is not busy, but, what defines busy? At least moving the camera around and shooting a squad off at thin air. Enter of course, skips this anyway

CamGlobalWorldFocus
Gives a nice zoomed out picture of darwinia with the connection sky if on the worldmap. Zips camera off to godknowswhere if called in a level.