TrainzNativeInterface

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (1 revision)
Line 1: Line 1:
−
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.'''
+
[[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. 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.
  
 +
Please note that this page is a "beginner's summary" of the TNI development process, and is not in itself a legal agreement.
  
−
=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.
+
=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.
  
−
Plugin DLLs should not make assumptions about their host environment. The TrainzNativeInterface is not limited to use by the Trainz game executable.
 
  
 +
=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:
  
−
=Resource Usage=
+
* Can your proposal be implemented effectively in TrainzScript? If yes, we are unlikely to approve a native solution.
−
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.
+
* 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.
  
−
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.
+
=TNI Codesigning=
 +
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.
  
−
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.
+
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.
  
−
=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.
+
=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.
  
−
Direct access to files within the Trainz program directory is not permitted.
+
The following interfaces are implemented or planned. No release schedule is available for interfaces which are not yet implemented.
 +
 
 +
* TNI Core
 +
* TNI TrainzScript Interface
 +
* TNI Train Physics Interface - Not yet implemented.
 +
* TNI Sound Interface - Not yet implemented.
 +
* TNI Graphics Interface - Not yet implemented.
 +
* TNI Control Interface - Not yet implemented.
 +
* TNI User Interface - Not yet implemented.
 +
* TNI Asset Database Interface - Not yet implemented.
 +
* TNI Surveyor Interface - Not yet implemented.

Revision as of 12:54, 11 May 2016

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

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


Contents

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.


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.


TNI Codesigning

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.


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
  • TNI TrainzScript Interface
  • TNI Train Physics Interface - Not yet implemented.
  • TNI Sound Interface - Not yet implemented.
  • TNI Graphics Interface - Not yet implemented.
  • TNI Control Interface - Not yet implemented.
  • TNI User Interface - Not yet implemented.
  • TNI Asset Database Interface - Not yet implemented.
  • TNI Surveyor Interface - Not yet implemented.
Retrieved from "https://online.ts2009.com/mediaWiki/index.php?title=TrainzNativeInterface&oldid=8848"
Personal tools