Note: due to Advtrains issues, the current version of this mod has the following flaw: displays are not saved across restarts.

Advtrains Info Displays

IMPORTANT: you will need Advtrains version 2.4.4 or higher, or this mod will not work!

Advtrains Info Displays is an API that allows Advtrains trains (and other vehicles) to display still text, scroling text, and images on displays (inside or outside the train). It also provides LuaATC functions and a tool to interact with the displays.

Technical overview

Each display on a wagon is associated to a certain "display slot", and will display the contents of that display slot. Trains can have several display slots; each of them is independent from the others, and their contents are shared between all the wagons of the train. Each display slot has a name - e.g, "side", "line"... - by which it is referred. See the Conventions section for more details on slot names.

Let us call a "display item" something that can be displayed on a display; it can be still text, scrolling text, or and image.

A display slot can contain any amount of (display) items; it will cycle through them, i.e if it has the two items "Line 2" and "Chasm of Segfault", then it will display "Line 2", then "Chasm of Segfault", then "Line 2", etc. It is possible to specify the duration each item should be displayed.

Conventions

This section specifies naming conventions for advtrains_info_displays slots.

Private display slot names - Any slots on a wagon that are intended for so-called "private use" should have an underscore and the name of the wagon before their name, in order to avoid naming collisions.

Standard display slot names - The following slots' primary uses are listed in the following table:

Defaults - The following slots are provided with global defaults:

LuaATC additions

Advtrains Info Displays will attempt to register new LuaATC functions to allow LuaATCs to interact with a train's display slots. (Advtrains provides such a mechanism for versions 2.4.4 onwards.) However, the contents of display slots will not be preserved across reloads. (See the Known caveats section for more details.)

The available new functions in the LuaATC system are:

set_info_display(train_id, name, contents)
    > name: the name of the display. Any string is accepted, but the wagons may
      not have displays configured to display the contents of that display slot.
      (See the wagon's mod for details on what display slots the wagon displays.)
    > contents: either a table of strings, or a single string. If it is a single
      string, it is splitted on newlines, *including the last newline(s)*.
Sets the contents of the info display with the specified name, on the train with
the specified train_id, to (a) the contents of the table, or (b) the string
(depending of the nature of the contents argument), creating one display item
per (resp.) element of the table / line of the string.

Note that if `contents` is nil, then the display is erased and its default (if
any) is displayed, whereas if `contents` is an empty string, an empty table,
etc., the default for the slot will not be displayed (even if it exists).

A get_info_display() function is in the works. It will return a table of display items.

Display item syntax

Display items are strings which specify what should be displayed. The simplest kind of display item is simply some still text to be displayed. For example, Line 2 will display "Line 2", and Chasm of Segfault will display "Chasm of Segfault". If a display slot ahs several display items, then each item will be displayed for the default duration (3 seconds).

It is possible to specify the duration of a display item by prepending a prefix to it. The prefix consists of a number (the duration of the item, in seconds) followed by a semicolon (";"). For example, 5;Chasm of Segfault will display "Chasm of Segfault" for 5 seconds.

It is also possible to display something else than still text; this can be specified by prepending a letter to the prefix. The available letters are:

• S: scrolling text. The text following the prefix will be scrolled on the display, from right to left. The scrolling will end after the duration of this display item; for example, S5;Chasm of Segfault will scroll "Chasm of segfault" on the display; after 5 seconds have elapsed the display will switch to the next display item.
• I: image. The text following the prefix will not be rendered as text, but interpreted as a Minetest texture string. The texture may be of any dimensions. For example, I2;subway_map_line_2.png will display the image named "subway_map_line_2.png" on the display for 2 seconds. Since it is a raw texture string, it is possible to use [fill, [combine and friends.

Note that you must add a prefix if you want to prepend a letter. Note that you also can not mix letters together: for example, IS5:banner.png will not scroll the image on the display.

Slot defaults

It is possible to specify defaults for slots, i.e things that will be displayed on any displays associated with that slot when the slot has nothing particular to display (e.g after a set_info_display(id, "line", nil)). Note that it is possible to prevent displaying a default by making the slot display e.g an empty string or an empty table (e.g set_info_display(id, "line", "")).

A default is either a string, which will be displayed as still text, or a function, which will be called, passing it the wagon table and the train table as arguments; its return value value will be displayed as still text. Defaults are applied wagon-wise, so it is possible e.g to have a slot display the wagon's ID by default.

There are two kinds of defaults: global defaults and wagon-kind-specific defaults. See the Conventions section for naming information.

Global defaults

These defaults apply to all wagons. They are registered using the register_default() function.

Wagon-kind-specific defaults

These defaults only apply to wagons of a certain kind, e.g dvtrains:subway_wagons. They are passed as a table as the fourth argument to set_textures().

Display inspection tool

Simply punch a wagon with the tool and a formspec will open, which allows you to change the contents of the display slots of the train to which the wagon belongs. Built-in help is provided, although maybe it is not very clear.

API

See README.

Known caveats

• Advtrains does not save all train data when saving files; thus the display slots will not be saved across restarts. There is currently no way to specify more train fields to be saved.
• (fixed in 2.4.4) Advtrains does not currently provide a mechanism to register custom LuaATC functions.