[[KIND Enginesound]] assets are locomotive enginesounds.

There is only one enginesound asset type, which may be used for Steam, Diesel or Electric locomotives.

Most modern diesel/electric engine sounds use the "ramping sound" configuration, which plays a looped sound file matched to the standard 8 throttle notches. Transition sounds can also be provided for changing up/down a throttle notch.

Trainz also supports a non-ramped configuration, which plays a single engine sound loop and applies a frequency shift based on train speed.

Steam engine sounds play a number of individual 'chuff' files at low speed, then switch to a series of frequency shifted loop sounds at higher speeds.

NOTE: As engine sounds are positional, all files should be 'mono' (i.e. single channel). If stereo files are provided then positional effects may not work, or the sound may not play at all.

==KIND Hierarchy==
===Parent Classes===
* [[KIND TrainzBaseSpec]]
===Child Classes===
* ''none.''

==Supported Tags==

kind "enginesound"
isramping 1
engine-sound-ramp-duration 1.5
engine-sound-ramp-up-durations 0.0,1.5,1.5,1.5,1.5,1.5,1.5,1.5
engine-sound-ramp-down-durations 0.0,1.5,1.5,1.5,1.5,1.5,1.5,1.5
speedup 2.2
isfading 0
number-slow-sounds 4
number-cylinders 2
number-power-strokes 2

====isramping====
:Type: Boolean
:Desc: Specifies whether the asset uses the 'ramping' sound style (default true). When enabled, the enginesound must provide 8 "Idle X.wav" files, one for each throttle notch.

====engine-sound-ramp-duration====
:New tag for trainz-build 3.6
:Type: Decimal.
:Desc: Sets the default duration of the transition sounds used to change between notches. If the individual ramp-up/down tags are not provided, or have insufficient values, this value will be used for the unspecified lengths.

====engine-sound-ramp-up-durations====
:New tag for trainz-build 3.6
:Type: Float list (normally 8 values)
:Desc: Sets the duration (in seconds) of each throttle notch transition sound, from "start.wav", through to "up 7 - 8.wav".
:Note: If a specific transition sound is not provided, the duration should be entered as 0.

====engine-sound-ramp-down-durations====
:New tag for trainz-build 3.6
:Type: Float list (normally 8 values)
:Desc: Sets the duration (in seconds) of each throttle notch transition sound, from "stop.wav", through to "down 8 - 7.wav".
:Note: If a specific transition sound is not provided, the duration should be entered as 0.

====speedup====
:Type: Decimal
:Desc: Used only when isramping is false. This controls the rate of frequency change for the sound loop based on speed. A value of 1.0 would mean the top frequency used is as much again as the base frequency - in other words, the frequency of the sound played would double over the speed range of the vehicle.

====isfading====
:Type: Boolean
:Desc: Used only when isramping is false. If true, the engine sound loops volume will fade in (i.e. get louder) as loco speed increases.

====number-slow-sounds====
:Type: Integer
:Desc: Specifies the number of 'chuff' sounds in a steam enginesound. These will be played in sequence as the loco crawls forward at low speed.

====number-cylinders====
:Type: Integer
:Desc: Number of cylinders in the locomotive for a steam enginesound. This controls the rate of the low speed chuff sounds, and the frequency shift rate for the loop sounds.

====number-power-strokes====
:Type: Integer
:Desc: Number of power strokes in the locomotive for a steam enginesound (should generally be left at the default, 2). This controls the rate of the low speed chuff sounds, and the frequency shift rate for the loop sounds.

:Refer to [[TS12 Doppler]] for usage examples.

==Example Config.txt==
====Diesel====
Sample [[config.txt file]] for a diesel type 'enginesound' asset, with the standard tags excluded for brevity:

kind "enginesound"
isramping 1
engine-sound-ramp-up-durations 14.706,7.086,4.241,4.861,3.017,2.245,2.278,5.119
engine-sound-ramp-down-durations 12.286,7.086,4.241,4.861,3.017,2.245,2.278,5.119

====Electric====
Sample [[config.txt file]] for an electric type 'enginesound' asset, with the standard tags excluded for brevity:

kind "enginesound"
isramping 0
isfading 0
speedup 4.0

====Steam====
Sample [[config.txt file]] for a steam type 'enginesound' asset, with the standard tags excluded for brevity:

kind "enginesound"
number-slow-sounds 4
number-cylinders 2
number-power-strokes 2

==Wave file naming==

====Ramping====
In a 'ramping' diesel/electric enginesound, the following 'idle' sound files are expected:

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! idle 1.wav
! engine idle / notch 1 sound
|-
! idle 2.wav
! notch 2 sound
|-
! idle 3.wav
! notch 3 sound
|-
! idle 4.wav
! notch 4 sound
|-
! idle 5.wav
! notch 5 sound
|-
! idle 6.wav
! notch 6 sound
|-
! idle 7.wav
! notch 7 sound
|-
! idle 8.wav
! notch 8 sound
|}

The following transition sounds are also supported, but any individual file can be omitted if no transition is required/desired.

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! start.wav
! engine startup
|-
! stop.wav
! engine shutdown
|-
! up 1 - 2.wav
! transition between notch 1 and notch 2
|-
! up 2 - 3.wav
! transition between notch 2 and notch 3
|-
! up 3 - 4.wav
! transition between notch 3 and notch 4
|-
! up 4 - 5.wav
! transition between notch 4 and notch 5
|-
! up 5 - 6.wav
! transition between notch 5 and notch 6
|-
! up 6 - 7.wav
! transition between notch 6 and notch 7
|-
! up 7 - 8.wav
! transition between notch 7 and notch 8
|-
! down 2 - 1.wav
! transition between notch 2 and notch 1
|-
! down 3 - 2.wav
! transition between notch 3 and notch 2
|-
! down 4 - 3.wav
! transition between notch 4 and notch 3
|-
! down 5 - 4.wav
! transition between notch 5 and notch 4
|-
! down 6 - 5.wav
! transition between notch 6 and notch 5
|-
! down 7 - 6.wav
! transition between notch 7 and notch 6
|-
! down 8 - 7.wav
! transition between notch 8 and notch 7
|}

