NIMBY Rails

NIMBY Rails

61 ratings
Mod development guide
By Weird and Wry
How to create mods for NIMBY Rails.
4
   
Award
Favorite
Favorited
Unfavorite
Introduction
At this time NIMBY Rails supports adding new train models to the game, new track kinds, and translation mods. Other kinds of mods may be added in the future. In this guide I will describe how these mods are structured, how to develop and test them, and how to upload them to Steamworks.

NOTE TO MOD AUTHORS FROM THE DEV: all the features described in this guide are correctly loaded and interpreted by game version 1.4 an later, but not all of them are displayed in the UI. In particular some tag sets and train information has no UI yet. Work is ongoing to enable them, and once they are are enabled, any mod that defined them will automatically display the data.
Changelog
Version 1.11
StyleLabelDefaults section in map style mods to change map label colors.

Version 1.10
  • New mod: map style mods
  • The game now renders textures using premultiplied alpha. You don't need to do anything to your mod textures, it is handled automatically. If you observed darkening or black borders in your textures when the game rendered them when zoomed out, it should now be corrected in 1.10.

Version 1.8
New TrainUnit properties: max_acceleration, max_regular_braking, max_emergency_braking, max_tractive_effort

Version 1.7
  • All tags are now allowed to appear in TrainUnit, including role tags
  • TrainUnit supports the year_introduced and year_retired properties
  • New cost_per_km property for TrainUnit
  • New allow_player_composition property for TrainUnit, to disable player custom trains using the TrainUnit
  • New front_coupler, front_coupler_mandatory, back_coupler, back_coupler_mandatory properties for TrainUnit
  • New category and description fields for TrainUnit
Concepts
Rules
In the game systems, a rule is an object that contains constant, immutable data that controls parameters of the simulation. Mods are just a collection of rules objects written in an easy to edit text format, plus any required data in separate files, like textures.

IDs
Rules objects usually have an ID field, and often make reference to other rules objects by using their ID. When creating your own mods you must pick unique IDs for your rules objects, not used by the game or by other mods. IDs are arbitrarily long strings so it should be easy to come up with both unique and readable IDs. Do not use spaces or special characters when picking up IDs. Latin characters, digits and underscores are OK.

If you reuse or reference IDs from the base game, the example mod, or from other Workshop mods, players using your mod can experience broken train textures and wrong train parameters. The game does not support sharing IDs between mods, even if they are your own mods.

schema
All the objects declared in the mod have a schema field. This declares the version of the mod structure, and allows the game to load older mods. Use the schema value indicated in the rules tables in the next section.

Train models
The game supports the concept of train models. One or more train models can be defined in a mod, in the sections called "TrainMultipleUnit", which despite the name, are not limited to MUs at all. Then each model can have one or more compositions, and the mod author is free to combine any TrainUnits defined inside their mod in any number in any combinations.
TrainUnit rules
TrainUnit
The rules object TrainUnit represents the combined concept of a train car and/or locomotive. The game makes no distinction, and a TrainUnit may act as both concepts at the same time, depending on how it is configured. It is of course possible to declare a TrainUnit with no power if unpowered cars are desired.

Field
Type
Range
Description
schema
integer
2
This guide describes schema version 2
id
string
any string
Global, unique ID that identifies this TrainUnit
name_loc
string
any string
ID used to localize name_en
name_en
string
any string
English name of the carriage
category
string
any string
English category name to group cars in the train editor car shop listing. Defaults to the mod name if not present.
description
string
any string
English short description of the car. Please respect the little space available for this in the UI.. Use <br> for line breaks.
tags
tag list
one or more tags
Tags that represent this unit. See the Tags section for more info.
year_introduced
integer
any integer
The year this model was introduced
year_retired
integer
any integer
The year this model was retired
length
meters
1 to 30
Length of the carriage
width
meters
1 to 3.75
Width of the carriage
max_speed
km/h
10 to 10,000
Max allowed speed
max_acceleration
m/s/s
0.1 to 10
Max allowed acceleration. If missing the default value is 1 m/s/s
max_regular_braking
m/s/s
0.1 to 10
Max allowed braking in regular operation, like station stops. If missing the default value is 1 m/s/s
max_emergency_braking
m/s/s
0.1 to 10
Max allowed braking in emergencies. If missing the default value is 2.5 m/s/s
max_tractive_effort
kN
0.0 to 10,000
Max allowed force generated by the engine in the TrainUnit. This value is ignored if power is 0. This value is auto generated if missing and the power is non 0. See formulas for more details.
power
kW
0 to 100,000
See the description in formulas
empty_mass
kg
1,000 to 100,000,000
Empty mass of the carriage
price
"cash"
0 to 1,000,000,000
Price for one carriage unit
max_pax
passengers
0 to 1,000
Max allowed passengers
standing_pax
passengers
0 to 1,000
How many of the max_pax are assumed to be standing. This is an optional value, if unknown or 0, do not declare it.
pax_doors_per_side
integer
0 to 100
How many doors in the TrainUnit for pax to enter or exit, per side. A "door" is defined as space for a single pax to enter/exit, so for example a wide door should add 2 to this number. This is an optional value, if unknown or 0, do not declare it.
allow_player_composition
boolean
true/false (default is false)
Allow the player to use this TrainUnit in their own train compositions.
cost_per_km
"cash"
0 to 1,000
Price to pay for every km
cost_per_km_per_pax
"cash"
0 to 1,000
Price to pay for every passenger in this carriage over 1km
cost_per_day
"cash"
0 to 100,000
Price to pay for running this carriage for 1 day
tex_base
relative path
any valid relative path
Base, colorizable texture
tex_top
relative path
any valid relative path
Top texture
tex_decors
relative path list
a list of valid relative paths
List to decorative colorizable textures
tex_decors_titles
list of strings
a list of decor title strings
List an UI title for each of the colorizable textures. This is optional.
tex_m_width
meters
30
This field must be always 30
tex_m_height
meters
3.75
This field must be always 3.75
recolor_base
boolean
true or false
Allow or disallow the player to recolor the base texture
recolor_decor
boolean
true or false
Allow or disallow the player to recolor the decor texture

