OMSIWiki - Benutzerbeiträge [de]

Leitfaden performancefreundlicher Fahrzeugbau

2014-10-17T18:54:54Z

Faaabiii: 1. Zeile entfernt -> Artikel wurde übersetzt! Link zur englischen Seite ergänzt

Wie der Name schon sagt, soll dieser Leitfaden Möglichkeiten und Denkanstöße bieten, OMSI-Fahrzeuge möglichst performance-freundlich zu gestalten.

Ein OMSI-Fahrzeug besteht aus 3D-Modellen, Texturen, Sound und Script – und in allen vier Bereichen sollte man mehr oder weniger intensiv auf eine Optimierung hinsichtlich der Performance achten!

Aber eines gilt immer: '''Auch wenn man nicht mehr so geizen muss wie früher: Verschwenden sollte man keinesfalls!''' - Also sollte man bei jedem Teil, welches man modelliert, bei jedem Sound und bei jeder Textur ein wenig im Hinterkopf haben, was sinnvoll und nötig ist oder was eventuell mehr ist, als man braucht. Dass das Geschmacks- und Ansichtssache ist, versteht sich natürlich von selbst.

== 3D-Modelle ==

=== Theorie ===

Zunächst muss der Begriff 'Drawcall' definiert werden:

Zwar wird der Bus (wie alles andere) aus einzelnen Dreiecken gezeichnet, die Dreiecke ihrerseits sind aber zusammengefasst zu Meshs mit gleichen Materialeigenschaften, Texturen und so weiter. Einen solchen zusammengefassten Zeichenvorgang bezeichnet man als Drawcall. Intern wird dieser zunächst von OMSI vorbereitet, dann werden alle Parameter der Grafikkarte übergeben und schließlich arbeitet die Grafikkarte "eigenständig" den Drawcall mit allen zugehörigen Dreiecken ab.

Dieser Zusammenhang erklärt auch, warum ein Drawcall mit 100.000 Vertices wesentlich schneller abgearbeitet wird, als 1000 Drawcalls mit jeweils 100 Vertices.

=== Nicht zuviele o3d-Dateien und nicht zuviele einzelne Texturen ===

Jede o3d-Datei verursacht mindestens einen Drawcall pro Textur, die die o3d-Datei verwendet. In bestimmten Fällen und insbesondere auch bei x-Dateien können es sogar mehrere Drawcalls pro Textur und o3d-Datei sein.

Hieraus ergeben sich folgende Regeln:

'''Verwende so wenig o3d-Dateien wie möglich pro Bus.'''

Unumgänglich ist eine Separierung bei Animationen und oft bei transparenten Dingen, bei denen über die Separierung die Renderreihenfolge festgelegt wird. Daran kann man nicht rütteln.

Es ist aber ohne weiteres möglich, das Fahrzeug nur aus sehr wenigen nicht-animierten o3d-Dateien zusammen zu setzen, z.B. (Reihenfolge = Renderreihenfolge):

# Innenmesh inkl. Fahrerarbeitsplatz ohne Leuchtmelder, Schalter usw.
# Transparenzen im Innenraum
# Außenmesh
# Fensterscheiben von innen
# Fensterscheiben von außen

'''Innerhalb einer o3d-Datei so wenig unterschiedliche Texturen wie möglich.'''

Mit der obigen Erklärung wohl einfach zu verstehen: Wenn mein komplettes Außenmesh nur eine Textur hat, dann ist es auch nur ein Drawcall. Das ist besser als wenn mein Außenmesh zwei Texturen benötigt, sodass das Außenmesh in zwei Drawcalls gerendert werden muss.

Wird ein Bauteil ohnehin immer animiert (typisches Beispiel: Räder), dann ist es weniger tragisch, wenn deren Textur separat ist. Allerdings sollten auch die [[LOD]]s berücksichtigt werden: Da unsere Fahrzeuge in größerer Entfernung keine animierten Räder haben, haben wir die Radtextur auch in die Haupttextur integriert.

=== Verwendung von reduzierter Darstellung für die Entfernung und für KI-Fahrzeuge ===

Mit Hilfe von [[LOD]]s ist es möglich, dass das Fahrzeug auf größerer Entfernung einfacher gezeichnet wird. Und auch, wenn der User es nicht selbst verwendet, sollte es einfacher werden.

'''Jedes Fahrzeug sollte mindestens über zwei [[LOD]]-Stufen verfügen, sodass es ab unter etwa 10% Bildschirmgröße zu einer starken Vereinfachung kommt.'''

[[Datei:2012 0716 05 Performance.jpg|600px|thumb|right|Das sehr einfache LOD-Mesh für die größere Entfernung des SD77. Zwar sehr einfach, aber für größere Entfernungen völlig ausreichend und sehr sparsam. Einziges Manko: Aufgrund der Repaint-Möglichkeiten muss trotzdem die große 1024er-Textur für die Außenhaut geladen werden, aber abgesehen von der Reflexionstextur ist das alles!]]
In dieser Größenordnung kann bereits auf den Innenraum komplett verzichtet werden, die äußere Hülle sollte nur noch ein sehr einfaches Mesh sein (20-50 Vertices). Wir haben außerdem auf Nachttexturen und Lichteffekte in dieser Entfernung komplett verzichtet. Man muss ja nur noch sehen, "dass da ein Bus fährt".

'''Jedes Fahrzeug sollte als KI-Fahrzeug wesentlich vereinfacht werden.''' (Obgleich unpräzise, ist mit "KI-Fahrzeug" auch ein "verlassenes" Userfahrzeug gemeint. Sämtliche Flags, wie die folgende, die sich auf diese Nomenklatur beziehen, stufen verlassene Userfahrzeuge als KI-Fahrzeuge ein.)

Hierzu dient der Viewpoint-Befehl. Die darunterstehende Zahl kann folgende Werte annehmen:

* 0 = immer sichtbar
* 1 = am aktuellen Userfahrzeug nur von außen sichtbar
* 2 = am aktuellen Userfahrzeug nur von innen sichtbar
* 3 = 1 + 2, also am aktuellen Userfahrzeug von innen und außen sichtbar
* 4 = nur an KI-Fahrzeugen sichtbar.
* 5 = 4 + 1, also an KI-Fahrzeugen sichtbar oder am Userfahrzeug nur von außen
* 6 = 2 + 4, also an KI-Fahrzeugen sichtbar oder am Userfahrzeug nur von innen
* 7 = 1 + 2 + 4, also immer sichtbar, dann kann man auch die 0 nehmen! :)

Zu beachten ist: Ein KI-Fahrzeug sieht man sich nur von außen an, aber meist nicht so genau. Es kann aber sehr dicht stehen und man guckt oft auch mal von hinten rein (an der Ampel oder Haltestelle).

