TNI Core Interface - Revision history

Pw3r at 02:19, 16 February 2026

2026-02-16T02:19:30Z

← Older revision		Revision as of 02:19, 16 February 2026
Line 387:		Line 387:

	This should be considered a last-resort mechanism, used only where the cost of the other object types is prohibitive.		This should be considered a last-resort mechanism, used only where the cost of the other object types is prohibitive.

			==TNIGameObjectID==
			A TNIGameObjectID is used to identify Trainz game objects such as trains, script libraries, etc. It can be considered equivalent to the GameObjectID script class.

			Code should only ever compare TNIGameObjectID objects using the explicit matching functions, such as TNIDoGameObjectIDsMatch(const TNIGameObjectID , const TNIGameObjectID ).

Modelermj: /* DLL Development */

2017-08-30T20:40:31Z

DLL Development

← Older revision		Revision as of 20:40, 30 August 2017
Line 6:		Line 6:
	* The TrainzNativeInterface SDK headers, which provide the [[TNI Core Interface]] and other component interfaces.		* The TrainzNativeInterface SDK headers, which provide the [[TNI Core Interface]] and other component interfaces.
	* The C standard library allocators and utility functions.		* The C standard library allocators and utility functions.
	* The C++ STL containers, allocators, and utility functions.		* The C++ STL (Standard Template Library) containers, allocators, and utility functions.


Line 100:		Line 100:
	}		}
	</pre></code>		</pre></code>


	=TrainzNativeInterface.h=		=TrainzNativeInterface.h=

Windwalkr at 09:15, 11 May 2016

2016-05-11T09:15:26Z

← Older revision		Revision as of 09:15, 11 May 2016
Line 388:		Line 388:

	This should be considered a last-resort mechanism, used only where the cost of the other object types is prohibitive.		This should be considered a last-resort mechanism, used only where the cost of the other object types is prohibitive.


			=Threading=
			Trainz is a preemptively multithreaded environment, which means that TNI functions need to be safe against certain thread usage. There are certain guarantees and limitations which are relevant to TNI development:

			* For any given TNIContext, only one thread will be making calls into TNI DLLs at a time. There is no guarantee that it will always be the same thread, only that multiple threads won't do it simultaneously. Because of this, don't use thread_local storage.
			* For any given TNI Plugin, multiple threads may call into your TNI DLL functions simultaneously on behalf of different TNIContexts. If you use global variables or file-scope static variables, you must protect them with appropriate thread-safe locks.
			* Never use function-scope static variables, as they are not thread-safe on Windows.
			* TNIObjects may be used on any thread.
			* TNIObjects may be read by multiple threads simultaneously.
			* TNIObjects must not be accessed on any thread while being modified on another thread. If you are in doubt as to whether a particular function may modify the state of a TNIObject, you should assume that it does.
			* TNIReference() and TNIRelease() modify the state of the TNIObject.
			* You may create your own worker threads using the TNI threading API, but you may not make TNILibrary or TNIContext calls from those threads.
			* You may not create threads using other APIs.

Windwalkr at 08:37, 11 May 2016

2016-05-11T08:37:03Z

@@ Line 108: / Line 108: @@
 * Ownership of function parameters is held by the caller throughout the function call. They may be retained by the callee if they are required to persist after the function returns. The callee is then responsible for ensuring that they are released at a later time. For mutable object types such as TNIArray, the caller should not modify the array after the callee returns, since it has no way to know if the callee has kept a reference to the array- instead, it should release its own reference to the array. Exceptions are permitted where shared access is considered beneficial, but these must be clearly documented at every use site.
 * Ownership of function return values is passed to the caller. For mutable object types such as TNIArray, the callee should not keep its own reference to the return value since the caller could further modify the object.
