What is the TpF3 mod tooling and mod structure? #3

New Issue

2026-10-04T19:53:47Z

haylan commented

2026-10-04 19:53:47 +00:00

Question

What do the external-tools wiki page, the example mod in .examples, and the docs say about mod folder layout, mod.json/metadata, Teal vs Lua, script entry points, logging/debugging, and recommended editor tooling (LuaLS/Teal LSP, VS Code extensions)? Also capture the wiki and script-doc into the repo so the AI can read them offline.

Part of #1

## Question What do the external-tools wiki page, the example mod in .examples, and the docs say about mod folder layout, mod.json/metadata, Teal vs Lua, script entry points, logging/debugging, and recommended editor tooling (LuaLS/Teal LSP, VS Code extensions)? Also capture the wiki and script-doc into the repo so the AI can read them offline. Part of #1

haylan added the wayfinder:research label 2026-10-04 19:53:47 +00:00

haylan referenced this issue

2026-10-04 19:56:16 +00:00

Locate the TpF3 install and junction the repo as a mod #4

haylan referenced this issue

2026-10-04 19:56:17 +00:00

Set up VS Code and the AI workflow for the mod #5

haylan closed this issue

2026-10-04 20:03:27 +00:00

haylan commented

2026-10-04 20:04:10 +00:00

Resolved. Full write-up: docs/research/mod-tooling.md on branch research/mod-tooling (commit 0213e22, pushed; main untouched). Offline copies: docs/reference/wiki/ (14+ modding wiki pages as Markdown) and docs/reference/script-doc/ (api*, app, a few content modules; the other ~300 content modules were not saved).

Layout: a mod is a plain dir <author>_<modname>/ with mod.json, _metadata/modinfo.json (+ optional description.html, 0.png..), content/ (resources, mirror base-game structure, optional mod.script.tl), optional strings.json. Install by copying into staging_area/ in the userdata dir.
mod.json: modId (a-z0-9_), revision, severityAdd/Remove (None|Warning|Critical), visible, cosmetic, dependencies, incompatibilities, params (defaultIndex 0-based), script hooks. Example: ug_tf3_config_change, rev 1, preRunScript = ug_tf3_config_change::mod.script@preRunFn.
Teal vs Lua: everything is Lua; Teal (typed Lua, .tl) is the usual dialect. Locals only, no globals. ug_require for imports; script-doc signatures are Teal, so they serve as type defs.
Entry points: preRunFn(configDict, allModParams, baseConfig) mutates BaseConfig (example sets trainAccelerationFactor = 0.5); runFn(configDict, allModParams); postRunFn(configDict, allModParams) uses api.res.* repositories. Own params via allModParams[getCurrentModId()].
Logging/debugging: debugMode=true in settings.lua (or Settings > Advanced); AltGr+D debug window; ingame console shows stdout.txt and runs Lua (\clear, \stdout on|off, \history); debugPrint(table).
Editor tooling: VS Code + Teal (teal-language/tl) + sumneko.lua + pdesaulniers.vscode-teal; Model Editor auto-creates workspace config in the Staging Area; Notepad++ is the fallback.
Gaps: contents of the auto-generated Teal workspace config, whether plain print hits stdout.txt, and how .tl is compiled are undocumented.

Resolved. Full write-up: `docs/research/mod-tooling.md` on branch `research/mod-tooling` (commit 0213e22, pushed; main untouched). Offline copies: `docs/reference/wiki/` (14+ modding wiki pages as Markdown) and `docs/reference/script-doc/` (api*, app, a few content modules; the other ~300 content modules were not saved). - **Layout**: a mod is a plain dir `<author>_<modname>/` with `mod.json`, `_metadata/modinfo.json` (+ optional `description.html`, `0.png`..), `content/` (resources, mirror base-game structure, optional `mod.script.tl`), optional `strings.json`. Install by copying into `staging_area/` in the userdata dir. - **mod.json**: `modId` (a-z0-9_), `revision`, `severityAdd/Remove` (None|Warning|Critical), `visible`, `cosmetic`, `dependencies`, `incompatibilities`, `params` (defaultIndex 0-based), script hooks. Example: `ug_tf3_config_change`, rev 1, `preRunScript` = `ug_tf3_config_change::mod.script@preRunFn`. - **Teal vs Lua**: everything is Lua; Teal (typed Lua, `.tl`) is the usual dialect. Locals only, no globals. `ug_require` for imports; script-doc signatures are Teal, so they serve as type defs. - **Entry points**: `preRunFn(configDict, allModParams, baseConfig)` mutates BaseConfig (example sets `trainAccelerationFactor = 0.5`); `runFn(configDict, allModParams)`; `postRunFn(configDict, allModParams)` uses `api.res.*` repositories. Own params via `allModParams[getCurrentModId()]`. - **Logging/debugging**: `debugMode=true` in settings.lua (or Settings > Advanced); AltGr+D debug window; ingame console shows `stdout.txt` and runs Lua (`\clear`, `\stdout on|off`, `\history`); `debugPrint(table)`. - **Editor tooling**: VS Code + Teal (teal-language/tl) + `sumneko.lua` + `pdesaulniers.vscode-teal`; Model Editor auto-creates workspace config in the Staging Area; Notepad++ is the fallback. - **Gaps**: contents of the auto-generated Teal workspace config, whether plain `print` hits stdout.txt, and how `.tl` is compiled are undocumented.

haylan referenced this issue

2026-10-04 20:04:36 +00:00

Map: TpF3 overtaking mod #1

haylan referenced this issue

2026-10-05 21:24:41 +00:00

Can rebuilding a road segment move a passer past its blocker? #11

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: haylan/tpf3-overtake#3