Note: The term wagon herein is used in the technical sense as AdvTrains and includes locomotives, carriages, wagons, coaches, multiple-units and so on that are individually placed and coupled.

References will be included throughout, but you should browse the wiki's Train catalogue as well to compare what exists.

Mods for AdvTrains are all made for Minetest Game (MTG) at this point, and I will be making references that imply that we are playing MTG throughout. You can of course make mods for other games like Mineclone2, but you will need to establish what materials and so on to use in those games.

The intent of writing this document is to publish it as a helpful guide for train pack creators and to guide the creation of an example mod that implements most of what is discussed, as a kind of template. It is also written to provide goals for AdvTrain Supplemental's existing group of mods as to what may be missing from existing mods.

The attachment offset patch lets the camera rotate freely when inside a wagon rather than orbiting in a large radius around the central point. It's a much more pleasant experience. Attachment offset patch data is provided for each seat inside a wagon.

Providing this data for each wagon is better than relying on the attachment offset patch project to maintain the data out of good will. It also gives the original author the creative control over where to place the camera.

Internationalised train packs can be used in different languages, which helps people who want to enjoy Minetest in their own language. There is usually not a huge number of strings of text to cover in a train pack, and Advtrains provides translations for some strings.

Not all mod authors read and write more than one language. But those that do should try to provide their pack in at least English and another language. Those who are monolingual should still internationalise their software and provide a template to make internationalisation easier for potential contributors.

Minetest provides an API for translations. Client-side translation is preferred in most cases.

While it is not easily possible to animate the wheel rotation on AdvTrains wagons, one can do so with a custom velocity change handler (`custom_on_velocity_change`). This is done in Basic Trains' “Detailed Steam Engine” for the valve gear and wheels.

It is not clear to the author whether AdvTrains supports multi-animation blending such that doors could open while the wheels are rotating - but this is not typical in a modern safe railway environment anyway. No, Minetest does not support this. There can only be one animation active at a time (global) and this animation will affect all bones in the model. I tried this. — orwell 2023-11-09 11:44

Diesel and steam locomotives can usually benefit from smoke or soot particles emitted from exhaust. There may be other creative uses for particles. Using a custom velocity handler can be helpful e.g. to stop smoke particles when the locomotive is halted.

Many people want to play AdvTrains in survival mode, but are limited by the lack of crafting recipes in some train packs. Try to provide unique crafting recipes that don't conflict with other train mods or other common mods. This may be difficult in some cases. It is a popular option for some mods to involve multiple intermediate crafting steps to making a full wagon.

Not everyone plays Minetest with sound, and not all sound design is good design. But a good sound design is very nice indeed. If you are able, try to source sounds from the internet on places like Freesound.org or make your own recordings.

Sounds checklist

• Motor sounds: Usually at least a takeoff and a loop sound.
• Horn sound: Sound of a horn, bell or other warning device.

Sound mastering is very important. Players usually want to be able to hear the trains somewhat, but they don't like very loud ones like the Basic Trains subway is known for. Rather than needing to edit your sound files directly, use the gain property which is provided by Minetest.

Do not use stereo sounds for your wagons, because they will not pan properly according to the wagon's position. Downmix any stereo files to mono.

`custom_on_step` is usually used for sounds, though it can be incorporated in the velocity change handler too. DlxTrains' Diesel Locomotives and the Linetrack Boat are examples of good sound.

The appearance of a wagon covers any part of its total presentation, including its model(s), texture(s) and even possibly sounds.

Appearance can be modified by player customisation, visual load indicators, outwards displays of internal properties such as the outside text and road number, and so on. Different appearances of the same wagon should usually be dynamically selected and *not* crafted and placed as different wagon types, unless you are sure they really *are* different wagon types.

What not to do: Register a “red subway wagon”, “green subway wagon” and so on where the only difference is the colour.

What to do instead: Have the wagon's appearance configurable with a tool like the bike painter/train painter, punching with dyes, airbrush or some tool you add in your mod.