* KI-Fahrzeuge sollten daher das komplette, detaillierte Außenmesh haben und die groben Dinge des Innenmeshs, wie Verkleidungen, Sitze usw. Hierbei sind vor allem die Dinge wichtig, die man von hinten sieht.
* KI-Fahrzeuge brauchen nicht über ein animiertes Cockpit verfügen (animierter Sitz, Lenkrad) und Haltestangen kann man auch wesentlich vereinfachen. Theoretisch gilt das auch für den ''eigenen'' Bus in der Außenansicht, aber hier muss man nicht so sparsam sein, da der eigene Bus ja nur einmal sichtbar ist - KI-Fahrzeuge dagegen oft in großer Zahl.
* Sehr viel Potenzial bieten wieder Drawcalls: Typischerweise gibt es bei aller Optimierung mehrere Texturen für den Innenraum, oft aber nur eine für das Außenmesh. Sinnvollerweise also sollte man soviele Texturen des Innenraums wie möglich einsparen. Das statische Dashboard, das Lenkrad, die übriggebliebenen Haltestangen usw. benutzen oft separate Texturen; dies alles sollte im KI-Mesh über einen kleinen Bereich einer weiterhin notwendigen Textur gemappt werden, z.B. eine simple dunkelgraue, leicht "angerauhte" Fläche. Aber Achtung: Es bringt erst dann was, wenn eine oder mehrere komplette Texturen eingespart werden.

==== Das KI-Modell des SD77 als Beispiel ====

Das KI-Innenmesh des SD77 benötigt lediglich die Texturen SD77_02.bmp, _03.bmp und _04.bmp. Eingespart werden die Texturen Fahrersitz, Panel, Thermometer und Zahltisch gegenüber dem User-Innenraum:

[[Datei:2012 0716 03 Performance.jpg|300px]]

Unterschiede KI- und User-Mesh beim SD77. In der Ansicht von Hinten erkennt man die nur geringen Unterschiede, die vor allem Mesh-Vereinfachungen mit größerem Poly-Reduktionspotential besitzen: Haltestangen, Haltewunschknöpfe, Griffe an den Sitzen. Wichtige Details wie die Sitze, Treppenwangen oder auch Leuchten müssen beibehalten werden:

[[Datei:2012 0716 04 Performance.jpg|300px]]

=== Nicht übermäßig viele Vertices verwenden - Texturen können auch sinnvolle Dienste leisten ===

Damals™, als wir im Flusi mit dem Modellbau angefangen haben, mussten wir noch das Mesh per Hand auf Millimeterpapier zeichnen und die Koordinaten selbst ausmessen und maßstäblich umrechnen. Dann haben wir uns an die Lochkarten-Stanzmaschine gesetzt und wehe, wenn wir einen Fehler gemacht haben... ok, genug der angestaubten Geschichten von früher™! :-D (Wobei der Anfang noch stimmt, die Design-Programme für den Flusi kamen erst mit den Versionen 2000/2002 mit FSDS und Gmax so richtig in Schwung...)

Was ich mit der kleinen Geschichte von "damals als wir nix hatten" sagen will: Schon aus Egoismus heraus war man mit Polys und Vertices sparsam. Das bleibt so drinn - während wir heute uns den Freeware-NL202 ansehen und den 3D-Löwen sowie den 3D-Schriftzug bestaunen - und ebenso erstaunt sind, dass das OMSI frisst...

Selbstverständlich ist der NL202 ein gelungenes und natürlich sehr beliebtes OMSI-Addon. Trotzdem bin ich mal so frech und stelle ihn neben unseren in Entwicklung befindlichen NG272:

[[Datei:2012 0716 07 Performance.jpg|300px]]

Was fällt auf? Der NL202 verfügt über wesentlich mehr Polygone als der NG272. Selbstverständlich lassen sich bestimmte Dinge nur darstellen mit entsprechend detaillierten Modellierungen, z.B. die Schrägstellung der Lüftungsschlitze oder das Profil des Fenstergummileisten. Aber man muss sich beim Fahrzeugbau ständig fragen: Brauch ich das wirklich? Lohnt sich einerseits der Aufwand und andererseits der Preis der höheren Polygonzahl? Natürlich sieht es sehr schick aus, aber wann ist man schonmal da hinten am Motorraum?

Denn wenn man von weitem schaut, dann reicht eine passende fotoreale Textur im Allgemeinen aus. Natürlich glänzen unsere Lüftungsschlitze dafür nicht so schön in der Sonne! :)

=== Vertices nur da einbauen, wo es auch sinnvoll ist ===

Noch ein Beispiel zum Thema Vertex-Einsparung:

[[Datei:2012 0716 06 Performance.jpg|300px]]

Natürlich ist das mittlere Rohr das schönste! :) Aber dieses hat auch die meisten Polygone. Die Frage ist nun - wie genau spart man Polygone ein und wieviel optische Einbuße bringt es?

In diesem Fall kann man entweder in Längsrichtung oder in Umfangrichtung sparen. Was bringt mehr? Wenn man ungefähr gleiche Vertex- und Face-Zahlen erhalten möchte, dann sehen die Rohre wie gezeigt aus. Links wird in Längsrichtung kein einziges Mal mehr gebrochen, dafür hat der Umfang immer noch 32 Kanten. Rechts dagegen hat das Rohr nur 8 Kanten, dafür konnten alle sieben Brüche (entspricht ebenfalls 32 Ecken entlang des Vollkreises!) beibehalten werden. Offensichtlich die bessere Lösung: Denn den Querschnitt nimmt man nur wahr, wo das Profil endet (Auspuff) oder auf eine andersfarbige Fläche trifft bzw. selbst eine andere Farbe annimmt, während man die Längsrichtung oft sehr direkt sieht, wie auch in diesem Beispiel.

Typische Ähnlichkeit hierzu haben Haltestangen, die bei heutigen Bussen oft schwungvoll gestaltet sind: Auch dort sollte der "Schwung" ausreichend rund sein - dafür kann das Profil ruhig etwas eckiger sein (Acht- oder nur Sechseck).

Um also zum Anfang zurück zu kommen: 1995 hatte der FlightShop-Jumbo-Jet für den Flight Simulator 95 einen achteckigen (!!!) Rumpfquerschnitt! Das sollte man immer bedenken, wenn man 32-eckige Haltestangenprofile konstruiert! :D

== Texturen ==

Ein wichtiger Punkt wurde schon genannt:

=== Wenige große Texturen sind im Allgemeinen besser als viele kleine ===