front_coupler
string list
one or more coupler names
Front coupler(s) of the car. When front_coupler is not present it assumed to be of type "universal"
front_coupler_mandatory
boolean
true or false
True means this car must be always coupled to another car at the front. Default value is false, making it optional
back_coupler
string list
one or more coupler names
Back coupler(s) of the car. When back_coupler is not present it assumed to be of type "universal"
back_coupler_mandatory
boolean
true or false
True means this car must be always coupled to another car at the back. Default value is false, making it optional
Formulas
power, max_tractive_effort and max_acceleration
The train tractive effort is dynamic and depends on the current speed of the train, and thus a dynamic acceleration ramp. It is a bit sped up compared to real life, but not too much. It's also a simplified linear function compared to the more complex curves of real motors.

// tractive effort is expressed in N // K = tuning constant, currently 0.75 // P = total train power in W // V = speed in m/s tractive effort = min(K * P / V, max_tractive_effort) acceleration = min(tractive effort / current train mass, max_acceleration)

The max_tractive_effort of a train is the sum of all the independent max_tractive_effort of each TrainUnit in the train which have power above 0. If this sum is 0, max_tractive_effort = max_acceleration * empty mass.

The max_acceleration of a train is the minimum of all max_acceleration values of the TrainUnit in the train.

If you are in doubt about the values of max_tractive_effort and max_acceleration, I recommend you don't set max_tractive_effort in your mods, and test values for max_acceleration which look good to you. In case of doubt, do not set any of them, and let the game use its default values.
TrainUnit coupling
Starting with game version 1.7 it is possible for players to purchase and edit custom composed trains, not just those defined in TrainMultipleUnit compositions. TrainUnit(s) defined in mods are automatically made available in the custom train editor, but only if they are explicitly enabled by using the allow_player_composition property. This property defaults to false, so modders must opt-in into this new system if they wish their TrainUnit(s) to be usable in the custom train editor.

To give modders finer control over how their TrainUnits are used, 1.7 introduces the concept of couplers in the train editor. When the player is composing a custom train, the couplers declared in the TrainUnit are checked for compatibility, and the game won't allow to purchase or reconfigure a train if one or more of the couplers between two cars are not compatible.

The properties controlling the set of car couplers are front_coupler and back_coupler. These properties must either not be present, which defaults them to universal, or if present, they must list one or more coupler names, separated by a coma. front_coupler_mandatory and back_coupler_mandatory indicate if a car must always be coupled in the front or back.

universal coupler

The universal coupler is the default coupler. It is able to couple with any other universal coupler and with the predefined couplers.

none coupler

The none coupler does not allow coupling with any kind of coupler, not even to the universal coupler. The none coupler overrides the mandatory flag, always behaving as false.

Predefined couplers

The following couplers are officially proposed for interoperability between mods, to avoid making every car universal. Predefined couplers can couple with themselves and with the universal coupler.

buffer-chain
aar
scharfenberg
sa3
dellner
ward

These are modern coupler or coupler families, some of them quite large, like Scharfenberg or AAR.

Custom couplers

TrainUnits can invent couplers which are only used within a mod or even within a specific train, for example for modelling MU trains with custom coupling not compatible with any other train. These couplers won't couple with the universal coupler.

For example if your mod is the usual mass transit EMU which can couple with other full EMUs, you can do this for the head/tail cars:

front_coupler=scharfenberg
back_coupler=my_custom_proprietary_coupler_123

