Scripting:Basic course

From STNE Wiki

Main | Syntax | Operators | Interfaces | FAQ | Contents | API Reference | Index

This is a beginners course for the STNE engine script. It is not complete and probably not 100% correct. I have basically taught myself to use the STNE engine through trail and error, bad translation, good examples, and the benevolence of others. My spelling sucks. I'm sorry. If you see a mistake please fix it.

Contents 1 Vorwort 2 Chapter 1 - Strings 2.1 "Hello World!" 2.2 Summary: Strings 3 Chapter 2 - Variables 3.1 Basic types 3.2 Variables 3.3 Anwendungsbeispiele mit Variablen 3.4 Umwandlung von Variablen in andere Datentypen 3.5 Regeln bei der Bennenung von Variablen 3.6 Zusammenfassung: Variablen 4 Kapitel 3 - Kontrollstrukturen 4.1 If - then - Else 4.2 Schleifen 4.2.1 while 4.2.2 Do 4.2.3 For 5 Kapitel 4 - Der Shipmanager - Einführung 5.1 Beamen 5.2 Fliegen 5.2.1 Fliegen mit dem Autopiloten 5.2.2 Fliegen ohne Autopilot 5.3 Schiffsystem nutzen 5.4 Alternative zum Schiffsmanager: Schiffsaktion 6 Enumeration ist Alles 7 Methoden 8 Klassen 9 Autoren

Vorwort

Much like the German version this course is aimed primarily at those who have never programmed and would like to start scripting in STNE. Please realize it is not easy and it will take a little while before you realize results. Be patient and keep at it! Like all good things it takes effort but it should be worth the time you put into it. I wish you the best of luck.

Chapter 1 - Strings

In programming a String is a series of characters. The chapter title would be a String as would this text. The famous line "Hello World!" is also a String and it is this String you will be working with.

"Hello World!"

We don't really know where it started but when first embarking on learning a programming language the first program you tend to write will be "Hello World!" In the STNE engine this is very easy. First launch the script editor under: Database -> Script Editor -> Create a new script -> Custom script without input wizard Then you will click "Edit source code". In the text field provided type:

WriteLine('Hello World!');

Now click Save&Run. Did it work? If not double check your input. Are the capital letters capital? Are there opening and closing quote marks and parentheses? Does it end with a semicolon? When it works you should see the line:

Hello World!

Congratulations you are now programming. Try making a program that says:

Hello World!
Live long and prosper!

Your code should look like this:

WriteLine('Hello World!');
WriteLine('Live long and prosper!');

Note every line of code ends with a semicolon. But what if you want to write everything on one line:

Hello World! Live long and prosper!

This is done by use of the & symbol:

WriteLine('Hello World!'&' Live long and prosper!');

The & symbol allows you to combine two Strings. It literately sticks them right next to each other which is why ' Live long and prosper!' has the preceding space. See what happens when you remove it!

"But wait!" You say. "I could simple code:

WriteLine('Hello World! Live long and prosper!');

and never have to deal with the & symbol!"

True, and as a programmer you will have many choices of different ways to do things. But the '&' is important as you will find out in the next chapter.

Summary: Strings

• A String is a sequence of several characters.
• A String is output, or printed, using the command WriteLine();.
• You may use the character & to combine one String with another within the parameters, or parentheses, of WriteLine();.

Chapter 2 - Variables

Basic types

Think of a variable as a reference that you can use again and again and again. They can be a word, a number, or true/false. These are all called Data Types and, of course, each has a special name:

• String - a series of characters
• Integer - a whole number
• Boolean - decision (True/False)

Variables

Imagine you have a gigantic project with hundreds of lines of code. Dozens upon dozens of times your code will output the lines:

Captain's log Stardate:

Da das Arbeiten mit statischen Daten auf Dauer, vor allem bei längeren Scripten, ziemlich zeitaufwendig und unflexibel ist, verwendet man Variablen. Diese speichern Daten, geben sie auf Wunsch aus und lassen sich auch belibig oft verändern.

Um eine Variable zu erschaffen verwendet man den Befehl var.

