Latest revision as of 13:04, 15 February 2021

TrainzNativeInterface is a plugin system which allows native-code developers to create extensions which perform tasks normally inaccessible from within the Trainz environment, such as communicating with custom hardware or external software. This allows third-party developers to extend Trainz into areas where the N3V Games development team do not presently have the resources to undertake core development.

Some sample ideas which might be viable candidates for TNI plugins:

• Connecting the controls in a real Train cab to a computer running Trainz.
• Controlling a model train layout from within Trainz Driver.
• Importing from third-party data sources into Surveyor.
• Implementing a custom train physics and/or train sound system for a specific series of locomotives.
• Interfacing with third-party train scheduling software.

Please note that this page is a "beginner's summary" of the TNI development process, and is not in itself a legal agreement.

[edit] TNI Developer Requirements

Creating a TNI plugin imposes a number of requirements on the developer:

• The developer program resources are in English, and the developer is required to provide a representative who can communicate technical concepts effectively in English. N3V Games is unfortunately unable to provide translation resources.
• The developer is required to agree to a development license. The license is intended to protect the developer, N3V Games, and the Trainz end users by defining a number of expectations and responsibilities. The license is not negotiable.
• The developer is expected to provide a short project proposal, which allows N3V Games to confirm that a TNI plugin is an appropriate solution for the project.
• The developer is expected to provide a development schedule detailing the proposed project, estimated delivery timeframe, business model, etc. Freeware and Open Source developers are welcome to apply.
• The developer is required to have an existing understanding of native C/C++ coding practices including the development of DLLs. N3V Games cannot assist with learning native code development.
• The developer must be willing to provide N3V Games with source-level access to the TNI plugin and all linked libraries for review and code-signing. If the plugin communicates with a third-party application, the source code of the application is not required.
• The developer must be prepared to address technical concerns raised by N3V Games, including bugs, stability concerns, and resource usage (memory, cpu, etc.) concerns.

[edit] TNI Proposal Review

Acceptance of a TNI development proposal is a complex process, but the following quick guide will help you determine if your idea is likely to be approved:

• Can your proposal be implemented effectively in TrainzScript? If yes, we are unlikely to approve a native solution.
• Does your proposal function as a reusable component? We are much more likely to approve projects which can be reused by many Trainz developers than a project which can only be deployed by the author. Individual components which work together via a documented API are preferred over monolithic systems which don't allow individual replacement of the various components.
• Does your proposal duplicate built-in functionality? We are unlikely to approve anything which duplicates core functionality. Exceptions to this guideline will be explicitly noted.
• Do you have the necessary resources to develop your proposal? Supporting TNI developers costs us time and money, which we will prefer to spend on developers who have the technical know-how or other necessary resources to complete their project.
• Does your proposal introduce unnecessary dependencies on third-party software or hardware? If there are two practical ways to do something, one which introduces dependencies and one which does not, we will favor the approach which does not.
• Does your proposed DLL require access to functionality outside that provided by the TrainzNativeInterface DLL? Direct usage of external functionality (including OS-provided functions) is not recommended and will only be approved if strictly necessary.
• Is your proposal mindful of user privacy, collecting only the minimum amount of data required to undertake its stated goal? Data collection that is not strictly required for a plugin's primary purpose will not be approved.

[edit] TNI Codesigning

As with any native software, TNI plugins are capable of performing any action authorised to the user account under which the Trainz application is running, typically including reading and writing user documents, changing security settings, and accessing the internet. As a security precaution, and to ensure ongoing compatibility, N3V Games does not allow ad hoc distribution of TNI plugin DLLs.

Access to the TNI development environment requires that the developer agrees to and abides by the TNI developer license agreement. Failure to abide by the terms of the agreement will make the developer subject to permanent ejection from the TNI developer program, meaning that they will no longer be able to develop TNI plugins or run development versions of plugins.

Outside of the TNI development environment, TNI plugins require code-signing before they can be deployed. Final build and code-sign of a TNI DLL is performed by N3V Games using source code provided by the developer. The (code-signed) distribution version of the TNI plugin may then be distributed according to the terms of the TNI developer license agreement.

Users require an active internet connection in order to authorise TNI plugins. Users who have no internet connection, or who choose to run Trainz in "offline mode" (where applicable) will not be able to utilise TNI plugins. The internet connection is not required to be permanently active while the TNI plugin is in use.

[edit] Interfacing with Trainz

TNI is not a magic wand to do anything within the Trainz environment. In order to access or replace any Trainz functionality, a relevant interface must be exposed by Trainz. Additional interfaces will be introduced over time as development resources allow. Please read and understand the capabilities of the interfaces to ensure that your project idea is actually feasible within the capabilities of TNI.

The following interfaces are implemented or planned. No release schedule is available for interfaces which are not yet implemented.

• TNI Core Interface
• TNI TrainzScript Interface
• TNI Controls Interface
• TNI Socket Interface
• TNI Physics Interface
• TNI Sound Interface - Not yet implemented.
• TNI Graphics Interface - Not yet implemented.
• TNI User Interface - Not yet implemented.
• TNI Asset Database Interface - Not yet implemented.
• TNI Surveyor Interface - Not yet implemented.