• Deutsch
  • English

Steuerschnittstelle

Das 3D-Modellbahn Studio stellt eine Programmierschnittstelle zur Verfügung, mit der das Studio über externe Programme um zusätzliche Funktionen erweitert werden kann, um somit noch komplexere Anlagenbetriebe zu ermöglichen. Die Schnittstelle ermöglicht das Abfragen von Zuständen, das Bearbeiten von Objekten sowie das Reagieren auf Ereignisse in eigens entwickelten Programmen. Zusätzlich können mit vorgefertigten Programmen, die von anderen Benutzern kostenfrei zur Verfügung gestellt werden und die ebenfalls die Steuerschnittstelle verwenden, die eigenen Anlagen einfach erweitert werden. Die Schnittstelle steht jedem Benutzer des 3D-Modellbahn Studio Professional automatisch zur Verfügung.

Inhaltsverzeichnis

1. Technische Grundlagen
    1.1. Kommandos
        1.1.1. Kommandogruppen
    1.2. Ereignisse
    1.3. Datentypen
    1.4. Plugins
       1.4.1 Anforderungen
       1.4.2 Startparameter
2. Liste der verfügbaren Kommandos
    2.1. Allgemeine Kommandos
    2.2. Allgemeine Objekt-Kommandos
    2.3. Kamera-Kommandos
    2.4. Gleis-Kommandos
    2.5. Rollmaterial-Kommandos
    2.6. Signal-Kommandos
    2.7. Steuerpult-Kommandos
    2.8. Text-Kommandos
    2.9. Kran-Kommandos
3. Liste der versendeten Ereignisse

1. Technische Grundlagen

Die Steuerschnittstelle des 3D-Modellbahn Studios unterscheidet zwischen Kommandos und Ereignissen. Ein Kommando stellt dabei einen Befehl dar, den das externe Programm an das Studio sendet und der verarbeitet werden soll. Ein Ereignis hingegen wird vom Studio an das externe Programm übermittelt, falls auf der Anlage eine entsprechende Veränderung auftritt. Kommandos und Ereignisse sind dabei einfache Textzeilen, die über eine TCP-Netzwerkverbindung zwischen den Programmen ausgetauscht werden.

Durch die Verwendung des weit verbreiteten TCP-Netzwerkprotokolls ermöglicht das Studio die Anbindung externer Programme aus beliebigen Programmiersprachen und Betriebssystemen heraus. Das 3D-Modellbahn Studio kann von einem Programm auf dem selben Computer, aber auch von einem anderen PC oder beliebigen Gerät im Internet angesteuert werden, solange eine TCP-Verbindung hergestellt werden kann. Dies erlaubt z.B. auch die Verwendung von Smartphones und Tablets mit Android oder iOS.

Das 3D-Modellbahn Studio verwendet für die Kommandos und Ereignisse zwei getrennte TCP-Verbindungen, sodass Kommandos und Ereignisse immer getrennt voneinander übertragen werden. Dies vereinfacht die Programmierung externer Programme, da diese ebenfalls den Code strikt nach Kommandos und Ereignissen trennen können und keine Vermischung behandeln müssen. Auch benötigt ein Programm z.B. keine Ereignis-Verbindung, wenn dieses nicht an den Ereignissen interessiert ist.

Die Kommando-Verbindung wird standardmäßig über Port 31285 und die Ereignis-Verbindung über Port 31286 aufgebaut. Beide Ports können in den Programmeinstellungen des 3D-Modellbahn Studios geändert werden. Bei der Installation des 3D-Modellbahn Studios wird die Windows-Firewall automatisch konfiguriert. Wird eine andere Firewall verwendet, so muss sichergestellt werden, dass eingehende und ausgehende TCP- und UDP-Verbindungen auf den beiden Ports freigegeben werden.

Eine Verbindung mit dem 3D-Modellbahn Studio wird über die IP bzw. den Host-Namen des Computers aufgebaut, auf dem das Studio läuft. Im lokalen Netzwerk bietet das Studio auch ein Broadcasting an, um ohne eine Eingabe der IP oder des Host-Namens eine Verbindung aufzubauen. Zu diesem Zweck sendet das externe Programm eine Broadcast-Nachricht (UDP) mit der Textzeile "{362E4489-482E-4E45-B782-43F80FF58809}" (ohne Anführungsstriche) in das lokale Netzwerk. Empfängt ein Computer mit laufendem 3D-Modellbahn Studio diesen Text, so sendet dieses den gleichen Text an den Sender zurück, wodurch das externe Programm Kenntnis über die IP des 3D-Modellbahn Studios erlangt.

1.1. Kommandos