-The core interface attempts to be as safe as possible against common programming errors. Pointer parameters are checked to ensure that they are not null, and so on. However, it is not feasible to make any native-code program completely bullet proof. Typical programming mistakes such as use-after-free, use-before-initialisation, and so on will cause Trainz to crash and are considered serious bugs with the TNI plugin that triggered the crash. Plugins which show repeated stability issues will be withdrawn from circulation.
+The core interface attempts to be as safe as possible against common programming errors. Pointer parameters are checked to ensure that they are not null, and so on. However, it is not feasible to make any native-code program completely bullet proof. Typical programming mistakes such as use-after-free, use-before-initialisation, memory leaks, and so on will cause Trainz to crash and are considered serious bugs with the TNI plugin that triggered the crash. Plugins which show repeated stability issues will be withdrawn from circulation.
 The following TNIObject-derived classes are provided by the [[TNI Core Interface]]:
@@ Line 302: / Line 303: @@
 ==TNIVector==
 TNIVector provides an immutable indexed element array containing 32-bit floating point values. Values for the entire vector are defined during construction. Random access within the vector is very fast.
 ==TNIContext==
 TNIContext provides the operating context in which the TNI plugin is operating. Trainz supports multiple concurrent TNI Contexts, and DLLs are typically shared between contexts, so the plugin must correctly track which context any given object or function call is made in. The TNI plugin should not leak data between contexts, although it may share non-context-specific resources internally in a manner which is opaque to the parent context. Each TNIContext is likely to run in a different thread of execution, although this is not guaranteed. Any internal storage maintained by the TNI plugin should be keyed to its parent context to prevent race conditions and other threading concerns. Access to private shared state must be protected by appropriate thread-safe locks.
 ==TNILibrary==

Windwalkr at 08:24, 11 May 2016

2016-05-11T08:24:45Z

← Older revision		Revision as of 08:24, 11 May 2016
Line 19:		Line 19:
	* The plugin may use C++ exceptions internally, but must not allow exceptions to be propagated back to the calling code.		* The plugin may use C++ exceptions internally, but must not allow exceptions to be propagated back to the calling code.
	* The plugin must not throw or attempt to catch native exceptions (win32 exceptions, posix signals, etc.)		* The plugin must not throw or attempt to catch native exceptions (win32 exceptions, posix signals, etc.)

			The TNI developer may use whatever build pipeline they like during development. When submitting to [[N3V Games]] for final build and code-signing, only a single folder of source files is accepted- a vanilla project file will be provided by N3V Games engineers which includes these files, the TNI SDK, and nothing else.


	==DLL Entry Point==		==DLL Entry Point==

Windwalkr at 07:53, 11 May 2016

2016-05-11T07:53:38Z

← Older revision		Revision as of 07:53, 11 May 2016
Line 313:		Line 313:
	// Desc: Allocate a new library in the specified context, given a unique		// Desc: Allocate a new library in the specified context, given a unique
	// library name and the initialisation data.		// library name and the initialisation data.
	// Parm: libraryName -		// Parm: context - The context in which this library is being created.
	// Parm: libraryInitData -		// Parm: libraryName - The name of this library, which frequently matches the
			// name of the plugin in which it is implemented (although it is possible
			// for a single plugin to export multiple libraries). Each library
			// created in a given context must have a unique name.
			// Parm: libraryInitData - A TNILibraryInitData structure which describes
			// the library to be created.
	// Retn: TNILibrary* - A valid object on success, or NULL on failure.		// Retn: TNILibrary* - A valid object on success, or NULL on failure.
	// ============================================================================		// ============================================================================
Line 323:		Line 328:
	// Name: TNIGetLibraryVersion		// Name: TNIGetLibraryVersion
	// Desc: Returns the developer-specified version for the given library.		// Desc: Returns the developer-specified version for the given library.
			// Parm: library - The library to query.
	// Retn: uint32_t - the developer-specified version for the given library.		// Retn: uint32_t - the developer-specified version for the given library.
	// Returns zero on failure.		// Returns zero on failure.

Windwalkr at 07:46, 11 May 2016

2016-05-11T07:46:00Z

Windwalkr at 07:44, 11 May 2016

