Scripting I - Introduction

The script language of Stranded II allows you to modify the game and create your own interactive maps.
It is based on an event system, which means that scripts are only interpreted by the game if certain events occur.
There are different types of scripts and events.

Types of scripts
Global scripts - scripts, that are only executed on certain events. These scripts are not bound to objects. Global scripts that you want to work on any map are to be written into the file "sys\game.inf" in the particular mod's folder. Global scripts that you want to affect only one specific map can be written into the map settings in the editor.
Object-bound scripts - these scripts refer directly to an object, a unit or an info. Consequently, they are then firmly bound to it. Events in the script are only triggered, if they happen to this object (which of course includes global events).
Definition scripts - they can be found in the definition files (in the subfolder "sys" of the mod's directory). They basically behave like object-bound scripts, but except one difference: they do not concern a single object, but all object of the particular type! If you want, for instance, that all health potions heal the player on usage, you should write that into the definition file, since it specifies all objects of the type "health potion", not only one of them.

Types of events
As mentioned in the explanation of the different types of scripts, there are global and object-bound events. Global events can be written into any type of script and will lurk there to be triggered whenever the event occurs. In contrast, object-bound events of course make only sense in object-bound or definition scripts, because these only describe interactions with objects.
An example: An exemplary global event is "on:start" - it is exuted when the map has just been loaded and started. This does not have to do with any specific object on the map and is therefore to be categorised as "global". But if you use an object in the game, fulfilling the event "on:use", you have triggered an object-bound event. There is no point in writing a script with such an event into the game.inf or into the global script of a map, because these do not relate to objects in the game that one could use.

Summary
To have global effect, scripts can be written into the "game.inf" or the global script of a map. You can also link them to make them affect certain objects in the editor or write them into the definitions (inf files in the "sys" folder) of specific types of objects.
Scripts are only executed on the events you specify. Global events are executed everywhere, whereas object-bound events are only executed if the scripts of the particular objects are triggered.

So far about the basic system of the script language of Stranded II. In the next lesson, we will write a "Hello World" program. Jubilate!

Scripting II - Hello World

Now that we know the logic of Stranded II's script language, we can begin with our first little script.

The editor
Scripts are, except those in the definitions, written directly in the map editor. It therefore contains a simple script editor.
Start Stranded II
Click "Editor" in the main menu

For the beginning, we shall create a global script. It is most recommendable to do this in the global map script, if not in the "game.inf".

Open the map settings:



Here you now see a text input field, branded with "global script". This is exactly what we search for. It is, however, a bit small - but that is nothing to worry about...

Click the "script" button to open the script editor:

http://home.arcor.de/ewokchieftain/Stranded/scripting_2_2.jpg

Now we can see the script editor. Apart from more space to fill with text, it offers a script import and export function, a button to add a command that opens a window with all commands, and an automatic completion function that during typing shows all commands that start with the same letters. They can then be selected per mouse click.

Hello World!
But now let's start with the script itself. When writing a script, one must always first figure out when it is supposed to be ran. The scripts of Stranded II are based on events, after all. That can be specified with the command "on".

The command "on" in the command reference

Since we want the script to be executed when the map starts, we choose the event "start". The event is to be attached to the on-command per colon. As a script, this looks as it follows:



This is not very meaningful yet. Stranded II may now know that it has to run this scrip when the map is started, but with no commands to execute.
We shall overcome this defiancy. Let us just display small short text. Herefore, the command "msg" is suitable.

The command "msg" in the command reference

You must write it into the curly bracket, for we want it to work at the start. But since the script has only a "on:start" and now further events, it would not make a difference if you just wrote it above or below the brackets. You see, Stranded II always executes the entire script - all that is located out of "on"-brackets and all that is within the "on"-brackets of the particular event - but only if there is a currently happening event in the script. Consequently, scripts without events are never ever executed and hence totally useless.

Let's get back to work and add the command:



The parameter "Hello World!" is delivered to the command to let him know, what to display. The semicolon must be written behind every "normal" command to signalise, that there are no following parameters anymore.
The space before "Hello World!" (1 Tab inwards) is not required, but tremendously improves the readableness of your script. Such tabwise spaces are a great aid especially for writing complex scripts.

Type the script shown above
Click the Okay button to access the script
Click "Test map" in the map settings:



If you have done all correctly, you will see the text "Hello World!" on the left hand side after loading.



Summary
When you write scripts for Stranded II, there are three steps to pass:
Specify WHERE you want the script to be executed
Specify WHEN you want the script to be executed and attach suitable events to the command "on".
Write the actual script into the right event's brackets.

Scripting III - Variables

Let's take a look at variables. They are a kind of container for values. Stranded II Script can only save Integer values, respectively natural numbers, to variables. Variables are branded by a Dollar sign ($).
Let us take the code we just worked on and implement a variable:



If we now test the script, we can state that "Hello World! 5" is put out. What have we done?
Easy to explain: Bloody nonsense. This script is total rubbish. But that's irrelevant. By "$myvalue=5;", we have declared a new variable and given it the value 5 via equal sign. This assignment is, just like commands, finalised by a semicolon. We have included the variable $myvalue into the parameter of the command "msg". The Dollar sign tells Stranded II that it is dealing with a variable and automatically replaces the variable's name by the value it contains. This is, strongly simplified, how variables work.
Now let us continue to change the code:



We can state: Calculations with variables are possible, too. Since the variable gets replaced by the value, Stranded II calculates 5*2 and afterwards saves the result (10) in the variable.
Apart from the normal assignment via equal sign, you can also increase or decrease a variable directly (if it does not exist yet, it will be set to 0 first and then increased or decreased):
++ - increases the value by 1
+= - increases the value by a given value
-- - increases the value by 1
-= - increases the value by a given value
Here is a little code for it to illustrate:



The lines that start with "//" are comments. All text within the line that is behind the "//" will be ignored. It is recommendable to write comments into the scripts from time to tome, so that you get along better and know immediately what the script does at the particular place again. You can also build in comments over several lines. They are initiated with "/*" and end with "*/".
Another to the former scripts is that we now just hand the variable to the msg-command without any additional text.
It would of course be possible as well to, for instance, increase one variable by another ($odin+=$thor;) and much more.But to show you all that here would extend the size of this tutorial - and is not necessary at all. Just try around a bit.

Local and global
Until now, we have just made our variables by writing $x=y. But variables that are created in that way are always global - automatically! That means: Any script has access to them. No matter where it is executed. Under special circumstances, this can, however, be undesirable. For instance, if you want to count for each object, seperately, how often the player hits it. A little experiment shall illustrate this:

Open the file "objects_palms.inf" in the folder "mods\Stranded II\sys"
Insert the following script directly under the line "script=start":



Save the file (we hereby just changed - resp.: created - a definition script!)
Start Stranded II (If it is already running, you must quit and restart it!)
Create a map with several palms (palms of type 1, of course!) and test it.
If you now hit a palm (point at it and left-click to attack), "Hits on the palm: X" will be displayed, and X will increase with every strike. If you now continue at another palm, X will just be increased further instead of beginning again at 0 for that palm. This is not what we desired in this. We want a seperate counter for the number of hits on each palm.
The solution are local varials. In contrast to global varials, access to them can only be gained in scripts of the object where they are definded as local (except if one uses the command setlocal or getlocal).

The command "local" in the command reference

Open the file "objects_palms.inf" in the folder "mods\Stranded II\sys"
Insert the following line below the line on:hit {, that we have just written:



Repeat the previous steps (Save, Creat map, Test)
And already, it works. For each palm there is an own counter now. Only thanks to local variables.
Attention: Do not forget to undo the changes in the "objects_palms.inf" after testing, or that is to say: remove the script you added.
That actually is all concerning local and global varials. By the way: All variables are saved with the savegames. Exept if you...

Temporary variables
...yes, except if you mark them as temporary variables. Another little speciality of Stranded II Script.
By the command "temp", you tell the game to treat a variable as temporary. It will then behave just like a normal variable, but with the difference that it will be automatically deleted before saving the map. With "tempall", all variables will instantly become temporary variables. Of course, global and local variables can both be temporary.

The command "temp" in the command reference
The command "tempall" in the command reference

Commands with output
This topic may actually not really belong to variables, but it will be broached here as well because commands that give back output values behave just like variables.
If you execute a command in Stranded II that gives back an output, you must keep in mind that there is a little difference to normal runs of commands here: The parameters must be set into round brackets. If there are no parameters to specify, just an empty pair of curved brackets is to be attached. The script will then replace the command with output by its output value - just like the name of a normal variable gets replaced by the value of the variable.
Voila, an example:



All commands with output values are sorted into an extra category of the command reference:

Return-commands in the command reference

Summary
Stranded II Script includes local and global variables which are branded by a Dollar sign. The variables are saved into savegames, except if they are marked as temporary.
Commands that return something are executed with parameters in brackets, or with an empty pair of round brackets after the command, if they have no parameters.

Scripting IV - Conditions

By the usage of conditions, you can let certain circumstances in the game (which can be checked per commands or read out of variables) influence scripts (and consequently, what happens afterwards).
The essential command behind it is "if".

The command "if" in the command reference

It serves to formulate a condition that is to be attached within the round brackets that follow. If it is fulfilled, the script that is in the subsequent curly brackets will be executed. Otherwise, it will not.
Hereafter, the examplary conditions are all constructed with numbers; but logically, those could as well be replaced by variables or return-commands! A simple example:



The msg-command is executed, because 5 undoubtably equals 5. You must keep in mind that for comparisons, you have to use a double equal sign instead of just one. Apart from "equals", you can also use "equals not", "greater than", "smaller than" etc. Detailed information about the way that is done can be found in the command reference, under the keyword "if".
If you now change one of the number, so that the "equation" becomes unequal, the command in the curly brackets will not get ran anymore.
But there is also a way to let the game run alternative script commands, if the condition is not met. Herefore, you can use "else" to extend the condition. It is simply added behind the curly brackets of the if-command and anon brings about its own curly brackets, which the alternative commands can be written into:



This will produce the output "3 doesn't equal 5!". If everything is alright with the universe, the condition is not met.
But this is not all yet. The whole if-contraption can be further pimped with the elesif-command. Elseif is about like an else, but brings along its own new condition. In practise, this is what it looks like:



Instead of else, one could just as well have used another "elseif". This chain of conditions can be infinitely extended.
There is, however, another way to express complex conditions: Linking them with "and", "or" etc. within the condition brackets itself:



"&&" stands for "and" - which you can also look up in the command reference under "if". Only if 3 equals 5 AND 2 equals 2, the condition is met. The whole procedure can be extended with many further kinds of links.
It is important to always write these components into round brackets.

Summary
The structure of conditions always looks as it follows: "If (condition){commands}". Via "else", "elseif" and links within the conditions (such as for instance "and" or "or"), they are expandable.

Scripting V - Scripts & Infos

Stranded II has so-called "infos" to give you more influence. Their purposes are specifying certain spots or conditions, that trigger scripts, if fulfilled.

Trigger-Infos
Infos that check conditions and trigger scripts are called "trigger-infos".
If you place them in the editor and click them, you can change various settings and assign them scripts. Apart from global events, they only understand the event "on:trigger". It is the case if the set condition is fulfilled.

Start Stranded II and create a new empty map in the editor
Select "infos" on the left top
Choose the local trigger (a T with a circle containing a dot)
Click the ground to set a local trigger
Select it and set it as this image shows it:



Accept per Ok-Button afterwards. You should now see the local trigger with a green circle that shows the size of the area that is checked:



If we now have a look at the settings from above, we can state that the local trigger is set in a way, that will trigger it, if the number of players in its area is greater than 0 - or briefly: If the player is in the area. Plus, we have activated the trigger, so that it can instantly work and check the conditions.
It is recommendable to always keep as few triggers running as possible, since they periodically check their conditions.That can slow the game down. Per script commands they can, however, turned on and off whenever you want.

Add the following script to the local trigger:



Test the map

If you have done all correctly, the message will turn up again and again as long as you are near enough to the local trigger.
The other trigger-infos allow you to check other kinds of conditions. They yet work the same way.

Infos as positions
Another application for infos in the context of script is to set them at positions around which you want certain things to go on. With script commands, you can easily find out their positions and use them however you want:

The command "getx" in the command reference
The command "gety" in the command reference
The command "getz" in the command reference

For sequence commands (to specify camera movements), you must even use infos directly.

Infos as containers
Since infos are invisible in the game, you can also use them to store stuff inside.
Apart from items and states, you can also save text or scripts in them. The info of the type "text container" is ideal for that. Text-container-infos have the special property that Stranded II ignores their entire script attachment like it would not exist and hence does not execute it.
Many script commands allow you to directly use the ID of an info as the source for a text or a script. That way, it is not necessary to store scripts and texts in external files.

Summary
Infos are versatile. They can check conditions and execute scripts, specify positions or serve as containers for scripts, texts, items and states.

Modding I - Introduction

Stranded II supports not only the creation and editing of maps, but also gives you the opportunity to modify the game itself. You can make your own objects, creatures and items and specify how they have to behave and much more.
The "new" games that result of what you change are called modifications, or shortly: Mods.

What do I have to pay attention to?
If you want to make your own mods, keep in mind that the time and experience you need to create them is considerably higher than for making maps. After all, mods are complete games on an existing engine.
So before you start to make a mod, you need to have become familiar with the creation of maps and the writing of scripts in Stranded II. Both is required to make good mods!

Modding II - Create a mod folder

Before you start with modding itself, you do some preparations for it. In Stranded II there are 2 ways to set up the frame for a new mod:
Copy an existing mod (i.e. Stranded II itself) and modify it
Create a new mod and make all anew
The method that fits better depends on how you want the mod to be like. If it will be similar to Stranded II, it is recommendable to just copy it and perform the changes on the copy.
But if you want to make something entirely now, that will not have to do too much with Stranded II at all, it is perhaps better to start up from the very bottom and make up all by yourself.
In the following part, both ways will be explained. The former will supposedly be the easier choice for the start.

Copy an existing mod
To create a mod that is based on an existing counterpart, just perform the following steps:
Select the "Stranded II" folder per Explorer/"My Computer"
Choose the subfolder "mods"
Mark the folder with the name of the mod that you want to copy (If you have no mods installed, choose "Stranded II")
Copy it per Ctrl+C and paste it again per Ctrl+V
Rename it to the particular name you want your mod to carry (right-click the folder -> Rename)



Create a new mod
Select the "Stranded II" folder per Explorer/"My Computer"
Choose the subfolder "mods"
Create a new directory (right-click somewhere into the void -> New -> Folder)
Give it the name you want your mod to carry (right-click the folder -> Rename)

Start the mod
Hooray-diddely-day! And already we have created our mods. All that is left to do is to start them. Especially if we have made a new one, this is of great importance, because only when starting it, the required files will be automatically copied into the folder of the mod!
To start the mod, you have to launch Stranded II with the particular command line parameter. Only that way, you can let it know that it is supposed to load our mod.

Click on "Start" -> Run
Click on "Browse..." and choose StrandedII.exe in the Stranded II folder
Write the following command behind the quotation marks: -mod "My mod's name"
Accept per Ok to start the mod!

Please note: If you have created a new mod, the first start will probably take longer as usual, because the necessary files must be copied into the mod's folder.

It is of course a very pedestrian method to start the mod that way. It hence is very recommandable to create a batch file or a link instead.
If you want to applicate a link, proceed just like for the executing: Create a link to StrandedII.exe and attach the "-mod"-parameter in its properties.
If you prefer a batch file, just create a new text file with the following content:



Then save the file with the appendix ".bat". A double-click on the file will start Stranded II with your mod.