Ein Kommando, welches über die TCP-Verbindung an das 3D-Modellbahn Studio gesendet wird, besitzt folgendes Format:

  • Eine ID (Zahl), die den Befehl identifiziert
  • Eine beliebige Liste von Parametern, die abhängig vom Kommando den Befehl genauer spezifizieren
  • Ein Linefeed (Zeilenvorschub), um das Ende einer Kommandozeile zu markieren

Die ID und die Parameter sind jeweils durch ein Semikolon (;) voneinander getrennt. Die Textzeile "5;Parameter 1;Parameter 2;Parameter 3" ist ein Beispiel für ein gültiges Kommando mit der ID 5 und 3 Parametern (der Zeilenvorschub ist hier nicht abgebildet).

Empfängt das 3D-Modellbahn Studio ein Kommando, wertet es dieses samt den Parametern aus und führt den Befehl entsprechend aus. Anschließend sendet das Studio auf der gleichen TCP-Verbindung eine Antwort zurück, die das Ergebnis des Befehls beinhaltet. Die Antwort ist dabei ebenfalls eine Textzeile mit folgendem Format:

  • Ergebniscode 0 oder 1 für einen nicht erfolgreichen bzw. erfolgreichen Befehl
  • Eine beliebige Liste von Parametern, die im Falle eines nicht erfolgreichen Befehls weitere Fehlerdetails und im Falle eines erfolgreichen Befehls das Ergebnis beinhalten
  • Ein Linefeed (Zeilenvorschub), um das Ende der Antwort zu markieren

Der Ergebniscode und die Antwortparameter sind ebenfalls durch ein Semikolon voneinander getrennt, z.B. "0;Falscher Parameter" für einen nicht erfolgreichen Befehl oder "1;Bodenplatte;Dampflok" für einen erfolgreichen Befehl mit zwei Rückgabewerten.

Das 3D-Modellbahn Studio sendet auf jedes Kommando eine Antwort zurück, unabhängig ob der Befehl erfolgreich verarbeitet werden konnte oder nicht. Ein zweites Kommando darf daher erst dann versendet werden, wenn die Antwort des ersten Kommandos empfangen wurde (eine Ausnahme spielen hier Kommandogruppen). Eine Antwort wird auch dann gesendet, wenn der Befehl keine Rückgabewerte ausgibt. In diesem Fall wird nur der Ergebniscode ohne Parameter zurückgesendet.

1.1.1. Kommandogruppen

Jedes Kommando, welches an das 3D-Modellbahn Studio gesendet wird, wird sofort von diesem bearbeitet. Mehrere versendete Kommandos werden nacheinander abgearbeitet, wobei der Nutzer zwischen den Kommandos auch andere Aktionen im Programm ausführen kann. Diese mögliche Unterbrechung der Abarbeitung von Kommandos durch den Nutzer kann durch die Nutzung von Kommandogruppen umgangen werden. Eine Kommandogruppe stellt für das 3D-Modellbahn Studio eine Sammlung von Kommandos dar, die immer als Einheit ausgeführt werden, ohne dass der Nutzer in der Zwischenzeit durch eine andere Aktion im Programm den Zustand ändern kann. Kommandogruppen eignen sich daher bei mehreren Aktionen, die aufeinander aufbauen (z.B. drehen und positionieren eines Objektes).

Das Gruppieren von Kommandos geschieht durch zwei explizite Einzelkommandos (10 und 11). Durch Senden des Kommandos 10 wird dem Studio mitgeteilt, dass alle folgende Kommandos Teil einer Gruppe sind und zusammen abgearbeitet werden sollen. Mit dem Senden des Kommandos 11 wird die Gruppe beendet, wodurch nachfolgende Kommandos wieder als Einzelkommandos betrachtet werden.

Im Gegensatz zu den Einzelkommandos werden die Kommandos, die innerhalb einer Gruppe versendet werden, nicht sofort, sondern lediglich zwischengespeichert und erst beim Beenden der Gruppe (Kommando 11) verarbeitet. Das bedeutet auch, dass auf ein Gruppenkommando keine sofortige Antwort vom 3D-Modellbahn Studio gesendet wird. Die Antwort wird erst nach Beendigung der Gruppe versendet. Beispiel:

  • Senden der Kommandos
    1. Start der Gruppe: Kommando 10
    2. Kommando X
    3. Kommando Y
    4. Kommando Z
    5. Beenden der Gruppe: Kommando 11 -> Jetzt beginnt die Verarbeitung aller gesendeten Kommandos
  • Empfang der Antworten
    1. Antwort von Kommando 10
    2. Antwort von Kommando X
    3. Antwort von Kommando Y
    4. Antwort von Kommando Z
    5. Antwort von Kommando 11