Nach VAR kommt dann der Variablen Name, dieser darf Zahlen und Buchstaben enthalten. Zahlen allerdings nur mit einer Ausnahme, sie dürfen nicht an erster Stelle stehen. Optional danach kann ein AS stehen (as, engl., als) dieses gibt an was für einen Datentyp die Variable hat, zb. String also eine Zeichenkette. Hier ein Beispiel:

VAR i1 AS String

Um dieser Variable einen Inhalt zuzuordnen, schreibt man in der nächsten Zeile die Variable vor ein Gleichheitszeichen, dahinter kommt dann der Inhalt, den die Variable annehmen soll, in unserem nächsten Beispiel ein Hallo!.

Var test AS String
test = 'Hallo!'

man kann das ganze auch in eine Zeile packen, das sieht dann wie folgt aus:

VAR test AS String = 'Hallo!'

Auch hier müssen wir wieder die einfachen Anführungszeichen setzen, als Kennzeichen dafür, dass wir einen String als Inhalt benutzen. Wir können Variablen aber auch andere Datentypen wie Integer oder Bolean zuweisen. Dazu einfach string durch den jeweiligen Datetyp ersetzten.(Liste der Typen: klick mich)

Auch kann man die Variable "leeren" hierzu gibt man ihr einfach nichts mit, hier auch dazu ein Beispiel:

VAR test AS String = 'Hallo!'
test = ''

Anwendungsbeispiele mit Variablen

VAR test AS String = 'Hallo!'
WriteLine( test & ' Wie gehts?');

Auch hier ist weider zu beachten das kein Leerzeichen eingefügt wird! Die Variable kann an jeder Stelle innerhalb der Klammern stehen, zu beachten ist nur, dass sie nicht innerhalb von Anführungszeichen steht sonst wird die Variable als String gewertet.

VAR test AS String = 'Hallo!'
WriteLine(test);

Hier wird nun zum Beispiel nur eine Variable ausgegeben.

Umwandlung von Variablen in andere Datentypen

Wollen wir eine Integer-Variable, also eine Zahl, ausgeben, so bekommen wir ein Problem. Der Computer verarbeitet ein Integer intern anders als ein String. Ein String kann er ausgeben ein Integer nicht. Daher müssen alle Integervariablen (wie allen anderen auch) in Stringvariablen umgewandelt werden, bevor man diese ausgeben kann. Die geschieht über den Befehl

CStr();

Beispiel:

VAR zahl AS Integer;
zahl = 5;
WriteLine(CStr(Zahl));

Umgekehrt müssen Stringvariablen in Integer umgewandelt werden, wenn mit diesen zum Beispiel gerechnet werden soll. Dies geschießt über:

CInt();

Beispiel:

VAR einstring AS String;
VAR einezahl AS Integer;
einstring = '42';
einezahl = CInt(einstring);

Regeln bei der Bennenung von Variablen

• Niemals reservierte Namen benutzen! Dazu Zählen u.a. alle Datumsangaben, wie Date, Minute, Day etc.; jegliche Befehle und vom Systemvorgegebenen Funktionsnamen und Eigenschaften wie: Flotte, BenutzeSchiff, Nahrung, FliegeZu etc.
• Man sollte der Übersicht wegen die Variablen immer (Richtlinie) mit drei Buchstaben beginnen lassen, welche beschreiben, welches Datenformat die Variable hat (z.B.: strVariablenName für ein String, IntVariablenName für ein Integer etc.)
• Man sollte immer die gleichen Namensrichtlinien einsetzen, damit man bei älteren Scripten noch den Durchblick behält

Zusammenfassung: Variablen

• Eine Variable ist ein Platzhalter für einen variablen Inhalt eines festgelegten Datentypen.
• Um eine Variable zu erstellen wird VAR Name AS Datentyp; verwendet.
• Um einer Variablen einen Inhalt zu zuweisen wird Name = Inhalt; verwendet.
• Um eine Variable auszugeben oder mit ihr zu arbeiten, wird der Name geschrieben zB: WriteLine(Name);
• Es ist möglich mehrere Variablen mit Hilfe des &-Zeichens innerhalb des Befehls WriteLine(); regelrecht anzuhängen.

Kapitel 3 - Kontrollstrukturen

