Scripting

Main Principle
You can program plug-in DLLs which have reading and writing access to the vehicle variables and which can activate triggers.

Each plugin consists of a Configuration File with the extension *.opl and a corresponding DLL. Both files have to be in the directory "OMSI\plugins".

Description of the Example Plug-In
OMSI contains already an example plug-in. You can activate it in renaming the file "test.txt" into "test.opl" (you will find it in the directory "OMSI\plugins").

Functional Range
This plug-in has three functions: A speedometer (analog and digital) on top, a track bar to set the red heater handle (even if it calls it "Rollband-Sollwert") and a door button named "Button1" (with the same function like the [Num /] key).



Format of the *.opt File
To activate, rename this file to "test.opl"

[dll] Test.dll

[varlist] 2 Velocity cockpit_heizregler_temp

[triggers] 1 bus_doorfront0

The first line is just a comment line. The command [dll] indicates the file name of the corresponding DLL.

The [varlist] command starts with the expected number of (only local!) vehicle variables. You can also use user variables of a special bus type. Of course this won't have any effect, if the driven bus has not these user variables.

In this example, the variable with index 0 is "Velocity", the variable with index 1 is "cockpit_heizregler_temp".

The [triggers] command starts with the number of the expected triggers. In this case, there is only one trigger: "bus_doorfront0" with index 0.

Format of the DLL
With the shown example, I give you the corresponding Delphi Code. In general it should be possible to create DLLs with other programming languages, but I never tested that.

The DLL contains of two units, but I present you only the main unit (the second unit does not contain any important implementations):

library Test;

uses SysUtils, Dialogs, Classes, TestU in 'TestU.pas' {Form1};

{$R *.res}

procedure Start( AOwner: TComponent ); stdcall; begin form1 := TForm1.Create( AOwner ); form1.Show; end;

procedure Finalize; stdcall; begin form1.Free; end;

procedure AccessVariable( varindex: word; var value: single; var write: boolean ); stdcall; begin case varindex of               0: begin form1.Label2.Caption := floattostrF( value, ffFixed, 5, 1 ) + ' km/h'; form1.Gauge1.Progress := round( value ); write := false; end; 1:               begin value := form1.TrackBar1.Position / 30; write := true; end; end; end;

procedure AccessTrigger( triggerindex: word; var active: boolean ); stdcall; begin case triggerindex of               0: begin active := form1.button1_pressed; end; end; end;

exports AccessVariable, AccessTrigger, Start, Finalize;

begin end.

First of all note the last section "exports": It contains the four needed procedures of the DLL: AccessVariable, AccessTrigger, Start und Finalize.

These four procedures have the following functions:

Start
Start( AOwner: TComponent ) will be called at the beginning and allows the DLL to initialize itself. In this example, it creates Form1 and puts it to the same named variable (which is part of the second Unit). The second step is calling the Show command to make Form1 visible. Start hands the parameter "AOwner" over, the Handler of the main form of OMSI.

Finalize
Finalize will be called while closing OMSI. In the example, Form1 will be destroyed and freed.

AccessVariable
While running OMSI, this procedure will be called for all variables listed in the *.opl file. The index of the variable will be handed over via the variable varindex. The procedure can write now value and write.

If you just would like to read a vehicle variable, you just have to read value like in the case "0:". But it is also possible (like in "1:") to give a new value to value. In this case you have to set write to true to advise OMSI to use the new value. In the example, the position of the track bar will be used as new value of the variable with index 1 ("bus_doorfront0").

AccessTrigger
This procedure is very similar to AccessVariable, but OMSI will use the trigger list of the *.opl file. The DLL can set active to true and can trigger the event.

Definition
Configuration Files (or shorter: config files) are all files which supply OMSI with external data and constants and which do not include executable code like the files of the Scripts. They are plain text files and are following a special syntax developed for OMSI. There are lots of config files:


 * options.cfg, envir.cfg, gamectrl.cfg and keyboard.cfg for global OMSI parameters


 * global.cfg and all associated *.map files of the maps


 * *.sco-, *.sli-, *.bus-, *.ovh- and *.hum-files, which contain the general and physical data of scenery objects, splines, vehicles and humans


 * Model, sound, texture change, cabin and path files with the ending *.cfg, which contains further information about 3D objects

Syntax
The syntax of config files follow a scheme which is quite simple but not very common. The basic rules is:

OMSI reads only lines which are following a key word!

Examples
In the following examples, we imply that [keyword] is a key word of this config file and that OMSI expects three values following:

This is a comment, because there is no key word leading. So OMSI do not care about this lines until there is no key word.

In the upper example, nothing will happen.

[keyword] 1 2 3

This was a valid command which was introduced by [keyword]. After the three parameters were read, OMSI again searchs for key words and ignores everything else (like these two lines).

Now we had a command which allot the values 1, 2 and 3 to the three parameters. In front of and behind the key word there must not stay any other character, even no tab or space!

Wrong:

[keyword] 1 2 3

Wrong:

[keyword] Comment 1 2 3

With this knowledge, it is very simple to comment commands out - you just have to add at least one character:

Not commented out:

[keyword] 1 2 3

Commented out:

[keyword] 1 2 3

... or ...

[keyword]## 1 2 3

Attention! Not every command follows the convention "[...]"! Also these which are not bracked, follow the convention explained.

Some commands / key words expect a quantity of parameters first, so that the count of read lines by OMSI depends of this number. One example of this behaviour is the command to include scripts in a scenery object or vehicle:

[script] 3 script\script1.sco script\script2.sco script\script3.sco

Finally, there are some key words which expect an [end] command like e.g. the command [description]:

[description] Der MAN SD 200 ...

-Technische Daten-

Länge: 11.490 mm Breite: 2500 mm Höhe 4060 mm

Motor: MAN D2566MUH, 141 kW bei 2100 U/min Getriebe: Voith D851 Höchstgeschwindigkeit: 75 km/h

Leergewicht: 10700 kg Zulässiges Gesamtgewicht: 16.000 kg

Sitzplätze Oberdeck: 53 Sitzplätze Unterdeck: 35 Stehplätze: 8 [end]