2016-05-11T07:44:20Z

← Older revision		Revision as of 07:44, 11 May 2016
Line 19:		Line 19:
	* The plugin may use C++ exceptions internally, but must not allow exceptions to be propagated back to the calling code.		* The plugin may use C++ exceptions internally, but must not allow exceptions to be propagated back to the calling code.
	* The plugin must not throw or attempt to catch native exceptions (win32 exceptions, posix signals, etc.)		* The plugin must not throw or attempt to catch native exceptions (win32 exceptions, posix signals, etc.)

			==DLL Entry Point==
			The TNI DLL must provide a standard entry point function:

			<code><pre>
			//=============================================================================
			// Name: TNIEntryPoint
			// Desc: DLL Entry point. Creates a TNILibrary for the specified context.
			// Parm: context - The context which we are being loaded into.
			// Retn: TNILibrary* - A new library which represents this plugin in the specified context.
			//=============================================================================
			extern "C" TNI_ENTRYPOINT_DECL TNILibrary* TNIEntryPoint(TNIContext* context)
			{
			// If there are no other libraries yet, and we maintain shared state, then we should
			// initialise the shared state here.
			// ..

			// Create a TNILibrary that Trainz can use to call our dispatch function.
			TNILibraryInitData info;
			info.m_libraryVersion = 1;
			info.m_libraryCall = &MyLibraryCall;
			info.m_shutdownCall = &MyLibraryShutdown;

			TNIString* libraryName = TNIAllocString("MyTNIPlugin");
			TNILibrary* library = TNIAllocLibrary(context, libraryName, info);
			TNIRelease(libraryName);

			// .. perform per-context initialisation here.

			return library;
			}
			</pre></code>


			The TNIAllocLibrary() function usage above also configured some callback functions, which should look something like this:

			<code><pre>
			//=============================================================================
			// Name: MyLibraryCall
			// Desc: Called by Trainz to perform one of the library function calls provided by this library.
			// Parm: context - The context in which this library resides.
			// Parm: library - The library object, typically created by TNIEntryPoint().
			// Parm: functionName - The function to perform.
			// Parm: params - The parameters to the function.
			// Retn: TNIObject* - The return value from the function.
			//=============================================================================
			TNIObject* MyLibraryCall(TNIContext* context, const TNILibrary* library, const TNILabel* functionName, const TNIObject* params)
			{
			if (functionName == ...)
			{
			.. do something ..
			return ...;
			}

			return nullptr;
			}


			//=============================================================================
			// Name: MyLibraryShutdown
			// Desc: Called when the specified library is being destroyed.
			// Parm: context - The context in which the library was loaded.
			// Parm: library - The library which is being destroyed. You may temporarily reference this library within
			// this function, however on return you must leave the reference count as you found it.
			//=============================================================================
			void MyLibraryShutdown(TNIContext* context, TNILibrary* library)
			{
			// Perform any necessary library shutdown.
			// ..

			// If this is the last TNILibrary for this plugin and we maintain shared state, we should also
			// release the shared state now.
			// ..
			}
			</pre></code>

Windwalkr at 05:07, 11 May 2016

2016-05-11T05:07:18Z

@@ Line 161: / Line 161: @@
 // ============================================================================
 void TNIAppendStringText(TNIString* string, const char* utf8text);
 </pre></code>
@@ Line 166: / Line 175: @@
 ==TNILabel==
 TNILabel provide an immutable string class which is designed to provide an efficient enumeration. Only one TNILabel object can exist for any unique string, so these objects can be rapidly compared by pointer equality. It is intended that you will create one TNILabel object for each enumeration during initialisation, and will then use these objects rather than creating new objects at runtime.
 ==TNIAssetID==
@@ Line 186: / Line 229: @@
 The plugin DLL may be unloaded at any point while there are no TNILibrary objects in existence for that plugin. The plugin should create any shared state when the first TNILibrary object is created, and release any shared state when the last TNILibrary object has is released.
 ==TNIBuffer==