Da wir uns in Kapitel 2 mit Variablen beschäftigt haben, können wir uns nun dem eigentlichen Aufwand beim Programmieren zuwenden: den Kontrollstrukturen. Diese Wort klingt ersteinmal sehr hochtrabend, an und für sich ist es jedoch sehr einfach.

If - then - Else

Es werden 2 Variablen miteinander verglichen oder überprüft, ob eine Variable einem Wert entspricht und dann wird darauf reagiert.

VAR var1 AS Integer = 42;
if (var1 = 42)
{
  WriteLine('var1 ist 42');
}
else
{
  WriteLine('var1 ist nicht 42');
}

Dies ist ersteinmal sehr einfach und wirkt auf den ersten Blick sinnlos, was es auch ist. Aber es zeigt auf einfache Art, wie man 2 Werte miteinander vergleicht, dies kann man zum Beispiel dafür nutzen, um zu prüfen wieviel Lageraum ein Schiff noch hat. Dazu aber irgendwann später mehr. Bleiben wir bei dem Code und schauen ihn uns einmal genauer an: In der ersten Zeile wird die Variable var1 definiert, dies sollte aus Kapitel 2 bekannt sein.

If (var1 = 42)

Hier wird der Vergleich durgeführt, in diesem Fall wir geschaut ob der Wert von Zahl1 42 ist. Man könnte an dieser Stelle genausogut prüfen ob der Wert größer oder kleiner ist, als ein anderer. Hierfür nutzt man dann nicht "=" sondern "<",">","<=",">=" Innerhalb der { } folgt dann der Code, welcher ausgeführt werden soll, wenn die Bedigung stimmt, also in diesem Fall, wenn var1 gleich 42 ist.

Das folgende Else mit den Klammern gibt, welche Aktionen ausgeführt werden sollen, wenn die Bedingung nicht stimmt.

Zu guter letzt gibt es noch Elseif dies ist dafür gedacht wenn man mehr als eine Alternative hat. Beispiel

VAR var1 AS Integer = 42;
if (var1 < 42)
{
  WriteLine('var1 ist kleiner als 42');
}
elseif (var1 > 42)
{
  WriteLine('var1 ist größer als 42');
}
else
{
  WriteLine('var1 ist weder größer noch kleiner als 42');
}

Dies ist nicht auf ein elseif beschränkt, es können beliebig viele sein.

Schleifen

Die soeben kennen gelernten Strukturen helfen uns Fallunterscheidungen zu machen. Aber was machen wir wenn wir eine ganze Liste (zum Beispiel Schiffe) haben und die abarbeiten wollen? Dafür gibt es Schleifen, hier unterscheid man in drei Arten: Kopf-, Fuss- und Zählergesteuert.

while

While Schleifen sind Kopfgesteuert, dass heißt, solange die Bedingung zutrifft, wird der Inhalt der Schleife ausgeführt. Es gelten die selben Operatoren wie bei Abfragen mit if: =,<,>,>=,<=,<>

VAR i AS Integer;
i = 0;
WriteLine('Ich zähle jetzt bis Zehn');
while ( i <= 10)
{
  WriteLine(CStr(i));
  i = i + 1;
}

Solange i kleiner oder gleich 10 ist, wird i ausgegeben und dann einen hochgezählt. Bei Whileschleifen ist zu beachten, dass wenn die Bedingung zu Anfang bereits nicht erfüllt ist, dass sie dann nicht durchläuft. Soll sie mindestens einmal durchlaufen muss man Fussgesteuerte Schleifen wählen.

Do

Do-Schleifen sind Fussgesteuert. Sie funktionieren wie While-Schleifen nur das sie mindestens einmal durchlaufen.

VAR i AS Integer;
i = 10;
WriteLine('Ich zähle jetzt bis Null');
Do
{
  WriteLine(CStr(i));
  i = i -1;
}
While (i >= 0);

Gebe i solange aus und zähle einen runter, solange i größer gleich null ist. Aus der Beschreibung wird deutlich wo der unterschied zwischen While- und Do-Schleifen liegt.

In beiden Schleifen wird deutlich das ich jedes mal die Variable i runter bzw. hochzählen muss, um dies zu umgehen gibt es die möglichkeit Zählergesteuerte Schleifen zu verwenden.