Da die Antworten der Einzelkommandos erst nach dem Beenden der Gruppe gesendet werden, können nur solche Kommandos gruppiert werden, deren Parameter nicht von dem Ergebnis eines vorhergehenden Gruppenkommandos abhängen.

1.2. Ereignisse

Tritt auf der geöffneten Anlage ein Ereignis ein, so informiert das 3D-Modellbahn Studio ein extern verbundenes Programm über die Ereignis-Verbindung. Ein Ereignis wird z.B. ausgelöst, wenn ein Zug ein Gleis betritt oder ein Schalter betätigt wird. Ein einzelnes Ereignis besitzt dabei folgendes Format:

  • Eine ID (Zahl), die den Ereignistyp spezifiziert
  • Eine beliebige Liste von Parametern, abhängig des Ereignisses, die weitere Informationen zum aufgetretenen Ereignis beinhalten
  • Ein Linefeed (Zeilenvorschub), um das Ende eines Ereignisses zu markieren

Ereignisse werden automatisch vom 3D-Modellbahn Studio versendet. Die Ereignis-Verbindung wird dabei nur zum Senden verwendet, d.h. das Studio erwartet keine Antwort auf der Ereignis-Verbindung. Reaktionen auf Ereignisse müssen per Kommando über die Kommando-Verbindung gesendet werden.

1.3. Datentypen

Die Kommandos und Ereignisse werden immer in Textform (UTF8-kodiert) übertragen. Dennoch erwartet das 3D-Modellbahn Studio die Parameter je nach Befehl in einer bestimmten Form bzw. Datentypen:

  • String: Definiert eine Zeichenkette und wird nicht speziell interpretiert.
  • Boolean: Definiert einen Zustand mit zwei Werten (Wahr/Falsch bzw. An/Aus), wobei eine 0 als falsch/aus und eine 1 als wahr/an interpretiert wird.
  • Zahl: Definiert eine ganze Zahl, z.B. 5 oder -3.
  • Gleitkommazahl: Definiert eine gebrochene Zahl, z.B. 3.141 oder -100.9. Zu beachten ist, dass Gleitkommazahlen im englischen Format interpretiert werden, d.h. der Dezimaltrenner ist immer der Punkt.

1.4. Plugins

Die Steuerschnittstelle kann in beliebigen Programmen verwendet werden, um das 3D-Modellbahn Studio mit neuen Funktionen zu erweitern. Damit alle Nutzer einen schnellen und einfachen Zugriff auf die Programme erhalten, erlaubt das 3D-Modellbahn Studio die Integration der Steuerschnittstellenprogramme in den Online-Katalog (Plugins). Dadurch ergeben sich folgende Möglichkeiten:

  • Die Programme können direkt aus dem 3D-Modellbahn Studio heraus aufgerufen werden (Menü "Katalog - Plugins"), ohne diese manuell zu entpacken oder zu installieren
  • Aktualisierte Programme werden automatisch heruntergeladen, sodass alle Nutzer immer die neueste Version besitzen
  • Plugins können mit Anlagen verknüpft werden, sodass diese beim nächsten Öffnen der Anlage automatisch starten

1.4.1. Anforderungen

Plugins sind normale ausführbare Anwendungen, die jedoch ein paar Anforderungen erfüllen müssen, damit sie zum Online-Katalog hinzugefügt werden können:

  • Das Plugin muss aus einem beliebigen Verzeichnis heraus aufgerufen werden können. Das 3D-Modellbahn Studio entpackt ein Plugin automatisch in ein temporäres Verzeichnis vor dem Start und löscht es auch wieder nach Beendigung.
  • Alle Dateien, die das Plugin zur Ausführung benötigt, müssen im Plugin-Verzeichnis (oder Unterverzeichnis) mitgeliefert werden. Es gibt keine getrennte Plugin-Installation.
  • Das Plugin muss ohne Administrator-Rechte laufen und stellt wenn möglich automatisch eine Verbindung zum 3D-Modellbahn Studio her. Die verwendeten Ports für die Steuerschnittstelle werden beim Start übergeben (siehe Startparameter).
  • Programmeinstellungen dürfen nicht im Programmverzeichnis gespeichert werden (da dieses eh nach dem Beenden des Plugins gelöscht wird). Einstellungen sollten im DataDir abgespeichert werden (siehe Startparameter).
  • Das Plugin sollte idealerweise ohne Rückfragedialoge beendet werden, da das 3D-Modellbahn Studio Plugins automatisch beendet, wenn die Anlage geschlossen wird.
  • Zur Veröffentlichung im Online-Katalog wird eine Kurzbeschreibung, ein Vorschaubild (512 x 384 Pixel) und ein eigenes Thema im Plugin-Forum benötigt. Die Kurzbeschreibung muss den Link zum Forenthema enthalten. Das Thema sollte eine ausführliche Beschreibung enthalten und dient für Nutzer-Rückfragen.
  • Zusätzliche Dateien, die nicht zur Ausführung benötigt werden (wie z.B. der Quellcode oder Hilfedateien), sollten gesondert im Forumthema als separater Download angeboten werden.

