The Map.lua file defines all runtime logic for a map in SubwaySim 2.

It is responsible for:

• registering the map in the ContentManager
• linking the Unreal Engine level to the map
• defining stations and platforms
• defining AI timetables and services
• configuring dispatching and depot logic
• providing optional career mode data

This page explains the structure and purpose of the Map.lua file and how it interacts with elements placed in the Unreal Editor (tracks, signals, Station Definitions).

The Map.lua acts as the central configuration and logic file for a map.

While the Unreal level defines the physical layout (tracks, stations, signals), the Map.lua defines the operational behavior:

• where trains may spawn
• how they route through the map
• which stations exist and how they are used
• when and how AI services operate

Without a Map.lua, a map:

• cannot be selected in the menu
• cannot spawn AI trains
• cannot provide station-based logic

Before working with the Map.lua, make sure that the following steps are completed:

• The Unreal level (.umap) is finished

→ Create a Level

• Tracks and signals are correctly placed

→ Railtool

• BP_StationDefinition actors exist for all stations and depots

→ Prepare a Map for SubwaySim

• Platform numbers, platform lengths, and platform directions are finalized

(these values are referenced directly by the Map.lua and must not change later)

The Map.lua relies on these elements being set up correctly and consistently in the level.

This page explains the structure of a Map.lua file for SubwaySim 2. It follows the file from top to bottom and explains each section in detail.

The Map.lua consists of two major parts:

• Map Registration (ContentManager DataTable)
• Runtime Map Logic (Lua class based on BaseMap)

--
--
-- SubwaySim2
-- Module TestMap.lua
--
-- Map file for SDK TestMap
--
--
-- Author:	SDK User
-- Date:	__/__/____
--
---@class TestMap : TestMap, BaseMap
TestMap = Class("TestMap", TestMap, BaseMap);
 
---@type SSB_Map_DataTable
local TestMap_DataTable = {
	contentType		= "map",
	contentName		= "TestMap",
	class			= TestMap,
	levelName		= "Testmap",
	author			= "$GameDeveloper",
 
	title			= "SDK TestMap",
	subtitle		= "This could be your text",
	description		= "This is a test map that demonstrates how to use the Modding SDK. You can also use it for testing your own vehicles.",
	previewFilename = "/SubwaySim2_Core/UI/MainMenu/Backgrounds/CityBerlin.CityBerlin",
};
g_contentManager:addContent(TestMap_DataTable);
 
--- Creates a new instance of this class
---@return TestMap
function TestMap:new()
	self = TestMap:emptyNew();
 
	self.levelName		= "Testmap";
	self.displayName	= "SDK TestMap";
 
	-- latitude and longitude of Berlin's city center
	self.latitude		= 52.518611;
	self.longitude		= 13.408333;
	-- UTC+1
	self.timezone		= 1;
 
	self:loadStations();
	self:loadTimetables();
	self:loadCareerMode();
 
	EventManager.callModListeners("onMapCreated", self);
 
	return self;
end;
 
--- Event to load any additionally required level instances
function TestMap:loadLevelInstances()
	assert(GameplayStatics.loadLevelInstance("SubwaySim2_Environment", Vector3.zero, Vector3.zero), "Failed to load a part of the level");
end;
 
--- Loads the station definitions for this map
function TestMap:loadStations()
	---@type table<string, Station>
	self.stations = {}
 
	self.stations.TS = Station:new("TS", "TestStation")
		:addSpawnPlatform("1", 115, 2)
		:addSpawnPlatform("2", 115, 2)
 
	self.stations.TSD = Station:new("TSD", "TestStation Depot")
 
	self.stations.TSA = Station:new("TSA", "TestStation Anfang")
		:addSpawnPlatform("1", 110, 1)
		:addSpawnPlatform("2", 110, 1)
 
	self.stations.DP = Station:new("DP", "Depot")
		:addSpawnPlatform("51", 220, 2)
		:addSpawnPlatform("52", 220, 2)
		:addSpawnPlatform("53", 220, 2)
		:addSpawnPlatform("54", 220, 2)
		:addSpawnPlatform("60", 110, 2)
 
end
 