And do this for the inner cars:
front_coupler=my_custom_proprietary_coupler_123
back_coupler=my_custom_proprietary_coupler_123

But what if you wanted to restrict the coupling to just compositions of the same EMU? head/tail cars:
front_coupler=my_custom_outer_coupler_123
back_coupler=my_custom_inner_coupler_123

Inner cars:
front_coupler=my_custom_inner_coupler_123
back_coupler=my_custom_inner_coupler_123

front_coupling_mandatory documents if it is mandatory to have anything coupled to that side of the car. For the previous example EMU head/tail:
front_coupling_mandatory=false
back_coupling_mandatory=true

And for the inner cars:
front_coupling_mandatory=true
back_coupling_mandatory=true

Suggested properties for mod compatibility

In order to make your cars as compatible as possible with other mods, I suggest you always use universal couplers or predefined couplers, none couplers, and the use of the mandatory flag. Using custom couplers to keep MU compositions from being too crazy is also not too bad for compatibility, since MUs cannot be freely mixed and matched.

TrainMultipleUnit rules
TrainMultipleUnit
A TrainMultipleUnit represents a train model and one or more compositions of said model. It's called "TrainMultipleUnit" but it can represent any kind of train, not just MUs. You must declare at least one TrainMultipleUnit containing at least one composition if you want to add new train models to the game

Field
Type
Range
Description
schema
integer
2
This guide describes schema version 2
id
string
any string
Global, unique ID that identifies this TrainMultipleUnit
name_loc
string
any string
ID used to localize name_en
name_en
string
any string
English name of the train model
tags
tag list
one or more tags
Tags that represent this train model. See the Tags section for more info.
description_loc
string
any string
ID used to localize description_en
description_en
string
any string
English long description of the train model. Use <br> for line breaks.
year_introduced
integer
any integer
The year this model was introduced
year_retired
integer
any integer
The year this model was retired
countries_operated
country code list
one or more country codes
A list of ISO 3166 alpha 2 codes[en.wikipedia.org]
countries_built
country code list
one or more country codes
A list of ISO 3166 alpha 2 codes[en.wikipedia.org]
photo
relative path
any valid relative path
A photo in JPG format of the train model, ideally square, but any ratio is valid. The UI will automatically scale and center the photo without cropping. Please keep this file at a reasonable resolution and size (1000px max on the side and less than 1MB, for example)
default_code
string
any string
Default train code. Use # as a digit placeholder.
default_name
string
any string
Default player train name. Use # as a digit placeholder.
composition
string
a valid composition syntax
A train composition. See the composition section.
Train compositions
In TrainMultipleUnit, it is possible to have one or more composition lines, with this syntax:

composition=translation_id,English name of composition,<unit spec 1>,<unit spec 2>,<unit spec 3>,...

Where a unit spec is defined as either just the TrainUnit ID:

unit_id1

Or a TrainUnit ID followed by a min, default and max number of duplications. 0 is allowed as the min and default number:

unit_id1 min default max

Both of the previous syntaxes can end with the word flip to flip the unit when drawing the train. For example:

composition=test1_compo1_name,Test Train,test1_head,test1_car 1 1 3,test1_head flip

Then, when the player goes to purchase a train and selects a "model" (a TrainMultipleUnit in the ini file), they are shown a listing of all the defined compositions for that TrainMultipleUnit, and the player can select one, then edit the counts of each variable unit.

TrainMultipleUnit compositions ignore all the coupling and authoring rules set in TrainUnit(s), since it is the modder themself who is adding them to the mod. TrainUnit coupling and restrictions only apply to players using the in-game custom train editor.

If you are porting a v1 mod, coming up with a compatible composition line is straightforward. This v1 spec:
head_id=test1_head car_id=test1_car tail_id=test1_head tail_flip=true min_cars=1 max_cars=3

Is equivalent to this v2 composition:
composition=test1_comp1_loc,TestTrain MU Compo 1,test1_head,test1_car1 1 2 3,test1_head flip

When porting a v1 mod to v2 with active users of the v1 mod, it's recommended to make the first composition line an equivalent composition to the old v1 mod, to make features like "clone train" work better with in-game.
Track rules
An example of a track mod can be found in github[github.com].

TrackKind
TrackKind represents a track kind in the track editor picker. It conceptually groups all the variations of a track (layer and mode), and it is the only named item. TrackLayer and TrackMode always reference a TrackKind.

Field
Type
Range
Description
schema
integer
1
This guide describes schema version 1
id
string
any string
Global, unique ID that identifies this TrackKind
name_loc
string
any string
ID used to localize name_en
name_en
string
any string
English name of the track kind
tags
tag list
one or more tags
Tags that represent this track. See the Tags section for more info.

