TrainzNativeInterface

The TrainzNativeInterface is a helper DLL and associated protocols which allow communication between Trainz executables and third-party DLLs. This page describes a work-in-progress and all details are subject to change.

Linkage

The trainznativeinterface.dll is provided in the Trainz bin folder, and is hard-linked by relevant executables. It is expected that any plugin DLLs will also hard-link the trainznativeinterface.dll such that a single shared instance of the DLL will exist in the parent executable's process space.

Any plugin DLL must use be built in MSVS 2005 (or compatible) and use the "Multi-threaded DLL" runtime. All Auran-supplied interface source is provided in C++ header format, however the trainznativeinterface.dll uses POD classes and global functions such that other languages should be able to link against the DLL if an appropriate interface is built.

Plugin DLLs should not make assumptions about their host environment. The TrainzNativeInterface is not limited to use by the Trainz game executable.

Resource Usage

A plugin DLL may allocate its own private storage using the standard library, however data sizes and counts must be kept to an absolute minimum as Trainz is extremely sensitive to the amount of available process space. It is strongly recommended that any plugin DLL which requires significant storage space or processing time should instead be written as a connector between Trainz and an external executable process. It is recommended that asynchronous Windows pipes are used for communication in this scenario.

Plugin DLLs must never attempt to present a user interface of any kind. The external executable process (if present) may present a user interface, however the external process must not attempt to steal focus from the Trainz executable at any time - the user must switch to the executable explicitly using standard Windows functionality (alt-tab or similar.)

Plugin DLLs must never block execution. Any calls made to the Plugin DLL from the Trainz executable should be serviced immediately or should configure internal state such that they may be serviced at a later time. The Plugin DLL must never wait on a response from an external executable process before returning control to the Trainz executable.

Plugin DLLs will be loaded and unloaded at runtime, and must take care to clean up their memory allocations and object references prior to being unloaded.

Data Passing

Private data allocated by the plugin DLL must never be passed to the Trainz executable. The trainznativeinterface.dll provides a number of functions for encapsulating data into reference-counted object primitives which are safe to pass between the plugin DLL and the Trainz executable. The plugin DLL must not make assumptions about the size or internal format of these objects - they are to be allocated and processed using the provided interface functions only.

Access to Trainz runtime data is limited to the functionality provided by the trainznativeinterface.dll interface. Access to the Win32 APIs is not currently restricted, however it is recommended that these are avoided where possible to ensure compatibility with future products.

Direct access to files within the Trainz program directory is not permitted.