Differences

This shows you the differences between two versions of the page.

--- dev:core:track [2023-05-26 17:26] – created orwell
+++ dev:core:track [2023-05-27 16:07] (current) – revised track definition orwell
@@ Line 3: / Line 3: @@
 //New Track definition format since 2023-05-26 route_prog_rework//
-===== Basics =====
+===== Track node definition (NEW!) =====
+Note: Advtrains supports rotating track nodes via param2, so defining one track node will define all 4 horizontal 90-degree rotations. Rotation is only supported along the vertical axis, param2 must always be within the range [0..3] (this is a restriction of the advtrains nodedb).
 	minetest.register_node(nodename, {
@@ Line 23: / Line 24: @@
 		( [3] = { c=0..15, y=0..1 }, )
 		( [4] = { c=0..15, y=0..1 }, )
+		( ... )
 	}
-	^- Connections of this rail. There can be up to 4 connections.
+	^- Connections of this rail. There are two general cases:
-connections are a normal rail, 3 connections a turnout (1->2 and 2/3->1) and 4 connections a crossing (1<>2 and 3<>4)
+	   a) SIMPLE TRACK - the track has exactly 2 connections, and does not feature a turnout, crossing or other contraption
-	   c is the direction of the connection (0-16) and y is the height of the connection (rail will only connect when this matches)
+	      For simple tracks, except for the at_conns table no further setup needs to be specified. A train entering on conn 1 will go out at conn 2 and vice versa.
+		  A track with only one connection defined is not permitted.
+	   b) COMPOUND TRACK - the track has more than 2 connections
+	      This will be used for turnouts and crossings. Tracks with more than 2 conns MUST define 'at_conn_map'.
+		  Switchable nodes, whose state can be changed (e.g. turnouts) SHOULD define a 'state_map' within the advtrains table.
+		  This differs from the behavior up until 2.4.2, where the conn mapping was fixed.
+	^- Connection definition:
+	   - c is the direction of the connection (0-16). For the mapping to world directions see helpers.lua.
+	   - Connections will be auto-rotated with param2 of the node (horizontal, param2 values 0-3 only)
+	   - y is the height of the connection (rail will only connect when this matches)
+	^- The index of a connection inside the conns table (1, 2, 3, ...) is referred throughout advtrains code as 'connid'
+	^- IMPORTANT: For switchable nodes (any kind of turnout), it is crucial that for all of the node's variants the at_conns table stays the same. See below.
+	at_conn_map = {
+		[1] = 2,
+		[2] = 1,
+		[3] = 1,
+	}
+	^- Connection map of this rail. It specifies when a train enters the track on connid X, on which connid it will leave
+	   This field MUST be specified when the number of connections in at_conns is greater than 2
+	   This field may, and obviously will, vary between nodes for switchable nodes.
 	can_dig=function(pos)
@@ Line 52: / Line 74: @@
 		   Possibly, some actions need not to be taken in this case. Only set if it's the very first node the train is standing on.
 		^- lzbdata should be ignored and nothing should be assigned to it
+		-- Fields of the "Passive Component API", which is used for any components that the interlocking system or LuaATC can switch.
+		getstate = "string" -OR- function(pos, node)
+		^- Provides (or, as a function, returns) the state string of this node. For a turnout, this is the direction the turnout is switched to.
+		   Also non-track nodes can define this (or any of the other following fields) to define states that can be switched from interlocking or LuaATC.
+		^- Conventions for this field are as follows:
+		   - Two-way straight/turn switches: 'st'=straight branch, 'cr'=diverting/turn branch
+		   - 3-way turnouts, Y-turnouts: 'l'=left branch, 's'=straight branch, 'r'=right branch
+		   - Any node that can be turned on and off (e.g. Mesecon switches, Andrews Cross): 'on' and 'off'
+		setstate = function(pos, node, newstate)
+		^- Function to set the node into the specified state given by 'newstate'.
+		   This may happen when interlocking sets a route, or when setstate() is called in LuaATC.
+		   Most commonly, this will just swap the node at pos, but it can perform additional tasks.
+		-- Be aware that above functions will be called even in unloaded areas. Always use the advtrains.ndb API to get and set nodes.
+		state_map = {
+			["st"] = { [1] = 2, [2] = 1, [3] = 1},
+			["cr"] = { [1] = 3, [2] = 1, [3] = 1},
+			["stateName"] = { ...conn_map table... },
+		}
+		^- The state map is required for the interlocking autorouter. For every possible state of the node that can be set with 'setstate',
+		   the state_map contains the appropriate conn map. The following conditions must be satisfied for this system to work:
+		   - The contents of the state_map for each state must be the same as the at_conn_map table of the node after calling setstate() on it
+		   - The state_map, as well as the at_conns table, must be identical for all states of any given track.
 	}
 	})