TrackLayer
Track kinds always have 3 layers: viaduct, ground and tunnel. TrackLayer rules store the technical values of the track for those levels. They all have default values. When in doubt, don't set a TrackLayer value, and let the game apply its defaults. The exception is price and speed, which are also the visible values in the track UI, and virtually all mods will want to change.

Field
Type
Range
Description
schema
integer
1
This guide describes schema version 1
track_kind_id
string
any string
Global, unique ID that identifies the TrackKind this TrackLayer belongs to
layer
string
viaduct, ground or tunnel
The layer level to configure
max_speed
real
10 to 600
Max speed of the track in this layer, in km/h
price
real
1,000 to 10,000,000,000
Price per km of track in this layer
angle_speed_factor
real
0.1 to 100 (default is 5.21)
When track has curve, speed is capped at angle_speed_factor*sqrt(radius), with radius in meters
station_price_mul
real
1 to 1,000 (default is 10)
Multiply track price per km of station platform with this factor
depot_price_mul
real
1 to 1,000 (default is 25)
Multiply track price per km of depot with this factor
crossing_price
real
1,000 to 1,000,000,000 (default is 125,000)
Price of automatically inserted road overpasses, when those are relevant for the layer
collides_ways
boolean
true/false (default is true)
For the ground layer, specify the track collides with roads and streets. Tram tracks need this setting set to false. Ignored in the viaduct and tunnel layers.
conflicts_tracks
boolean
true/false (default is false)
Change diamonds into track collision conflicts. Useful for track kinds with no diamond intersections like maglevs. Ignored in infinite levels.

TrackMode
Track layers have one of 6 modes. Modes represent the current state of the track, like built or blueprint. This rules object is purely for storing texture paths, and it is also fully pre-populated with default textures by the game. Modders are encouraged to reuse stock textures as much as possible, either by using the "@stock" syntax described later, or just by not setting the texture fields, as the example mod and the stock tracks do.

Field
Type
Range
Description
schema
integer
1
This guide describes schema version 1
track_kind_id
string
any string
Global, unique ID that identifies the TrackKind this TrackMode belongs to
layer
string
viaduct, ground or tunnel
The layer level this TrackMode belongs to
mode
string
built, built_branch, blueprint, blueprint_branch, built_diamond, blueprint_diamond
The mode being configured by this object
border
string
a valid relative path or a @stock path
Border of the track, painted first. Used to give very visual distinct shape for tunnel and viaduct layers.
base
string
a valid relative path or a @stock path
The base of the track, painted on top of the border. Ballast, concrete bases, etc.
sleepers
string
a valid relative path or a @stock path
The sleepers of the track, painted on top of the base.
rails
string
a valid relative path or a @stock path
The rails of the track, painted on top of the sleepers.
TrackMode textures
All textures for all track modes for all layers have default values, picked to look like the stock "High Speed" track. If you want to customise your mod textures, you are free to do so, but you are also encouraged to make heavy use of those defaults and the stock textures using the @stock syntax. The nr-example-tracks[github.com] mod only adds a single texture, yet it's very visually distincting from the stock track.

When authoring textures, keep in mind the transparent pixels must contain valid color values in order for the texture minification to work correctly. For example, by default GIMP discards color information for transparent pixels, and those are assumed to be black, resulting in ugly rendering of the texture when the game generates mipmaps for it. The reason for this effect is explained here:

https://substance3d.adobe.com/documentation/spdoc/padding-134643719.html

mode=built
layer
border
base
sleepers
rails
viaduct
@stock/viaduct/border.png
@stock/viaduct/base.png
@stock/common/sleepers.png
@stock/common/rails.png
ground
@stock/common/empty.png
@stock/ground/base.png
@stock/common/sleepers.png
@stock/common/rails.png
tunnel
@stock/tunnel/border.png
@stock/tunnel/base.png
@stock/common/sleepers.png
@stock/common/rails.png

mode=built_branch
layer
border
base
sleepers
rails
viaduct
@stock/viaduct/border.png
@stock/viaduct/base.png
@stock/common/sleepers_short.png
@stock/common/rails.png
ground
@stock/common/empty.png
@stock/ground/base.png
@stock/common/sleepers_short.png
@stock/common/rails.png
tunnel
@stock/tunnel/border.png
@stock/tunnel/base.png
@stock/common/sleepers_short.png
@stock/common/rails.png

mode=blueprint
layer
border
base
sleepers
rails
viaduct
@stock/viaduct/border.png
@stock/common/base_bp.png
@stock/common/sleepers_bp.png
@stock/common/rails_bp.png
ground
@stock/common/empty.png
@stock/common/base_bp.png
@stock/common/sleepers_bp.png
@stock/common/rails_bp.png
tunnel
@stock/tunnel/border.png
@stock/tunnel/base_bp.png
@stock/common/sleepers_bp.png
@stock/common/rails_bp.png

