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
• loading AI timetables and services (see timetable guide)
• 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();
 
	-- Timetables define AI service patterns.
	-- Full guide: manual:subwaysim:map_construction:create_timetable
	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
--- Full guide: manual:subwaysim:map_construction:create_timetable
function TestMap:loadTimetables()
	-- (Implementation depends on your map and service patterns)
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
• loading 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()` defines AI services and dispatching/depot logic
• `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.

⚠️ 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.

Timetables define the AI service pattern of a map.

They control:

• which trains are spawned
• which routes they drive
• which stations and platforms are used
• when and how services operate

In Map.lua, timetables are created inside:

• `function <MapClass>:loadTimetables()`

This function acts as the integration point for all timetable-related data. It typically references or initializes:

• the final list of active services (`self.timetables`)
• timetable templates (e.g. per line and direction)
• depot definitions (`self.depots`)
• dispatching strategies (`self.dispatchingStrategies`)

The complete timetable workflow — including templates, stops, composition weights, service repetition, depot handling, and dispatching logic — is documented separately:

• Create Timetables

This page intentionally does not describe timetable creation in detail, to keep the Map.lua documentation focused on structure and integration.

Career Mode configuration is optional.

If your map does not support career mode, `loadCareerMode()` may remain empty.

If implemented, this function defines:

• where the player can take over a train
• optional route closures for scenario logic
• which train compositions are available
• which timetable templates are used for pathfinding

All career mode logic is map-specific and independent from timetable creation.

After stations and timetables are defined, they must be registered with the ControlCenter:

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

If this step is missing or incomplete:

• AI traffic will not operate
• station-based routing may fail

Continue with:

• Build Mod (.pak)

• SDK Changelog
• SDK Download
• Create Timetables