Système de script

1. Généralités

Le système de scripts dans OMSI sert d'interface entre le noyau du jeu OMSI (y compris le moteur graphique et sonore) et les objets du décor ou les véhicules. La communication se fait dans les deux sens, de sorte que les objets du décor ou les véhicules peuvent être équipés de routines de script individuelles qui interprètent les entrées ou les informations du noyau de jeu OMSI ou qui transmettent des informations au noyau de jeu.

2. Conditions préalables

Pour étendre son propre contenu avec des fonctions de script, les conditions préalables suivantes sont nécessaires:

• un (ou plusieurs) fichier(s) de script avec code exécutable (*.osc)
• Fichiers varlist et stringvarlist pour la définition de variables locales
• Fichiers constfile pour définir les constantes utilisateur et le tableau des fonctions

Tous les fichiers qui doivent être lus par le véhicule/l'objet de scénario doivent être définis dans le fichier de configuration correspondant. Cela ne s'applique pas aux variables prédéfinies, qui peuvent être lues et écrites dans les fichiers de script sans être explicitement définies.

3. Application

Dans la configuration, les commandes suivantes peuvent être utilisées pour mettre en œuvre les différents fichiers:

• [script]
• [varnamelist]
• [stringvarnamelist]
• [constfile]

La commande est suivie du nombre de fichiers définis, puis des fichiers avec le chemin correspondant par rapport au fichier de configuration. Le nom du fichier peut être choisi librement, mais il faut éviter les caractères spéciaux comme "Ä,Ö,Ü", car cela peut poser des problèmes avec les systèmes qui n'ont pas installé de Windows en allemand. Il est préférable de s'en tenir à l'alphabet anglais, qui est généralement pris en charge de manière native par chaque système.

4. Les bases du langage de script

Le système de scripts d'OMSI utilise les notation polonaise inversée (RPN). Contrairement à l'écriture typique d'une opération arithmétique (2+5), l'opérateur ne se trouve pas entre les opérandes, mais derrière (25+). Même si la RPN semble inhabituelle au premier abord, elle présente quelques avantages que nous examinerons plus loin. Outre l'entrée plus efficace des opérations arithmétiques), la RPN permet également le traitement par lots, qui a une grande importance dans OMSI. Un exemple plus compliqué : " (1 + 2) * (3 + 4) " correspond à 1 2 + 3 4 + *.

Lors de la création de fichiers texte OMSI et de scripts, il faut faire attention aux majuscules et aux minuscules. OMSI est Case-Sensitive.

5. Stack(pile) et registre

Grâce à l'utilisation du RPN, OMSI possède une pile de chaînes (chaînes de caractères complexes) et une pile de virgules flottantes. Dans ce qui suit, le terme "pile" désigne toujours la pile en virgule flottante, sinon on parle de "pile de chaînes".

Les deux piles contiennent 8 emplacements de mémoire numérotés de 0 à 7 (basés sur 0). Chaque opération de script insère une nouvelle valeur dans la pile (push) ou extrait des valeurs de la pile (pop/pull). Une lecture (peek) sans modification de la pile est également possible. La dernière valeur définie prend alors la première place dans la pile, chaque valeur définie précédemment "monte" d'une place.

Si des valeurs doivent être stockées temporairement pour un traitement ultérieur dans le script, sans utiliser de variables locales, OMSI propose huit emplacements de mémoire indexés (0-7), qui peuvent être lus et écrits directement et se trouvent dans le registre. Cela ne vaut toutefois que pour les nombres à virgule flottante, il n'y a pas de registre pour les chaînes de caractères.

6. Exemple d'opérations

exemple:

L'opération est 1 + 2. Le code de script pour cela ressemble à ceci:

1 2 +

Le tableau suivant illustre le comportement de la pile lors de l'opération susmentionnée:

Dans l'état initial, la pile est généralement remplie de zéros. La commande "1" déplace le 1 vers le haut de la pile, tous les chiffres déjà présents remontent d'une place. La commande "4" place le quatre en haut de la pile, le un en deuxième position et tous les autres chiffres en troisième position. La commande "+" compare les deux premières valeurs de la pile et place le résultat à la première place de la pile. Lors de l'utilisation d'opérateurs, les valeurs à calculer sont retirées de la pile, le résultat se trouve alors à la place la plus haute de la pile.

Un autre exemple:

(1 + 2) * (3 + 4) doit être noté de la manière suivante, comme indiqué plus haut:

1 2 + 3 4 + *

Der Stack verhält sich somit folgendermaßen:

A la fin de l'opération, le résultat correct se trouve dans l'emplacement de pile 0.

Au lieu de chiffres, il est également possible d'utiliser des variables ou des résultats d'autres calculs comme opérandes.

7. Nombres flottants et chaînes de caractères

OMSI travaille exclusivement avec les types de données nombre à virgule flottante et chaîne de caractères. Ces types de fichiers ont des piles séparées et fonctionnent donc en général indépendamment l'un de l'autre. Il est toutefois possible de convertir des valeurs à virgule flottante en chaînes de caractères ou des chaînes de caractères en valeurs à virgule flottante - certaines fonctions peuvent donc avoir accès aux deux domaines en même temps.