====Non-ramping====

In a non ramping engine sound only one file is used: engine_loop.wav.

====Steam====

These are background sounds for when the loco is stationary. The fast will be played when the loco has just stopped, and if it is left for a while, the sound will progress down to 'med' and then eventually 'slow'.

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! loco_stationary_fast.wav
|-
! loco_stationary_med.wav
|-
! loco_stationary_slow.wav
|}

The low speed 'chuff' sounds are named "piston_strokeX.wav", where X is an index from 1 to the value specified by the 'number-slow-sounds' tag.

For example, if number-slow-sounds is set to '4' (the default).

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! piston_stroke1.wav
|-
! piston_stroke2.wav
|-
! piston_stroke3.wav
|-
! piston_stroke4.wav
|}

The following loops are played as the loco picks up speed. They are frequency shifted to match the wheel rotation speed, so the audible 'chuffs' within the loop maintain synchronisation with the drive bogie animation. They also vary in volume based on the regulator setting of the locomotive.

This system enables sound files to be shared between locomotives with different wheel sizes. 60RPM (which is one revolution per second) on a 2 cylinder loco will produce four chuffs per second irrespective of the wheel size - the only difference this makes is what speed the train will be doing when the drive wheels are rotating at 60RPM.

Any individual file can be omitted from this set - the system will use what files are available and use adjacent files to cover for any missing files.

It is anticipated that a sound creator will pick and choose which wave files are used based on what recordings are available, and that a released enginespec will not have all sound files present - particularly the higher speed ones, which are likely to be irrelevant for most locos, but are provided just in case...

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! steam_loop_30RPM.wav
|-
! steam_loop_35RPM.wav
|-
! steam_loop_40RPM.wav
|-
! steam_loop_50RPM.wav
|-
! steam_loop_60RPM.wav
|-
! steam_loop_75RPM.wav
|-
! steam_loop_90RPM.wav
|-
! steam_loop_100RPM.wav
|-
! steam_loop_125RPM.wav
|-
! steam_loop_150RPM.wav
|-
! steam_loop_175RPM.wav
|-
! steam_loop_200RPM.wav
|-
! steam_loop_250RPM.wav
|-
! steam_loop_300RPM.wav
|-
! steam_loop_350RPM.wav
|-
! steam_loop_400RPM.wav
|-
! steam_loop_500RPM.wav
|-
! steam_loop_600RPM.wav
|-
! steam_loop_700RPM.wav
|-
! steam_loop_800RPM.wav
|-
! steam_loop_1000RPM.wav
|-
! steam_loop_1200RPM.wav
|-
! steam_loop_1400RPM.wav
|-
! steam_loop_1600RPM.wav
|-
! steam_loop_2000RPM.wav
|}

Earlier assets may instead provide a single steam loop sound, titled "steam_loop.wav". If only this file is present, modern Trainz code will use it with a default of 50RPM, in order to maintain compatibility.

The following file is also played continually in the background. It's volume will vary based on train speed.

{| border=1 cellpadding=2 cellspacing=0 style="text-align: left;"
|-
! smoke_stack_hiss.wav
|}

==Downloads==
''Attach sample files here?''

==Categories==
[[Category:Asset KIND|E]]

2026-08-10T02:14:23Z

Pw3r:

'''The specified TCB flags are invalid, please check the wiki for valid configurations.'''

The track circuit block (TCB) detector flags on this asset include an invalid combination. TCB flags are given as a semicolon-separated list and fall into two groups:

* '''Traffic type''' - E.g. 'Freight', 'Passenger'. These may be combined with each other and with any track type.
* '''Track type''' - E.g. 'MainLine', 'BranchLine', 'YardShunting', etc. These may only be combined with each other in certain configurations.

The following track type combinations are not allowed and cause this error:
* 'MainLine' cannot be combined with any branch-line type ('BranchLine', 'Siding' or 'Spur').
* Yard types cannot be combined with other track types ('MainLine', 'BranchLine', 'Siding' or 'Spur').

You may combine multiple flags within the same group - for example a block can be both 'YardReceiving' and 'YardDeparture', or can be both 'BranchLine' and a 'Siding'.

To fix this error, correct the flag list so it does not mix incompatible track categories.

[[Category:Validation Errors]]

2026-02-16T02:27:39Z

Pw3r:

TNIPhysics is a builtin TNILibrary within Trainz which allows [[KIND tni-physics-plugin|physics plugin]] assets to control all the internal train physics for any traincar. This includes engine physics, braking systems and shared systems such as track/air resistance. It doesn't currently include systems such as random motion, coupling interactions, collisions or derailments.

Before continuing, it is recommended you first familiarise yourself with the following pages:
* [[TrainzNativeInterface]] - For an overview of TNI and the associated licensing requirements
* [[TNI Core Interface]] - For details of the core TNI functionality, object types, etc.
* [[KIND tni-physics-plugin]] - For the specification of the physics plugin asset kind.

''NOTE: This page is a work in progress. If you notice anything out of date, please advise N3V Games.''
''The original release of TNI Physics was in TRS19 SP3 in April 2021. However information and systems may change over time.''

==Overview==
TNIPhysics is initialised at game startup, and will automatically locate and load any installed TNI physics plugin assets at world/map load time. All TNIPhysics plugins must have a QueryProcessingPriority function, which will allow Trainz to determine which of the user's installed plugins is best suited to handle each specific vehicle. TNIPhysics will make all physics update calls through the plugin's LibraryCall interface.

The specific function calls supported by TNIPhysics are detailed in the next section.

