System Macros are a set of pre-defined procedures which can be called from scripts in order to interact with data beyond the scripting engine, for example reading data from HOF files.
System Macros are called with (M.V.example); like Operators, most consume operands from the float and/or string stacks. For the purpose of these descriptions the operands are labelled f0–f7 for the float stack and $0–$7 for the string stack. Because the stacks are independent, string operands can come before, after or intermingled amongst float operands.
Different sets of System Macros are available for use with Sceneryobjects and Vehicles, with Script-Texture macros being available for both.
These are declared in /program/callbacklist_scenobj.txt.
GetArrBusLineReturns the Line Number (e.g. "92E") for the Arrival Index-th (zero-based) bus to arrive at the bus stop. The sceneryobject must be parented to a bus stop cube to get a result returned.
E.g.: 1 (M.V.GetArrBusLine) returns the route number of the 2nd bus due to arrive at the bus stop.
GetArrBusTerminusReturns the Destination (e.g. "Stadtgrenze") for the Arrival Index-th (zero-based) bus to arrive at the bus stop. The sceneryobject must be parented to a bus stop cube to get a result returned.
E.g.: 1 (M.V.GetArrBusTerminus) returns the terminus of the 2nd bus due to arrive at the bus stop.
GetArrBusTimeDiffReturns the Time until arrival in seconds for the Arrival Index-th (zero-based) bus to arrive at the bus stop. The sceneryobject must be parented to a bus stop cube to get a result returned.
E.g.: 1 (M.V.GetArrBusTimeDiff) returns the number of seconds until the 2nd bus due to arrive at the bus stop arrives.
These are declared in /program/callbacklist_roadvehicle.txt.
GetTerminusIndexReturns the index (zero-based) of a terminus in the HOF file from its Terminus Code, or -1 if no matching terminus is found.
GetTerminusCodeReturns the terminus code of the specified terminus in the HOF file.
GetTerminusStringReturns the String Index-th (zero-based) string of the specified terminus in the HOF file.
GetBusstopIndexReturns the index (zero-based) of a bus stop in the HOF file from its internal name, or -1 if no matching busstop is found.
GetBusstopStringReturns the String Index-th (zero-based) string of the specified bus stop in the HOF file.
GetRouteIndexReturns the index (zero-based) of a route ([infosystem_trip]) in the HOF file from its Route Code, or -1 if no matching route is found.
GetRouteTerminusIndexReturns the terminus index of the specified route in the HOF file—the HOF file creator can put any integer here, so a terminus with this index is not guaranteed to exist in the HOF file.
GetBusstopCountReturns the number of bus stops for the specified route, as defined with [infosystem_busstop_list].
GetRouteBusstopIdentReturns the Route-Busstop Index-th (zero-based) entry in the bus stop list for the specified route. While the implication is that this is a Busstop Ident, and the default IBIS script passes the return value straight into GetBusstopIndex, this can be any arbitrary string—get creative!
GetTTLineStringReturns the Line Number (e.g. "92E") for the active timetable.
GetTTTerminusIndexReturns the terminus index for the active timetable. The map creator can put any integer here, so a terminus with this index is not guaranteed to exist in the HOF file.
GetTTBusstopCountReturns the number of bus stops in the active timetable.
GetTTBusstopIndexReturns the index (zero-based) of the current stop in the active timetable (e.g. 0 when driving from the lay-over point to the starting bus stop, incrementing each time the bus stop changes in the red line until 1 less than GetTTBusstopCount).
GetTTDelayReturns the difference between where the bus is and where OMSI thinks the bus should be according to the timetable in seconds, e.g. -1.3 indicates the bus is 1.3 seconds ahead of schedule.
GetTTBusstopNameReturns the name (as defined in the bus stop cube) of the specified bus stop in the active timetable.
GetTTBusstopArr, GetTTBusstopDepReturn the arrival or departure times for the specified bus stop in the active timetable. These should be seconds since midnight, like the system variable Time.
GiveChangeCoinIssue the specified coin (zero-based index within currency config file) as change.
GetTicketNameReturn the name of the specified ticket (zero-based index within ticketpack).
GetTicketValueReturn the price of the specified ticket (zero-based index within ticketpack).
GetHumanCountOnPathLinkAdded in version 1.03.
Return the number of passengers standing or walking on the specified [pathlink] (zero-based index within paths config file).
Can be used to animate entry barriers that the passengers walk through, like on the default EN/GN92.
NrSpecRandomAdded in version 2.00.
Returns a pseudo-random value (0–1?) based on the fleet number and Seed—the same combination of fleet number and seed will result in the same random value.
This is intended to be used to simulate random variations across a fleet of vehicles—each vehicle will have different but consistent variations.
GetHeightAbovePointAdded in version 2.00.
Returns the distance (metres) from the point (X, Y, Z) (metres, relative to vehicle origin) that a ray cast along the vehicle's -Z axis (down, but relative to the vehicle not gravity) would intersect the ground (terrain, road or pavement).
Particularly useful for scripting wheelchair ramps/lifts to stop when touching the ground, like the one on the default EN/GN92. Could also be used to simulate the door sill coming to rest on a kerb when kneeling (bonus points if the door jams because the body is being twisted! 😈).
GetDepotStringGlobalAdded in version 2.00.
Returns the String Index-th (zero-based) global string in the HOF file.
GetHumanCountOnSeatAdded in version 2.2.
Return the number of passengers (zero or one) sitting or standing in the specified [passpos] (zero-based index within passenger cabin config file).
Can be used to animate flip-up seats like the ones often found in wheelchair bays.
These are declared in /program/callbacklist_scripttex.txt.
STNewTexInitialises the script-texture (replaces any existing data with a black bitmap rectangle matching the dimensions of the script-texture). Initialising a script-texture should be done irregularly to avoid slow downs.
After initialisation, the script-texture will be unlocked, regardless of whether it was locked beforehand.
STLockLocks the script-texture, allowing your script to draw to the script-texture and preventing OMSI from displaying the changes while the script-texture is locked.
STUnlockUnlocks the script-texture, allowing OMSI to display any changes that have been made.
STFilterCreates mipmaps for the script-texture. If this is not done, the texture gets blurry in the distance. Filtering a script-texture should be done irregularly to avoid slow downs.
STFilter can only be performed on an unlocked script-texture.
STSetColorSets the colour to be used for drawing operations on the script-texture. The value for each channel should be an integer between 0 and 255 (inclusive).
STDrawPixelDraws a single pixel at (X, Y) (0-based) in the drawing colour.
STDrawRectDraws a filled rectangle with top-left pixel (X1, Y1) and bottom-right pixel (X2, Y2) in the drawing colour. Bottom-right pixel is inclusive, so 0 0 1 1 will result in a 2 × 2 square.
STTextOutWrites text with top-left pixel (X, Y) in the given font.
Font Index can be found with GetFontIndex.
If Full Colour is true the font's colour bitmap will be used for the colour channels, otherwise a rectangle is drawn in the drawing colour. The alpha channel is always taken from the font's alpha bitmap.
Letter Spacing specifies a number of additional pixels to insert between each character.
GetFontIndexReturns the index for the given font. Font Name must be exactly as the font is named internally.
Font indexes below 1 are invalid.
TextLengthReturns the length in pixels of the given text in the given font.
STReadPixelSets the colour to be used for drawing operations on the script-texture to the colour of the pixel at (X, Y) (0-based).
STCopyColorSets the colour to be used for drawing operations on the destination script-texture to the drawing colour of the origin script-texture.
STLoadTexReplaces the script-texture bitmap with the given texture file. If the texture file does not exist, the script-texture is unchanged.
Loading a DXT-compressed DDS image works fine, but any attempts to draw onto the image will appear corrupted.
If drawing to the script texture in the same frame as a texture is loaded, STLock should be run after STLoadTex, otherwise the drawing actions may be run before the texture has finished loading, causing glitches and crashes.
STGetR, STGetG, STGetB, STGetAReturns the Red, Green, Blue or Alpha value of the drawing colour respectively.