mode=blueprint_branch
layer
border
base
sleepers
rails
viaduct
@stock/viaduct/border.png
@stock/common/base_bp.png
@stock/common/sleepers_short_bp.png
@stock/common/rails_bp.png
ground
@stock/common/empty.png
@stock/common/base_bp.png
@stock/common/sleepers_short_bp.png
@stock/common/rails_bp.png
tunnel
@stock/tunnel/border.png
@stock/tunnel/base_bp.png
@stock/common/sleepers_short_bp.png
@stock/common/rails_bp.png

The diamond modes are special and ignore all textures except the base texture. The other textures will be picked from the actual mode of the track.

mode
base
built_diamond
@stock/common/base_diamond.png
blueprint_diamond
@stock/common/base_diamond_bp.png
Building rules
An example of a building mod can be found in github[github.com].

BuildingKind
BuildingKind represents a building kind in the track editor building picker. In-game buildings actually represent parts of buildings, like towers, awnings, roofs, floors, track trenches, etc. A BuildingKind is meant to display one of these parts, using a single texture. The way this texture is mapped into a player provided rectangle can be controlled via some attributes of BuildingKind.

Field
Type
Range
Description
schema
integer
1
This guide describes schema version 1
id
string
any string
Global, unique ID that identifies this BuildingKind
name_loc
string
any string
ID used to localize name_en
name_en
string
any string
English name of the building kind
tags
tag list
one or more tags
Tags that represent this building. See the Tags section for more info.
default_draw_layer
string
base, floor, roof
Correspond to the in-game settings of under, over, and roof. The player can change this value.
recolor
boolean
true/false (default is false)
Allow the player to recolor the texture.
rule_x, rule_y
string
repeat, stretch (default is repeat)
Repeat or stretch the texture along the x or y axis
partial_repeat_x, partial_repeat_y
boolean
true/false (default is true)
If repeat is enabled for a given axis, allow the mapped texture to have a final partial segment. In other words, when set to false, the texture will always be repeated whole, without a final partial segment, with some small stretching
border_x, border_y
integer
0 to 62 (default is 0)
If stretch mode is enable for a given axis, set appart some pixels border of the texture. This border won't be stretched in the given axis. This setting is not compatible with repeat mode.
pixel_m
real
1 to 100
Texture pixels per meter. Default is 25.6 pixels/m
price_m2
real
0 to 100000 (default is 1000)
Price per square meter. Setting this to 0 disables blueprint mode for the building.

default_w
real
0.1 to 1000 (default is 5)
Default building width, in meters
default_h
real
0.1 to 1000 (default is 5)
Default building height, in meters
default_attached_offset_bot
real
-100 to 100 (default is -2.5)
Default building track attachment bottom offset, in meters
default_attached_offset_top
real
-100 to 100 (default is 2.5)
Default building track attachment top offset, in meters
default_color
hex
000000 to ffffff(default is ffffff)
Default building color. Only 6 hex lowercase digits are allowed.
decals
IDs
list of building IDs
Only buildings defined in the same mod are allowed. These buildings will be removed from the building listing and instead offered as a decal choice in the building properties of the built building
tex
string
a valid relative path
The building texture. Only 128x128 PNGs images are allowed. Other formats or sizes might be subjected to forced resizing or replacement with a placeholder texture.
Tags
Concepts for tags

Tags are single word or hyphen separated short text strings that give a single fact of information about a game rules object like TrainUnit or TrackKind. Objects can have zero or more tags, and they can have multiple if it applies. For example an hybrid diesel-electric locomotive can have both the tag "electric" and "diesel". Or versatile train models can have both regional and commuter tags. The game uses tags to make it easier for players to find train models when they have many mods installed.

Tags for TrainUnit and TrainMultipleUnit

TrainMultipleUnit will also automatically inherit all the tags present in its TrainUnits.

Car kinds: coach, baggage, cable-car, end-of-train, railbus, locomotive, tank, tender, generator, brake, autorack, battery, control

Car interior: restaurant, bar, lounge, observation, sleeper, sitting, standing, compartments, open-coach, couchette, kitchen, vending, toilet

Role: metro, commuter, intercity, high-speed, tram, light-rail, regional, long-distance, shuttle, people-mover

Gauge: minimum-gauge, narrow, standard, broad, monorail, maglev, tyres

Power: steam, turbine, diesel, electric

Misc: linear-induction, third-rail, cable, heritage, prototype, fantasy, concept, private, hotel, tilting, mu, push-pull

Tags for TrackKind

Gauge: minimum-gauge, narrow, standard, broad, monorail, maglev, tyres

Misc: catenary, third-rail, cable, prototype, fantasy, concept

Tags for BuildingKind

Moddable buildings are as of v1.4.1 purely cosmetic, so the proposed tags only cover cosmetic concepts. These tags have no gameplay effect whatsoever.

