Advanced Trains

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Features of a Good Train Pack ======

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
[[usage:trains:start|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.

===== Attachment offset patch data =====

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.

===== Internationalisation and localisations =====

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 [[http://minetest.gitlab.io/minetest/translations/|an API]]
for translations. Client-side translation is preferred in most cases.

===== Animation =====

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//
===== Particles =====

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.

===== Crafting recipes =====

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.

===== Sounds =====

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.

===== Livery and Other Appearance Features =====

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

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 [[https://content.minetest.net/packages/Marnack/advtrains_livery_tools/|AdvTrains Livery
Tools]]

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

====  Visual Loads ====

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.

====  Information displays and markings ====

Visual line number displays is a feature included in [[https://forum.minetest.net/viewtopic.php?f=9&t=27732|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 =====

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.

====  Driver's Seats ====

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.

====  Passenger seats ====

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.


===== Registering in your own namespace =====

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", {

===== Provide access to wagon properties =====
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.

===== Balanced Gameplay =====

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.

====  Speed ====

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.

====  Inventory ====

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.

====  Recoverability and Destruction ====

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.

===== Avant-garde features =====

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.
Advanced Trains

User Tools

Site Tools

Page Tools