For

For-Schleifen sind genau dies.

VAR i AS Integer;
For ( i = 0 To 10)
{
  WriteLine(CStr(i));
}

auf diese Weise kann man sich ein wenig Arbeit abnehmen, da die Schleife einem das Zählen abnimmt. So kann man auch Endlosschleifen vermeiden, die auftreten wenn man vergisst, die Schleifenvariable (in diesen Fällen immer i) runter- bzw. hochzuzählen.

For-Schleifen bieten noch eine weitere Möglichkeit: Es kann angegeben werden in welchen Schritten die Schleife zählt.

VAR i AS Integer;
For ( i = 0 To 100 Step 10)
{
  WriteLine(CStr(i));
}

Der Code ist der bis auf das Step identisch. Die Zahl die hinter Step steht kann sowohl positiv als auch negativ sein.

Kapitel 4 - Der Shipmanager - Einführung

Nachdem wir nun über ein paar Grundlagen verfügen, wollen wir uns den wirklich interessanten Dingen zuwenden, der Steuerung von Spielinhalten durch Scripte.

Um mit Schiffen zu interagieren gibt es eine Sammlung von Methoden, welche im Shipmanager zu finden sind. Hierzu müssen wir dem Shipmanager als erstes Mitteilen, welches bzw. welche Flotte er verwenden soll.

Hierführ gibt es die Befehle:

ShipManager.BenutzeSchiff(NCC-Nummer des Schiffes);

bzw.

ShipManager.BenutzeFlotte(ID der Flotte);

Damit weiß der ShipManager schonmal welches Schiff, bzw. welche Flotte die Aktionen ausführen soll.

Mit dem Shipmanager können folgende Aktionen ausgeführt werden:

• An- und Abdocken
• Alarm Stufe ändern
• Aus Flotten austreten
• Aus Orbit einfliegen austreten
• Benennen(Name As String)
• Deuterium sammeln (Nur mit FP)
• Erz sammeln (Nur mit FP)
• Fliegen
• Sensoren aktivieren / deaktivieren
• Reparieren
• Batterien entladen
• Schilde aktivieren/deaktiviere/aufladen
• Reservebatterie aufladen
• Traktorstrahl ein- / ausschalten
• Beamen
• Verstecken
• Replikator aktivieren/deaktivieren
• Waren über Bord werfen
• Warpkern aktiveren/deaktivieren
• Wrackextraktoren

Eine vollständige Auflistung aller Funktionen findet sich im Objekt-Explorer.

Im folgenden wollen wir uns einige Funktionen genauer anschauen:

Beamen

Syntaxe:

ShipManager.TransferiereZuSchiff(Schiffid, Menge, EBeamRessource.Ware);

Hier musst du nun nurnoch den kursiven Text mit deinen Angaben ersetzten. Hier ein Beispiele:

ShipManager.BenutzteSchiff(1);
ShipManager.TransferiereZuSchiff(2, 20, EBeamRessource.Nahrung);

Natürlich kann man auch eine ganze Flotte beamen lassen, dazu ersetzt du ShipManager.BenutzteSchiff(1); durch ShipManager.BenutzteFlotte(1); Dann sieht das Script folgendermasen aus:

ShipManager.BenutzteFlotte(1);
ShipManager.TransferiereZuSchiff(2, 20, EBeamRessource.Nahrung);

Fliegen

Bei der Syntaxe gibt es 2 Möglichkeiten, die eine für Spieler unter Level 8 oder mit Feature-Pack, also mit Autopilot, und die andere für die Leute über Level 8 und ohne Feature-Pack, die Variante ohne Autopilot.

Fliegen mit dem Autopiloten

Nur für Spieler mit Feature-Pack oder unter Kolonisationslevel 8 möglich!

Der Befehl:

ShipManager.FliegeZu(xxx|yyy);

Auch hier Gilt es wieder das kursive durch die eigenen Angaben zu ersetzten. Wie in folgendem Beispiel:

ShipManager.BenutzteSchiff(1);
ShipManager.FliegeZu('123|465');

oder mit dem Flottenbefehl:

ShipManager.BenutzteFlotte(1);
ShipManager.FliegeZu('123|465');