Cosmetic: base, floor, roof, wall, decoration, furniture, technical, lighting, barrier, translucent, glass, metal, concrete, rough, smooth, shiny, worn, brick, pavement, shingle, tile, stone, wood, weathered, herringbone, framed, vaulted, domed, vegetation
Map styles
It is possible to change the way the game renders the OpenStreetMap geometry with map style mods. These mods control the way OSM objects are rendered by matching OSM tags to the OSM objects distributed with the game, and then apply some styles like colors, textures or line thickness.

OSM Tags[wiki.openstreetmap.org] express the purpose, role or usage of an object in the OSM database. There's thousands of tag keys and millions of tag-key combinations. For compression reasons NIMBY Rails only supports a subset of around 60 tag keys, and of those keys, only the top 254 values are stored. Despite this a wide range of combinations are possible and little information is lost for the purposes of the game.

Map inspector
To help learn what data is actually available in the game, you can use the new map inspector tool in the debug panel (key: F11). When enabled this tools allows you to position a small "sample rectangle" which then queries the game OSM database for any objects being touched by said rectangle, and displays a list of them. It is most usable when zoomed since, since when zoomed out it will either display too many objects or when above lod 0, it will display too little, due to the way the game starts discarding objects after a certain zoom level.

Tip: inline editing of colors
Map style mods use CSS color syntax, so if you use VSCode, you can install this plugin[marketplace.visualstudio.com] and enable plain text files (like mod.txt) to show interactive color swatches when it detects CSS color syntax.

Matching operators
Once you have an idea of what you want to mod by using the map inspector and by looking at the default map style mod.txt file, you need to come up with matching operators for these objects. Matching operators are simple combinations of a single level deep of boolean logic operators: or, and, and- and not.

Operators are written in the sections of the mod.txt file in this format
(operator kind) (tag key) = (tag value 1), (tag value 2), ...

or
The or matching operator enables a given rule when the given key has one of the listed values.
For example:
[StyleLine] or highway = primary, primary_link color = #ff00ffff
This will enable all OSM objects tagged highway=primary or highway=primary_link to be displayed as a line, and then use some ugly color to do so. Now imagine you also want to do this to rivers. You could write a second StyleLine rule just for rivers, but since or activates with just one match, you can combine both:
[StyleLine] or highway = primary, primary_link or waterway = river color = #ff00ffff
One or more or matches might fail, but as long as one or is accepted, the rule is accepted (as long as the and and and not operators match too). If at least one or operator is present in a rule, it means at least one or must match, otherwise the rule fails.

and
The and matching operator enables a given rule when the given key has one of the listed values. All and operators in a rule must be true for the rule to be accepted. A common use for this rule is to apply area styles to OSM objects which are usually line features:
[StyleMesh] or highway = pedestrian and area = yes color = #ff00ffff
This would make all closed pedestrian highways a filled area with some ugly color.

and not
The and not matching operator is the same as and, but it only accepts a rule if does not match any of the values in its list. A rule cannot be composed exclusively of and not operators. At least one or or one and operator must be present, otherwise the rule will always fail.
Palette style rules
StyleLandPalette

StyleLandPalette allows to change the color palette used by the map land texture. This is a table of 37 colors, each assigned to an index. Each index has a category of terrain assigned to it. To change one or more palette colors, use a section in your mod.txt file like:

[StyleLandPalette] index 4 = #e5e0d6 index 10 = #aac800 index 18 = #8ca000

For a reference of the meaning of every index, check the default game styles in the file <steamapps install folder>/resources/styles/mod.txt.

StyleLabelDefaults

StyleLabelDefaults allows to change the colors used by the map label text. To change one or more colors, use a section in your mod.txt file like:

[StyleLabelDefaults] region_color_fg = #aa33aaff region_color_bg = #ddddddff main_color_fg = #222222ff main_color_bg = #ddddddff poi_color_fg = #444444ff poi_color_bg = #ddddddff

StyleSpeedPalette

StyleSpeedPalette allows to change the color palette used by the track speed overlay. You must provide a single RGBA PNG file, sized up to 600x1, where each X coordinate point represents a km/h color. Add a StyleSpeedPalette section in your mod.txt file like:

[StyleSpeedPalette] texture = myspeed.png

StylePopulationPalette

StylePopulationPalette allows to change the color palette used by the population. You must provide a single RGBA PNG file, sized up to 2000x1, where each X coordinate represents an amount of people living in a given texture pixel at the game most detailed level (other levels use an extrapolation of this value). Add a StylePopulationPalette section in your mod.txt file like:

[StylePopulationPalette] texture = mypop.png
StyleMesh rules
OSM objects which form one or more closed shapes can be rendered as an area if they match one or more StyleMesh rules.