==TNIPhysics Library Calls==

====Init====
TNIPhysics will call the plugin library DLL with the function name "Init" on initialization. This call can safely be ignored if no initialisation is necessary. This function expects no return object, and takes no parameters.

====QueryProcessingPriority====
This function is called from Trainz code to query the processing priority of a plugin for a given traincar. The function will be called across every plugin for every vehicle at load/creation time and when switching control modes (DCC vs cab). Whichever plugin returns the highest priority result will process the vehicle's physics. It has a single TNIPhysicsVehicle as the param, and expects a TNIInteger return result. The TNIPhysics_Priority enum defines a list of example return values, but the programmer is not constrained to using these defines.
*TNIPhysics_PriorityInvalid - Never use this plugin (-127)
*TNIPhysics_PriorityLowest - Only use this plugin if there's no other option (-20)
*TNIPhysics_PriorityLow - Prefer not using this plugin, but it might work ok (-10)
*TNIPhysics_PriorityDefault - This plugin can handle the request adequately (0). The builtin core plugin asset always returns this value.
*TNIPhysics_PriorityHigh - This plugin is somewhat specialised to handle the request (10)
*TNIPhysics_PriorityHighest - This plugin was built exactly for this request (20)

====RegisterVehicle====
This function is called from Trainz code on the plugin which returns the highest valid result from a call to "QueryProcessingPriority". It notifies a physics plugin that it has been selected to manage the vehicle, and should perform any appropriate internal initialisation. This function takes a single TNIPhysicsVehicle param (being the vehicle to register) and expects no return object.

====UnregisterVehicle====
This function is the counter to RegisterVehicle, and instructs a plugin that it is no longer managing the physics for a particular vehicle. This will occur when the vehicle is deleted, or Trainz hands it over to a more appropriate plugin (based on the result of a call to the "QueryProcessingPriority" function). This function takes a single TNIPhysicsVehicle param (being the vehicle to unregister) and expects no return object.

When called, the plugin should discard any internal data is has for the specified vehicle. If Trainz required anything to be saved, then a TNIP_SaveVehicleState command will have already been run.

====ProcessPhysicsCommands====
The main vehicle update function. This function is called from Trainz code to process a physics command stream for a specific vehicle. The function takes a TNIArray object which contains the TNIPhysicsVehicle (element 0) and a TNIStream (element 1) containing the commands to run (see enum TNIPhysicsPluginCommand for a list of physics commands and their params). Trainz expects a TNIStream return result, containing a list of physics update commands to Trainz from the plugin (see enum TNIPhysicsGameCommand).

==Physics Commands==
The ProcessPhysicsCommands LibraryCall uses incoming and outgoing command buffers to communicate physics information with Trainz.
The command buffer data is sequential - each command ID is written as a 16 bit integer, and will be followed followed by any relevant command parameters (see enum TNIPhysicsPluginCommand for specific command details).

As this is a raw command stream it is critical that the programmer carefully reads the documentation on each specific command, and correctly reads off each parameter value, even if they are not being used by the plugin. Failure to correctly read all command parameters will result in corruption of the stream, and undefinied application behaviour.

The stream has no terminating value, but stream end may be detected using the TNIStreamTell and TNIStreamGetSize functions, or simply by reading commands until failure is detected (e.g. <code>while (TNIStreamReadInt16(commandStream, 0))</code>).

The programmer must employ similar practices when writing the reply command stream. I.e. Each command is written as a 16 bit integer (TNIStreamWriteInt16), and must be followed by the parameters detailed in enum TNIPhysicsGameCommand. Failure to write data in the correct format will result in undefined behaviour within the application.

==Incoming Commands (TNIPhysicsPluginCommand)==
The following describes the possible physics commands the game may issue to a plugin, as per <code>enum TNIPhysicsPluginCommand</code>. Commands and parameters will be written, in sequence, to the TNIStream param passed to the ProcessPhysicsCommands library call.

====TNIP_UpdatePhysicsForVehicle====
The main physics update function. This is regularly called by Trainz code to update the traincar physics for a particular time period. This function takes two extra params for the front and rear coupled vehicles, but keep in mind these may be using different TNI plugins.

Parameters:
*float - The time interval to update for.
*TNIPhysicsVehicle - The front coupled vehicle.
*TNIPhysicsVehicle - The rear coupled vehicle.

====TNIP_AdjustMomentum====
Called from Trainz to notify of an adjustment to a vehicles momentum. This is typically used to apply the results of coupler physics interactions. Vehicles for which the plugin does not internally track momentum can safely ignore this call.

Parameters:
*double - The new vehicle momentum.

====TNIP_FinaliseFramePhysics====
Called by Trainz to notify that all updates relating to this vehicle for the current frame are complete. This includes all plugin updates and all coupler interactions. Plugins may use this as an appropriate location to synchronise plugin state to that of the game, or apply visible state changes only. At the time this call is made it is "too late" to perform or apply physics calculations for a given frame.

Parameters:
*float - The time interval that's been updated.
*double - The final momentum for this frame.

====TNIP_NormalisePhysicsData====
Called following an external physics state update in order to perform any physics-mode-specific follow up validation/correction. Examples include after physics/control state replication in multiplayer.

This command takes no parameters.

====TNIP_SaveVehicleState====
Called by Trainz code to request save data for a specific vehicle. If the plugin maintains any internal state for the specified vehicle then this function should save that state, so that players are able to save and reload with seamless physics behaviour. The save state should be returned to the game by adding a TNIP_ReturnSaveState command to the library call result stream (see TNIPhysicsGameCommand for more). If the plugin tracks no state for the vehicle passed, then this call can be safely ignored. That said, it is courteous to return known/common save data, even if this plugin itself may not use/require it, as it aids in seemless plugin switchover during gameplay.

This command takes no parameters.