Eine Sammlung vorhandener Plugins sind im Plugin-Forum zu finden.

1.4.2. Startparameter

Plugins werden direkt vom 3D-Modellbahn Studio gestartet und wieder beendet. Um die Kommunikation zwischen einem Plugin und dem Studio zu vereinfachen, übergibt das 3D-Modellbahn Studio einige Kommandozeilenparameter an das Plugin:

  • /DataDir:"Pfad" - Enthält den Namen eines Verzeichnisses, das das Plugin für dauerhafte Datenspeicherungen nutzen kann. Dieses Verzeichnis ist für jedes Plugin individuell und kann z.B. zum Speichern von Einstellungsdateien verwendet werden. Die Daten stehen auch beim nächsten Plugin-Start zur Verfügung und werden erst mit der Deinstallation des 3D-Modellbahn Studios gelöscht.
  • /Locale:Name - Enthält die im 3D-Modellbahn Studio eingestellte Sprache, sodass die Plugins ihre eigene Sprache anpassen können.
  • /CommandPort:Port - Enthält den Port für die Kommando-Verbindung zur Steuerschnittstelle.
  • /EventPort:Port - Enthält den Port für die Ereignis-Verbindung zur Steuerschnittstelle.

2. Liste der verfügbaren Kommandos

Im Folgenden werden die zur Verfügung stehenden Kommandos tabellarisch nach Thema aufgelistet, wobei die einzelnen Parameter und Rückgabewerte der Befehle erklärt werden.

Objekte werden im 3D-Modellbahn Studio über ihren Namen angesprochen. Es ist daher sinnvoll, Objekten, die über die Steuerschnittstelle abgefragt oder verändert werden, eindeutige Namen zuzuweisen.

2.1. Allgemeine Kommandos

Die folgenden Kommandos beziehen sich auf allgemeine Themen rund um das 3D-Modellbahn Studio und eine eventuell geöffnete Anlage.

ID Beschreibung Parameter Rückgabewerte
1 Liefert die Programmversion des 3D-Modellbahn Studios zurück Keine String - 4-stellige Versionsnummer im Format X.Y.Z.W
2 Liefert den vollständigen Dateipfad des 3D-Modellbahn Studios zurück Keine String
10 Startet eine neue Kommandogruppe Keine Zahl - Anzahl der verarbeiteten Kommandos innerhalb der Gruppe
11 Beendet die aktive Kommandogruppe Keine Keine
20 Liefert die ID der geöffneten Anlage zurück Keine String - ID der geöffneten Anlage als GUID
21 Liefert zusätzliche Informationen zur geöffneten Anlage zurück Keine String - Name der geöffneten Anlage
40 Gibt die Einheit für das Längenmaß zurück Keine Zahl - 0 für mm, 1 für cm, 2 für dm, 3 für m, 4 für Zoll
41 Setzt die Einheit für das Längenmaß. Hinweis: Die Einheit gilt nur für die Kommunikation über die Steuerschnittstelle und muss nach jeder Verbindung neu gesetzt werden. Zahl - Einheit als Zahl, siehe Kommando 40 für eine Liste unterstützter Einheiten. Keine
42 Gibt die Einheit für das Winkelmaß zurück. Keine Zahl - 0 für Grad, 1 für Bogenmaß
43 Setzt die Einheit für das Winkelmaß. Hinweis: Die Einheit gilt nur für die Kommunikation über die Steuerschnittstelle und muss nach jeder Verbindung neu gesetzt werden. Zahl - Einheit als Zahl, siehe Kommando 42 für eine Liste unterstützter Einheiten. Keine
50 Gibt zurück, ob die Animationen im Studio aktiviert sind Keine Boolean
51 Aktiviert oder deaktiviert die Animationen im Studio Boolean Keine
52 Gibt zurück, ob Geräusche im Studio aktiviert sind Keine Boolean
53 Aktiviert oder deaktiviert die Geräusche im Studio Boolean Keine
54 Gibt zurück, ob der Simulationsmodus im Studio aktiviert ist Keine Boolean
55 Aktiviert oder deaktiviert den Simulationsmodus im Studio Boolean Keine
60 Gibt alle Variablen aus der Ereignissteuerung zurück String - Optionaler Name des Objektes, für das die Variablen zurückgegeben werden sollen. String, String, String... - Für jede Variable den Namen und ihren Wert als eigenen String
61 Gibt den Wert einer bestimmten (Objekt)-Variable zurück String - Name der Variable String - Wert der Variable
62 Setzt den Wert einer bestimmten (Objekt)-Variable