Field
Type
Range
Description
or, and, and not
match operator
any string
See the previous section on how to write matching operators
display
boolean
true or false
Allows to explicitly disable the display of the matching objects
texture
string
a valid relative path
Texture to use in this rule. 64x64 RGBA PNG files are recommended. Other resolutions will be resized with no guarantee of quality
color
RGBA CSS hex color
#00000000 to #ffffffff(default is #ffffffff)
Color to modulate the texture. If your texture does not need to be modulated you can leave this out
StyleLine rules
OSM objects with more than one node can be rendered as a line if they match one or more StyleLine rules.

The central concept of rendering lines is line thickness. There's two kinds of line thickness: pixel thickness and physical thickness. Pixel thickness is expressed in 1/10 pixel units and directly corresponds to the on-screen pixel thickness of a line (times the UI scaling factor). Physical thickness scales with the zoom level, just like it is done with tracks, and it can scale down to almost 0 if zoomed out enough. This is useful to hide spammy objects like waterways. But if you want to make sure some other objects remain visible, like highway=motorway, you can specify both thickness, and the game will pick whatever results in a thicker line for the current zoom level.

Lines are rendered twice. By giving different thickness values to each render pass, you can achieve border-like effects which fuse together between lines. Refer to the game built-in mod.txt styles for examples of both border and non-border lines.

Field
Type
Range
Description
or, and, and not
match operator
any string
See the previous section on how to write matching operators
display
boolean
true or false
Allows to explicitly disable the display of the matching objects
visual_layer_bias
integer
-5 to 5
Changes the visual OSM layer of the matching object by adding the value to the existing value in the database. This is only for the rendered value. Track vs map collision is not affected by this
pass1_texture
pass2_texture
string
a valid relative path
Texture to use in this rule. Internally stored at 128x64 resolution, but there's no need to match this. If your texture has a different size or ratio, feel free to use it, but it's not recommended to exceed either 128 width or 64 height
pass1_color
pass2_color
RGBA CSS hex color
#00000000 to #ffffffff(default is #ffffffff)
Color to modulate the texture. If your texture does not need to be modulated you can leave this out
pass1_half_stroke_phys_mm
pass2_half_stroke_phys_mm
integer
0 to 16000
Physical half thickness of the line, in millimeters
pass1_half_stroke_px_dec
pass2_half_stroke_px_dec
integer
0 to 120
Half thickness of the line, in 1/10 pixels
Mod structure and development
A mod is just a folder that contains a file named mod.txt. This file is formatted using the simple INI syntax[en.wikipedia.org]. Inside mod.txt you must declare at least one ModMeta section, and then one or more rules sections.

Folder structure
Here's how the structure of folders and files looks like when you are developing a mod in your local PC. If you put your mod in the "mods" folder of your local saved games folder, it will show up in game. In this example you are developing a mod inside the folder "nr-example-train".


The only mandatory file is "mod.txt". You can also create any other folders and files required to organize and bundle textures in your mod.

Example mod.txt

This mod.txt file can be found in the example mod github[github.com].

ModMeta
The ModMeta section gives some general information that is displayed to the user in the game UI.

Field
Type
Range
Description
schema
integer
1
This guide describes schema version 1
name
string
any string
Mod name used in the in-game UI
author
string
any string
Mod author name used in the in-game UI
desc
string
any string
Mod description used in the in-game UI
version
string
any string
Mod version used in the in-game UI

Steamworks uploader
In order to create and upload your mods to Steamworks, you first need to make sure your mod works properly as a local mod, and have it installed as such. So the first step is to develop your mod as a local mod, in your local mods folder as described in the first section of this chapter.

Once your local mod is ready, you can use the Steamworks mod uploader available in the Main Menu, Options dialog.


By default the mod uploader shows a listing of your authored mods already uploaded in Steamworks, and a series of options.
  • New mod: Create a new mod from an existing local mod
  • Update mod: Update the selected Steamworks mod from an existing local mod
  • View mod in workshop: view the selected Steamworks mod in the Steam overlay
  • Manage workshop: view your private Workshop in the Steam overlay
  • Mod development guide: opens a browser with this guide

When you select "New mod" or "Update mod" the mod editor is displayed:


You must fill all the displayed fields before you can create or update an existing Steamworks mod.
  • Title: mod title to display in the Workshop
  • Visibility: decide if you want to make your mod public or not. You can change this option later if you update your mod again
  • Local mod to upload: select an existing, local, valid mod as the contents for this Steamworks mod
  • Icon file: type a path or open a file picker to select an image to display in the Workshop as the mod icon
  • Description: mod description to display in the Workshop
  • Update note: mod change log to display in the Workshop (only for updates)

You may find it easier and more usable to edit the description and update note fields from the Workshop interface than from the uploader interface, after the uploader is done creating or updating your mod.