--- Loads the default timetables for this map
function TestMap:loadTimetables()
 
	---@type Timetable[]
	self.timetables = {};
 
	-- Direction 1 (TS -> TSA)
	self.TestLine_Dir1 = Timetable:new("U1", 0)
		:addTrainComposition("Berlin_HK_1x", 0.5)
		:addTrainComposition("Berlin_HK_2x")
		:addTrainComposition("Berlin_A3L92_1x", 0)
		:addTrainComposition("Berlin_A3L92_2x", 0)
		:addTrainComposition("Berlin_A3L92_3x", 0.5)
		:addTrainComposition("Berlin_A3L92_4x")
		:addStop({
			station = self.stations.TS,
			platform = 2,
			departure = 0,
			speedLimit = 70,
			routeSettingMaxETA = 0.5, -- Fahrstraße stellt sich erst 0.5 Minuten vor Abfahrt
		})
		:addStop({
			station = self.stations.TSD,
			platform = 2,
			departure = 0,
			speedLimit = 70,
		})
		:addStop({
			station = self.stations.TSA,
			platform = 1,
			departure = 0,
			speedLimit = 70,
			altPlatform = { "2",},
		})
 
	-- Direction 2 (TSA -> TS)
	self.TestLine_Dir2 = Timetable:new("U1", 0)
		:addTrainComposition("Berlin_HK_1x", 0.5)
		:addTrainComposition("Berlin_HK_2x")
		:addTrainComposition("Berlin_A3L92_1x", 0)
		:addTrainComposition("Berlin_A3L92_2x", 0)
		:addTrainComposition("Berlin_A3L92_3x", 0.5)
		:addTrainComposition("Berlin_A3L92_4x")
		:addStop({
			station = self.stations.TSA,
			platform = 1,
			departure = 0,
			speedLimit = 70,
			routeSettingMaxETA = 0.5, -- Fahrstraße stellt sich erst 0.5 Minuten vor Abfahrt
		})
		:addStop({
			station = self.stations.TSD,
			platform = 1,
			departure = 0,
			speedLimit = 70,
		})
		:addStop({
			station = self.stations.TS,
			platform = 2,
			departure = 0,
			speedLimit = 70,
			altPlatform = { "1",},
		})
 
	-- List of templates by line, then by direction
	---@type Timetable[][]
	self.templatesByLine = {
		[1] = {
			[1] = self.TestLine_Dir1,
			[2] = self.TestLine_Dir2,
		},
	};
 
	---@type table<1|2, Timetable[]>
	self.templatesByDirection = {
		[1] = {
			self.TestLine_Dir1,
		},
		[2] = {
			self.TestLine_Dir2,
		},
	};
 
	local DM = DayMask;
 
	-- Repeating interval example
	TableUtil.insertList(self.timetables, self.TestLine_Dir1:clone(daytime(04, 30)):repeatUntil(daytime(23, 30), 10));
	TableUtil.insertList(self.timetables, self.TestLine_Dir2:clone(daytime(04, 35)):repeatUntil(daytime(23, 35), 10));
 
	---@type table<string, Depot_DepotSpace[]>
	self.depots = {
	};
 
	---@type table<Station, ControlCenter_DispatchingStrategy[]>
	self.dispatchingStrategies = {
 
		-- Turnaround logic at TS
 		[self.stations.TS] = {
			{
				sourceStation = self.stations.TS,
				targetStation = self.stations.TS,
				sourcePlatforms = { "1", "2" },
				targetPlatforms = { "1", "2" },
				replaceFirstPlatform = true,
				keepLine = false,
				minLayover = 4,
			}, 
		},
 
		-- Turnaround logic at TSA
		[self.stations.TSA] = {
			{
				sourceStation = self.stations.TSA,
				targetStation = self.stations.TSA,
				sourcePlatforms = { "1", "2" },
				targetPlatforms = { "1", "2" },
				replaceFirstPlatform = true,
				keepLine = false,
				minLayover = 4,
			}, 
		},
	};
end;
 
--- Initializes data for career mode
function TestMap:loadCareerMode()
end;
 
--- Registers all valid timetables to the given `controlCenter` instance
---@param controlCenter ControlCenter
function TestMap:registerTimetables(controlCenter)
	controlCenter:setStationList(self.stations);
	controlCenter:setTimetableList(self.timetables, self.dispatchingStrategies, self.depots);
end;

The DataTable registers the map in the ContentManager. Without it the map will not appear in the map selection menu and cannot be loaded.

After the table is defined, it must be registered:

g_contentManager:addContent(TestMap_DataTable);

If this call is missing, the map is not registered and will never load.

The runtime class is responsible for everything that happens when the map is loaded:

• defining stations and their platforms
• defining timetables and AI services
• configuring dispatching / turnaround rules
• optional career mode setup

TestMap = Class("TestMap", TestMap, BaseMap);

This creates a new map class inheriting from `BaseMap`.

The constructor creates the map instance and prepares the runtime data.

The order matters:

• `loadStations()` must run first (timetables reference stations)
• `loadTimetables()` uses station references
• `loadCareerMode()` is optional

EventManager.callModListeners("onMapCreated", self);

This allows other mods or systems to react when the map instance is created.

GameplayStatics.loadLevelInstance("SubwaySim2_Environment", Vector3.zero, Vector3.zero)

This call loads the shared environment level used by SubwaySim 2.

It provides:

• weather effects (e.g. rain)
• global lighting
• time-of-day behavior

By loading this prepared level, mod maps can use the full weather and lighting system without accessing license-protected core code.

The environment level is loaded in addition to the map level and runs alongside it.

⚠️ Current limitation: Loading multiple levels that contain Railtool Blueprints can cause issues. At the moment, only one loaded level should contain Railtool infrastructure. This limitation will be resolved in future updates.

Stations defined in `loadStations()` must match BP_StationDefinition actors placed in the Unreal Editor.

The connection is made via the station short name:

• In Unreal: BP_StationDefinition → Name Short
• In Lua: `Station:new(“TS”, “TestStation”)`

If the short name does not match exactly:

• stations may not register correctly
• AI routing can fail
• timetable stops may not resolve

Stations are stored as a keyed table:

---@type table<string, Station>
self.stations = {}

The key is usually identical to the short name:

• `self.stations.TS`
• `self.stations.TSA`
• `self.stations.DP`

Creating a station:

Station:new("TS", "TestStation")

Spawn platforms define where trains may spawn for player spawning (depending on map setup)

Example:

:addSpawnPlatform("1", 115, 2)

⚠️ Important Platform numbers are not “free”. They must match exactly the platform configuration inside BP_StationDefinition.

The depot station `DP` uses multiple platform numbers:

• 51–54
• 60

This is a common pattern to represent multiple depot tracks.

Timetables define:

• which trains spawn (compositions)
• what route they drive (stops)
• on which platforms they stop
• how often services repeat

A timetable template is created with:

Timetable:new("U1", 0)

Templates are usually created per direction:

• Direction 1: TS → TSA
• Direction 2: TSA → TS

Train compositions define which vehicle sets may be used when this timetable spawns AI trains.

Each composition is referenced by its `contentName`, exactly as it is registered in the ContentManager (e.g. in `Vehicle.lua` or `Composition.lua`).

Example:

contentName = "Berlin_HK_2x"

The name must match exactly. If a composition is not registered or the name is incorrect, no train will spawn for it.

Compositions are added directly to the timetable template:

:addTrainComposition("Berlin_HK_2x")

A weight can optionally be provided:

:addTrainComposition("Berlin_HK_1x", 0.5)

If no weight is specified, a default weight of `1.0` is assumed.

Weights control how likely a composition is selected relative to other compositions within the same timetable.

They only affect AI spawning behavior for this timetable.

A weight of `0.0` prevents the composition from being selected when AI trains are spawned by this timetable.

The composition itself remains a valid registered vehicle and may still:

• exist in the content system
• appear in the vehicle selection menu

This behavior is intentional and allows a composition to be:

• available to the player
• but excluded from AI traffic on a specific line or timetable

Stops define the actual route of a timetable. Each stop is a table passed into `addStop({ … })`.

Example:

:addStop({
	station = self.stations.TS,
	platform = 2,
	departure = 0,
	speedLimit = 70,
	routeSettingMaxETA = 0.5,
})

Example:

altPlatform = { "2", }

⚠️ Use string values (`“1”`, `“2”`) because platform identifiers are typically handled as strings in routing/dispatch contexts.

This allows AI to select another platform if:

• the preferred platform is blocked
• dispatching assigns an alternative

Example:

routeSettingMaxETA = 0.5

Meaning:

• the route will be requested/updated roughly 0.5 minutes before departure

This can help avoid early route locking and improves traffic handling at busy stations.

A timetable template does not spawn trains by itself. It must be cloned into real timetable entries and inserted into `self.timetables`.

For day-based schedules, use `DayMask`:

local DM = DayMask;

The typical workflow is:

• Create a timetable template (e.g. `self.TestLine_Dir1`)
• Clone it for a start time (optionally with a day mask)
• Either insert a single trip, or generate a repeating service

This creates a repeating service between two times:

TableUtil.insertList(
	self.timetables,
	self.TestLine_Dir1:clone(daytime(04, 30), DM.Weekdays):repeatUntil(daytime(23, 30), 10)
);
 
TableUtil.insertList(
	self.timetables,
	self.TestLine_Dir2:clone(daytime(04, 35), DM.Weekdays):repeatUntil(daytime(23, 35), 10)
);

Result:

• a full service pattern is generated automatically

If you want to schedule individual trips (first/last train, gaps, special runs), insert a single cloned entry:

table.insert(self.timetables, self.TestLine_Dir1:clone(daytime(12, 07), DM.Weekdays));
table.insert(self.timetables, self.TestLine_Dir2:clone(daytime(12, 12), DM.Weekdays));

This creates exactly one departure at the given time.

Use this approach when you need full control over:

• exact departure times
• exceptions or gaps
• different patterns on different days

The following patterns are commonly used when building more advanced schedules. They are shown here using the TestMap stations (`TS`, `TSD`, `TSA`, `DP`).

Sometimes a service should start later or terminate earlier than the full route. This is useful for:

• depot in/out runs
• special services
• partial line operations

Example: terminate at `TSD` (short turn / depot related movement):

local TS_to_TSD = self.TestLine_Dir1:clone(0, nil, true):terminateAtStation("TSD", true);
 
table.insert(self.timetables, TS_to_TSD:clone(daytime(05, 10), DM.Weekdays));

Example: start at `TSD` (depot insertion into service):

local TSD_to_TSA = self.TestLine_Dir1:clone(0, nil, true):startAtStation("TSD", true);
 
table.insert(self.timetables, TSD_to_TSA:clone(daytime(05, 20), DM.Weekdays));

If you want to use the same template but spawn on a different platform, you can override platform numbers after cloning.

Example: force first stop to use platform 1 instead of 2 at TS:

local TS_Platform1 = self.TestLine_Dir1:clone(0, nil, true);
TS_Platform1:getFirstStop().platform = 1;
 
table.insert(self.timetables, TS_Platform1:clone(daytime(06, 00), DM.Weekdays));

This is useful if:

• multiple platforms exist
• you want different patterns at different times of day
• you temporarily reroute services during testing

A service run is a trip that should not be treated as a normal passenger service.

Example: a depot-related move to TS marked as service run:

local DP_to_TS_SR = self.TestLine_Dir2:clone(0, nil, true)
	:startAtStation("DP", true)
	:terminateAtStation("TS", true)
	:setIsServiceRun(true);
 
table.insert(self.timetables, DP_to_TS_SR:clone(daytime(04, 10), DM.Weekdays));

If you modify stop properties (platforms, PIS text, flags), it can be helpful to ensure the stop list is unique:

local Variant = self.TestLine_Dir1:clone(0, nil, true);
Variant:forceUniqueStopList();

This prevents accidental shared stop references when creating multiple variants.

This section defines:

• depot storage spaces (optional)
• turnaround / dispatch behavior at stations

Depots define where AI trains are allowed to park when they are not in service. They are also used by the ControlCenter for dispatching and (later) career mode.

In the TestMap, the depot station is:

• `DP` (Depot)

And it provides these depot tracks:

• 51, 52, 53, 54 (long depot tracks)
• 60 (short depot / test track)

`self.depots` is a table that groups depot tracks into named blocks (groups). Each group contains a list of `Depot_DepotSpace` entries.

---@type table<string, Depot_DepotSpace[]>
self.depots = {
 
	-- Main depot area (long tracks)
	["DP_51_54"] = {
		{ station = self.stations.DP, platform = "51", direction = 2, noParkingTimetable = false },
		{ station = self.stations.DP, platform = "52", direction = 2, noParkingTimetable = false },
		{ station = self.stations.DP, platform = "53", direction = 2, noParkingTimetable = false },
		{ station = self.stations.DP, platform = "54", direction = 2, noParkingTimetable = false },
	},
 
	-- Short depot / test track (useful to keep free or for special moves)
	["DP_60"] = {
		{ station = self.stations.DP, platform = "60", direction = 2, noParkingTimetable = true },
	},
};

Notes:

• The group keys (`“DP_51_54”`, `“DP_60”`) are just identifiers for readability.
• `platform` must match the platform numbers inside your BP_StationDefinition for DP.
• Use `noParkingTimetable = true` if you want to keep a track free (e.g. for turnarounds or testing).

Dispatching Strategies define how trains are handled outside of normal passenger service. They are used to:

• turn trains around at terminal stations,
• spawn trains from depots,
• send trains back to depots,
• resolve platform conflicts,
• and keep traffic flowing when timetables alone are not sufficient.

Dispatching is handled by the ControlCenter and works in addition to normal timetables.

Dispatching strategies are defined as a table, grouped by station:

---@type table<Station, ControlCenter_DispatchingStrategy[]>
self.dispatchingStrategies = {
    [self.stations.WA] = {
        -- strategies for this station
    },
}

Each station can have multiple strategies. They are evaluated top to bottom, so order matters.

Dispatching strategies are evaluated when:

• a timetable ends at a station,
• a train needs to turn around,
• no suitable train is available for a departure,
• or a train must be moved to or from a depot.

If no strategy matches, the train will remain idle.

Each dispatching strategy can define the following fields:

Not all fields are required for every strategy.

This is the most common case: A train arrives at a station and turns around to serve the opposite direction.

Example (Test Map):

{
    sourceStation = self.stations.Kbo,
    targetStation = self.stations.Kbo,
    sourcePlatforms = { "1" },
    targetPlatforms = { "2" },
    minLayover = 3,
}

What happens:

• a train arriving on platform 1
• waits at least 3 minutes
• and departs again from platform 2

No depot is involved.

Some stations require a shunting move to turn a train.

In this case, a hidden timetable is attached:

{
    sourceStation = self.stations.Go,
    targetStation = self.stations.Go,
    sourcePlatforms = { "1" },
    targetPlatforms = { "2" },
    minLayover = 3,
    timetable = Timetable:new("", 0)
        :setIsServiceRun(true)
        :addStop({
            station = self.stations.Go,
            platform = "6",
            departure = 2,
            turnAround = true,
        })
        :addStop({
            station = self.stations.Go,
            platform = "2",
            departure = 3,
        }),
}

This allows:

• temporary use of siding or crossover tracks
• clean turnarounds without blocking passenger platforms

When no train is available, dispatching can fetch a train from a depot.

Example:

{
    sourceStation = nil,
    targetStation = self.stations.WA,
    targetPlatforms = { "1", "2" },
    depotName = "WA_06_09",
    overrideFirstPlatform = "3",
    timetable = Timetable:new("", 0)
        :setIsServiceRun(true)
        :addStop({
            station = self.stations.WA,
            platform = "7",
            departure = -5,
        })
        :addStop({
            station = self.stations.WA,
            platform = "3",
            departure = -3,
        }),
}

Key points:

• `sourceStation = nil` means the train comes from a depot
• the depot name must match the depots table
• negative departure times happen before the actual service

After service ends, trains can be removed from traffic.

Example:

{
    sourceStation = self.stations.WA,
    sourcePlatforms = { "1", "2" },
    targetStation = nil,
    depotName = "WA_11_18",
    timetable = Timetable:new("", 0)
        :setIsServiceRun(true)
        :addStop({
            station = self.stations.WA,
            platform = "3",
            departure = 2,
        })
        :addStop({
            station = self.stations.WA,
            platform = "11",
            departure = 6,
        }),
}

Here:

• the train leaves passenger service
• moves into the depot
• and is no longer available for dispatching

Timetables inside dispatching strategies:

• are not shown to the player
• are always marked as `setIsServiceRun(true)`
• are used only for internal movements

They allow precise control over:

• routing
• speed limits
• platform usage
• turnarounds

Dispatching strategies are evaluated in order.

Recommended structure per station:

1. normal turnarounds
2. depot spawn strategies
3. depot despawn strategies
4. fallback strategies

This avoids unnecessary depot movements and keeps traffic stable.

• depot names not matching the depots table
• missing `setIsServiceRun(true)` on hidden timetables
• conflicting platform definitions
• wrong strategy order

If dispatching behaves unexpectedly, always check the order first.

`loadCareerMode()` is optional and currently empty.

This is where career mode related data can be initialized later.

The final step is registering runtime data with the ControlCenter:

controlCenter:setStationList(self.stations);
controlCenter:setTimetableList(self.timetables, self.dispatchingStrategies, self.depots);

If this function is missing or incomplete:

• AI traffic will not work
• stations may not be recognized for routing