String - Name der Variable
String - Wert der Variable

Keine
70 Ermittelt alle Countdowns der Ereignisverwaltung Boolean - Gibt an, ob nur aktive Countdowns ermittelt werden sollen (True) String, String, String... - Für jeden Countdown den Namen
71 Ermittelt den aktuellen Zustand eines Countdowns String - Name des Countdowns

Gleitkommazahl - Restlaufzeit
Gleitkommazahl - Gesamtdauer
Boolean - Automatischer Neustart

80 Animiert das aktive Projekt eine feste Zeitspanne lang Gleitkommazahl - Anzahl der Sekunden, um die das Projekt animiert werden soll. Keine

2.2. Allgemeine Objekt-Kommandos

Die folgenden Kommandos beziehen sich auf alle Objekttypen und ermöglichen die Abfrage und das Setzen von Zuständen, die für alle Objekte gelten.

ID Beschreibung Parameter Rückgabewerte
100 Liefert eine Liste der Namen aller Objekte auf der Anlage zurück Zahl - 0 für alle Objekte, 1 für Gleise, 2 für Rollmaterial, 3 für Signale, 4 für Schranken, 5 für Lokschuppen, 6 für Oberleitungen, 7 für Kameras, 8 für Licht, 9 für Bodenplatten, 10 für Grundkörper, 11 für Steuerelemente, 12 für Objektgruppen, 13 für allgemeine Modelle, 14 für Beschriftungsobjekte String, String, String... - Für jedes Objekt ein Name
101 Gibt den Typ eines Objektes zurück String - Name des Objektes Zahl - siehe Kommando 100 für eine Liste von Objekttypen
102 Gibt die 3D-Position eines Objektes zurück String - Name des Objektes 3x Gleitkommazahl - X, Y, Z
103 Setzt die 3D-Position eines Objektes String - Name des Objektes
3x Gleitkommazahl - X, Y, Z
Keine
104 Gibt die Rotation eines Objektes um die 3 Achsen zurück. String - Name des Objektes 3x Gleitkommazahl - Rotation um X, Y, Z
105 Setzt die Rotation eines Objektes String - Name des Objektes
3x Gleitkommazahl - Rotation um X, Y, Z
Keine
106 Gibt die Skalierung eines Objektes zurück String - Name des Objektes Gleizkommazahl
107 Setzt die Skalierung eines Objektes String - Name des Objektes
Gleitkommazahl - Neue Skalierung
Keine
108 Gibt die Größe eines Objektes zurück (entlang X, Y, Z) String - Name des Objektes 3x Gleitkommazahl - Größe entlang X, Y, Z
130 Gibt die Namen aller selektierten Objekte zurück Keine String, String, String... - Für jedes selektierte Objekt ein Name
131 Selektiert eine Liste von Objekten Boolean - Gibt an, ob die Objekte zur aktuellen Selektion hinzugefügt werden sollen oder sie ersetzen
String, String, String... - Für jedes zu selektierende Objekt ein Name
Keine
133 Liefert die Katalog-GUID eines Objekts zurück String - Name des Objekts. Existiert das Objekt nicht im Katalog, so wird eine Fehlermeldung zurückgegeben. String - GUID des Objekts
134 Fügt ein neues Objekt aus dem Katalog auf der Anlage ein String - GUID des Katalogobjektes
String - Optionaler Name des neuen Objektes
Keine
135 Dupliziert ein vorhandenes Objekt auf der Anlage String - Name des zu duplizierenden Objektes
String - Name des neuen Objektes
Keine
136 Löscht ein vorhandenes Objekt von der Anlage String - Name des zu löschenden Objektes Keine
137 Benennt ein Objekt um String - Name des Objektes
String - Neuer Name
Keine
138 Gruppiert eine Liste von Objekten String - Name der neuen Gruppe
String, String, String... - Für jedes zu gruppierende Objekt ein Name. Werden keine Namen angegeben, so wird die aktuelle Selektion gruppiert.
Keine
139 Löst eine Objektgruppe auf String - Name der Gruppe Keine
140 Verknüpft zwei Objekte (A folgt B) String - Name des Objektes A
String - Name des Objektes B
Keine
141 Hebt die Verknüpfung eines Objektes auf String - Name des Objektes Keine
142 Ermittelt den Namen des verknüpften Objektes String - Name des Objektes, dessen Verknüpfung ermittelt werden soll String - Name des verknüpften Objektes bzw. leer, falls das Objekt nicht verknüpft ist.
143 Ermittelt die Sichtbarkeit eines Objektes String - Name des Objektes Boolean - 0 für unsichtbar, 1 für sichtbar
144 Setzt die Sichtbarkeit eines Objektes String - Name des Objektes
Boolean - 0 für unsichtbar, 1 für sichtbar
Keine
150 Gibt eine Liste aller Objekte mit benutzerdefinierten Animationen zurück Keine String, String, String... - Für jedes Objekt mit einer Animation ein Name
151 Startet eine Objekt-Animation