====TNIP_LoadVehicleState====
Called by Trainz code to load previously saved vehicle state. Note that this is always called during load, even if the plugin does not produce any save state when TNIP_SaveVehicleState is called. Also note that the passed soup param may have been produced by a different plugin.

Parameters:
*TNISoup - A saved soup generated by a previous TNIP_SaveVehicleState call on this or another plugin. The soup will contain an AssetID param for the plugin that produced it, using the tag name "plugin-kuid".

====TNIP_SteamEngine_AddCoalToFire====
Called by Trainz code to add coal to a steam engine. For example, when the player uses the manual "Shovel coal" command.

Parameters:
*double - The volume (not mass) of coal to add.

====TNIP_ScriptFunctionCall====
Called from script to execute custom behaviour within the plugin. This will be added when a script calls Vehicle.LibraryCallPhysicsPlugin().

Parameters:
*TNILabel - The name of the plugin function to execute. If the function name is unrecognised or unsupported, the plugin should log an error and ignore it. (The TNISoup param must still be read though, to avoid the command stream being corrupted.)
*TNISoup - An optional TNISoup to be included with the command. This is used to pass more parameters to the custom plugin function, where required. Parsing code must handle the possibility that the parameter is null, even if the extra parameters are not optional for the plugin code. Similarly, plugins must not make assumptions about the validity of the soup data, and should either appropriately handle all inputs or ignore the command entirely.

==Outgoing Commands (TNIPhysicsGameCommand)==
The following describes the possible physics commands a plugin may issue to the game, as per <code>enum TNIPhysicsGameCommand</code>. A TNIPhysics plugin may write these commands (and their params) to the TNIStream being returned from a ProcessPhysicsCommands library call.

====TNIP_UpdateVehicleBegin====
Specifies which vehicle a sequence of update commands refers to. Use of this command is not necessary, and by default any written commands will update the vehicle which ProcessPhysicsCommands() was called for. If, however, the plugin wishes to run commands for connection data on one of the coupled vehicles (such as brake pipes, etc) then this is used to specify that vehicle.

Parameters:
*TNIPhysicsVehicle - The vehicle to start updating.

====TNIP_UpdateVehicleEnd====
Used to mark the end of a vehicle update stream. This will set the update vehicle to null. Following this, a new TNIP_UpdateVehicleBegin command *must* be written before any further update commands.

This command takes no parameters.

====TNIP_ReturnSaveState====
Used to return the generated save state for a TNIP_SaveVehicleState command (documented above, in TNIPhysicsPluginCommand).

Parameters:
*TNISoup - A soup containing the saved plugin state. The plugin should write enough state to adequately restore its current internal state for the given vehicle on reload. It is also courtesy to return known/common save data which this plugin itself may not use/require, but which may be useful/expected by other plugins (this aids in seemless plugin switchover during gameplay).

===Engine Commands===

====TNIP_SetResistanceForce====
Sets the current resistant force for train movement. This includes all track resistance, slope resistance, and internal engine resistances.

Parameters:
*double - The current resistance force, in Newtons.

====TNIP_SetBrakingForce====
Sets the current braking force for the train. This is the force from any/all applied brakes.

Parameters:
*double - The current braking force, in Newtons.

====TNIP_SetEngineForce====
Sets the force currently being output by the engine.

Parameters:
*double - The current engine force, in Newtons.

====TNIP_SetAppliedEngineForce====
Sets the force currently being applied to the wheels by the engine. In other words, this is the engine force minus any wheelslip.

Parameters:
*double - The current applied engine force, in Newtons.

====TNIP_SetWheelslipForce====
Sets the amount of force currently being lost to wheelslip.

Parameters:
*double - The current wheelslip force, in Newtons.

====TNIP_SetCurrentDrawn====
Updates the current drawn stat.

Parameters:
*double - The current being drawn, in Amps.

====TNIP_SetPFXEnergyUseAmount====
Updates the "energy use" stat, which is used to generate the PFX "load" variable. This currently has no effect on traincar physics, just particle effects (smoke).

Parameters:
*double - The energy use for the current time interval.

====TNIP_SetWheelMomentum====
Sets the current forward momentum for a traincar (i.e. this value will be negative if the traincar is not moving forwards).

Parameters:
*double - The new forward momentum for the updated traincar, in Newton seconds.

====TNIP_AddWheelMomentum====
Adds momentum to the updated traincar. A negative (or positive, for backward travelling traincars) value may be used to remove momentum.

Parameters:
*double - The momentum to add onto the traincar, in Newton seconds.

====TNIP_SetExtraEngineMass====
Sets the amount of 'extra' engine mass a vehicle currently has. This is typically the fuel mass (water and coal) for steam locos.

Parameters:
*double - The current extra engine mass, in kg.

====TNIP_SetEngineParam====
Sets the value of a named engine param, as returned by the script <code>GetEngineParam()</code> function on Vehicle. This is used to add support for custom named parameters, attempting to override the natively supported params may not work.

Parameters:
*TNILabel - The name of the engine parameter to add/update.
*double - The new value of the parameter.

====TNIP_SetEngineThrottle====
Sets the current engine throttle. This should gradually move toward the throttle setting, with some amount of latency.

Parameters:
*double - The new engine throttle amount (0 to 1).

====TNIP_SetCompressorActive====
Sets whether the brake system compressor is active.

Parameters:
*int8_t - The new compressor state (0- off, 1-on).

====TNIP_SetEqualiserPressure====
Sets the pressure of the brake system equaliser.

Parameters:
*double - The new equaliser pressure, in g/m^3.

====TNIP_SetMainReservoirPressure====
Sets the pressure of the brake system main reservoir.

Parameters:
*double - The new main reservoir pressure, in g/m^3.

====TNIP_SetAuxReservoirPressure====
Sets the pressure of the brake system auxiliary reservoir.

Parameters:
*double - The new auxiliary reservoir pressure, in g/m^3.

