Control via external interface
3D Train Studio provides a programming interface with which the Studio can be expanded with additional functions via external programs in order to enable even more complex system operations. The interface enables status queries, processing of objects and reacting to events in specially developed programs. In addition, you can easily expand your own systems with ready-made programs that are provided free of charge by other users and that also use the control interface. The interface is available to every user of 3D Train Studio Professional.
Technical basics
The control interface of 3D Train Studio differentiates between commands and events. A command is a command that the external program sends to the studio and that is to be processed. An event, on the other hand, is transmitted from the studio to the external program if a corresponding change occurs on the system. Commands and events are simple lines of text that are exchanged between the programs via a TCP network connection.
3D Train Studio uses two separate TCP connections for the commands and events, so that commands and events are always transmitted separately from each other. This simplifies the programming of external programs, as these can also strictly separate the code according to commands and events and do not have to deal with mixing. A program does not need an event connection, for example, if it is not interested in the events.
By default, the command connection is established via port 31285 and the event connection via port 31286. Both ports can be changed in the program settings of the 3D model railway studio. When installing the 3D model railway studio, the Windows firewall is configured automatically. If a different firewall is used, it must be ensured that incoming and outgoing TCP and UDP connections are enabled on both ports.
A connection with the 3D model railway studio is established via the IP or host name of the computer on which the studio is running. In the local network, the studio also offers broadcasting in order to establish a connection without entering the IP or the host name. For this purpose, the external program sends a broadcast message (UDP) with the text line “{362E4489-482E-4E45-B782-43F80FF58809}” (without quotation marks) to the local network. If a computer with a running 3D Train Studio receives this text, it sends the same text back to the sender, whereby the external program gains knowledge of the IP of 3D Train Studio.
Commands
A command that is sent to the 3D model railway studio via the TCP connection has the following format:
- An ID (number) that identifies the command
- Any list of parameters that, depending on the command, specify the command more precisely
- A linefeed to mark the end of a command line
The ID and the parameters are separated from each other by a semicolon (;). The text line “5; Parameter 1; Parameter 2; Parameter 3” is an example of a valid command with ID 5 and 3 parameters (the line feed is not shown here).
If the 3D model railway studio receives a command, it evaluates this including the parameters and executes the command accordingly. The studio then sends back a response on the same TCP connection that contains the result of the command. The answer is also a line of text with the following format:
- Result code 0 or 1 for an unsuccessful or successful command, respectively
- Any list of parameters that contain further details of the error in the event of an unsuccessful command and the result in the event of a successful command
- A linefeed to mark the end of the response
The result code and the response parameters are also separated from one another by a semicolon, eg “0; Incorrect parameter” for an unsuccessful command or “1; Floor plate; Steam locomotive” for a successful command with two return values.
3D Train Studio returns a response to every command, regardless of whether the command could be processed successfully or not. A second command may therefore only be sent when the response to the first command has been received. Command groups are an exception.
A response is also sent if the command does not return any values. In this case, only the result code is sent back without parameters.
The command group
Every command that is sent to the 3D Train studio is processed by it immediately. Several commands sent are processed one after the other, whereby the user can also carry out other actions in the program between the commands. This possible interruption in the processing of commands by the user can be circumvented by using command groups. For the 3D model railway studio, a command group is a collection of commands that are always executed as a unit, without the user being able to change the status in the meantime by any other action in the program. Command groups are therefore suitable for several actions that build on each other (eg rotating and positioning an object).
The grouping of commands is done using two explicit single commands ( 10 and 11 ). By sending command 10, the studio is informed that all subsequent commands are part of a group and should be processed together. When command 11 is sent, the group is ended, which means that subsequent commands are again viewed as individual commands.
In contrast to the individual commands, the commands that are sent within a group are not stored immediately, but only stored temporarily and only processed when the group is terminated (command 11). This also means that no immediate response is sent from 3D Train Studio to a group command. The answer will only be sent after the group has ended.
Example:
- Sending the commands
- Start of the group: command 10
- Command X
- Command Y
- Command Z
- Ending the group: Command 11 Now processing of all sent commands begins
- Receipt of the answers
- Response from command 10
- Response from command X
- Response from command Y
- Response from command Z
- Response from command 11
Since the responses to the individual commands are only sent after the group has ended, only those commands can be grouped whose parameters do not depend on the result of a previous group command.
Events
If an event occurs on the open layout, the 3D Train Studio informs an externally connected program about the event connection. An event is triggered, for example, when a train enters a track or a switch is operated. A single event has the following format:
- An ID (number) that specifies the type of event
- Any list of parameters , depending on the event, that contain further information about the event that has occurred
- A linefeed to mark the end of an event
Events are sent automatically from 3D Train Studio. The event connection is only used for sending, ie the studio does not expect a response on the event connection. Reactions to events must be sent by command via the command connection.
Data types
The commands and events are always transmitted in text form (UTF8-coded). Nevertheless, the 3D Train Studio expects the parameters depending on the command in a certain form or data type:
- String : Defines a character string and is not specially interpreted.
- Boolean : Defines a state with two values (true / false or on / off), whereby a 0 is interpreted as false / off and a 1 as true / on.
- Number : Defines an integer, e.g. 5 or -3.
- Floating-point number : Defines a fractional number, e.g. 3.141 or -100.9. It should be noted that floating point numbers are interpreted in the English format, ie the decimal separator is always the point.
Plugins
The control interface can be used in any program to expand 3D Train Studio with new functions. So that all users have quick and easy access to the programs, the 3D Train Studio allows the integration of the control interface programs in the online catalog (plugins). This gives the following options:
- The programs can be called up directly from the 3D Train Studio (menu “Catalog – Plugins”) without having to unpack or install them manually
- Updated programs are downloaded automatically so that all users always have the latest version
- Plugins can be linked to layout so that they start automatically the next time the layout is opened
Requirements
Plugins are normal executable applications, but they must meet a few requirements in order to be added to the online catalog:
- The plugin must be able to be called from any directory. 3D Train Studio unpacks a plugin automatically into a temporary directory before the start and deletes it again afterwards.
- All files that the plugin needs to run must be included in the plugin directory (or subdirectory). There is no separate plugin installation.
- The plug-in must run without administrator rights and, if possible, automatically connects to the 3D model railway studio. The ports used for the control interface are transferred at startup (see start parameters).
- Program settings must not be saved in the program directory (as this is deleted after the plugin is closed anyway). Settings should be saved in the DataDir (see start parameters).
- Ideally, the plug-in should be closed without a prompt, as the 3D Train Studio closes the plug-in automatically when the layout is closed.
- For publication in the online catalog, a short description, a preview image (512 x 384 pixels) and your own topic in the plugin forum are required. The short description must contain the link to the forum topic. The topic should contain a detailed description and is used for user queries.
- Additional files that are not required for execution (such as the source code or help files) should be offered in the forum topic as a separate download.
A collection of 150+ existing plugins can be found in the plugin forum. German language.
Start parameter
Plugins are started and terminated directly from the 3D Train Studio. In order to simplify the communication between a plugin and the studio, the 3D Train Studio transfers some command line parameters to the plugin:
- / DataDir: “Path” – Contains the name of a directory that the plugin can use for permanent data storage. This directory is individual for each plugin and can be used, for example, to save settings files. The data is also available the next time the plugin is started and is only deleted when the 3D model railway studio is uninstalled.
- / Locale: Name – Contains the language set in 3D Train Studio so that the plugins can adapt their own language.
- / CommandPort: Port – Contains the port for the command connection to the control interface .
- / EventPort: Port – Contains the port for the event connection to the control interface .