advtrains organizes LuaATC components into so-called environments. An environment represents a single automation system that has own global variables and function definitions. Components from different environments can only communicate with each other through interrupt_pos().

This concept allows different automation systems to coexist without interfering with each other.

Every LuaATC component is assigned to exactly one environment. Thus, to use LuaATC components in a world, you are required to create at least one environment.

Creating environments is done through a chat command:

/env_create <name of environment>

You should choose a name that consists only of letters, numbers and/or the underscore character.

Once created, components can be set up by selecting this environment from the dropdown in the formspec, and Initialization Code can be specified.

There are 3 types of variable scopes in LuaATC applications:

• Variables declared using the local keyword are temporary. Their values are only preserved during this single run of the component code.
• Variables accessed without any qualifier, being “global” in Lua sense, are local to the LuaATC component from which they are used. Every component can declare independent component-local variables. All component-local variables that are not of type function are saved across game restarts.
• The S and F variables are environment-global tables. Values stored in these tables are shared between all components of the current environment.

The S table serves as persistent global value storage. Any data saved in this table is preserved across game restarts, as long as it is not of type function.

The contents of the F table are not persistent. They are reset when the game is restarted.

The F table is supposed to be populated by the Initialization Code, and hold:

• Function definitions of functions that can be used from components.
• Global preset values, such as lookup tables for station names.

--Initialization Code:
F.abcd = "ABCD"
function F.print_me(str)
  print("Test: ".. (str or "nil") )
end
 
--Component A
local foo
if event.train then
  foo = "Foo"
  bar = "Bar"
  S.baz = "Baz"
  interrupt(1,"")
elseif event.int then
  F.print_me(foo)
  F.print_me(bar)
  F.print_me(S.baz)
end
-- This will print:
-- Test: nil
-- Test: Bar
-- Test: Baz
 
--Component B
F.print_me(bar)
F.print_me(S.baz)
F.print_me(F.abcd)
-- This will print:
-- Test: nil
-- Test: Baz
-- Test: abcd

The initialization code is code that is run at every game startup. Because functions can not be saved to disk, this code is used to set up commonly used function definitions for an environment, and populate the F table.

The initialization code editor can be summoned by the chat command:

/env_setup <name of environment>

The buttons on the top row can be used to save the changes, re-run the init code and to delete the environment. The text field on the top-right can be used to copy-paste the position that was last punched by you. (with the introduction of Passive Component Naming, this facility had become obsolete)

Whenever you made changes to the init code, it is desirable to re-run it. Note that re-running the init code clears the F table first.

Until version 2.3.0, any errors or print() outputs were printed to all players in the server chat. This has changed to reduce chat spam on public servers. Players have to explicitly subscribe to the environments they are interested in. To do this, the following commands are used:

• /env_subscribe <env_name>, /env_unsubscribe <env_name>: Subscribe or unsubscribe from log/error messages originating from this environment

• /env_subscriptions [env_name]: With no arguments, lists the environments you have subscribed to. Given an env name, lists the players that have subscribed to this environment.

When creating an environment using /env_create, you are automatically subscribed to it.