String - Name des Objektes
String (optional) - Name der Animation. Falls nicht angegeben, werden alle Animationen gestartet.
Zahl - Richtung der Animation, -1 für Rückwärts, 1 für Vorwärts
Boolean - Gibt an, ob die Animation automatisch wiederholt werden soll

Keine
152 Stoppt eine Objekt-Animation String - Name des Objektes
String (optional) - Name der Animation. Falls nicht angegeben, werden alle Animationen gestoppt.
Keine
153 Setzt eine Objekt-Animation an eine bestimmte Position String - Name des Objektes
String (optional) - Name der Animation. Falls nicht angegeben, werden alle Animationen zurückgesetzt.
Gleitkommazahl - Neue Position der Animation zwischen 0 (Anfang) und 1 (Ende)
Keine
161 Startet ein Objektgeräusch

String - Name des Objektes
String (optional) - Name des Geräusches. Falls nicht angegeben, werden alle Geräusche gestartet.
Boolean - Gibt an, ob das Geräusch automatisch wiederholt werden soll

Keine
162 Pausiert ein Objektgeräusch String - Name des Objektes
String (optional) - Name des Geräusches. Falls nicht angegeben, werden alle Geräusche pausiert.
Keine
163 Stoppt ein Objektgeräusch String - Name des Objektes
String (optional) - Name des Geräusches. Falls nicht angegeben, werden alle Geräusche gestoppt.
Keine

2.3. Kamera-Kommandos

Die folgenden Kommandos ermöglichen die Steuerung der Kameras auf einer Anlage.

ID Beschreibung Parameter Rückgabewerte
250 Gibt eine Liste der Namen aller Kameras zurück Zahl - 0 für alle Kameras, 1 für die freie und 2D-Kamera, 2 für benutzerdefinierte Kameras, 3 für Cockpit-Kameras String, String, String... - Für jede Kamera ein Name
260 Gibt einen Screenshot als JPEG einer Kamera zurück String - Name der Kamera, für die ein Screenshot aufgezeichnet werden soll. Falls leer, dann wird ein Bild der aktiven Kamera zurückgeliefert.
Zahl - Breite des Screenshot in Pixel, maximal 2048.
Zahl - Höhe des Screenshot in Pixel, maximal 2048.
Zahl - Kompressionsqualität zwischen 0 und 100.
String - Die JPEG-Datei, kodiert in Base64
270 Gibt den Namen der aktiven Kamera zurück Keine

String - Name der Kamera
Boolean - Gibt an, ob es sich bei der Kamera um eine technische Ansicht handelt (nur bei 2D-Kamera)

271 Aktiviert eine Kamera String - Name der Kamera
Boolean - Gibt an, ob die technische Zeichnungsansicht aktiviert werden soll (nur bei 2D-Kamera)
Keine

2.4. Gleis-Kommandos

Die folgenden Kommandos ermöglichen die Abfrage und das Steuern von Gleisen auf einer Anlage.

ID Beschreibung Parameter Rückgabewerte
300 Gibt eine Liste aller Gleise zurück Zahl - 0 für alle Gleise, 1 für gerade Gleise, 2 für gebogene Gleise, 3 für Flexgleise, 4 für Weichen, 5 für Kreuzweichen, 6 für Dreiwegweichen, 7 für Kreuzungen, 8 für Prellbockgleise, 9 für Drehscheiben, 10 für Entkupplungsgleise String, String, String... - Für jedes Gleis ein Name
301 Gibt den Typ eines Gleises zurück String - Name des Gleises Zahl - Siehe Kommando 300 für eine Liste der Gleistypen
302 Gibt die Anzahl der Spuren eines Gleises zurück String - Name des Gleises Zahl
303 Gibt die Geometrie einer Gleisspur zurück

String - Name des Gleises
Zahl - 0-basierter Index der Spur
Boolean (optional) - Gibt an, ob zusätzlich die Segmentpositionen zurückgeliefert werden sollen

