TrainzNativeInterface - Revision history

Microlem: Add TNIPhysics link

2021-02-15T03:04:44Z

Add TNIPhysics link

← Older revision		Revision as of 03:04, 15 February 2021
Line 53:		Line 53:
	* [[TNI Controls Interface]]		* [[TNI Controls Interface]]
	* [[TNI Socket Interface]]		* [[TNI Socket Interface]]
	* TNI ~~Train~~ Physics Interface ~~- Not yet implemented.~~		* [[TNI Physics Interface]]
	* TNI Sound Interface - Not yet implemented.		* TNI Sound Interface - Not yet implemented.
	* TNI Graphics Interface - Not yet implemented.		* TNI Graphics Interface - Not yet implemented.

Pw3r: /* Interfacing with Trainz */

2017-12-11T23:35:16Z

Interfacing with Trainz

← Older revision		Revision as of 23:35, 11 December 2017
Line 52:		Line 52:
	* [[TNI TrainzScript Interface]]		* [[TNI TrainzScript Interface]]
	* [[TNI Controls Interface]]		* [[TNI Controls Interface]]
			* [[TNI Socket Interface]]
	* TNI Train Physics Interface - Not yet implemented.		* TNI Train Physics Interface - Not yet implemented.
	* TNI Sound Interface - Not yet implemented.		* TNI Sound Interface - Not yet implemented.

Pw3r: /* Interfacing with Trainz */

2017-11-22T03:30:01Z

Interfacing with Trainz

← Older revision		Revision as of 03:30, 22 November 2017
Line 51:		Line 51:
	* [[TNI Core Interface]]		* [[TNI Core Interface]]
	* [[TNI TrainzScript Interface]]		* [[TNI TrainzScript Interface]]
			* [[TNI Controls Interface]]
	* TNI Train Physics Interface - Not yet implemented.		* TNI Train Physics Interface - Not yet implemented.
	* TNI Sound Interface - Not yet implemented.		* TNI Sound Interface - Not yet implemented.
	* TNI Graphics Interface - Not yet implemented.		* TNI Graphics Interface - Not yet implemented.
	* TNI Control Interface - Not yet implemented.
	* TNI User Interface - Not yet implemented.		* TNI User Interface - Not yet implemented.
	* TNI Asset Database Interface - Not yet implemented.		* TNI Asset Database Interface - Not yet implemented.
	* TNI Surveyor Interface - Not yet implemented.		* TNI Surveyor Interface - Not yet implemented.

Windwalkr at 07:58, 11 May 2016

2016-05-11T07:58:51Z

← Older revision		Revision as of 07:58, 11 May 2016
Line 31:		Line 31:
	* 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 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.		* 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.

Windwalkr at 03:16, 11 May 2016

2016-05-11T03:16:18Z

← Older revision		Revision as of 03:16, 11 May 2016
Line 48:		Line 48:
	The following interfaces are implemented or planned. No release schedule is available for interfaces which are not yet implemented.		The following interfaces are implemented or planned. No release schedule is available for interfaces which are not yet implemented.

	* TNI Core		* [[TNI Core Interface]]
	* TNI TrainzScript Interface		* [[TNI TrainzScript Interface]]
	* TNI Train Physics Interface - Not yet implemented.		* TNI Train Physics Interface - Not yet implemented.
	* TNI Sound Interface - Not yet implemented.		* TNI Sound Interface - Not yet implemented.

Windwalkr at 03:15, 11 May 2016

2016-05-11T03:15:40Z

← Older revision		Revision as of 03:15, 11 May 2016
Line 1:		Line 1:
	[[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 ~~time or interest~~ to undertake core development.		[[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:		Some sample ideas which might be viable candidates for TNI plugins:

Windwalkr at 03:13, 11 May 2016

2016-05-11T03:13:19Z

← Older revision		Revision as of 03:13, 11 May 2016
Line 1:		Line 1:
	[[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~~.		[[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 time or interest 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.		Please note that this page is a "beginner's summary" of the TNI development process, and is not in itself a legal agreement.
Line 27:		Line 34:

	=TNI Codesigning=		=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.		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.

Windwalkr at 02:54, 11 May 2016

2016-05-11T02:54:03Z

← Older revision		Revision as of 02:54, 11 May 2016
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.

Windwalkr: 1 revision

2010-02-03T14:00:04Z

1 revision

← Older revision	Revision as of 14:00, 3 February 2010
(No difference)

Windwalkr at 06:51, 9 January 2009

2009-01-09T06:51:08Z

New page

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.