Differences

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

--- manual:subwaysim:vehicle_development:vehicle_lua [2026/01/13 08:13] – dcs
+++ manual:subwaysim:vehicle_development:vehicle_lua [2026/01/13 19:57] (current) – dcs
@@ Line 32: / Line 32: @@
 	author			= "$GameDeveloper",
-	emptyMass			= 37.0,
+	emptyMass		= 37.0,
-	vmax				= 70,
+	vmax			= 70,
-	length				= 12.64,
+	length			= 12.64,
 	frontToFirstBogie	= 2.53,
 	rearToLastBogie		= 2.53,
@@ Line 170: / Line 170: @@
 ---@type RailVehicle_DataTable
-local GI1E_b 								= TableUtil.deepCopy(GI1E_a);
+local GI1E_b 					= TableUtil.deepCopy(GI1E_a);
-GI1E_b.components 							= GI1E_a.components; -- TODO
+GI1E_b.components 				= GI1E_a.components; -- TODO
-GI1E_b.contentName 							= "Berlin_GI1E_b";
+GI1E_b.contentName 				= "Berlin_GI1E_b";
-GI1E_b.blueprintFilename 					= "/SubwaySim_Berlin/Vehicles/GI1E/BP_GI1E_B.BP_GI1E_B";
+GI1E_b.blueprintFilename 			= "/SubwaySim_Berlin/Vehicles/GI1E/BP_GI1E_B.BP_GI1E_B";
-GI1E_b.lights.headLights					= nil;
+GI1E_b.lights.headLights			= nil;
-GI1E_b.lights.tailLights					= nil;
+GI1E_b.lights.tailLights			= nil;
 GI1E_b.couplingFront.couplingBoneName		= "Coupling_Rotation3";
 GI1E_b.couplingRear.couplingBoneName		= "Coupling_Rotation4";
@@ Line 698: / Line 698: @@
 Using `TableUtil.deepCopy` keeps your Lua files clean, maintainable, and easy to extend when creating multiple vehicle variants.
+----
+===== Train Compositions and Content Registration =====
+At the end of the file comes one of the most important parts:
+**Train compositions** and the registration of all DataTables in the **Content Manager**.
+Without these steps, the game would know that the vehicle exists as a data table — but it would not know:
+  * how to spawn it as a full train consist,
+  * and it would not load the content at all.
+----
+==== What is a TrainComposition_DataTable? ====
+A `TrainComposition_DataTable` defines a **complete train consist** (multiple vehicles in a fixed order).
+AI trains in SubwaySim 2 are usually spawned using **train compositions**, not single vehicles.
+That is why this section is essential for AI vehicles.
+----
+==== Example: GI1E_1x (one train unit) ====
+<code lua>
+---@type TrainComposition_DataTable
+local GI1E_1x = {
+    contentType     = "trainComposition",
+    contentName     = "Berlin_GI1e_1x",
+    title           = "GI1e x1",
+    author          = "Simuverse GmbH",
+    -- not required for AI trains
+    description         = "",
+    previewFilename     = "",
+    hidden              = true,
+    vehicles = {
+        { contentName = "Berlin_GI1E_a", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = false },
+        { contentName = "Berlin_GI1E_a", forward = false },
+    },
+};
+</code>
+^ Field ^ Meaning ^
+| `contentType = "trainComposition"` | Defines that this table is a train composition. |
+| `contentName` | Internal unique identifier for this consist. Used by the Content Manager and spawners. |
+| `title` | Display name (used in menus or debug lists). |
+| `author` | Author name. |
+| `hidden = true` | Hides this composition from the vehicle selection menu. Very common for AI-only trains. |
+| `vehicles` | The ordered list of vehicles that form the train consist. |
+----
+==== The vehicles list ====
+The most important part is the `vehicles = { ... }` block.
+Each entry uses:
+^ Field ^ Meaning ^
+| `contentName` | Refers to a vehicle previously defined and registered (e.g. `Berlin_GI1E_a`). |
+| `forward` | Defines the orientation of that vehicle inside the consist. `true` means forward-facing, `false` means reversed. |
+This is where you can clearly see why `contentName` is so important:
+It acts as the unique key that links your **vehicle DataTables** into a full train consist.
+----
+==== Example: GI1E_2x (two units coupled) ====
+The 2x consist simply repeats the same unit again, resulting in a longer AI train.
+<code lua>
+---@type TrainComposition_DataTable
+local GI1E_2x = {
+    contentType     = "trainComposition",
+    contentName     = "Berlin_GI1e_2x",
+    title           = "GI1e x2",
+    author          = "Simuverse GmbH",
+    -- not required for AI trains
+    description         = "",
+    previewFilename     = "",
+    hidden              = true,
+    vehicles = {
+        { contentName = "Berlin_GI1E_a", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = false },
+        { contentName = "Berlin_GI1E_a", forward = false },
+        { contentName = "Berlin_GI1E_a", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = true  },
+        { contentName = "Berlin_GI1E_b", forward = false },
+        { contentName = "Berlin_GI1E_a", forward = false },
+    },
+};
+</code>
+----
+==== Registering Content with the Content Manager ====
+At the very end, we must register all content tables so SubwaySim 2 actually loads them.
+<code lua>
+g_contentManager:addContent(GI1E_a);
+g_contentManager:addContent(GI1E_b);
+g_contentManager:addContent(GI1E_1x);
+g_contentManager:addContent(GI1E_2x);
+</code>
+This does two things:
+  * It tells the game: **"These DataTables exist and should be loaded."**
+  * It makes the `contentName` entries usable by the spawning and AI systems.
+Important:
+  * We pass the **local Lua variables** here (e.g. `GI1E_a`), not the string names.
+  * If you forget to register a table, it will not exist in the game content system.
+----
+==== Summary ====
+  * `RailVehicle_DataTable` defines **single vehicles**
+  * `TrainComposition_DataTable` defines **AI train consists**
+  * `g_contentManager:addContent(...)` is required so SubwaySim 2 loads the vehicles and compositions at all
+With this section completed, the vehicle and its AI train compositions are fully registered and can be used by SubwaySim 2.
+----
+===== What's Next? =====
+This page covered the setup of a **simple vehicle.lua**, mainly intended for AI-operated trains.
+If you want to create more advanced vehicles — such as player-driven trains, vehicles with interactive cabs, advanced systems, or extended logic — you will find further detailed information in the following chapters:
+  * **[[manual:subwaysim:vehicle_development:complex_vehicle_blueprint|Complex Vehicle Blueprint]]**
+    Learn how to build advanced vehicle Blueprints with interactive components, cab logic, and extended systems.
+  * **[[manual:subwaysim:vehicle_development:complex_vehicle_lua|Complex Vehicle.lua]]**
+    Explore advanced Lua setups including player controls, extended systems, and complex vehicle behavior.
+These chapters expand on the foundations explained here and guide you step by step towards fully-featured, player-ready vehicles.
 {{page>manual:footer}}