Mit deisem Befehl fliegt das Schiff zu einer belibigen Position, NPC-Gebiete ausgenommen, und umgeht dabei wie der Autopilot Energie-intensive Hindernisse, sowie solche die das Schiff oder die Crew Gefährden.

Fliegen ohne Autopilot

Der Befehl hierzu sieht wie folgt aus:

ShipManager.Fliege(Strecke, EShipRichtung.Richtung);

Auch hier ersetzt du die kursiven Worte mit deinen Angaben, ein Beispiel folgt:

ShipManager.BenutzteSchiff(1);
ShipManager.Fliege(5, EShipRichtung.Hoch);
ShipManager.Fliege(8, EshipRichtung.Links);

oder wenn es eine ganze Flotte ist:

ShipManager.BenutzteFlotte(1);
ShipManager.Fliege(5, EShipRichtung.Hoch);
ShipManager.Fliege(8, EshipRichtung.Links);

Schiffsystem nutzen

kommt noch

Alternative zum Schiffsmanager: Schiffsaktion

Für Objekte des Typ's CMyFlotte und CMyShip kann über die Eigenschaft Aktion direkt auf die Funktionen des Schiffsmanagers zugegriffen werden.

VAR Schiff AS CMyShip = new CMyShip( 4711 )
Schiff.Aktion.Abdocken()

VAR Flotte AS CMyFlotte = new CMyFlotte( 4711 )
Flotte.Aktion.Abdocken()

Enumeration ist Alles

kommt noch

Methoden

Öfters wiederkehrende Aufgaben können in Methoden zusammengefasst werden:

Function ShowKoords(x As Integer, y As Integer)
{
  WriteLine(CStr(x) + '|' + CStr(y));
}

Die Methode ShowKoords kann dann im Script folgendermaßen aufgerufen werden:

ShowKoords(3, 4);
ShowKoords(ship.MapPosition.X,ship.MapPosition.Y);

Wenn berechnete Werte von der Methode zurückgegeben werden sollen:

Function Distanz(x1 As Integer, y1 As Integer, x2 As Integer, y2 As Integer) As Integer
{
  Var distanz As Integer;
  
  distanz = Math.Abs(x1 - x2) + Math.Abs(y1 - y2);
  Return distanz ;
}

WriteLine(Distanz(1, 1, 5, 5));

Einfache Typen werden immer 'ByVal' übergeben, d.h. die Werte werden als Kopie an die Methode übergeben und die entsprechenden Variablen im Script nicht verändert. 'ByRef' ist zwar in der Scriptengine vorgesehen und kann angegeben werden, ist aber derzeit ohne Funktion. Objekte werden immer ByRef übergeben.

Klassen

In Klassen können Daten und Methoden in einem Objekt gekapselt werden:

Class CKoords
{
  Var x As Integer;
  Var y As Integer;
  
  Function New(x As Integer, y As Integer)
  {
    This.x = x;
    This.y = y;
  }
  
  Function ToString() As String
  {
    Return (CStr(x) + '|' + CStr(y);
  }
  
  Function Distanz(koord As CKoords) As Integer
  {
    Return Math.Abs(x - koord.x) + Math.Abs(y - koord.y);
  }
}

Var ko1 As New CKoords(3, 5);
Var ko2 As CKoords;


ko2 = New CKoords(8, 9);
WriteLine('Distanz von ' + ko1.ToString() + ' nach ' + ko2.ToString() + ': ' + CStr(ko1.Distanz(ko2)));

Wichtig: Klassen brauchen immer eine Methode New(), sonst kann kein neues Objekt der Klasse generiert werden!

Autoren

(hier dürfen sich diejenigen verewigen die hier min. ein Kapitel geschrieben haben [sonst kommt noch einer daher nur weil er nen Rechtschreibfehler verbessert hat ;)])

Nickname	IG-id	Kapitel
WiZz4Rd	16475	Kapitel 1, Kapitel 2, Kapitel 4
Stryke	28885	Vorwort, Kapitel 3, Kapitel 4
Xenon	10127	Korrektur & Überarbeitung Kapitel 1
Fling	54865	Kapitel 7, Kapitel 8

Anfängerkurs