====== LuaATC Environments ======

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

Creating environments is done through a chat command:

<code>
/env_create <name of environment>
</code>

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.

===== Global Variables =====

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.

==== Global value storage: S ====
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''.

==== Global Function and Preset Values: F ====
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.

==== Examples ====
<code lua>
--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

</code>

===== Initialization Code =====

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:

<code>
/env_setup <name of environment>
</code>

{{usage:nodes:formspec-edit-env.png?300}}

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 [[usage:atlatc:passive#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.

===== Errors and ''print()'' messages =====

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.