..., insbesondere dann, wenn sie zusammen auf einer o3d-Datei zur Anwendung kommen. Natürlich gibt es Grenzen: Einerseits werden die Texturen ab einer bestimmten Auflösung irgendwann etwas "unhandlich", weshalb wir meistens nur bis 1024x1024 gehen, obgleich diese Grenze sicherlich auch nicht mehr ganz zeitgemäß ist.

=== Regelmäßige Auflösungen verwenden! ===

Was früher jeder Objektbauer im Flugsimulator wusste, ist heute nicht mehr allgemein bekannt: Texturen sollten Pixel-Maße haben, die der Zwei-Hoch-Reihe folgen:

1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, (2048, 4096, ...)

Die eingeklammerten Werte sind jenseits dessen, was wir üblicherweise nutzen und ehrlich gesagt weiß ich nicht, welche Einschränkungen da eventuell auch heute noch warten. Bis 1024 ist aber keinesfalls ein Problem.

Rechtecke sind auch ok, solange die obige Reihe eingehalten wird. 256x256 war früher im Flusi der ultimative Standard für alle Texturen, deshalb findet man bei "alten Hasen" oft heute noch dieses Maß. Aber 1024x128 ist ebenso ok wie 512x512 oder 4x128. Aber man sollte alle krummen Maße vermeiden (200x300 oder aber auch 256x77), weil die Verarbeitung tendentiell schlechter wird. Inwieweit das auf aktuellen Grafikkarten noch der Fall ist, weiß ich nicht - aber hinsichtlich der Kompatibilität zu älteren Karten kann es nicht schaden, sich an die Regel zu halten.

Insbesondere wird in solchen "krummen" Fällen ohnehin aufgerundet zum nächsten "zulässigen" Maß. Dann kann man auch gleich selbst aufrunden und die übrigen Bereiche noch sinnvoll nutzen anstatt verfallen zu lassen.

=== Dateiformate ===

DirectX lädt relativ viele Formate. Das traditionelle Format ist Bitmap (*.bmp). Da dieses Format nicht komprimiert ist, ist mancher geneigt, JPG zu verwenden.

Ob die Ladezeit schneller wird oder langsamer, vermag ich nicht zu sagen und das hängt sicherlich auch vom Aussehen der Textur und von einer Vielzahl anderer Faktoren ab. Allerdings sollte klar sein, dass (soweit ich weiß) es aber nichts bringt, um Grafikspeicher zu sparen, da das JPEG-Format nicht im Grafikkartenspeicher zur Anwendung kommen kann.

Möchte man also Grafikkartenspeicher sparen, dann sollte man eher auf das DDS-Format zurückgreifen, welches eine Komprimierung anbietet, die sich - soweit ich richtig informiert bin - auch in den Grafikkartenspeicher überträgt.

== Sound ==

Beim Sound kann man eigentlich gar nicht so viel falsch machen. Grundsätzlich ist OMSI da recht genügsam und auch dafür ausgelegt, dass Fahrzeuge viiiele Sounds haben, damit man richtig viel Spaß hat und normalerweise sind auch etwas längere Sample von 48kHz kein Thema.

Allerdings hat OMSI aus Performance-Gründen einen Soundzähler und eine Sortierfunktion, welche dafür sorgen, dass eine gewisse Höchstanzahl an Sounds nicht überschritten werden. Dies betrifft aber nicht nur aktuell hörbare sondern auch "theoretisch hörbare" Sounds, die also ständig geprüft werden müssen, ob sie demnächst hörbar werden müssen. Damit nun keine unnötigen freien "Soundplätze" verschwendet werden, gibt es die Möglichkeit, dass KI-Fahrzeuge (und wiederum User-Fahrzeuge, die verlassen wurden) mit einem einfacheren Sound-Set ausgerüstet werden.

Dies ist relativ einfach zu realisieren:

1. Zuerst erstellt man die normale Sound.cfg wie gewohnt und stellt sie komplett fertig.

2. Nun kopiert man sie und benennt sie um, praktischerweise z.B. in Sound_AI.cfg.

3. Nun löscht man alle Sound-Einträge in dieser Datei, die bei Fahrzeugen, die nicht der User selbt in der Hand hat, unnötig sind - als da wären:
:* Anlasser und Abschaltsound
:* Soundeffekte, die vor allem innen hörbar sind, wie z.B. der Luftpresser oder das Klappern im Stand beim SD
:* Cockpit- und ähnliche Systemsounds wie Schalter, Warnungen, IBIS, Rollband, Scheibenwischer usw. usw.
:* Beibehalten haben wir aber Motor, Achsplaneten, Getriebesounds, die man von außen hört, Retarder, Türen, Standheizung und Bremsenquietschen.

