chore(prototype): point probe header at the position-flip ticket

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/research/modio-terms.md

@@ -0,0 +1,26 @@
+# mod.io Terms: what applies to a published mod
+
+Ad-hoc research 2026-10-05 (no ticket — reference material for the map).
+Fetched from the no-chrome legal routes: `https://mod.io/legal/terms?no_links=true` (Terms of Use) and `https://mod.io/legal/aup?no_links=true` (Acceptable Use Policy). `mod.io/terms` itself is a JS app; the same text is also available via `GET /agreements/types/:id/current` (1 = Terms of Use, 3 = Game Terms, 4 = API Access Terms) with an API key — not needed for offline reading.
+
+## Why this matters
+
+TpF3 has **no Steam Workshop**: the official in-game mod browser is mod.io (see `docs/reference/wiki/modding_general_publishing.md`). The map's old "Steam Workshop publishing" out-of-scope line has been corrected to mod.io. This note is the mod.io side of that story; the game-side rules (free, non-commercial, no offensive content, monetization) are already captured in the publishing wiki doc.
+
+## Key clauses (Terms of Use, by number)
+
+- **§1.5** The Acceptable Use Policy is incorporated into the ToU; breaching the AUP is breaching the ToU.
+- **§1.7 Priority order** (first wins on conflict): Game Terms > game's AUP > mod.io AUP > ToU clauses 15/16 (EU/AU consumers) > Monetization Terms > ToU. So **Urban Games' own rules override mod.io's**.
+- **§1.9** mod.io may change the ToU; 30 days after publication the new terms bind you.
+- **§6.2 UGC license** — by uploading a mod you grant mod.io **and the Relevant Game Admin (Urban Games)** a transferable, sublicensable, royalty-free, **irrevocable, non-exclusive, perpetual worldwide** license to use, reproduce, modify, make derivative works of, and distribute the mod "for the sole purpose of providing the Services". Optional *Enhanced License Rights* (sale/resale) only if separately opted in via the UGC Control Panel, and those are revocable.
+- **§6.3 warranty** — you warrant the UGC is yours or you have the right to distribute it, and does not violate others' rights. This is what makes the wiki's "no content you don't have copyright or permission to distribute" enforceable.
+- **§8 Copyright** — DMCA-style process; mod.io (or the Game Admin) may delete/disable content alleged to infringe.
+- **§11 Termination** — mod.io may terminate/suspend the account immediately for material or repeated breach; and the Game Admin may **restrict access to the game's mod services at any time, without notice**.
+- **AUP** — standard prohibitions: nothing illegal, no spam/malware, no harassment/defamation, no probing or unauthorised access to the service, no scraping of data you aren't meant to get.
+
+## Implications for this mod
+
+- Free and non-commercial is the game-side rule anyway; nothing new here.
+- Uploading = a perpetual irrevocable license to mod.io + Urban Games. Fine for a code-only behavioural mod; just know it before publishing anything with third-party assets (see also the base-game-file reuse rules in the publishing wiki doc).
+- The mod can be pulled or access restricted at Urban Games' discretion at any time — no recourse beyond the ToU's notice process.
+- Nothing in the ToU/AUP touches the technical side of the mod (script API, staging area, etc.); it only governs distribution and conduct.

docs/research/vehicle-probe.md