Windwalkr at 04:57, 11 May 2016

2016-05-11T04:57:41Z

← Older revision		Revision as of 04:57, 11 May 2016
Line 27:		Line 27:
	* Ownership of function parameters is held by the caller throughout the function call. They may be retained by the callee if they are required to persist after the function returns. The callee is then responsible for ensuring that they are released at a later time. For mutable object types such as TNIArray, the caller should not modify the array after the callee returns, since it has no way to know if the callee has kept a reference to the array- instead, it should release its own reference to the array. Exceptions are permitted where shared access is considered beneficial, but these must be clearly documented at every use site.		* Ownership of function parameters is held by the caller throughout the function call. They may be retained by the callee if they are required to persist after the function returns. The callee is then responsible for ensuring that they are released at a later time. For mutable object types such as TNIArray, the caller should not modify the array after the callee returns, since it has no way to know if the callee has kept a reference to the array- instead, it should release its own reference to the array. Exceptions are permitted where shared access is considered beneficial, but these must be clearly documented at every use site.
	* Ownership of function return values is passed to the caller. For mutable object types such as TNIArray, the callee should not keep its own reference to the return value since the caller could further modify the object.		* Ownership of function return values is passed to the caller. For mutable object types such as TNIArray, the callee should not keep its own reference to the return value since the caller could further modify the object.

			The core interface attempts to be as safe as possible against common programming errors. Pointer parameters are checked to ensure that they are not null, and so on. However, it is not feasible to make any native-code program completely bullet proof. Typical programming mistakes such as use-after-free, use-before-initialisation, and so on will cause Trainz to crash and are considered serious bugs with the TNI plugin that triggered the crash. Plugins which show repeated stability issues will be withdrawn from circulation.

	The following TNIObject-derived classes are provided by the [[TNI Core Interface]]:		The following TNIObject-derived classes are provided by the [[TNI Core Interface]]:

← Older revision		Revision as of 07:46, 11 May 2016
Line 28:		Line 28:
	// Desc: DLL Entry point. Creates a TNILibrary for the specified context.		// Desc: DLL Entry point. Creates a TNILibrary for the specified context.
	// Parm: context - The context which we are being loaded into.		// Parm: context - The context which we are being loaded into.
	// Retn: TNILibrary* - A new library which represents this plugin in the specified context.		// Retn: TNILibrary* - A new library which represents this plugin in the
			// specified context.
	//=============================================================================		//=============================================================================
	extern "C" TNI_ENTRYPOINT_DECL TNILibrary* TNIEntryPoint(TNIContext* context)		extern "C" TNI_ENTRYPOINT_DECL TNILibrary* TNIEntryPoint(TNIContext* context)
Line 58:		Line 59:
	//=============================================================================		//=============================================================================
	// Name: MyLibraryCall		// Name: MyLibraryCall
	// Desc: Called by Trainz to perform one of the library function calls provided by this library.		// Desc: Called by Trainz to perform one of the library function calls provided
			// by this library.
	// Parm: context - The context in which this library resides.		// Parm: context - The context in which this library resides.
	// Parm: library - The library object, typically created by TNIEntryPoint().		// Parm: library - The library object, typically created by TNIEntryPoint().
Line 81:		Line 83:
	// Desc: Called when the specified library is being destroyed.		// Desc: Called when the specified library is being destroyed.
	// Parm: context - The context in which the library was loaded.		// Parm: context - The context in which the library was loaded.
	// Parm: library - The library which is being destroyed. You may temporarily reference this library within		// Parm: library - The library which is being destroyed. You may temporarily
	// this function, however on return you must leave the reference count as you found it.		// reference this library within this function, however on return you
			// must leave the reference count as you found it.
	//=============================================================================		//=============================================================================
	void MyLibraryShutdown(TNIContext* context, TNILibrary* library)		void MyLibraryShutdown(TNIContext* context, TNILibrary* library)