Marcel Kuhnt: Translated from German OMSIWiki

2011-11-18T17:11:14Z

Translated from German OMSIWiki

New page

= 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).

[[File:Beispiel-Plugin.jpg|600px|thumb|right|User interface of the example plug-in]]

== Format of the *.opt File ==

<pre>
To activate, rename this file to "test.opl"

[dll]
Test.dll

[varlist]
2
Velocity
cockpit_heizregler_temp

[triggers]
1
bus_doorfront0
</pre>

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):

<pre>
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.
</pre>

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.

[[Category:Developing Reference]]

[[de:Plug-in-Schnittstelle]]

Plug-In Interface - Revision history

Marcel Kuhnt: Translated from German OMSIWiki