Note: References to "Simutrans-Experimental" changed to "Simutrans-Extended" 13 February 2017.
This list should now be supplemented by the following lists:
Dat file reference for: Vehicles and Ways (http://forum.simutrans.com/index.php?topic=15174.0)
Dat file reference for: Buildings and Stops (http://forum.simutrans.com/index.php?topic=15222.msg150137#msg150137)
Dat file reference for: Factories and Goods (http://forum.simutrans.com/index.php?topic=15229.0)
Dat file reference for: Signals and Signalboxes (http://forum.simutrans.com/index.php?topic=14848.0)
Last updated: 12th of July 2013 for version 11.0. Note that this version also introduced Nathaneal Nerode's building clustering feature, but, since that also appears in the latest Standard nightlies, this does not appear in this list.
Simutrans-Extended has a number of new features that can only be used fully with a compatible pakset. For those new to Simutrans, a pakset comprises all of the data files, such as the vehicles, roads, trees, buildings, etc.. Paksets are created by taking plain text files with the extension .dat and image files in the .png format, and running them through a console application called Makeobj to create compressed files with the extension .pak, which can then be read by Simutrans. Simutrans-Extended has its own version of Makeobj (see here (http://forum.simutrans.com/index.php?topic=1894.0) for how to get it): for any of the new features to work, the Simutrans-Extended version of Makeobj must be used. However, Simutrans-Extended will work with .pak files created by the standard version of Makeobj, but the settings that work with the new features will all be set to default values (comfort, for example, will always be 100).
The reference documentation for the format specification of the .dat files for all the standard settings can be found here (http://en.wiki.simutrans.com/index.php/Creating_addons) and here (http://simutrans-germany.com/wiki/wiki/tiki-index.php?page=de_doPak&bl=y). This document is intended to be read alongside those documents as an addendum: it contains only the extra information that is specific to Simutrans-Extended. The various settings are listed in the appropriate categories below. Where the category of .dat file is not listed, there are no Simutrans-Extended specific settings.
Because Makeobj ignores any setting that it does not recognise, it is possible to use a single version of any .dat file both for Simutrans-Standard and Simutrans-Extended. Just make the .dat file complete with all the Simutrans-Extended settings, then run it through both the standard Makeobj and the Simutrans-Extended version of Makeobj (with different output file names to avoid confusion or conflict: I suggest adding -ex to the end for all Simutrans-Extended.pak files) to produce a Simutrans-Standard and a Simutrans-Extended version. Note that, while Simutrans-Extended can read any .pak file from Simutrans-Standard, Simutrans-Standard cannot read .pak files compiled with the Extended version of Makeobj.
To see a working example of the sources of a complete pakset with these features implemented, see the Github repository (https://github.com/jamespetts/simutrans-pak128.britain) for Pak128.Britain-Ex.
Some of the settings involve concepts that are unique to Simutrans-Extended. A brief summary is given here for reference.
Way constraints are a way of making sure that only suitable vehicles use particular (usually specialist) ways. For example, way constraints can be used to create underground urban rail networks (such as the London Underground), which have tunnels too small for ordinary trains to fit through, but whose trains can also travel on the same tracks as ordinary trains. They can also be used, for example, to create specific sorts of electrification, so that AC electrified trains cannot run on DC electrified track, and vice versa.
Both vehicles and ways can have way constraints. There are two types of way constraints: permissive and prohibitive. Each pakset can have up to eight of each type of way constraint. A permissive way constraint means that the way permits a vehicle with the matching constraint to use it. For example, a permissive way constraint might be "DC electrification". DC electrified vehicles can only run on DC electrified ways. With a permissive constraint, if the vehicle has it, the way must have it. Permissive way constraints do not stop vehicles without the constraint from using them.
A prohibitive way constraint means that the way prohibits any vehicles that does not have a matching constraint from using them. For example, a prohibitive way constraint might be "tube tunnel". Only tube sized vehicles can fit into tube tunnels. With a prohibitive constraint, if the way has it, the vehicle must have it. Vehicles with prohibitive way constraints are not prohibited from using ways without a matching constraint.
Way constraints are numbered: so a vehicle with prohibitive way constraint 1 in its .dat file would be able to use a way with prohibitive way constraint 1 in its .dat file. Naming of the way constraints is achieved in the translation files. By default, the constraints are called "Permissive X" and "Prohibitive X", where X is a number between and including 0 and 7. The translation file is the [ISO-LANGUAGE].tab file (en.tab for English) for the specific pakset (not the one in the /simutrans/text directory). Here is a brief example:
Tilting trains are designed to lean into corners to enable them to travel more quickly on curved track without causing excessive passenger discomfort. In Simutrans-Extended, any vehicle marked as "tilting" can take corners about 30% faster than other vehicles. However, for realism, the tilting setting should be confined to modern express passenger trains (tilting trains were first invented in the 1970s, but not used in service until the 1980s). Tilting trains are generally more expensive both to purchase and run than non-tilting trains because of the complexity of the tilting mechanism.
In Simutrans-Extended, as well as being replaced by other vehicles, vehicles can be upgraded to other vehicles. The vehicle retains its original identity, but is converted to being of a new type. This is useful to simulate, for example, major refurbishments of vehicles that give them substantially different characteristics, but while still retaining much of the original vehicle. Upgrading is generally cheaper than buying a vehicle new.
To make upgradeable vehicles in the .dat files, the vehciles to which the present vehicle can be upgraded should be specified in the vehicle's .dat file. For example, if a Petts Co. Mark I 'bus can be upgraded to a Petts Co. Mark I-A 'bus or the Petts Co. Mark I-B 'bus, the Mark I's .dat file should specify the Mark I-A and the Mark I-B. A special upgrade price can be specified: this is the price that the player pays to upgrade to that vehicle. So, suppose that the Mark I-A 'bus cost 10,000.00c to buy from new, but it costs only 5,000c to upgrade to it, the upgrade price in the Mark I-B would be specified as 5,000.00.
Some vehicles are only available as upgrades: this is to simulate vehicles that are substantially modified later in life without any examples of the modified type being built from new. Pakset/addon authors should be careful to make sure that there are enough vehicles available to buy new in every era, as players will not necessarily have all of the right type of vehicles to upgrade to vehicles that are available only as upgrades.
For upgrades to work, all the vehicles involved in the upgrade path must be in the same .pak file. So, in the example above, upgrading would not work if the 'buses were in separate petts-mk1.pak and petts-mk1a.pak files - it would only work if all three vehicles were compiled together into a single petts-buses.pak file (the exact name does not matter: the names are given as examples only).
In Simutrans-Extended, it is possible to have a catering vehicle in a convoy. This is a vehicle in which food and drink is served to passengers during their journey, such as a buffet car (http://en.wikipedia.org/wiki/Buffet_car) on a train. Catering vehicles are useful in two ways: firstly, they earn their own revenue stream, and secondly, they increase the comfort level for the whole convoy.
There are five different catering levels, to simulate everything from a trolley service selling canned drinks and packets of crisps to luxury dining freshly cooked on board. The levels are represented by the numbers 1 to 5, 1 being the lowest and 5 being the highest. Specifying a catering level of 0 is equivalent to having no catering at all. If any number higher than 5 is specified, it will be truncated to 5.
The levels have the following meanings:
Level 1: Trolley service (+ 5 comfort)
Level 2: Miniature buffet (cold food only) (+ 10 comfort)
Level 3: Buffet selling hot food (+ 16 comfort)
Level 4: Full cooked meals (possibly including at-seat service) (+ 20 comfort)
Level 5: Pullman-style luxury dining. (+ 25 comfort)
The longer the journey (in time, not distance), the more useful that catering is (this can be calibrated fully in simuconf.tab). On shorter journeys, catering vehicles do not earn any revenue at all (but still contribute towards comfort of the whole convoy, which is itself less important on shorter journeys). As the distances get longer, so does the revenue that can be earned from catering facilities. On shorter journeys, the revenue that can be earned by higher levels is no greater than that which can be earned by lower levels. Only on the longest journeys do the highest levels of catering earn more than those below them.
To calibrate this feature effectively, it should be noted that, in real life, catering vehicles are more expensive to build and much more expensive to run than ordinary vehicles, and have a reduced passenger capacity (a catering vehicle can carry passengers at the same time, but need not do so). Also, when calibrating the comfort levels of longer distance vehicles, remember to take into account the fact that catering ought be added to longer distance journeys, and adjust accordingly. The catering revenue earned by the catering vehicle is based on the number of passengers in the whole convoy, not just the catering vehicle.
Mail vehicles have an equivalent of catering: the travelling post office. There are no different levels for travelling post office vehicles, and comfort is not relevant to mail. Like catering vehicles for passengers, they earn extra revenue for the whole convoy, and are more useful at longer than at shorter journeys (measured in time, not distance).
Tractive effort is a way of fine tuning the physical characteristics and capabilities of powered vehicles. See the Wikipedia article (http://en.wikipedia.org/wiki/Tractive_force) on tractive effort to learn more about this topic. Tractive effort in Simutrans works more or less as it does in real life.
In Simutrans-Extended, braking distances are calculated from physics parameters of the convoys, rather than based on universal values as in Standard. Each vehicle has a brake force value, which can be set in the .dat file for that vehicle, which affects the power applied by that vehicle when the convoy brakes. Other parameters taken into account include the air and rolling resistances, the speed and weight of the convoy.
In Simutrans-Extended, industries can close down when they become obsolete. As an alternative to closing down, however, they can be upgraded to another industry. It is only possible for an industry to be upgraded when the industry that is being upgraded is exactly the same shape and size as that to which it is being upgraded. Before version 9.11, the input and output goods also had to be identical. In future versions, however, there may be fewer such constraints, and upgrades that do not match the constraints can still be specified as upgrades, albeit they will not be used in the present version.
Airport control towers
In Simutrans-Extended, airports must have control towers to work, unless allow_airports_without_control_towers = 1 is set in simuconf.tab. Airport control towers are station extension buildings with a special flag set in their .dat files.
Minimum runway lengths
In Simutrans-Extended, aircraft have a minimum runway length in meters. This will vary in its in game effect based on the meters per tile setting: for example, an aircraft with a minimum runway length of 500m will require 2 tiles of runway at 250 meters per tile, and 4 tiles of runway at 125 meters per tile. The value for the minimum runway length is set in the aircrafts' .dat files.
In Simutrans-Extended, vehicles can have different liveries. Liveries are organised according to livery schemes. Individual liveries within livery schemes are distinguished by introduction date. Players select the livery scheme to apply to the convoy/line, and the appropriate livery is chosen according to the current date. Livery schemes are only available when the current date is later than the earliest livery introduction date in the scheme. The scheme itself has a retirement date, after which the scheme as a whole will no longer be available. Vehicles will retain their existing livery until the livery is changed manually. In future versions, it is anticipated that liveries will change automatically when the vehicle is overhauled (overhauls being a feature that it is planned to introduce in the future).
Livery schemes are set in simuconf.tab. Here is an example of the liveries part of the simuconf.tab for the next version of Pak128.Britain-Ex, which has a few work in progress liveries:
################################### Livery settings ##################################
# These settings define livery schemes for vehicles. Each scheme can have a number
# of liveries, each with their own introduction dates. When a livery scheme is applied,
# the livery of that scheme with the latest introduction date that is not in the
# future will be selected. The livery scheme's retirement date is the date after which
# that livery scheme can no longer be selected and applied. The retirement date is
# optional: with no retirement date specified, the livery does not retire.
# The following example defines two livery schemes (Yellow and Blue), each with two
# liveries (Bright-Yellow and Dark-Yellow and Navy-Blue and Royal-Blue respectively)
# with introduction dates. The default scheme will be the lowest number scheme available.
# livery_scheme = Yellow
# retire_year = 1990
# retire_month = 4
# livery = Bright-Yellow
# intro_year = 1900
# intro_month = 1
# livery = Dark-Yellow
# intro_year = 1950
# intro_month = 5
# livery_scheme = Blue
# livery = Navy-Blue
# intro_year = 1900
# intro_month = 1
# livery = Royal-Blue
# intro_year = 1960
# intro_month = 4
livery_scheme = British-Railways
retire_year = 1986
retire_month = 6
livery = BR-Early
intro_year = 1948
intro_month = 1
livery = BR-Revised
intro_year = 1956
intro_month = 2
livery = BR-Blue
intro_year = 1966
intro_month = 6
livery = BR-Large-Logo
intro_year = 1979
intro_month = 6
Note that liveries can only be defined in a pakset's simuconf.tab. Attempting to define liveries in the general simuconf.tab will have no effect.
In Simutrans-Extended, the revenue for transporting goods and passengers can be made non-constant per unit of distance, to reflect what is and was commonly real world practice of charging x per kilometre for the first n kilometres, then y per kilometre thereafter, or similar.
In Simutrans-Extended, the weight limit for ways other than bridges is based on a vehicle's axle load. This is either the total loaded weight of the vehicle divided by the total number of axles (assumed to be 2 unless otherwise specified), or a fixed number (for use when not all axles bear an even proportion of the load; use the value for the maximum axle weight). The axle load does not fluctuate depending on whether the vehicle is loaded, and thus is more predictable than weight. (Bridges use the total convoy weight divided by the maximum proportion of the convoy that is on the bridge at any one time, which does depend on load).
For a fuller overview of new concepts and game features in Simutrans-Extended, see here (http://forum.simutrans.com/index.php?topic=1959.0).
Bridges, tunnels, way objects and ways
The following additional settings are common to bridges, tunnels and ways (such as roads and track). Note that the "max_weight" parameter is available on ways (but not bridges and tunnels) with the standard version of Makeobj
max_weight: For all ways other than bridges, specifies the maximum axle load in metric tonnes of vehicles which can traverse the way. This setting has no effect on way objects, such as catenary. For bridges, specifies the maximum convoy weight (including load), divided by the maximum proportion of the convoy that can be on the bridge at any given moment, that can traverse the bridge. Default: 4,294,967,295 tonnes
way_constraint_permissive[X]=X: (Where X is a number between 0 and 7 inclusive) Specifies a permissive way constraint affecting the way, by number. Default: no constraints
way_constraint_prohibitive[X]=X (Where X is a number between 0 and 7 inclusive) Specifies a prohibitive way constraint affecting the way, by number. Default: no constraints
Note that the retire_year and retire_month settings are available in standard Makeobj for factories, but have no effect in Simutrans-Standard.
retire_year: the year after which factories of that type are liable to close down. Default: will never close down.
retire_month: the month in the retire_year after which factories of that type are liable to close down. Default: January
electricity_proportion: the proportion of electricity, expressed in percent, that the factory takes relative to its production. 100 is equivalent to the Simutrans-Standard values. This allows different factories to take different amounts of electricity for an equivalent amount of production. Default: 17%
upgrade[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255) A list of the factories to which the current factory might be upgraded when it closes down. Default: blank - factory cannot be upgraded.
is_tilting: Whether this is a tilting vehicle (1=true, 0=false). Default: 0 - not tilting.
way_constraint_permissive[X]=X: (Where X is a number between 0 and 7 inclusive) Specifies a permissive way constraint affecting the vehicle, by number. Default: no constraints
way_constraint_prohibitive[X]=X (Where X is a number between 0 and 7 inclusive) Specifies a prohibitive way constraint affecting the vehicle, by number. Default: no constraints
catering_level: whether this vehicle is a catering vehicle, and, if so, how well equipped that it is. May be any number between 0 and 5, where 0 is a non-catering vehicle, and 1 - 5 are progressively better equipped/more luxurious catering facilities. If catering_level is set to a non-zero number on a mail vehicle, it becomes a travelling post office. Setting catering_level on vehicles other than passenger or mail vehicles has no effect. Default: 0
bidirectional: whether this vehicle can reverse without turning around (not applicable to road or air vehicles): for example, a railway locomotive with a cab at each end, or a railway carriage. This affects the graphics (the vehicle is not flipped when it turns around), and the game-play (makes reversing faster). 0=false, 1=true. Default: 0
can_lead_from_rear: whether this vehicle can lead the convoy when it is at the rear of the convoy. Useful for, for example, multiple unit trains that can travel in each direction without turning around. This affects the graphics (the convoy is not flipped or re-arranged when it turns around), and the game-play (makes reversing much faster). If the rear vehicle has can_lead_from_rear enabled, the "bidirectional" flags of all the other vehicles in the convoy are ignored, and the whole convoy travels backwards without flipping or being re-arranged. 0=false, 1=true. Default: 0
comfort: how comfortable that the vehicle is. May be any number between and including 0 and 255. This is only relevant for passengers - the setting should be 0 for all non-passenger vehicles. Default: 100
overcrowded_capacity: the vehicle's additional capacity when overcrowded. For a 'bus, for example, this would be the standing capacity. Default: 0.
max_loading_time: the minimum/maximum time, in game seconds (measured on the same scale as travelling times) that this vehicle takes to load. The loading time of a convoy is the loading time of the slowest loading vehicle in the convoy. If no passengers/goods board/alight, the loading time is the longest minimum loading time of any vehicle in the convoy. If the maximum possible number of passengers/goods board/alight, the loading time is the longest maximum loading time of any vehicle in the convoy. Between those two points, an intermediate number is interpolated on a linear scale.
loading_time: the time, in real time milliseconds at normal (1.0) speed that this vehicle takes to load. This is deprecated in favour of the min_loading_time and max_loading_time parameters above: compatibility is maintained for legacy paksets only. Using this parameter can cause inconsistent results with different meters_per_tile settings.
upgrade[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255) A list of the vehicles to which the current vehicle can be upgraded. Default: blank - vehicle cannot be upgraded
upgrade_price: the price in Simucents (1/100th of a SimuCredit, the currency used in Simutrans) that it costs to upgrade to this vehicle from any other vehicle. Default: the same as the purchase price of this particular vehicle.
available_only_as_upgrade: whether this vehicle is available only as an upgrade to one or more other vehicles, and cannot be bought new. 0=false, 1=true. Default: 0
fixed_cost: the fixed monthly cost, in Simucents (1/100th of a SimuCredit, the currency used in Simutrans) of maintaining this vehicle irrespective of how far that it has travelled in the month. Default: 0
Note: this feature is now present in Simutrans-Standard. It previously used the keyword "fixed_maintenance" in Simutrans-Experimental, and this is still usable for backwards compatibility.
tractive_effort: the tractive effort (http://en.wikipedia.org/wiki/Tractive_force), in kiloNewtons, of this vehicle. This can be specified either as well as or instead of "power", and the other value will be calculated. Default: (calculated according to a formula from "power").
brake_force: the brake force, in kiloNewtons, of this vehicle. Default: (calculated based on the vehicle's weight). If set to zero, this is an unbraked vehicle.
rolling_resistance:the rolling resistance, in Newtons per Kilogram, of the vehicle. Default (varies depending on the type of vehicle)
Note: this has been substantially recalibrated for version 10.12, released on the 28th of October 2012. All manually specified values will need to be adjusted.
constraint[next]=any: this vehicle cannot be at the rear of a convoy without specifying any particular vehicle that should be behind it. This is an addition to the existing Simutrans-Standard coupling constraint system: this exact syntax must be used to produce the desired effect. Default: any or no vehicle may be attached to the rear of this vehicle (as in Simutrans-Standard).
air_resistance: the level of air resistance generated by this vehicle when moving: used for the physics engine. It is recommended to leave this blank unless the vehicle is properly streamlined (in which case, use the example value below). This value is 100x the value used internally and in most standard physics calculations to allow greater precision: for example, a value of 108 becomes 1.08. Defaults: (varies depending on the type of vehicle)
Note: this has been substantially recalibrated for version 10.12, released on the 28th of October 2012. All manually specified values will need to be adjusted.
increase_maintenance_after_years: the number of years after a vehicle's retirement date that its maintenance costs (both fixed and per kilometre) increase. The default values are set in simuconf.tab.
years_before_maintenance_max_reached: the number of years after the vehicle's maintenance costs start to increase (under the above setting) before they reach their Maximilian level (specified in the below setting). Between these two dates, the maintenance costs are scaled linearly. The default values are set in simuconf.tab.
increase_maintenance_by_percent: the increase over the vehicle's base maintenance level, in percentage terms, that is applied at and after the date specified in the above setting. The default values are set in simuconf.tab.
minimum_runway_length:the length in meters of the shortest runway at which this vehicle (being an aircraft) can land or take off. The distance in meters of a runway is calculated using the meters per tile value applicable to the particular game. Default: 0 (can use any runway).
liverytype[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255) the name of the livery defined in the vehicle's livery slot at X.
The paths to the images for the vehicles must then be matched with the livery index number specified in the liverytype parameter, so, for example, all of the EmptyImage[direction] parameters must be the graphics for the livery "BR-Revised" in the above example.
Liveries can be combined with freight images thus:
where the first number (4 here) is the number of the type of cargo, and the second (0 here) is the livery index.
Here is an example from Pak128.Britain-Ex:
station_capacity: the capacity of the station building. This is an alternative to specifying the capacity using "level". Default: set by "level".
Note: From Standard r6656, and from Experimental 11.6, the keyword "capacity" can be used instead of "station_capacity". If both are set, "capacity" will override "station_capacity". It is intended to deprecate "station_capacity" to bring the keywords in line with Standard.
station_maintenance: the cost in Simucents (1/100th of a SimuCredit, the currency used in Simutrans) per month for the maintenance cost of the station building. This is an alternative to specifying the maintenance cost using "level". Default: set by "level".
Note: From Standard r6656, and from Experimental 11.6, the keyword "maintenance" can be used instead of "station_maintenance". If both are set, "maintenance" will override "station_maintenance". It is intended to deprecate "station_capacity" to bring the keywords in line with Standard.
station_price: the price in Simucents (1/100th of a SimuCredit, the currency used in Simutrans) of purchasing the station building. This is an alternative to specifying the price using "level". Default: set by "level".
Note: From Standard r6656, and from Experimental 11.6, the keyword "cost" can be used instead of "station_price". If both are set, "cost" will override "station_price". It is intended to deprecate "station_price" to bring the keywords in line with Standard.
allow_underground: whether a station or signal may be built underground, overground or both. 0 means that that the station or signal can be built only overground. 1 means that the station or signal can be built only underground. 2 means that the station or signal can be built either underground or overground. Default: 2
Station extension buildings
is_control_tower: whether the building is an airport control tower. If enabled, building this connected to an airport will allow aircraft to use it. Default: 0 (not enabled).
traction_type[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255). A list of the traction types that can be built in this depot. Default: - all traction types can be built. Note that unpowered vehicles can be built in any depot.
value[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255). A list of the revenues per kilometre of each type of goods (including passengers and mail correlating with the to_distance (specified below) of the equivalent value for X. If specified, value[X]= will supersede value=. See the example for to_distance for an example.
to_distance[X]: (Where X is a number in sequence, starting from 0, and being no higher than 255). A specification for each item on the list of revenues of the maximum number of kilometres for which each per kilometre fare specified in value[X]applies. Beyond this distance, the value specified in the next number applies
Notes: In this example, these goods will yield 60c/km for the first 16km, 50c/km for the next 32km, and 47c/km thereafter. Note the value of zero in the final to_distance - a real distance cannot be specified, as there is no value representing what revenue that these goods should produce per kilometre beyond this distance.