Gleitkommazahl - Gesamtlänge
Gleitkommazahl - Start
Gleitkommazahl - Länge 1
Gleitkommazahl - Radius
Gleitkommazahl - Winkel
Gleitkommazahl - Länge 2
Gleitkommazahl - Kreuzungswinkel
Gleitkommazahl, Gleitkommazahl, Gleitkommazahl... - Absolute 3D-Positionen (X, Y, Z) der Segmente, aus denen die Spur aufgebaut ist

304 Gibt den Index der aktiven Spur eines Gleises zurück String - Name des Gleises Zahl
305 Aktiviert eine Spur eines Gleises String - Name des Gleises
Zahl - 0-basierter Index der zu aktivierenden Spur
Keine
306 Gibt den Entkupplungszustand eines Entkupplungsgleises zurück String - Name des Gleises Boolean - Entkupplungszustand
307 Setzt den Entkupplungszustand eines Entkupplungsgleises

String - Name des Gleises
Boolean - Entkupplungszustand

Keine

2.5. Rollmaterial-Kommandos

Die folgenden Kommandos ermöglichen das Steuern von Loks und Wagons auf einer Anlage.

ID Beschreibung Parameter Rückgabewerte
350 Gibt einer Liste des Rollmaterials zurück Zahl - 0 für alle Loks und Wagons, 1 für Loks, 2 für Wagons
String (optional) - Name eines Gleis. Es wird nur Rollmaterial zurückgegeben, welches sich auf dem angegeben Gleis befindet.
Zahl (optional) - 0-basierter Index der Gleisspur, auf dem sich ein Rollmaterial befinden muss (nur falls auch ein Gleis angegeben wurde).
String, String, String... - Für jedes Rollmaterial ein Name
351 Gibt den Typ eines Rollmaterials zurück String - Name des Rollmaterials Zahl - 1 für Loks, 2 für Wagons
360 Gibt das Gleis zurück, auf dem sich ein Rollmaterial befindet String - Name des Rollmaterials String - Name des Gleises
Zahl - 0-basierter Index der Gleisspur
Gleitkommazahl - Relative Position des Rollmaterials auf der Spur
Zahl - Richtung des Rollmaterials relativ zur Spur (1 für vorwärts, -1 für rückwärts)
370 Gibt die Geschwindigkeit einer Lok zurück String - Name der Lok
Zahl - 0 für Ist-Geschwindigkeit, 1 für Soll-Geschwindigkeit
Gleitkommazahl
371 Setzt die Geschwindigkeit einer Lok String - Name der Lok
Zahl - 0 für Ist-Geschwindigkeit, 1 für Soll-Geschwindigkeit
Gleizkommazahl - Neue Geschwindigkeit der Lok
Keine
374 Gibt die Aktivierungszustände der Kupplungen zurück String - Name des Rollmaterials
Zahl - 0 für vordere Kupplung, 1 für hintere Kupplung
Boolean - Gibt an, ob die Kupplung aktiviert oder deaktiviert ist
375 Aktiviert/Deaktiviert eine Kupplung String - Name des Rollmaterials
Zahl - 0 für vordere Kupplung, 1 für hintere Kupplung
Boolean - Neue Aktivierungszustand
Keine
380 Ermittelt den Aktivierungszustand der Lichter einer Lok String - Name der Lok Boolean - Gibt an, ob die Lichter der Lok aktiviert oder deaktiviert sind
381 Aktiviert oder deaktiviert die Lichter einer Lok String - Name der Lok
Boolean - Gibt an, ob die Lichter aktiviert oder deaktiviert werden sollen
Keine

2.6. Signal-Kommandos

Die folgenden Kommandos ermöglichen das Steuern von Signalen.

ID Beschreibung Parameter Rückgabewerte
400 Gibt eine Liste aller Signale zurück Keine String, String, String... - Für jedes Signal ein Name
401 Gibt den Zustand eines Signals zurück String - Name des Signals Zahl - ID des aktiven Signalbegriffs
402 Setzt den Zustand eines Signals String - Name des Signals
Zahl - ID des neuen Signalbegriffs
Keine

2.7. Steuerpult-Kommandos

Die folgenden Kommandos ermöglichen die Abfrage und das Setzen von Steuerpult-Objekten, wie z.B. dem Drehregler oder dem Kippschalter.

ID Beschreibung Parameter Rückgabewerte
450 Gibt eine Liste aller Steuerobjekte zurück Zahl - 0 für alle Objekte, 1 für analoge Steuerobjekte, 2 für digitale Objekte String, String, String... - Für jedes Steuerobjekt ein Name
451 Gibt den Typ eines Steuerobjektes zurück String - Name des Steuerobjektes Zahl - 1 für analoge Steuerobjekte, 2 für digitale Objekte
452 Gibt den Wert eines Steuerobjektes zurück String - Name des Steuerobjektes Gleitkommazahl - Wert zwischen 0 und 1
453 Setzt den Wert eines Steuerobjektes String - Name des Steuerobjektes
Gleitkommazahl - Neuer Wert zwischen 0 und 1
Keine