Les variables booléennes ne sont pas utilisées dans OMSI. En règle générale, les valeurs numériques 0 et 1 sont utilisées pour true et false - c'est-à-dire le principe classique de oui/non en informatique.

8. Mots-clés de script

8.1. Commentaires

Les annotations ne sont possibles qu'en plaçant une apostrophe ' tout au début de la ligne à supprimer:

'Je suis un commentaire
 'Je NE SUIS PAS un commentaire!
_'Je NE SUIS PAS un commentaire!

OMSI ne reconnaît pas non plus une zone en retrait via des tabulations comme un commentaire - la tabulation est interprétée comme un signe. Tout à l'avant signifie donc tout à l'avant!

8.2. Entry-/Exitpoints, Trigger, Macros

Toutes les commandes doivent se situer entre un point d'entrée et un point de sortie. Les points d'entrée sont identifiés à l'aide des mots-clés suivants:

8.3. Appel de macro

L'appel d'une macro se fait par (M.L.''nom''). L'appel d'une macro doit toujours se faire AVANT la macro elle-même.

8.4. Division du script en plusieurs fichiers

Pour les scripts simples ou courts, l'utilisation du bloc principal {frame}-{end} (éventuellement en combinaison avec un bloc {init}-{end}) peut suffire. Pour les scripts complexes, il est recommandé d'utiliser un script principal qui contient un bloc de script principal et un bloc d'initialisation. Dans ce bloc, il est possible de définir des sous-scripts dans des fichiers séparés à l'aide d'un {Macro:Name}.

Il convient à cet égard de respecter les consignes suivantes:

• Un script principal qui contient les blocs {frame} et {init}, mais qui n'appelle que les subscripts à l'aide d'une macro
• Chaque script devrait avoir son propre fichier *.osc et - selon les besoins - ses propres Varlist et Consfiles. Les déclencheurs de touches qui appartiennent à cette section de script devraient également être définis dans le script correspondant.
• Les macros doivent être nommées de manière appropriée afin que les tiers puissent suivre les scripts - par exemple {macro:''subsystem''_frame} et {macro:''subsystem''_init}.
• Rappelons que l'appel d'une macro doit toujours se faire AVANT la macro elle-même. Si des sous-scripts sont utilisés, le script principal doit être appelé en premier dans le fichier de configuration. En cas d'appel de macros dans plusieurs fichiers, il faut également veiller à respecter l'ordre correct.

8.5. Trigger

Une section {trigger:''name''}...{end} peut être appelée de différentes manières à partir du programme principal. Il s'agit notamment de

• Déclenchement par le clavier.
  Si la combinaison de touches a été nommée ''Combinaison de touches'', {trigger:Combinaison de touches} est appelé lorsque la touche est enfoncée, {trigger:Combinaison de touches_off} est appelé lorsque la touche est relâchée
• Déclenchement par la souris.
  Si l'on a cliqué sur un maillage dont la désignation [mouseevent] est ''mouse_event'', {trigger:mouse_event} est appelé. En maintenant le bouton de la souris enfoncé, {trigger:mouse_event_drag} est appelé et en relâchant le bouton de la souris, {trigger:mouse_event_off} est appelé. Un déclencheur normal peut également être attribué à un mesh avec [mouseevent]. - Cette distinction n'est en général nécessaire que lorsque le mouvement de la souris a une influence sur l'animation ou les valeurs transmises (par ex. commutateur rotatif).

* Il existe également une série de LINK:Systemtrigger, qui sont définis par le noyau du jeu OMSI.

9. Operationen

9.1. Stack-Operationen

9.2. Opérations logiques

Les opérations logiques fonctionnent selon le principe 0 = FALSE, tout le reste est TRUE.

9.3. Opérations de comparaison

Les opérations de comparaison comparent les valeurs dans les deux emplacements de pile les plus élevés respectifs et insèrent ensuite un 1 ou un 0 dans l'emplacement de pile le plus élevé, en fonction du résultat.

9.4. Opérations mathématiques

9.5. Opérations sur les chaînes de caractères

* Attention: la commande ne supprime pas l'opérateur float de la pile. La valeur à la longueur de laquelle la chaîne a été raccourcie reste donc sur la pile0.

10. Accès aux variables

OMSI fait la différence entre les variables système et les variables locales. Les variables système peuvent être lues partout, les variables locales sont liées au véhicule/objet. Les variables système sont par exemple l'heure ou la météo, les variables locales sont par exemple la position d'un interrupteur dans le véhicule ou la température du chauffage.

Il existe également des variables locales prédéfinies qui ne sont pas définies par l'utilisateur. Il s'agit par exemple de la vitesse du bus. Les variables locales peuvent être attribuées par l'utilisateur de manière illimitée. Il existe également des variables "à la demande" qui sont prédéfinies par OMSI, mais qui doivent être définies par l'utilisateur.

Vous trouverez ici une description détaillée des différentes variables système et variables locales prédéfinies disponibles : LINK Variables