====TNIP_SetAutoBrakeCylinderPressure====
Sets the pressure of the brake cylinder.

Parameters:
*double - The new brake cylinder pressure, in g/m^3.

====TNIP_SetIndependentBrakeCylinderPressure====
Sets the pressure of the independent/loco brake cylinder.

Parameters:
*double - The new independent/loco brake cylinder pressure, in g/m^3.

====TNIP_SetTrainBrakePipePressure====
Sets the pressure of the main train brake pipe.

Parameters:
*double - The new train brake pipe pressure, in g/m^3.

====TNIP_SetEpReservoirPipePressure====
Sets the pressure of the electro-pneumatic brake pipe.

Parameters:
*double - The new electro-pneumatic brake pipe pressure, in g/m^3.

====TNIP_SetNo3PipePressure====
Sets the pressure of the no3 brake pipe.

Parameters:
*double - The new no3 brake pipe pressure, in g/m^3.

====TNIP_SetNo4PipePressure====
Sets the pressure of the no4 brake pipe.

Parameters:
*double - The new no4 brake pipe pressure, in g/m^3.

====TNIP_SetBrakePressureFlowRate====
Notifies of the brake pressure flow rate.

Parameters:
*double - The new brake pressure flow rate, in g/m^3.

===Steam Engine Commands===

====TNIP_SetCoalLevel====
Sets the coal level in a steam locomotive. This is the current ratio between the minimum (0) and maximum (1) coal levels for the firebox. i.e., a reading of 0 indicates the fire is at minimum coal, not that it's necessarily "empty", and a value over 1 indicates the fire is over-filled with coal.

Parameters:
*double - The current coal level in the firebox.

====TNIP_SetWaterLevel====
Sets the water level in a steam locomotive. This is the current ratio between the minimum (0) and maximum (1) water levels for the boiler, as would be shown on the cab gauge(s). i.e., a reading of 0 indicates the boiler is at or below minimum, not that it's necessarily "empty".

Parameters:
*double - The current water level in the boiler.

====TNIP_SetBoilerPressure====
Sets the current pressure within the boiler, in pascals.

Parameters:
*double - The new boiler pressure, in pascals.

====TNIP_SetSteamChestPressure====
Sets the current pressure within the steam chest, in pascals.

Parameters:
*double - The new steam chest pressure, in pascals.

====TNIP_SetThrashing====
Sets the amount the engine is being 'thrashed', as returned to script by a call to <code>Locomotive.GetEngineParam("thrashing");</code>

Parameters:
*double - The amount the engine is being 'thrashed', 0 to 1 for normal engine operation, >1 for thrashing.

====TNIP_ConsumeCoal====
Informs Trainz to consume an amount of coal product, for use as steam engine fuel. The caller should first verify that there is sufficient fuel to meet the request, using TNIPhysicsGetVehicleCoalAvailable().

Parameters:
*int32_t - The amount of product to consume.

====TNIP_ConsumeWater====
Informs Trainz to consume an amount of water product, for use as steam engine fuel. The caller should first verify that there is sufficient fuel to meet the request, using TNIPhysicsGetVehicleWaterAvailable().

Parameters:
*int32_t - The amount of product to consume.

===Effect Commands===

====TNIP_SetWheelAngularVelocity====
Sets the angular velocity of the wheels on a steam locomotive. This affects the value of the "cyclespeed2" PFX variable.

Parameters:
*float - The angular velocity of the driving wheels, in m/s.

====TNIP_SetWheelAnimationData====
Sets the animation data for the wheels of a traincar. Two values are always written here, but which is used will depend on the type of wheel animation which being used by the traincar.

Parameters:
*float - The current wheel rotation, from 0 to 2PI.
*float - The wheel velocity, in m/s.

====TNIP_SetBrakeReleaseSoundFade====
Sets the volume of the brake release sound on this traincar.

Parameters:
*float - The new brake release sound volume, 0 to 1.

====TNIP_SetPFXVariableValue====
Sets the value of a named PFX variable. See validation/steam-mode.txt for a list of valid variable names.

Parameters:
*TNILabel - The name of the variable to update.
*float - The new value of the variable.

===Script Commands===

====TNIP_SetPluginFeatureSupport====
Specifies the custom features which this plugin supports, so that they can be queried by script. This API is optional, but plugins should normally specify at least one feature ID, to allow scripts to query which plugin is running.

Parameters:
*TNIArray - An array of string IDs (using TNILabel) for the supported features. This may be empty or null, but it must be written to avoid corrupting the command stream. Each string ID should be prefixed with the plugins base (i.e. versionless) KUID, followed by an English human readable feature string. For example: "<kuid:1111:2222>/diesel-consumption".

Note:

When this is called, the supplied feature list will completely replace any existing feature list. I.e. You must always provide the complete list of supported features for the current vehicle.

====TNIP_ScriptPostMessage====
Posts a message to the vehicle script. This can be used to trigger the execution of custom script code from the plugin, if any script supports it. The posted message will use the 'major' value of "TNIPhysicsPlugin". The 'minor' value is specified by the first parameter to this command.

Parameters:
*TNIString - The value to use for Message.minor. Must not be empty.
*TNISoup - An optional TNISoup to be included with the message. This allows custom data/parameters to be provided to script. This may be null but it must be written to avoid command stream corruption.

==Accessor Commands (TNIPhysics.h)==
Basic accessors for TNIPhysicsVehicle member variables, including those on the frame data, engine spec or steam engine spec.

==TNIGameObjectID/Matching Accessors==
{{MethodHeader|const TNIGameObjectID* TNIPhysicsGetVehicleID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNIGameObjectID* TNIPhysicsGetVehicleTrainID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsDoesVehicleMatchID(const TNIPhysicsVehicle* vehicle, const TNIGameObjectID* id)}}