2.8. Text-Kommandos

Die folgenden Kommandos ermöglichen die Abfrage und das Setzen von Textobjekten, die im Katalog unter Zusätzlich - Beschriftung zu finden sind.

ID Beschreibung Parameter Rückgabewerte
500 Gibt eine Liste aller Textobjekte zurück Keine String, String, String... - Für jedes Textobjekt ein Name
501 Gibt die Eigenschaften eines Textobjektes zurück String - Name des Textobjektes String - Textinhalt
String - Schriftart
Zahl - Schriftfarbe als Hex-Wert (RGB)
Zahl - Textstil, binäres Oder - 0 für normal, 1 für fett, 2 für kursiv, 4 für unterstrichen
Zahl - Textausrichtung - 0 für links, 1 für rechts, 2 für zentriert
Boolean - 0 für kein Hintergrund, 1 für Hintergrund
Zahl - Hintergrundfarbe als Hex-Wert (RGB)
502 Setzt die Eigenschaften eines Textobjektes String - Name des Steuerobjektes
String - Textinhalt
String - Schriftart
Zahl - Schriftfarbe als Hex-Wert (RGB)
Zahl - Textstil, binäres Oder - 0 für normal, 1 für fett, 2 für kursiv, 4 für unterstrichen
Zahl - Textausrichtung - 0 für links, 1 für rechts, 2 für zentriert
Boolean - 0 für kein Hintergrund, 1 für Hintergrund
Zahl - Hintergrundfarbe als Hex-Wert (RGB)
Keine

2.9. Kran-Kommandos

Die folgenden Kommandos ermöglichen die Abfrage und das Steuern von Kränen, die im Katalog unter Landschaft/Industrie/Kräne zu finden sind.

ID Beschreibung Parameter Rückgabewerte
550 Ermittelt den Namen des Transportguts eines Krans String - Name des Krans String - Name des Transportguts. Leer, falls der Kran keine Last trägt.
551 Nimm ein Transportgut auf/setzt es ab

String - Name des Krans
String - Name des Ziels. Trägt der Kran gerade keine Last, so nimmt er das Ziel auf, ansonsten setzt er die Last auf dem Ziel ab.

Keine
552 Setzt ein Kran auf die Anfangsposition zurück String - Name des Krans Keine

3. Liste der versendeten Ereignisse

Im folgenden werden die Ereignisse inkl. den Parametern aufgelistet, die vom 3D-Modellbahn Studio an das externe Programm gesendet werden.

ID Beschreibung Parameter
20 Neues Projekt wurde geladen String - ID des geöffneten Projektes
21 Geöffnetes Projekte wurde geschlossen String - ID des geschlossenen Projektes
40 Kamera wurde aktiviert String - Name der neu aktivierten Kamera
50 Countdown wurde beendet String - Name des Countdowns
60 Variable wurde geändert String - Name der Variable
String - Wert der Variable
70 Animation wurde gestartet/gestoppt

String - Name des Objektes
String - Name der Animation

100 Aktive Spur eines Gleises hat sich geändert String - Name des Gleises
Zahl - 0-basierter Index der neuen aktiven Spur
101 Zustand eines Entkupplungsgleises hat sich geändert String - Name des Entkupplungsgleises
Boolean - Neuer Entkupplungszustand
150 Ein Zug betritt ein Gleis

String - Name des Rollmaterials
String - Name des Gleises
Zahl - 0-basierter Index der Gleisspur
String - Name des Gleises, welches verlassen wird
Zahl - 0-basierter Index der Gleisspur, die verlassen wird

151 Ein Zug verlässt ein Gleis String - Name des Rollmaterials
String - Name des Gleises
Zahl - 0-basierter Index der Gleisspur
String - Name des Gleises, welches betreten wird
Zahl - 0-basierter Index der Gleisspur, die betreten wird
200 Signalzustand hat sich geändert String - Name des Signals
Zahl - ID des aktiven Signalbegriffs
210 Steuerobjekt-Wert hat sich geändert String - Name des Steuerobjektes
Gleitkommazahl - Neuer Wert des Steuerobjektes zwischen 0 und 1
220 Ein Kran hat ein Transportgut aufgenommen/abgesetzt String - Name des Krans
Zahl - Aktion (0 für aufgenommen, 1 für abgesetzt)
String - Name des Transportguts