@@ -0,0 +1,86 @@
+# In-game vehicle probe
+
+Ticket "Probe vehicle data and native passing in game" (part of map "Map: TpF3 overtaking mod"). Run 2026-10-05 on game build 40408, with the throwaway probe `mod/content/overtake_probe.{gs.lua,script.tl}` on branch `prototype/vehicle-probe`. Log excerpt: `probe-logs/2026-10-05-vehicle-probe.txt`.
+
+## How the probe works
+
+- A mod registers a per-tick game script by shipping `content/<name>.gs.lua` (`data()` returns `updateScript = { fileName = "<name>.script@update" }`), the same way the base game's `vehicle/vehicle_modifier.gs.lua` does. No `mod.json` entry is needed. Adding it to an existing save logs `Creating entity for newly added GameScript haylan_tf3_overtake::/overtake_probe.gs`.
+- `update` runs every 0.2 s of game time (`dt = 0.2`).
+- **Module-level Lua variables don't persist between calls**: the script runs in several or fresh Lua states. Persistent state has to go through `GameScriptState`.
+- **No hot reload**: an edited `.tl` takes effect only after the save is reloaded.
+- `print` goes to `<Steam>/userdata/<id>/3493540/local/crash_dump/stdout.txt`.
+
+## API facts (observed, overriding tealdef where they differ)
+
+- Player vehicles: `api.engine.getEntitiesWithComponent(TRANSPORT_VEHICLE, { requireOwnedByPlayer = api.engine.util.getPlayer() })`. Road vehicles also carry `LAND_VEHICLE` and `MOVE_PATH`.
+- `MovePath.path.edges` is a **1-based Lua table of `EdgeIdDir` userdata** (`.edgeId`, `.dir`), **not** `{EdgeId, boolean}` as the tealdef says. The current edge is `edges[dyn.pathPos.edgeIndex + 1]`.
+- `EdgeId.entity` is the **street segment** (it carries `BASE_EDGE` and `TRANSPORT_NETWORK`). `EdgeId.index` is the **lane** within that segment's `TransportNetwork.edges`.
+- `TransportNetwork.turnaroundEdges[index + 1]` is the opposite lane. `TransportNetwork.edges[i]` has `transportModes`, `speedLimit` and `curSpeed`.
+- `BaseEdge.laneConfigs` lists the lanes, with `forward`, `offset`, `width` and `transportModes`. Mode keys print as integers: sidewalks `[0,1]`, driving lanes `[2,3,4]`.
+- `landVehicleMoveSystem.getVehicleInfo` only returns `availPower`, `traction`, `tractiveEffort` and `vehicleAvailPower`.
+- `MovePath.blocked` stayed `0` for every vehicle the whole time, including vehicles clearly queued behind a slower one. It doesn't signal "held up by the vehicle ahead".
+- `MovePath.dyn.timeToIgnore` is negative and counts down for almost every vehicle. It was briefly positive (+9.4) once, right after a stop. Its meaning is unknown.
+
+## Observed traffic behaviour
+
+| Road | Lanes per direction | What happened |
+|---|---|---|
+| `country_new_medium` (segments 6527 → 29697) | 2 (lanes 3 and 4 forward) | 29251 (power 243) followed 29852 (power 160) in lane 4 over 6 segments, 24–30 m behind. It accelerated to 17.7 m/s and then dropped to 15.1 m/s to match the vehicle ahead. Lane 3 was free and stayed unused. |
+| `country_new_medium` (segment 28894) | 2 | The two vehicles were in different lanes (3 and 4), but their order never changed. This looks like lane choice for the next turn, not passing. |
+| `country_new_small` (segments 26513 → 28566) | 1 (lane 2 forward, lane 1 opposite) | 29251 was held at exactly 16.67 m/s (29851's top speed) behind 29851, below the road's 22.2 m/s limit, for 6+ segments. |
+
+## Verdict
+
+- The engine does **not** pass natively, on either multilane or two-way roads. Bus lanes weren't tested.
+- The read side is sufficient: a script can tell, per vehicle, which segment, lane and direction it's in, where it is, how fast it's going, and what the opposite lane is. So both the "held back" condition and an oncoming-traffic check can be computed. "Held back" must be derived (same segment and lane, small gap, speed below the vehicle's capability), because `blocked` doesn't report it.
+- **No documented command can make a vehicle ignore the one ahead** (see `overtake-feasibility.md`).
+
+## Searching for a way to make a vehicle ignore the one ahead
+
+- **Script commands:** none of the commands in `api.cmd` moves a vehicle, changes its lane, or turns off the queueing. The full list was checked.
+- **Model metadata:** `landVehicle` (engines, topSpeed, weights) and `extent` have no following or blocking parameters.
+- **`Transformator.LandVehicleScriptingApi` / `TransfOutput.setUserTransf`:** a per-model animation script. It can offset the model on screen, which could make a vehicle look like it changes lanes, but it doesn't touch the simulation.
+- **Executable strings:** `LandVehicleMoveSystem.cpp` contains `GetNextEdgeTrafficPenaltyAndAlternatives`, `existingPathLaneSwitch` and `switchIndices`. So the engine itself switches lanes at segment boundaries based on a traffic penalty, which matches the lane split seen on segment 28894. None of it is exposed to scripts.
+- **`api.cmd.debug.makeComponentExchangeCmd(entity, MovePath)`** (save loaded with "Debug mode is active"): building the command with a `MovePath` **succeeds**. `api.cmd.sendCommand(cmd, callback)` fails with `Error decoding argument #3`, because engine-state scripts can't pass a callback (base scripts never do). The version without a callback was committed but **never ran in game**. Whether the swap is applied, and what a positive `timeToIgnore` does, are both **untested**.
+
+## Decision
+
+Overtaking on two-way roads (one lane per direction) is dropped (decided by the user, 2026-10-05). The effort continues on multilane roads only: a held-back vehicle should switch to a lane the slower vehicle isn't in.
+
+## Segment rebuild (ticket "Can rebuilding a road segment move a passer past its blocker?")
+
+- The script sent 3 `makeWorldBuildProposalCmd` proposals (remove segment + re-add a copy of its `BaseEdge`/`BaseEdgeStreet`, `ignoreErrors = true`) for segments 29701 and 29699 (`country_new_medium`). **None took effect**: both segment ids stayed in use by vehicles until the end of the log, and 29699 was "rebuilt" twice. The game logged no error, and there's no callback in engine state. The copied `BaseEdge.distance` read `0.0`, so the copy is probably incomplete. A next attempt would need `api.engine.util.proposal.makeProposalData` to see the proposal's errors.
+- The human's manual segment deletion left no trace in the probe data: every vehicle stayed `tvState=1` (en route), with only normal path trimming.
+- Related find: `api.cmd.makeVehicleSendToDepotCmd(vehicle, sellOnArrival, jumpToDepotEntity)` "teleports" a vehicle to a depot. The engine can relocate vehicles instantly, but only to depots.
+
+## Lessons from downloaded mods and the game folder (2026-10-05)
+
+Scanned: the 9 mods in `C:\Users\Public\mod.io\10640\mods\` (e.g. `devers_1`, `move_it_probe_overpass`, `zhenya_auto_assign_terminals`, `celmi_timetables`, `burntnuggie_line_priority_1`), and every `.lua`/`.tl` in the install's `base`, `mods/release` and `dlcs`, including inside the zips.
+
+- **Callbacks only work on the GUI thread.** Mods send commands from a `guiUpdateScript`/`guiHandleEventScript` (declared in the same `.gs.lua`) and get `function(res, success, resultEntities)` back. Errors are readable via `res.resultProposalData.errorState.messages`. From `update` (engine thread), callbacks fail with `Error decoding argument #3`, which is what we hit.
+- **Rebuilding a segment:** `api.engine.util.proposal.replaceSegment(entity, streetTemplate?)` returns a ready `Proposal`. The official campaign (mission 03 `init.script.tl`) sends it from engine state with `makeWorldBuildProposalCmd(proposal, nil, true, true)`. `devers_1` uses it the same way. It keeps lane links, edge objects (signals) and electrification. `api.engine.util.proposal.makeProposalData(proposal)` validates a proposal (`.costs`, `.errorState`) without sending it.
+- **Teleport:** only `makeVehicleSendToDepotCmd(vehicle, sellOnArrival, jumpToDepotEntity)`. Mission 05 uses it for a ship, then `makeVehicleSetLineCmd(vehicle, newLine, 0)` and a restart. No coordinate or lane-position teleport exists for line vehicles. `makeCustomVehicleCreateOrUpdateCmd` is aircraft-only ("carrier currently must be Air").
+- `api.engine.util.transport.calcPosition(edge.geometry, t)` gives a world position along an edge geometry.
+- `burntnuggie_line_priority_1` sets line **reservation** priority via `makeLineUpdateCmd`. That's path reservation for rail, not road traffic.
+- `makeVehicleSetLineCmd` to the vehicle's own line: the lanes planned ahead change, but the engine re-plans them on its own all the time (the leader's changed too, without a command). It doesn't force a lane change, and with `stopIndex=0` it re-targets the line's first stop.
+
+## Segment rebuild via `replaceSegment` (run 2026-10-05 ~20:55 UTC)
+
+- `api.engine.util.proposal.replaceSegment(seg)` plus `makeWorldBuildProposalCmd(p, nil, true, true)` from engine state **works**: segments 29702, 21304 and 29012 never appeared again after their rebuild (they got new ids).
+- **After all 3 rebuilds, the follower and leader ended up in different lanes** (`country_new_medium`, 2 lanes per direction). Each time the *leader* moved from lane 4 to lane 3, either right away or one segment later, and the follower stayed in lane 4.
+  - #1 (seg 29702): follower 29251 at 50.4 m behind leader 29852 at 76.7 m. Afterwards, on seg 29699, 29251 is at 29.1 m (lane 4) and 29852 at 20.2 m (lane 3). 29251 drives 18.6–19.6 m/s, above its earlier 16.67, and stays a segment ahead. **The follower got past.**
+  - #2 (seg 21304): 29851 (leader) moved to lane 3 on seg 27833. The lanes split, but the order was unchanged.
+  - #3 (seg 29012): 29251 (leader) moved to lane 3 on seg 29322.
+  - Without rebuilds, the same pair stayed together in lane 4 for 6 segments (first probe). The engine also switches lanes by itself at segment ends sometimes, so 3/3 is suggestive, not proof.
+  - Likely cause (human's hypothesis): the vehicles' `MovePath` refers to lanes of the removed segment, so the engine must re-attach them to the new segment and re-plan, and a vehicle can land in a different lane.
+- **Debug `MovePath` exchange is unusable from engine state**: `api.cmd.sendCommand(api.cmd.debug.makeComponentExchangeCmd(v, movePath))` fails with `Error decoding argument #3` even **without** a callback. So the earlier error wasn't caused by the callback. The only untried route is the GUI thread.
+- Not yet tested: a rebuild on a two-way (one lane per direction) road.
+
+## Rebuild on a two-way road (run 2026-10-05 ~21:12 UTC)
+
+- 3 `replaceSegment` rebuilds on `country_new_small` (one lane per direction), segments 30213, 29776 and 30215, follower 25.8 m behind leader. **No effect**: the next snapshot had the same gap (22.6/48.4 → 49.3/75.1), both vehicles stayed in lane 2, same speeds, same order for 10+ snapshots. Rebuilding does not move vehicles past each other on single-lane roads.
+- How the multilane lane change happens is still uncaught: snapshots every 2 s only show before (both lane 4) and after (the leader in lane 3 two segments later). The probe now traces the two vehicles on every update for ~30 s after a rebuild (`TRACE` lines), and rebuilds only multilane segments.
+
+## Segment rebuild dropped (2026-10-05)
+
+The human confirmed in game what the log showed: rebuilding the segment under a held-back vehicle does not get it past the blocker on a single-lane road. The rebuild code is removed from the probe (it's still in git history, last in commit 5d3a254). The lane split after rebuilds on multilane roads (see above) is left as an observation for the multilane ticket, not pursued here.

mod/_metadata/modinfo.json

@@ -9,7 +9,9 @@
     "summary": "Vehicle overtaking (WIP)",
     "name": "Overtake",
     "tags": [
-        "script"
+        "Script Mod",
+        "Car",
+        "Road"
     ],
-    "url": ""
+    "url": "https://git.arthurerlich.de/haylan/tpf3-overtake"
 }

mod/content/overtake_probe.gs.lua

@@ -0,0 +1,11 @@
+-- PROTOTYPE (ticket "Probe vehicle data and native passing in game"): throwaway, lives only on branch prototype/vehicle-probe.
+function data()
+	return {
+		updateScript = {
+			fileName = "overtake_probe.script@update",
+		},
+		guiUpdateScript = {
+			fileName = "overtake_probe.script@guiUpdate",
+		},
+	}
+end

mod/content/overtake_probe.script.tl

@@ -0,0 +1,160 @@
+-- PROTOTYPE (ticket "Can a script swap the positions of a follower and its leader?"): throwaway,
+-- lives only on branch prototype/vehicle-probe.
+-- Engine thread: every INTERVAL it logs every player-owned road vehicle (segment, lane, position, speed).
+-- GUI thread: EXPERIMENT flipping the positions of a follower and its leader (see below).
+-- Earlier experiments (timeToIgnore, engine-side jump, set-line, segment rebuild) are in git history and
+-- docs/research/vehicle-probe.md; none moved a vehicle past another on a single-lane road.
+-- ponytail: module-local timer, not GameScriptState; fine for a probe (state resets between calls anyway).
+
+local TAG = "[overtake_probe] "
+local INTERVAL = 2.0
+local MAX_GAP = 40.0
+local elapsed = 0.0
+local ticks = 0
+
+local function p(s : string)
+	print(TAG .. s)
+end
+
+local function edgeAt(mp : Engine.Component.MovePath) : EdgeId, boolean
+	-- path.edges is 1-based, elements are EdgeIdDir userdata (tealdef says {EdgeId, boolean})
+	local e = (mp.path.edges as {any})[mp.dyn.pathPos.edgeIndex + 1] as UtilPathfinding.EdgeIdDir
+	if e == nil then return nil, nil end
+	return e.edgeId, e.dir
+end
+
+local function turnaround(edge : EdgeId) : integer
+	local tn = api.engine.getComponent(edge.entity, api.type.ComponentType.TRANSPORT_NETWORK) as Engine.Component.TransportNetwork
+	if tn == nil or tn.turnaroundEdges == nil then return nil end
+	return tn.turnaroundEdges[edge.index + 1]
+end
+
+local record Car
+	v : integer
+	pos : number
+	pos01 : number
+	speed : number
+	dir : boolean
+end
+
+local function dump(dt : number)
+	local player = api.engine.util.getPlayer()
+	local vehicles = api.engine.getEntitiesWithComponent(api.type.ComponentType.TRANSPORT_VEHICLE, { requireOwnedByPlayer = player })
+	p(string.format("tick=%d dt=%s playerVehicles=%d", ticks, tostring(dt), #vehicles))
+	for _, v in ipairs(vehicles) do
+		local lv = api.engine.getComponent(v, api.type.ComponentType.LAND_VEHICLE) as Engine.Component.LandVehicle
+		local mp = api.engine.getComponent(v, api.type.ComponentType.MOVE_PATH) as Engine.Component.MovePath
+		local tv = api.engine.getComponent(v, api.type.ComponentType.TRANSPORT_VEHICLE) as Engine.Component.TransportVehicle
+		if lv ~= nil and not lv.isTram and mp ~= nil then
+			local edge, dir = edgeAt(mp)
+			p(string.format(
+				"veh=%d seg=%d lane=%s dir=%s turnaround=%s edgeIndex=%d/%d pos=%.1f speed=%.2f state=%s tvState=%s line=%s standing=%.1f",
+				v, edge and edge.entity or -1, tostring(edge and edge.index), tostring(dir), tostring(edge and turnaround(edge)),
+				mp.dyn.pathPos.edgeIndex, #(mp.path.edges as {any}), mp.dyn.pathPos.pos, mp.dyn.speed, tostring(mp.state),
+				tostring(tv and tv.state), tostring(tv and tv.line), mp.dyn.timeStanding))
+		end
+	end
+end
+
+-- EXPERIMENT (GUI thread, where sendCommand callbacks work): flip the positions of a follower and its leader by
+-- exchanging their MovePath components (route + position) with api.cmd.debug.makeComponentExchangeCmd.
+local MAX_FLIPS = 2
+local FLIP_SCAN_FRAMES = 60 -- scan for a pair about once per second
+local FLIP_TRACE_FRAMES = 600 -- then log both vehicles every 10 frames for ~10 s
+
+local record GuiState
+	frames : integer
+	flips : integer
+	traceLeft : integer
+	a : integer
+	b : integer
+end
+
+local function movePathOf(v : integer) : Engine.Component.MovePath
+	return api.engine.getComponent(v, api.type.ComponentType.MOVE_PATH) as Engine.Component.MovePath
+end
+
+local function flipLine(v : integer) : string
+	local mp = movePathOf(v)
+	if mp == nil then return "veh=" .. v .. " no MovePath" end
+	local edge, _dir = edgeAt(mp)
+	return string.format("veh=%d seg=%s lane=%s pos=%.1f v=%.2f", v, tostring(edge and edge.entity), tostring(edge and edge.index), mp.dyn.pathPos.pos, mp.dyn.speed)
+end
+
+local function sendFlip(gs : GuiState, follower : integer, leader : integer)
+	local mpF, mpL = movePathOf(follower), movePathOf(leader)
+	p("FLIP_TEST before " .. flipLine(follower) .. " | " .. flipLine(leader))
+	local function done(label : string) : function(any, boolean)
+		return function(res : any, success : boolean)
+			p(string.format("FLIP_TEST result %s success=%s res=%s", label, tostring(success), tostring(res)))
+		end
+	end
+	api.cmd.sendCommand(api.cmd.debug.makeComponentExchangeCmd(follower, mpL as Engine.Component), done("follower<-leader"))
+	api.cmd.sendCommand(api.cmd.debug.makeComponentExchangeCmd(leader, mpF as Engine.Component), done("leader<-follower"))
+	gs.flips = gs.flips + 1
+	gs.traceLeft = FLIP_TRACE_FRAMES
+	gs.a, gs.b = follower, leader
+end
+
+-- same pair rule as the engine-side probe: same segment + lane, follower < MAX_GAP behind a moving leader
+local function findPair() : integer, integer
+	local player = api.engine.util.getPlayer()
+	local byLane : {string : {Car}} = {}
+	for _, v in ipairs(api.engine.getEntitiesWithComponent(api.type.ComponentType.TRANSPORT_VEHICLE, { requireOwnedByPlayer = player })) do
+		local lv = api.engine.getComponent(v, api.type.ComponentType.LAND_VEHICLE) as Engine.Component.LandVehicle
+		local mp = movePathOf(v)
+		if lv ~= nil and not lv.isTram and mp ~= nil then
+			local edge, dir = edgeAt(mp)
+			if edge ~= nil then
+				local key = edge.entity .. ":" .. edge.index
+				byLane[key] = byLane[key] or {}
+				table.insert(byLane[key], { v = v, pos = mp.dyn.pathPos.pos, pos01 = mp.dyn.pathPos.pos01, speed = mp.dyn.speed, dir = dir })
+			end
+		end
+	end
+	for _, cars in pairs(byLane) do
+		for i = 1, #cars do
+			for j = 1, #cars do
+				local a, b = cars[i], cars[j]
+				local ahead = (a.dir and b.pos > a.pos) or (not a.dir and b.pos < a.pos)
+				if i ~= j and ahead and math.abs(b.pos - a.pos) < MAX_GAP and b.speed > 1.0 then
+					return a.v, b.v
+				end
+			end
+		end
+	end
+	return nil, nil
+end
+
+local function guiStep(gsState : GameScriptState<GuiState>)
+	local gs = gsState:get()
+	gs.frames = (gs.frames or 0) + 1
+	gs.flips = gs.flips or 0
+	gs.traceLeft = gs.traceLeft or 0
+	if gs.traceLeft > 0 then
+		if gs.traceLeft % 10 == 0 then
+			p(string.format("FLIP_TRACE f=%d %s | %s", FLIP_TRACE_FRAMES - gs.traceLeft, flipLine(gs.a), flipLine(gs.b)))
+		end
+		gs.traceLeft = gs.traceLeft - 1
+	elseif gs.flips < MAX_FLIPS and gs.frames % FLIP_SCAN_FRAMES == 0 then
+		local follower, leader = findPair()
+		if follower ~= nil then sendFlip(gs, follower, leader) end
+	end
+	gsState:set(gs)
+end
+
+local ret : GameScriptWithGui<table, GuiState> = {
+	update = function(_userParams : table, _state : GameScriptState<table>, dt : number) : nil
+		ticks = ticks + 1
+		elapsed = elapsed + dt
+		if ticks == 1 then p("update running, first dt=" .. tostring(dt)) end
+		if elapsed < INTERVAL then return end
+		elapsed = 0.0
+		xpcall(dump, function(err : any) p("ERROR " .. tostring(err)) end, dt)
+	end,
+	guiUpdate = function(_userParams : table, _state : GameScriptStateReadOnly<table>, guiState : GameScriptState<GuiState>)
+		xpcall(guiStep, function(err : any) p("ERROR gui " .. tostring(err)) end, guiState)
+	end,
+}
+
+return ret