===AssetID/Config Accessors===
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleAssetConfig(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleEngineAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleEngineAssetConfig(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNIAssetID* TNIPhysicsGetVehicleTrackAssetID(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|const TNISoup* TNIPhysicsGetVehicleTrackAssetConfig(const TNIPhysicsVehicle* vehicle)}}

===AssetID/Config Accessors===
{{MethodHeader|double TNIPhysicsGetTrainLocoCount(const TNIPhysicsVehicle* vehicle}}

===Train Control Settings===
{{MethodHeader|int8_t TNIPhysicsGetVehiclePhysicsModelSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleTractionSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleThrottleSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSteamRegulatorSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSteamCutoffSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleTrainBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleDynamicBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleLocoBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleEpBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBailTimeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleHandBrakeSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleSandingSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleCoalRateSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleInjector1Setting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleInjector2Setting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBlowerSetting(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleCustomSetting(const TNIPhysicsVehicle* vehicle, const TNILabel* settingName)}}

===Vehicle State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleVelocity(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleIsStopped(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelMomentum(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslip(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslipTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelslipMomentumMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEngineForce(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEngineThrottle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleThrottleGraphOutput(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleDynamicBrakeGraphOutput(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|bool TNIPhysicsGetVehicleIsDerailed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleAllowsUserControl(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|bool TNIPhysicsGetVehicleIsAutomaticFireman(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|uint32_t TNIPhysicsGetVehicleCoalAvailable(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|uint32_t TNIPhysicsGetVehicleWaterAvailable(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleSandingTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleScriptTractionMultiplier(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Brake Pressure State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleEqualiserPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMainReservoirPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleNo3PipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleTrainBrakePipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleEpReservoirPipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleNo4PipePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAuxReservoirPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAutoBrakeCylinderPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleIndependentBrakeCylinderPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleScriptBrakePressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBrakePipeEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleCompressorEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int8_t TNIPhysicsGetVehicleCompressorActive(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleBrakeReleaseSoundFade(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Track State Accessors===
{{MethodHeader|double TNIPhysicsGetVehicleTrackGradient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleTrackCurveAngle(const TNIPhysicsVehicle* vehicle)}}

===Vehicle Spec Accessors===
{{MethodHeader|int8_t TNIPhysicsGetVehicleEngineType(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMaximumTractiveEffort(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleWheelDiameter(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleMaxSpeed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxDCCAcceleration(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxDCCDeceleration(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleMaxVoltage(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetEngineBrakeRatio(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleThrottleAdjustmentRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAxleCount(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleSurfaceArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleMovingFrictionCoefficient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleAirDragCoefficient(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|double TNIPhysicsGetVehicleDrivingWheelWeightRatio(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Flowsize Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EpReservoirPipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No4Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToNo3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToTrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AutoBrakeCylinderVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_AuxReservoirToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserMainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVentHandleOff(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVentEmergency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EqualiserVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeMainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_Compressor(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipeReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_TrainBrakePipeVent(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_No3PipeToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_EpReservoirPipeToAutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleFlowsize_MainReservoirEP(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Volume Accessors===
{{MethodHeader|float TNIPhysicsGetVehicleVolume_Equaliser(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_MainReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_No3Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_TrainBrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_EpReservoirPipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_No4Pipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_AuxReservoir(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_AutoBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehicleVolume_IndependentBrakeCylinder(const TNIPhysicsVehicle* vehicle)}}

===Engine Spec Pressure Accessors===
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakePipe(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakeInitial(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_BrakeFull(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_IndBrakeFull(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetVehiclePressure_Compressor(const TNIPhysicsVehicle* vehicle)}}

===Steam Engine Spec Accessors===
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonVolumeMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonVolumeMax(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonLength(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|int TNIPhysicsGetSteamEnginePistonAngularOffsetsCount(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEnginePistonAngularOffset(const TNIPhysicsVehicle* vehicle, int i)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineTractiveEffortConstant(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineHandBrakeMaxForce(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineTestSpeed(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineTestCutoff(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBurnRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBurnRateIdle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMinFireTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMaxFireTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxEfficiency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxHeatingSurfaceArea(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxPlateThickness(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFireboxThermalConductivity(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBlowerEffect(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBlowerMaxFlow(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineStartingCoal(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineIdealCoalMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineMaxFireCoalMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFuelEnergy(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineFuelSpecificHeatCapacity(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolumeMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerVolumeMax(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerFusiblePlugVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSteamChestVolume(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSteamChestMaxFlow(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineValveLapPercent(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficency(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficencyIdle(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerEfficencyMin(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineBoilerHeatLoss(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineInitialBoilerTemperature(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSuperheatingConstant(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineStartingWater(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineStartingBoilerSteam(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveLowPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveLowFlow(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveHighPressure(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineSafetyValveHighFlow(const TNIPhysicsVehicle* vehicle)}}

{{MethodHeader|float TNIPhysicsGetSteamEngineCoalShovelMass(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineWaterInjectorRate(const TNIPhysicsVehicle* vehicle)}}
{{MethodHeader|float TNIPhysicsGetSteamEngineWaterInjectorRate2(const TNIPhysicsVehicle* vehicle)}}

TNI Core Interface

2026-02-16T02:19:30Z

Pw3r:

The [[TNI Core Interface]] is a protocol and associated functions which allows communication between Trainz and a third-party [[TrainzNativeInterface|TNI plugin]].

=DLL Development=
All TNI plugin DLLs must be written in C/C++. Due to the code-signing requirements imposed by the TNI developer agreement, it is not possible to create TNI plugin DLLs in other languages. At the current time, all TNI plugin DLLs must compile under Microsoft Visual Studio 2013's subset of C++11. TNI DLLs may use the following external headers and techniques:

* The TrainzNativeInterface SDK headers, which provide the [[TNI Core Interface]] and other component interfaces.
* The C standard library allocators and utility functions.
* The C++ STL (Standard Template Library) containers, allocators, and utility functions.

TNI DLLs must not use the following external headers and techniques unless a specific exception is granted.

* Windows Platform SDK.
* File, network, permissions, process, or other "system access" or "external access" headers.
* Third-party DLLs.
* Third-pary source code which does not follow these requirements.
* Assembly language.
* Bytecode machines, JIT compilers, and other forms of state machine whose runtime characteristics cannot be determined in advance; i.e. programs which effectively treat input data as source 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 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==
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>

=TrainzNativeInterface.h=

The TNI core interface is designed to abstract the passing of data between Trainz and the TNI plugin DLLs. All data is represented by an opaque polymorphic object basetype, TNIObject. The objects are reference counted, with simple reference-count rules:

* 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.
* Care must be taken to avoid reference count cycles where two objects directly or indirectly reference each other (e.g. a->b->a or a->b->c->a) as this prevents the objects from ever being released, causing a memory leak.

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]]:

==TNIObject==
TNIObject is the polymorphic base class for all the entire TNI object hierarchy. All TNIObjects are considered opaque types, are constructed via helper functions provided in the TrainzNativeInterface DLL, and are released with TNIRelease().

<code><pre>
// ============================================================================
// TNI OBJECT TYPES
// ============================================================================
enum
{
TNI_CLASS_NONE = 0,
TNI_CLASS_OBJECT = 1,
TNI_CLASS_STRING = 2,
TNI_CLASS_ARRAY = 3,
TNI_CLASS_CONTEXT = 4,
TNI_CLASS_LIBRARY = 5,
TNI_CLASS_STREAM = 6,
TNI_CLASS_GRAPHICS = 7,
TNI_CLASS_VECTOR = 8,
TNI_CLASS_ASSETID = 9,
TNI_CLASS_LABEL = 10,
TNI_CLASS_BUFFER = 11,
TNI_CLASS_SOUP = 12,
};

// ============================================================================
// Name: TNIGetObjectClass
// Desc: Return the type of the specified object, as per the above enumeration
// values.
// Parm: object - the object to query. It is safe to pass a NULL value here.
// ============================================================================
uint32_t TNIGetObjectClass(const TNIObject* object);

// ============================================================================
// Name: TNIReference
// Desc: Add a reference to the specified object. The object will be released
// when the reference count drops to zero.
// Parm: object - The object to which we will add a reference. It is safe to
// pass a NULL value here.
// ============================================================================
void TNIReference(const TNIObject* object);

// ============================================================================
// Name: TNIRelease
// Desc: Remove a reference to the specified object. The object will be
// released when the reference count drops to zero. TNIRelease() should
// be called exactly once for each call to TNIReference() and once for
// any function return value (for example, from TNIAllocString().)
// Parm: object - The object from which we will remove a reference. It is safe
// to pass a NULL value here.
// ============================================================================
void TNIRelease(const TNIObject* object);
</pre></code>

==TNIString==
TNIString provides a simple string class. The raw string data is zero-terminated in the usual C fashion, and is encoded as UTF-8. UTF-8 is a superset of ASCII, so ASCII strings can be stored directly in a TNIString with no conversion necessary.

<code><pre>
// ============================================================================
// Name: TNIAllocString
// Desc: Allocates a TNIString given a zero-terminated UTF8 text buffer.
// Parm: utf8text - The UTF-8 text buffer. The contents of the buffer are
// copied into the TNIString. The function results are undefined if this
// parameter does not represent a valid UTF-8 encoded string.
// Retn: TNIString - The newly allocated TNIString.
// Note: You must eventually release the allocated string using TNIRelease().
// Note: If 'utf8text' is nullptr, the returned TNIString is an empty string.
// ============================================================================
TNIString* TNIAllocString(const char* utf8text);

// ============================================================================
// Name: TNIGetStringText
// Desc: Retrieves a pointer to the internal text buffer of the TNIString
// object. This is a read-only reference, and remains valid only while
// (1) you hold a reference to the TNIString, and (2) you do not modify
// the TNIString.
// Parm: string - The TNIString object to query.
// Retn: const char* - A temporary pointer to the internal string text, in
// utf8 encoding.
// Note: If 'string' is a nullptr, the return value is a pointer to an empty
// string.
// ============================================================================
const char* TNIGetStringText(const TNIString* string);

// ============================================================================
// Name: TNIGetStringSize
// Desc: Returns the size in bytes of the specified string.
// Parm: string - A TNIString object, or nullptr.
// Retn: size_t - The size in bytes of the text string. Note that this is the
// size of the UTF-8 encoded text data, not including zero termination,
// and not including any overheads. If the string is null or empty, this
// returns zero.
// ============================================================================
size_t TNIGetStringSize(const TNIString* string);

// ============================================================================
// Name: TNISetStringText
// Desc: Modifies the TNIString to a copy of the supplied UTF-8 encoded text
// buffer.
// Parm: string - The existing TNIString object to modify. Modifying the string
// invalidates any pointer previously returned by TNIGetStringText().
// Parm: utf8text - The UTF-8 text buffer. The contents of the buffer are copied
// into the TNIString. The function results are undefined if this
// parameter does not represent a valid UTF-8 encoded string.
// Note: If 'string' is a nullptr, this function does nothing.
// Note: If 'utf8text' is a nullptr, it is considered an empty string.
// ============================================================================
void TNISetStringText(TNIString* string, const char* utf8text);

// ============================================================================
// Name: TNIAppendStringText
// Desc: Appends the supplied UTF-8 encoded text buffer to the TNIString.
// Parm: string - The existing TNIString object to modify. Modifying the string
// invalidates any pointer previously returned by TNIGetStringText().
// Parm: utf8text - The UTF-8 text buffer. The contents of the buffer are copied
// into the TNIString. The function results are undefined if this
// parameter does not represent a valid UTF-8 encoded string.
// Note: If 'string' is a nullptr, this function does nothing.
// Note: If 'utf8text' is a nullptr, this function does nothing.
// ============================================================================
void TNIAppendStringText(TNIString* string, const char* utf8text);

// ============================================================================
// HELPER FUNCTIONS
// ============================================================================
// The "cast" functions do not follow the normal semantics of returning a
// referenced object. They return the same object that you pass in, with no
// additional references taken. You should discard the cast result and release
// the original object when complete.
const TNIString* TNICastString(const TNIObject* object);
</pre></code>

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

<code><pre>
// ============================================================================
// Name: TNIAllocLabel
// Desc: Returns a label object for the specified text. Only one label object
// can exist for a given label at any time- repeated calls to this
// function with the same text string will result in the same object
// being returned (although the refcount is increased with each call.)
// It is safe to rely on this property, so you can directly compare the
// returned pointer for equality or inequality.
// This is a relatively slow function; you should call it once to
// generate the label, then store the label for as long as you need to
// use it. You should not attempt to regenerate the same label for each
// usage.
// Parm: utf8text - The text which corresponds to the label. A null or empty
// string will result in a nullptr label; this is not considered an
// error.
// ============================================================================
TNILabel* TNIAllocLabel(const char* utf8text);

// ============================================================================
// Name: TNIGetLabelDebugText
// Desc: Returns a string representation of the label, for debugging purposes.
// Note that there is no guarantee that this representation matches the
// string passed to TNIAllocLabel, and it should not be machine parsed.
// Parm: label - The label to query.
// Retn: const char* - A utf8-encoded string representing the label for the
// purposes of debug logging. The returned string is not owned by the
// caller but references a buffer internal to the label object.
// If 'label' is nullptr, the result will be the empty string.
// ============================================================================
const char* TNIGetLabelDebugText(const TNILabel* label);
</pre></code>

==TNIAssetID==
TNIAssetID encodes a KUID or other Asset ID. You should avoid making any assumptions about the meaning of the data encoded in an TNIAssetID, as the interpretation is subject to change without notice.

==TNIArray==
TNIArray provides an indexed element array containing TNIObjects. Space for the entire array is allocated when the size is set. Random access within the array is very fast.

==TNISoup==
TNISoup provides a key-value mapping, similar in concept to the [[class Soup]] and the [[config.txt]] file format. Keys are TNILabel objects, and values are TNIObjects.

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

TNIContext objects are created by the host process, and cannot be created or destroyed by TNI plugins.

<code><pre>
// ============================================================================
// Name: TNIGetContextVersionCode
// Desc: Returns the Trainz Version code for this context.
// Parm: context - The context to query.
// Retn: uint32_t - The version code.
// ============================================================================
uint32_t TNIGetContextVersionCode(const TNIContext* context);

// ============================================================================
// Name: TNIGetContextLibrary
// Desc: Looks up a library in the specified context by name.
// Parm: context - The context to query.
// Parm: libraryName - The unique name of the library to return.
// Retn: TNILibrary* - The located library object, or NULL on failure.
// ============================================================================
TNILibrary* TNIGetContextLibrary(const TNIContext* context, const TNIString* libraryName);
</pre></code>

All TNI libraries within the same context are available to each other by name. This allows plugins to reference each other. Care must be taken to avoid reference count cycles when accessing a library in this fashion- there should always be a clear "parent" and "child" relationship between any two libraries, with the parent referencing the child and the child never referencing the parent.

==TNILibrary==
The TNI plugin DLL entry point is expected to construct a TNILibrary descriptor and return it to Trainz. This serves as the public interface to the plugin, and may be accessed by Trainz native code, [[TrainzScript]], and other TNI plugins. TNILibrary objects are context-specific, so multiple TNILibrary objects may be created for a single plugin DLL.

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.

<code><pre>
// ============================================================================
// Name: TNIAllocLibrary
// Desc: Allocate a new library in the specified context, given a unique
// library name and the initialisation data.
// Parm: context - The context in which this library is being created.
// 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.
// ============================================================================
TNILibrary* TNIAllocLibrary(TNIContext* context, const TNIString* libraryName, const TNILibraryInitData& libraryInitData);

// ============================================================================
// Name: TNIGetLibraryVersion
// 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.
// Returns zero on failure.
// ============================================================================
uint32_t TNIGetLibraryVersion(const TNILibrary* library);

// ============================================================================
// Name: TNICallLibraryFunction
// Desc: Calls into the specified library's LibraryCall function.
// Parm: library - The library on which to make the call.
// Parm: functionName - The name of the function to call. Must be a non-empty
// string.
// Parm: params - NULL, or a TNIObject object.
// Retn: TNIObject* - The return value from the LibraryCall function, which may
// be NULL or a valid TNIObject. Returns NULL on failure. It is the
// caller's responsibility to release the returned object.
// ============================================================================
TNIObject* TNICallLibraryFunction(const TNILibrary* library, const TNILabel* functionName, const TNIObject* params);
</pre>
</code>

==TNIBuffer==
TNIBuffer provides untyped binary data storage. This is used in scenarios where large amounts of complex-type data needs to be rapidly created and passed between systems. This should be considered a last-resort mechanism, used only when the cost of the other object types is prohibitive.

==TNIStream==
TNIStream provides a mechanism for serialising both data and TNIObjects into a "command buffer" which can be passed to another system. This is used in scenarios where large numbers of commands must be rapidly packed and later replayed. The writer and reader must agree on the stream format- the reader must make the appropriate calls to match what the writer used when constructing the stream. It is strongly recommended that some form of version negotiation is used to allow future changes to any streamed formats. TNIObjects are written to a TNIStream by reference- the TNIObjects themselves are not serialised or copied.

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

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