Textures for trains
Train units are drawn with 3 texture layers: base, decal and top. Every layer is a full RGBA 32bit PNG image of size 1024x128, which always corresponds to a real world size of 30m x 3.75m. Train units can be shorter and narrower than this size, in that case the unit must be aligned to the left of the image for the X axis, and centered in the Y axis. The real size of the train unit is then declared in the TrainUnit section of the mod.txt file (in meters, never in pixels). Use a conversion factor of 34.13 pixels per meter when drawing the textures.

You can store the PNG files in the mod folder with any name, and with any subfolder structure you wish to use, as long as you use correct relative paths to reference them from the mod.txt file.


The base layer is drawn first, and it can be colorized by the user in the train properties editor. For this reason it is recommended to make this layer grayscale. The colorization function is a simple component-wise color multiplication. Use this layer to represent the bulk of the train unit.


The decal layer is drawn on top of the base layer. It is also colorizable by the user, and uses the same multiplication function. It is possible to declare a series of decal layers in the same TrainUnit by separating them with commas. The user will then be capable of choosing one in the train properties editor. Use this layer as a decoration, to give the user more customization options. The user can also colorize this layer with the line colors.


The top layer is drawn on top of the decal layer, and it is not colorizable. Use this layer for final details and for parts of the train that should never be colorized, like windows.
Translation mods
Translation mods are structured in the same way as any other mod: a main mod.txt file which declares generic information about the mod, and then one or more sections declaring which language is being supported, and which dictionary files are to be loaded. Read the "Mod structure and development" section on how to create local mods for development, and how to upload your work to Steamworks.

Source translation
To make a new translation you will need to customize the official Spanish translation[github.com] to your language. This translation is kept up to date with the game, so on new versions you will be able to also track the changes in your own translations. Edit the mod.txt and game.po files as described in the rest of this guide.

mod.txt for translation mods
Make sure to read what is the mod.txt file and its basic ModMeta section as described earlier in this guide. This is a complete example of a mod.txt file for the Spanish translation:

[ModMeta] schema=1 name=Traducción al Español author=Weird and Wry version=1.0.0 [Language] code_iso_639_2=spa name=Español [LanguageDict] code_iso_639_2=spa po=game.po

There are 2 translation specific sections: Language and LanguageDict.

Language section
The language section identifies a language to be displayed in the options drop down in the game Options dialog. If no Language section is provided, the game will never display the option to select a language, even if a LanguageDict and a PO file is present.

Field
Type
Range
Description
code_iso_639_2
string
an ISO 639-2 code
Languages are identified by ISO 632-2 codes
name
string
any string
Native name of the language

Only use ISO 632-2, 3 letter codes to identify languages, do not make up any random code or use the 2 digit codes. You can look up the codes in this page[en.wikipedia.org]. Also always use UTF-8 file encoding, both in mod.txt files and PO files. No other encoding is supported.

LanguageDict section
The LanguageDict section declares a PO file as a translation dictionary for a given language ISO 632-2 code.

Field
Type
Range
Description
code_iso_639_2
string
an ISO 639-2 code
Languages are identified by ISO 632-2 codes
po
string
a relative path
Relative path to a PO file

The PO file
Translation dictionaries are a simple text file that repeatedly lists the strings to translate in the game. Edit PO files with any text editor that supports UTF-8 editing. For every string you will find 3 entries: msgctxt, msgid and msgstr. For example:

msgctxt "host_game" msgid "Host game" msgstr "Hospedar partida"

  • msgctxt: the internal identifier for the string. Do not edit this text. It often gives extra information about the context of the string.
  • msgid: the original english text of the string.
  • msgstr: the translated text of the string. This is the text you have to edit.

Sometimes strings contain arguments, indicated as {}, and your translated text MUST preserve these arguments. For example:

msgctxt "banner_join_friend" msgid "{} wants to join your game." msgstr "{} quiere entrar a tu partida."

You can locate the {} argument anywhere inside your string. Sometimes there's more than one argument, and this is indicated by a series of arguments like {0} and {1}:

msgctxt "banner_prompt_nogame_join_user" msgid "{0} proposes you to join a game hosted by {1}. Do you want to join?" msgstr "{1} hospeda una partida y {0} te propone entrar a jugar. Quieres jugar con ellos?"

Again, if an argument is present in msgid, it MUST also be present in msgstr, but it does not have to be in the same position. Reorder arguments as you see fit for your language. Occasionally you will also come across more complicated arguments like {2:+.2f}. Just locate them in any position you decide, but don't modify the contents. The game will actively reject your translated strings if their arguments don't match, and it may even crash if your translated string is too malformed.

To test your translation in-game, first make a local mod in your Saved Games folder as described earlier in this guide. If it's created properly it will show up in the Languages drop down in the Options dialog, and it can be immediately activated. Keep in mind a few strings are not properly updated when changing languages this way, like tab titles. Restarting the game will fix this.