11. Constantes et fonctions

Les constantes locales et les fonctions définies à la pièce peuvent être définies dans les fichiers de constantes (''constfiles'', ''~_constfile.txt''). La structure de chaque fichier de constantes se compose d'un mot-clé, d'une variable et des valeurs correspondantes. Seules les valeurs en virgule flottante peuvent être définies, pas les chaînes de caractères.

[const] définit une nouvelle constante et indique sa valeur :

[const]
nom
valeur

exemple:

[const]
Power
200

[newcurve] introduit la définition d'une nouvelle fonction (linéaire par morceaux):

[newcurve]
nom

[pnt] ajoute une nouvelle paire x-y à la fonction définie précédemment avec [newcurve]. Chaque fonction doit normalement disposer d'au moins deux paires. L'ordre des paires ''doit'' être croissant dans la direction x!

[pnt]
x
y

exemple:

[newcurve]
Turbo_Curve

[pnt]
50
0

[pnt]
1000
0.3

[pnt]
2500
1

Les constantes sont appelées par la commande (C.L.''Constante'') dans le script et chargées dans la pile.

Les fonctions sont appelées par la commande (F.L.''Fonction''). La valeur qui se trouve sur la position supérieure de la pile est utilisée comme "entrée" (paramètre X) pour la courbe. La valeur Y définie par la fonction en position X est émise. Si la valeur x se déplace en dehors des limites des points d'angle définis par les entrées [pnt], la valeur y du point d'angle le plus proche est toujours utilisée. La fonction est donc prolongée horizontalement à l'infini avant le premier et après le dernier point d'angle.

12. Déclencheur de son

Les déclencheurs sonores ne sont pas des déclencheurs qui peuvent être contrôlés par des entrées au clavier ou à la souris. Les déclencheurs sonores sont déclenchés par le véhicule/script de scène et servent à la possibilité de jouer des sons. Il existe deux possibilités:

(T.F.''Soundtrigger'') Joue une fois un son défini par le script. Pour cela, la chaîne de pile la plus haute est lue et utilisée comme nom de fichier, le chemin d'accès au fichier étant interprété relativement au dossier son de l'objet.

exemple:

Le fichier son "Test.wav" défini avec le déclencheur "Soundtrigger" est lu lorsque (T.L.MeinTrigger) est appelé dans le script.

"Test2.wav" (T.F.MeinTrigger) joue le fichier Test2.wav. Ceci est nécessaire par exemple pour les annonces d'arrêts, pour lesquelles le script du véhicule calcule l'arrêt actuel et permet ainsi de jouer un fichier son différent à chaque arrêt avec le même déclencheur.

13. Macros système

Les fonctions mises en lumière jusqu'à présent permettent au script de communiquer avec OMSI de la manière suivante:

- Lecture de valeurs via des variables système et des variables locales prédéfinies

- Écriture de valeurs via ces mêmes valeurs

- Réception de déclenchements clavier, souris ou système

Outre ces possibilités, il existe également des "macros système". Ces macros sont des fonctions complexes qui attendent des entrées du script OMSI et qui transmettent des données au script en fonction de leur fonction. Ceci est par exemple nécessaire pour la lecture du fichier de la ferme.

L'application est identique à celle des macros définies par l'utilisateur, mais la macro système attend des informations qu'elle récupère dans la pile et réécrit le résultat dans la pile.

Une liste de toutes les macros système se trouve ici: LINK System-Makros

14. Conditions et boucles

Le seul contrôle du déroulement du programme n'est pour l'instant possible qu'avec la condition IF. Les boucles et les go-to ne sont que partiellement possibles avec le système de scripts OMSI.

14.1. Condition IF

'Il doit y avoir une condition:
    (L.L.blubb) 1 =
    {if}
'Cette section est exécutée si blubb = 1:
        2 3 +
    {else}
'Dans le cas contraire, cette section sera exécutée:
        3 4 +
    {endif}
    (S.L.bla)

En raison de la notation inversée avec traitement par lots, il est également logique que la condition soit définie en premier : les valeurs doivent d'abord être placées dans la pile pour que l'opérateur puisse les comparer. Le résultat est 0 ou 1, par conséquent true ou false. La condition {if} peut alors être évaluée avec cette valeur.

Ainsi, dans l'exemple ci-dessus, si ''blubb'' a la valeur 1, ''bla'' aura la valeur 5, sinon elle aura la valeur 7.

Les imbrications de la condition IF servent à remplacer les constructions "Else-If" (qui n'existent pas) :

'Une condition doit figurer ici, par exemple:
    (L.L.blubb) 1 =
    {if}
'Cette section est exécutée si blubb = 1:
        2 3 +
    {else}
        (L.L.blubb) 5 =
        {if}
'Cette section est exécutée lorsque blubb = 5:
            3 4 +
        {else}
'Dans le cas contraire, cette section sera exécutée:
            13
        {endif}
    {endif}
    (S.L.bla)

Il faut ici faire particulièrement attention au double {endif} ! Pour chaque condition {if} ouverte, il faut également placer un {endif}.