Livery, also known as paint schemes, painting, recolouring and so on, is the customisation of the textures applied to a wagon. Some wagons simply allow you to change the colour of the main body of the train with the bike painter\*, others use more advanced libraries like the AdvTrains Livery Tools

\*pending some better tool from another mod/in the core that replaces the need for the bike mod

Another appearance feature is visual loads. This is when a cargo wagon changes appearance according to what is inside. For instance, the logging wagons from Moretrains (gpcf fork) will dynamically change the texture applied to the visible logs inside of the wagon, or appear empty when the inventory is empty.

Visual line number displays is a feature included in doxy's Minitram along with the Konstal 105N, which is not available as a separate mod yet. This allows a lot of customisation of the outside destination display. It is applied on top of the livery.

DlxTrains' Diesel Locomotives will show their Road Number on the outside of the locomotive. This internal property is meant for railways to track and identify all of their wagons with self-assigned numbers; it is configurable from the wagon properties dialogue when onboard a wagon that you own or from many wagons' inventories.

Seats in AdvTrains belong to groups. Each group can have permissions and default seats. It is possible to switch seat groups while on board a train, provided that the seat group is not fully occupied. However, it is not possible to switch seats within a seat group. The Konstal 105N allows the driver to sit at the front or back and passengers in one of four spots by defining one seat group for each seat. Wagons with only one seat group have no seat selection.

Wagons commonly use dstand and pass as the seat group indices for the driver stand and the passenger area, respectively.

If no seat group is defined, the player can freely choose the seat when getting on. However, this behavior appears to be provided for backward compatibility, as players in such wagons can only get off (i.e. they can not access wagon properties, even in the driver stand, and they can only switch seats by getting off and on)

The assign_to_seat_group defines a list of seat groups. When a player gets on, the player is put into the first seat group in the list that has a free seat and (for driver seats) is accessible to the player. It is common to put the driver stand in front of the passenger area in the assign_to_seat_group table.

The important thing is that you test your wagon to make sure all of the seats are positioned properly. You can do this easily on a PC by running your world running as a server and launching as many copies of Minetest in parallel as there are seats, or less excitingly by providing a way to switch seats while on board :)

When providing data for attachment offset patch, you provide data for each seat.

Thanks to the attachment offset patch, it is easy to provide multiple drivers' seats at the front and rear of small wagons like trams or controls that face both ways inside of a locomotive. This makes for much better driver visibility than the compromise of sitting in the middle of the wagon.

It is typical to provide at least four seats on board a passenger wagon, and often as many as six if there are no driving controls present in a wagon. Do what you think is appropriate according to the wagon's size.

When you go to register a wagon, you should namespace it so it does not conflict with other authors' wagons which might have similar names. If you do not provide a namespace, the wagon will simply start with the “advtrains:” prefix which may conflict.

What not to do:

advtrains.register_wagon("passenger_wagon", {

instead do:

advtrains.register_wagon("my_wagon_mod:passengerwagon", {

AdvTrains wagons have three configurable properties that can apply to any wagon, and which players will want to be able to configure. You should provide them a way to do it.

These properties are:

• Wagon whitelist (“allow these players to access your wagon”) - this allows

players to share inventories of wagons or driving of trains.

• Wagon road number - this is for tracking rolling stock
• Freight codes (FC) - this is used for freight operation, where trains can be

split with LuaATC or (un)loaded with (un)loading tracks based on FC.

For those unaware, formspec is the interface library of Minetest. Saying “the formspec of \<x\>” refers to the menu that opens when it is interacted with, usually by right clicking. For instance there is a formspec for when you are onboard a wagon, and cargo wagons provide their own formspecs when right-clicked.

Thankfully you do not have to provide all of these properties manually, there is an API for opening the wagon properties formspec on a wagon.

Locomotives should make these properties available from the driver's seat Passenger wagons should make these properties available to the owner from any seat. Cargo wagons have historically been the most troublesome with wagon properties, since the wagon properties button isn't automatically added when you can't get onboard them. The cargo wagon's formspec should provide access to its inventory and access to the wagon's properties.

The costs of crafting a wagon should be proportionate to the gameplay benefits it provides. You may even want to provide compromises such as capacity versus speed or recoverability.

AdvTrains uses the nodes/second unit of Minetest's physics, which directly correlates to metres per second, m/s. Hereafter I will simply write m/s.

The conversion rates from metres/second are:

1 m/s = 3.6 km/h 1 m/s = 2.24 mi/h (approximately)

The train driver's HUD always shows the speed in m/s. Wagons define a maximum speed. The maximum speed of a train is the minimum speed of all of its wagons. For example, a locomotive rated for 20 m/s hauling 10 m/s wagons makes a train that is limited to 10 m/s.

Speed follows a few conventions:

• <10 m/s for very old systems like carts and Stephenson's Rocket
• 10 m/s for steam locomotives and wagons
• 15 m/s for metro, subway and tram
• 20 m/s for modern diesel and electric trains, whether locomotive hauled or

heavy rail multiple-unit.

What is more important is if you want to create a sense of progression within a train pack, you should provide speed and inventory upgrades as technology progress.

Going beyond 20 m/s is usually not desirable due issues with the world not being able to load and send over the network fast enough. The train driver's HUD speedometer is also not calibrated to go beyond 20 m/s.

Cargo wagons are usually much lesser in capacity than the equivalent space filled with Minetest Game chests (32 slots). They vary in size from 48 slots in the AdvTrains Freight Train pack, which is limited to 10 m/s, to a 'standard' size of 24 in Basic Trains Steam and down to as low as 4 for the Moretrains carts.

It is possible to include an inventory in a wagon that has driving controls and passenger seats, however that is not usual. It might provide interesting gameplay though.

There are two competing schools of thought about what should happen to an AdvTrains wagon when it is taken off the tracks. The standard approach used by Basic Trains is that the train is scrapped and only some steel (called wrought iron if one is playing with technic) is recovered.

The destruction approach must be carefully balanced to make sure that an increase in material is not achieved. So for instance, if one were to require 3 blocks of steel to make a wagon, it should not drop 4 blocks of steel when destroyed.

The destruction approach incentivises players to store wagons in depots and yards when they are not in use. It encourages more 'realistic' operations. It also means that one cannot truly sell a wagon to another player since AdvTrains has no method of permanent transfer of ownership on a wagon.

The alternative forgiving or 'creative-mode' approach is that wagons will drop themselves, like they are minecarts that can be picked up and placed in the inventory. This makes trains easily tradeable, moveable by players instead of under their own power, and generally a bit more light-hearted.

One can use a mix of approaches inside of a pack, but that requires careful thought about what to make recoverable and destructible. For instance, one can reduce the maximum speed and capacity of recoverable trains. The Diesel Locomotive included with AdvTrains Freight Train is recoverable unlike the Basic Trains locomotives, but is limited to 10/ms instead of 20. This has earned the Diesel Locomotive the nickname of “Shunter”, because it is easier to use for moving wagons but too slow for the mainline which has 20 m/s trains.

To make a train pack stand out, you may want to consider something that hasn't been done yet and implement it, or at least which innovates greatly over what has come before.

Features of the JPN TLR600 tram are non-illuminating simulated headlights and interior cabin illumination during in-game night hours. This combination is not present in other mods and I can't say how good or bad it is yet, but I can definitely say it sticks out.

The diesel locomotives from the DlxTrains mod pack also features dynamic non-illuminating simulated exterior lighting although the effect is much more subtle than the JPN TLR600 tram and is based on the locomotive's movement rather than in-game time of day. These lights are off when the locomotive is stationary and turned on while moving. Also, they are activated appropriately for their direction of travel based on the era and regional regulations of their real world prototypes. The European G1206 diesel locomotive, for example, has white lights turned on in the forward direction of movement and red lights in the rearward direction regardless of the locomotive's orientation while the North American SW1500 diesel locomotive has white lights turned on in both directions whenever moving.