4. Zuletzt muss man noch die *.bus/*.ovh-Datei um folgenden Eintrag ergänzen: [sound_ai] | sound\Sound_AI.cfg, sodass OMSI nun weiß, dass hier ein KI-Soundset vorliegt.

Man stellt schnell fest, wieviel man hier einsparen kann und wieviel mehr Fahrzeuge dann noch in der Umgebung "klingen" im Gegensatz zu vorher.

== Script ==

=== Allgemein ===

Ähnlich wie beim Sound gibt es die Möglichkeit, ein vereinfachtes Script ablaufen zu lassen. Wie das geht, wird im Artikel [[Scriptsystem]] beschrieben.

Damit man allerdings jederzeit die Möglichkeit hat, das Fahrzeug zu übernehmen, werden stets alle normalen Variablen vorgehalten. Dies ist allerdings normalerweise kein größeres Problem.

Abgesehen davon ist OMSI auch hinsichtlich des Scripts genügsam bzw. gibt es kein größeres Optimierungspotential. Ganz allgemein kann man dem Script-Entwickler nur ganz allgemein auf den Weg geben: Sie wenig wie möglich, so viel wie nötig. Geizen muss man nicht, Verschwenden sollte man nicht und wenn man sich zwischen zwei Varianten entscheiden kann, sollte man versuchen, die mit besserer Leistung zu nehmen.

Wenn übrigens mehrfach genutzte Script-Sequenzen in ein gemeinsames Macro ausgelagert werden, dann spart das Ladezeit und Speicher. Zwar vermutlich nur mikroskopisch wenig, aber immerhin! ;-)

=== Spezielle Performance-Probleme ===

Was man beim Script aber beachten sollte, sind eventuelle Engpässe. Das Script selbst ist relativ unkritisch. Die [[System-Makros]] allerdings erfordern bisweilen einige Verarbeitung durch OMSI, z.B. wenn irgendwelche Hofdateien durchsucht werden. Es ist hier also sinnvoll, möglichst sparsam mit System-Makros umzugehen.

Außerdem erlaubt die Variable [[Refresh Strings|System- und vordefinierte lokalen Variablen]] ein gezieltes Aktualisieren von OMSI-Fonts am Fahrzeug (oder Szenerieobjekt): Dies sollte auch nur dann geschehen, wenn sich auch wirklich etwas geändert hat. Beim eigenen Fahrzeug ist das noch unkritisch, aber KI-Fahrzeuge sollten ihre Strings nur dann aktualisieren, wenn sich wirklich etwas ändert - z.B. die Matrix-Anzeige.

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:Guide to Performance-Friendly Vehicle Construction]]

Boundingbox

2014-05-16T14:21:48Z

Faaabiii:

Die Boundingbox wird in den geometrischen Grunddaten für die Konfigurierung eines Fahrzeugs benötigt.

=Anwendung=

Die Boundingbox wird unter dem Punkt "[boundingbox]" in der jeweiligen .bus oder .ovh-Datei eines Fahrzeugs eingetragen. Sie erstellt ein kubisches Kollisionsmodell um das Fahrzeug herum, das dafür sorgt, dass es mit der Szenerie und anderen Objekten zusammenstoßen kann.

=Definition=

Die Boundingbox setzt sich wie folgt zusammen:

==Voraussetzungen==

*Breite ohne Außenspiegel des zu simulierenden Fahrzeugs in m
*Länge des zu simulierenden Fahrzeugs in m
*Höhe des zu simulierenden Fahrzeugs in m

==Vorgehensweise==

Die Boundingbox besteht aus sechs Werten, die in je eine Zeile eingetragen werden:

#Breite
#Länge
#Höhe
#Abstand des Mittelpunkts der Boundingbox vom Nullpunkt des lokalen Koordinatensystems auf Breitenachse in m (x)
#Abstand des Mittelpunkts der Boundingbox vom Nullpunkt des lokalen Koordinatensystems auf Längsachse in m (y)
#Abstand des Mittelpunkts der Boundingbox vom Nullpunkt des lokalen Koordinatensystems auf Hochachse in m (z)

=Hinweis!=

Viele Maps weisen an Objektübergängen "unsichtbare Wände" auf, an denen vorwiegend tief liegende Fahrzeuge hängen bleiben. Um dies zu vermeiden, kann die Höhe von betroffenen Fahrzeugen um einen Meter reduziert und der Abstand der Box zum Nullpunkt um einen Meter auf der z-Achse erhöht werden.

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:Bounding Box]]

DISABLED-Befehl

2014-05-16T14:19:44Z

Faaabiii:

''OMSI-Version: 2.0''

Die Befehle "-<DISABLED>-" und "-<ENABLED>-" sind in einigen Konfigurationsdateien erlaubt und dienen dem Auskommentieren mehrerer Zeilen, ohne dass die jeweiligen Schlüsselworte einzeln auskommentiert werden müssen.

Die Anwendung erfolgt schlicht:

<pre>
...
{gültige Zeilen}
...
-<DISABLED>-
...
{auskommentierte Zeilen}
...
-<ENABLED>-
...
{gültige Zeilen}
...
</pre>

In folgenden Konfigurationsdateien kann dieser Befehl benutzt werden:

*.bus, *.ovh, *.sco, *.hum, model.cfg, envir.cfg, passengercabin.cfg, path.cfg

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:DISABLED-Command]]

Kehrwert des minimalen Lenkradius

2014-05-16T14:17:51Z

Faaabiii:

Der Kehrwert des minimalen Lenkradius wird in den physikalischen Grunddaten für die Konfigurierung eines Fahrzeugs benötigt.

=Anwendung=

Der Kehrwert des minimalen Lenkradius wird unter dem Punkt "[inv_min_turnradius]" in der jeweiligen .bus oder .ovh-Datei eines Fahrzeugs eingetragen.

=Berechnung=

Der Kehrwert des minimalen Lenkradius ergibt sich wie folgt:

==Voraussetzungen==

*Radstand des zu simulierenden Fahrzeugs in m
*Wendekreis vom kurvenäußeren zum kurvenäußeren Rad des zu simulierenden Fahrzeugs in m
*Optional: Windows-Taschenrechner in der wissenschaftlichen Ansicht

==Vorgehensweise==

# (2 * Radstand) / Wendekreis = sin(maximaler Einschlagwinkel der Räder auf Lenkachse in °)
# tan(maximaler Einschlagwinkel der Räder auf Lenkachse in °) / Radstand

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:Inverse of the Minimum Turning Radius]]

Fahrzeugmasse

2014-05-16T14:13:36Z

Faaabiii:

Die Masse eines Fahrzeugs wird für dessen korrekte Simulation benötigt. Dabei berechnet OMSI immer das aktuelle Gewicht aus dem in den physikalischen Grunddaten unter [mass] eingegebenen Leergewichts, sowie aller momentan beförderten Fahrgäste.

Daher ist es wichtig beim Eintragen eines Wertes für [mass] nach Möglichkeit das "trockene" Leergewicht zu verwenden, also das Gewicht ohne Tankinhalt, Gepäck, Fahrgäste und natürlich den Fahrer selbst.

Die Masse des Fahrzeugs wird in t angegeben.

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:Vehicle Mass]]

Scriptsystem

2014-05-16T14:09:46Z

Faaabiii:

''OMSI-Version: 1.0 - 2.0''

Das Scriptsystem in OMSI ermöglicht es, dass Szenerieobjekte und vor allem Fahrzeuge mit individuellen Systemen ausgestattet werden können, die über Variablen und Funktionsaufrufe mit dem Hauptprogramm und der Grafik- und Soundengine kommunizieren.

Der hier beschriebene Stand des Scriptsystems entspricht OMSI Version 1.01.

== Dateien des Scriptsystems ==

Das Scriptsystem umfasst folgende Dateien:

* Scriptdateien mit ausführbarem Code (*.osc)
* Varlist- und Stringvarlist-Dateien im OMSI\program-Verzeichnis zur Definition von Systemdateien und vordefinierten Dateien
* Varlist- und Stringvarlist-Dateien zur Definition von Uservariablen
* Constfile-Dateien zur Definition von Userkonstanten und Funktionstabellen

Abgesehen von den Dateien zur Definition von Systemvariablen müssen alle benötigten Dateien für jedes Fahrzeug/Szenerieobjekt (im folgenden kurz: Objekt) in dessen [[Konfigurationsdatei]] angemeldet werden.

Hierfür gibt es die Befehle ''[script]'', ''[varnamelist]'', ''[stringvarnamelist]'' und ''[constfile]''. Der erste Eintrag jedes Befehls ist die Anzahl der Dateien, darauf folgen die entsprechenden Dateinamen (inkl. Pfad relativ zur Konfigurationsdatei. Die Namen der Dateien sind nicht relevant, solange sie korrekt in die Listen eingetragen werden.

Auf die Funktion der jeweiligen Dateien wird im Laufe der Beschreibung der Scriptsprache eingegangen.

== Grundlagen der Scriptsprache ==

Das OMSI-Scriptsystem arbeitet mit der [http://de.wikipedia.org/wiki/Umgekehrte_Polnische_Notation umgekehrten Polnischen Notation]. Hierbei steht der Operator hinter den beiden Operanden; vereinfacht gesagt bedeutet es, dass die Operation " 1 + 2 " stattdessen folgendermaßen notiert wird: " 1 2 + ". Ein komplizierteres Beispiel: " (1 + 2) * (4 + 5) " entspricht " 1 2 + 4 5 + * ".

Ganz wichtig ist die Tatsache, dass die OMSI-Textdateien und insbesondere die Scriptsprache [http://de.wikipedia.org/wiki/Case_sensitivity Case-Sensitive] ist! D.h. es ist immer auf die Groß- und Kleinschreibung zu achten!

=== Stack und Register ===

Bei der Verarbeitung der Scripts verfügt OMSI über einen String-Stack und einen [http://de.wikipedia.org/wiki/Stapelspeicher Stack] für [http://de.wikipedia.org/wiki/Gleitkommazahl Gleitkommazahlen]. Im folgenden ist mit "Stack" immer der Stack für Gleitkommazahlen gemeint, andernfalls wird von "String-Stack" gesprochen.

Beide Stacks enthält 8 Speicherplätze, welche von 0 bis 7 durchnumeriert sind. Jede Script-Operation kann nun einen oder mehrere neue Werte in einen der Stacks einfügen (push), wobei der neue Wert auf die Position 0 gesetzt wird und alle folgenden Werte "einen Platz aufrücken", oder sie kann einen oder mehrere Werte aus dem Stack herausziehen (pop/pull) oder lediglich auslesen (peek).

Fürs temporäre Ablegen von Zahlen gibt es zusätzlich acht indizierte Speicherplätze, welche direkt geschrieben oder gelesen werden können, die sich im sogenannten Register befinden - hier gibt es jedoch nur einen Register für die Gleitkommazahlen.

=== Beispiel-Operationen ===

Beispiel: Die Operation 1 + 4. Der Code hierfür lautet:

<pre>
1 4 +
</pre>

In der folgenden Tabelle wird demonstriert, wie sich hierbei der Stack verhält:

<pre>
Operation: Stack: 0 1 2 3 4 ...
-----------------------------------------------------------------------------
vorher: 0 0 0 0 0
"1" 1 0 0 0 0
"4" 4 1 0 0 0
"+" 5 0 0 0 0
</pre>

Im Ausgangszustand ist der Stack nur mit Nullen (oder unbekannten/zufälligen Werten) gefüllt. Der Befehl "1" schiebt die Eins in den obersten Stackplatz und schiebt alle weiteren Werte (Nullen) nach hinten. Der Befehl "4" schiebt die Vier auf den 0. Platz und alle folgenden Werte, also insbesondere die Eins auf den jeweils nächsten Platz. Im nächsten Schritt "+" werden die obersten beiden Werte aus dem Stack herausgezogen - also 4 und 1 - und summiert. Das Ergebnis (5) wird wiederum in den Stack geschoben. Die beiden ursprünglichen Zahlen sind im Stack nicht mehr vorhanden.

Ein zweites Beispiel:

(1 + 2) * (4 + 5) muss wie bereits erwähnt folgendermaßen notiert werden:

<pre>
1 2 + 4 5 + *
</pre>

Der Stack verhält sich somit folgendermaßen:

<pre>
Operation: Stack: 0 1 2 3 4 ...
-----------------------------------------------------------------------------
vorher: 0 0 0 0 0
"1" 1 0 0 0 0
"2" 2 1 0 0 0
"+" 3 0 0 0 0
"4" 4 3 0 0 0
"5" 5 4 3 0 0
"+" 9 3 0 0 0
"*" 27 0 0 0 0
</pre>

Am Ende befindet sich also das korrekte Ergebnis auf Stackplatz 0!

=== Gleitkommazahlen und Strings ===

Das OMSI-Skriptsystem arbeitet ausschließlich mit den Datentypen Gleitkommazahl (einfache Präzision mit Vorzeichen) und String. Beide Datentypen haben getrennte Stacks. Deshalb laufen die Verarbeitung von Gleitkommazahlen und Strings im Allgemeinen unabhängig nebeneinander. Jedoch kann es natürlich vorkommen, dass bestimmte Funktionen z.B. Zahlen in Strings umwandeln und somit gleichzeitig auf beide Teilbereiche zugreifen.

Auf boolische Variablen wurde verzichtet. Für boolische Werte werden im Allgemeinen die Zahlenwerte 0 und 1 verwendet.

== Script-Schlüsselwörter ==

=== Kommentare ===

Kommentierungen sind nur möglich, indem in der auszukommentierenden Zeile ganz vorne ein Apostroph ['] gesetzt wird:

<pre>
'Ich bin eine Kommentarzeile
'Ich bin KEINE Kommentarzeile!
</pre>

=== Einstiegs- und Ausstiegspunkte, Makros und Trigger ===

Alle Befehle müssen zwischen einem Einstiegs- und einem Ausstiegspunkt liegen.

Der Einstiegspunkt wird durch eins der folgenden Schlüsselwörter gekennzeichnet:

* {frame} Im Laufe jedes Frames ruft OMSI über diesen Einstiegspunkt die frameweise Scriptverarbeitung auf, sofern er vorhanden ist.
* {init} Bei der Initialisierung ruft OMSI über diesen Einstiegspunkt die Script-Initialisierung auf.
* {frame_ai} Hierbei handelt es sich um eine Variante des {frame}-Einstiegspunktes, welcher bei Fahrzeugen dann aufgerufen wird, wenn diese nicht im Fokus des Benutzers stehen, z.B. wenn sie als KI-Fahrzeug unterwegs sind. Ist dieser Einstiegspunkt jedoch nicht vorhanden sondern nur {frame}, dann wird dieser alternativ aufgerufen. Bei Szenerieobjekten kommt dieser Eintrittspunkt nicht zur Anwendung.
* {macro:''name''} Dieser Einstiegspunkt ruft ein Subsektion (Makro) auf, welche '''stets nach dem Aufruf''' definiert werden muss.
* {trigger:''name''} Dieser Einstiegspunkt wird vom Hauptprogramm aufgerufen, wenn der Benutzer die Tastenkombination oder das Maus-Event mit der Bezeichnung ''name'' aufruft - es gibt auch bestimmte Trigger, die direkt vom Hauptprogramm aufgerufen werden, z.B. wenn OMSI bei KI-Bussen die Anzeige wechselt u.Ä.

{end} ist der universelle Ausstiegspunkt. Er muss stets den Block abschließen, der mit einem der obigen Befehle eröffnet wird.

==== Makroaufruf ====

Der Aufruf eines Makros erfolgt über (M.L.''name''). Der Aufruf des Makros muss ''immer'' vor dessen Definition erfolgen. Andernfalls meldet OMSI, dass das Makro nicht gefunden wurde.

==== Aufteilung des Scripts in mehrere Dateien ====

Bei einfachen Scripts (z.B. bei reinen KI-Fahrzeugen oder Szenerieobjekten) reicht es im Allgemeinen eine *.sco-Datei zu erstellen, welche über einen {frame}...{end}- und ggf. einen {init}...{end}-Block verfügt.

Handelt es sich jedoch um ein komplettes Fahrzeugscript, dann empfiehlt es sich für die verschiedenen Subsysteme getrennte Dateien anzulegen. Hierbei sollte folgendermaßen vorgegangen werden:

* Es gibt ein Hauptscript und die nötigen Subsystemdateien. Die Hauptdatei enthält dabei die {frame}- und {init}-Blöcke, die jedoch nur Makros aufrufen, welche in den Subsystemdateien definiert sind.
* Für jedes Subsystem gibt es eine *.sco-Datei und je nach Bedarf eine eigene Varlist und Constfile mit den zum System gehörenden Variablen. Außerdem werden auch hier die Trigger für die Tastenbefehle einsortiert.
* Die Makros sollten sinnvollerweise folgendermaßen benannt werden: {macro:''subsystem''_frame} und {macro:''subsystem''_init}.
* Damit die Makros vom Hauptscript aufgerufen werden, muss dieses in der Liste der Scripts in der Objekt-Konfigurationsdatei als erstes aufgerufen werden. Die Reihenfolge der Scripts untereinander muss ebenfalls so gewählt werden, dass alle dateiübergreifenden Makroaufrufe stets vor der jeweiligen Makrodefinition stehen.

Die Einschränkung, dass Makros immer hinter dem Aufruf definiert werden müssen, kann zwar bisweilen hinderlich sein, ist aber ein sehr wirksamer Schutz gegen Zirkelschlüsse und Endlosschleifen.

==== Trigger ====

Wie schon geschrieben wurde, kann ein {trigger:''name''}...{end}-Abschnitt durch verschiedene Möglichkeiten aus dem Hauptprogramm heraus aufgerufen werden. Hierzu zählen:

* Auslösung per Tastatur. Wurde die Tastenkombination mit dem Namen ''tastkomb'' bezeichnet, wird {trigger:tastkomb} aufgerufen, wenn die Taste gedrückt wird und {trigger:tastkomb_off}, wenn die Taste losgelassen wird.
* Auslösung per Maus. Wurde ein Mesh angeklickt mit der [mouseevent]-Bezeichnung ''mouse_ev'', so wird {trigger:mouse_ev} aufgerufen, wenn die Maustaste gedrückt wird, {trigger:mouse_ev_drag}, während die Maustaste gehalten wird und {trigger:mouse_ev_off}, wenn die Maustaste losgelassen wird.
* Außerdem gibt es noch eine Reihe von [[System-Trigger|System-Triggern]].

=== Operationen ===

==== Stack-Operationen ====

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |%stackdump%
| align="left" |Gibt eine Dialogbox mit dem Gleitkomma-Stackinhalt aus. Sollte deshalb natürlich nur zu Debug-Zwecken eingesetzt werden.
|-
| align="left" |s0, s1, ..., s7
| align="left" |Speichern des aktuellen Stackwertes im durch die Ziffer angegebenen Register. Der Wert verbleibt hierbei im Stack
|-
| align="left" |l0, l1, ..., l7
| align="left" |Laden des entsprechenden Registerwertes und Verschiebung in den Stack. Registerwert bleibt erhalten.
|-
| align="left" |d
| align="left" |Dubliziert den obersten Stackwert; alle weiteren Stackwerte rücken nach hinten.
|-
| align="left" |$msg
| align="left" |Schreibt den obersten String-Stack-Wert in die Debug-Zeile von OMSI - egal, ob es sich um ein User-, KI-Fahrzeug oder Szenerieobjekt handelt.
|-
| align="left" |$d
| align="left" |Dubliziert den Stringstack-Wert analog zu "d".
|}

==== Logische Operationen ====

Die logischen Operationen arbeiten nach dem Prinzip 0 = FALSE, alles andere ist TRUE.

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |&&
| align="left" |UND, d.h. wenn einer der beiden obersten Stackwerte gleich 0 ist, ist das Ergbnis 0, sonst 1.
|-
| align="left" |<nowiki>||</nowiki>
| align="left" |ODER
|-
| align="left" |<nowiki>!</nowiki>
| align="left" |Verneinung
|}

==== Vergleichsoperationen ====

Die Vergleichsoperationen vergleichen die Werte in den beiden jeweils obersten Stackplätzen und fügen dann je nach Ergebnis eine "1" oder "0" im obersten Stackplatz ein. Die Größer-/Kleinerzeichen stehen dabei entsprechend für der Reihenfolge, in der die Werte zuvor angegeben wurden. Das bedeutet:

4 2 > ist wahr, weil die intern durchgeführte Operation in diesem Fall "4 > 2" ist.

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |=
| align="left" |"1", falls die obersten Stackwerte identisch sind, sonst "0".
|-
| align="left" |<
| align="left" |"1", falls Stackwert 1 kleiner ist als Stackwert 0, sonst "0".
|-
| align="left" |>
| align="left" |... größer ist ...
|-
| align="left" |<=
| align="left" |... kleiner als oder gleich ist ...
|-
| align="left" |>=
| align="left" |... größer als oder gleich ist ...
|-
| align="left" |$=
| align="left" |Wie "=" nur für die obersten beiden Stringstack-Plätze.
|-
| align="left" |$<
| align="left" |Kleiner als (String). Die Ungleich-Operationen bei Strings prüfen auf alphabetische Reihenfolge. "A" ist also kleiner als "B".
|-
| align="left" |$>
| align="left" |Größer als (String).
|-
| align="left" |$<=
| align="left" |Kleiner oder gleich (String).
|-
| align="left" |$>=
| align="left" |Größer oder gleich (String).
|}

==== Mathematische Operationen ====

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |+
| align="left" |Plus
|-
| align="left" |-
| align="left" |Minus (Stackplatz 1 - Stackplatz 0, also vom Prinzip her wie bei den Größer/Kleiner-Operationen)
|-
| align="left" |*
| align="left" |Mal
|-
| align="left" |/
| align="left" |geteilt (Stackplatz 1 / Stackplatz 0)
|-
| align="left" |%
| align="left" |Rest der Division (folgendermaßen erweitert für Gleitkommazahlen: Stack0 - trunc(Stack1 / Stack0) * Stack1 )
|-
| align="left" |/-/
| align="left" |Vorzeichenwechsel
|-
| align="left" |sin
| align="left" |Sinus
|-
| align="left" |arcsin
| align="left" |Umkehrfunktion zum Sinus ''(ab OMSI2)''
|-
| align="left" |arctan
| align="left" |Umkehrfunktion zum Tangens ''(ab OMSI2)''
|-
| align="left" |min
| align="left" |Wahl des kleineren der beiden obersten Stackwerte
|-
| align="left" |max
| align="left" |Wahl des größeren der beiden obersten Stackwerte
|-
| align="left" |exp
| align="left" |Exponentialfunktion zur Basis e (e^Stack0)
|-
| align="left" |sqrt
| align="left" |Quadratwurzel
|-
| align="left" |sqr
| align="left" |Quadrat
|-
| align="left" |sgn
| align="left" |Rückgabe des Vorzeichens; je nachdem entweder -1, 0 oder 1
|-
| align="left" |pi
| align="left" |Kreiszahl pi
|-
| align="left" |random
| align="left" |ganzzahlige Zufallszahl 0 <= x < Stack0
|-
| align="left" |abs
| align="left" |Rückgabe des Absolutwertes
|-
| align="left" |trunc
| align="left" |Abrunden auf nächste ganze Zahl
|}

==== String-Operationen ====

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |"''bla''"
| align="left" |Einfügen des Strings ''bla'' auf dem obersten String-Stack-Platz
|-
| align="left" |$+
| align="left" |Zusammenfügen zweier Strings. "Omnibus" "simulator" $+ ergibt "Omnibussimulator"
|-
| align="left" |$*
| align="left" |Der oberste Stack-String wird sooft wiederholt, bis die resultierende Zeichenlänger gerade noch kleiner oder gleich des obersten Stackwertes ist. Beispiel: "nu" 6 $* ergibt "nununu"
|-
| align="left" |$length
| align="left" |Gibt die Anzahl der Zeichen des obersten Stack-String zurück in den Stack.
|-
| align="left" |$cutBegin
| align="left" |Schneidet ''stack0'' Zeichen vorne vom obersten Stack-String ab.
|-
| align="left" |$cutEnd
| align="left" |Schneidet ''stack0'' Zeichen hinten vom obersten Stack-String ab.
|-
| align="left" |$SetLengthR
| align="left" |Passt die Länge des obersten Stack-Strings auf ''stack0'' rechtsbündig an, indem am Anfang Zeichen entfernt oder Leerzeichen ergänzt werden.
Achtung: Der Befehl entfernt den Float-Operator nicht vom Stack. Der Wert, auf dessen Länge der String gekürzt wurde, verbleibt also auf Stack0.
|-
| align="left" |$SetLengthC
| align="left" |Passt die Länge des obersten Stack-Strings auf ''stack0'' zentriert an, indem am Anfang und am Ende Zeichen entfernt oder Leerzeichen ergänzt werden ''(ab OMSI2)''.
Achtung: Der Befehl entfernt den Float-Operator nicht vom Stack. Der Wert, auf dessen Länge der String gekürzt wurde, verbleibt also auf Stack0.
|-
| align="left" |$SetLengthL
| align="left" |Passt die Länge des obersten Stack-Strings auf ''stack0'' linksbündig an, indem am Ende Zeichen entfernt oder Leerzeichen ergänzt werden.
Achtung: Der Befehl entfernt den Float-Operator nicht vom Stack. Der Wert, auf dessen Länge der String gekürzt wurde, verbleibt also auf Stack0.
|-
| align="left" |$IntToStr
| align="left" |Rundet ''stack0'' ab und wandelt die resultierende Ganzzahl um in einen String.
|-
| align="left" |$IntToStrEnh
| align="left" |Die erweiterte Version von IntToStr. Hierbei wird der oberste Stack-String verwendet, um das Format der String-Umwandlung zu bestimmen: Das erste Zeichen im String wird zum Auffüllen der fehlenden Zeichen verwendet, die folgenden Zeichen müssen eine Zahl ergeben, die die Stellen angibt. Beispiel: 35 " 5" $IntToStrEnh führt zu " 35" und 123456789 "011" $IntToStrEnh führt zu "00123456789". Falls ein Fehler vorliegt, wird "ERROR" ausgegeben.
|-
| align="left" |$StrToFloat
| align="left" |Wandelt den obersten Stack-String in eine Gleitkommazahl um, falls möglich. Andernfalls wird eine -1 geschrieben.
|-
| align="left" |$RemoveSpaces
| align="left" |Entfernt sämtliche Leerzeichen vor und nach dem eigentlichen String. Aus " Spandau Freudstr " wird "Spandau Freudstr" ''(ab OMSI2)''.
|-
|}

=== Variablenzugriff ===

Es wird unterschieden in Systemvariablen und in lokale Variablen. Die Systemvariablen gelten OMSI-weit, die lokalen Variablen werden zum Fahrzeug/Objekt zugehörig gespeichert.

Bei den lokalen Variablen gibt es stets einen Grundstamm an Variablen, welcher von OMSI vordefiniert werden. Darüber hinaus können beliebig viele Variablen mit Hilfe der Varlist-Dateien ergänzt werden. Außerdem gibt es seit OMSI2 die Variante, dass man die Variable zwar selbst definieren muss, sie dann aber trotzdem mit einem OMSI-Internen Zustand verbunden wird ("on-demand-vordefinierte Variablen").

{| class="wikitable" style="font-size:95%;"
|- class="hintergrundfarbe5"
| align="left" |(L.S.''varname'')
| align="left" |Lädt die Systemvariable ''varname'' in den obersten Stackplatz
|-
| align="left" |(L.L.''varname'')
| align="left" |Lädt die lokale Variable ''varname'' in den obersten Stackplatz
|-
| align="left" |(L.$.''varname'')
| align="left" |Lädt die lokale String-Variable ''varname'' in den obersten String-Stackplatz
|-
| align="left" |(S.L.''varname'')
| align="left" |Speichert den obersten Stackplatz in die lokale Variable ''varname''
|-
| align="left" |(S.$.''varname'')
| align="left" |Speichert den obersten String-Stackplatz in die lokale String-Variable ''varname''
|}

Eine detaillierte Beschreibung der einzelnen Systemvariablen und der vordefinierten lokalen Variablen finden Sie hier: [[System- und vordefinierte lokalen Variablen]]

=== Konstanten und Funktionen ===

Lokale Konstanten und [http://de.wikipedia.org/w/index.php?title=Datei:Linear_interpolation.svg&filetimestamp=20080226155013 stückweise definierte lineare Funktionen] können in den Konstantendateien (''constfiles'', ''~_constfile.txt'') definiert werden. Der Aufbau jeder Konstantendatei entspricht der der [[Konfigurationsdateien|Konfigurationsdatei]]. Es gibt lediglich drei Schlüsselwörter. Zu beachten ist: Bisher können keine Strings, sondern nur Fließkommazahlen als Konstanten definiert werden.

[const] definiert eine neue Konstante und gibt ihren Wert an:

<pre>
[const]
name
wert
</pre>

Beispiel:

<pre>
[const]
leistung
200
</pre>

[newcurve] leitet die Definition einer neuen (stückweise linearen) Funktion ein:

<pre>
[newcurve]
name
</pre>

[pnt] fügt der zuvor mit [newcurve] definierten Funktion ein neues x-y-Paar hinzu. Jede Funktion sollte normalerweise über mindestens zwei Paare verfügen. Die Reihenfolge der Paare ''muss'' in x-Richtung aufsteigend sein!

<pre>
[pnt]
x
y
</pre>

Beispiel:

<pre>
[newcurve]
Drehzahl_Drehmoment_Kennlinie

[pnt]
50
0

[pnt]
300
400

[pnt]
1000
600
</pre>

Konstanten werden über den Befehl (C.L.''konstantenname'') in den Stack geladen.

Funktionen werden über den Befehl (F.L.''funktionsname'') aufgerufen. Dabei wird stets der zuvor auf oberster Stackposition befindliche Wert als x-Parameter übergaben und der resultierende y-Wert der Funktion stattdessen auf dem obersten Stackplatz gespeichert. Bewegt sich der x-Wert außerhalb der Grenzen der durch die [pnt]-Einträge definierten Eckpunkte, wird stets der y-Wert des nächstliegenden Eckpunktes verwendet. Die Funktion wird also vor dem ersten und hinter dem letzten Eckpunkt ins Unendliche waagerecht verlängert.

=== Sound-Trigger ===

Soundtrigger sind nicht mit den weiter oben erwähnten Triggern zu verwechseln!

Sie stellen vielmehr eine Möglichkeit dar, direkt einen gewünschten Sound abzuspielen. Hierbei gibt es zwei Möglichkeiten:

(T.L.''soundtriggername'') ist ein einfacher Soundtrigger. Der so markierte Sound wird (einmalig) abgespielt.

(T.F.''soundtriggername'') ist ein Soundtrigger mit Dateiwechselfunktion. Hierbei wird der oberste Stackstring ausgelesen und als Dateiname verwendet, wobei der Dateipfad relativ zum Sound-Ordner des Objektes interpretiert wird.

Beispiel:

Angenommen, die Sounddatei lautet "diese.wav" und ist mit dem Trigger ''MeinTrigger'' verknüpft, dann spielt

(T.L.MeinTrigger)

die Datei "diese.wav" ab und

"andere.wav" (T.F.MeinTrigger)

die Datei "andere.wav". Alternativ zu (T.L.''soundtriggername'') kann beim Befehl (T.F.''soundtriggername'') auch ein "Nullstring" im Stack liegen (also der String: "").

=== System-Makros ===

Die bisherigen Methoden erlauben dem Script folgende Kommunikationsmöglichkeiten mit OMSI:

* Lesen von Werten über System- und vordefinierte lokale Variablen
* Schreiben von Werten über ebendiese
* Empfangen von Tastatur-, Maus- oder Systemtriggern

Schließlich gibt es noch eine weitere Methode, um mit dem Hauptprogramm zu kommunizieren, die sogenannten System-Makros, gelegentlich auch unpräzise als "Callback-Funktionen" bezeichnet.

In bestimmten Situationen ist es nötig, dass das Script Werte von OMSI bekommt, die in größeren Datenbanken vorliegen und daher nicht über vordefinierte Variablen übermittelt werden können, z.B. die Inhalte der Hofdatei. Hier kommen nun die System-Makros ins Spiel.

Diese arbeiten scriptseitig sehr ähnlich wie die lokalen, selbstdefinierten Makros: Der Aufruf (M.V.''macroname'') ruft das System-Makro auf ("V" stand ursprünglich für "Vehicle-Macro", gilt aber genauso auch in Szenerieobjekten), das sich während der Ausführung Werte aus den beiden Stacks holt und/oder in diese schreibt. Eine Aufstellung aller System-Makros findet sich hier: [[System-Makros]]

=== Bedingungen und Schleifen ===

Die einzige Steuerung des Programmablaufs ist zur Zeit nur mit der IF-Bedingung möglich.

==== IF-Bedingung ====

<pre>
'Hier muss eine Bedingung stehen, z.B.:
(L.L.bla) 1 =
{if}
'Dieser Abschnitt wird ausgeführt, wenn bla = 1 ist:
2 3 +
{else}
'Dieser Abschnitt wird andernfalls ausgeführt:
3 4 +
{endif}
(S.L.blub)
{end}
</pre>

Dass erst die Bedingung formuliert wird und dann erst das Schlüsselwort {if} folgt, sollte einleuchten: Zunächst muss an oberster Stelle des Stacks der Wert abgelegt werden und erst dann folgt das Schlüsselwort {if}, welches diesen Wert prüft. Hierbei bedeutet ähnlich wie bei && und || Gleichheit mit Null gleichbedeutend mit ''False'', alle anderen Werte bedeuten ''True''.

Wenn also im obigen Beispiel ''bla'' den Wert 1 hat, wird ''blub'' auf den Wert 5 gesetzt, andernfalls auf den Wert 7.

Verschachtelungen der IF-Bedingung dienen als Ersatz für die (nicht vorhandenen) "Else-If"-Konstruktionen:

<pre>
'Hier muss eine Bedingung stehen, z.B.:
(L.L.bla) 1 =
{if}
'Dieser Abschnitt wird ausgeführt, wenn bla = 1 ist:
2 3 +
{else}
(L.L.bla) 5 =
{if}
'Dieser Abschnitt wird ausgeführt, wenn bla = 5 ist:
3 4 +
{else}
'Dieser Abschnitt wird andernfalls ausgeführt:
13
{endif}
{endif}
(S.L.blub)
{end}
</pre>

Hierbei ist insbesondere auf das doppelte {endif} zu achten! Hier gilt:

* bla = 1 ==> blub = 5
* bla = 5 ==> blub = 7
* sonst ==> blub = 13

[[Kategorie:Nachschlagewerk für Addon-Entwickler]]
[[en:Scripting System]]

Scriptsystem

2014-05-16T14:08:43Z

Faaabiii: