Teardown Modding

Teardown Modding

Use the API reference in reference/ to answer questions and write code for Teardown mods.

• API index: reference/_index.md — full category listing with descriptions
• API by category: reference/<category>.md — one file per API category (e.g. body.md, player.md, user_interface.md)

Always read the relevant reference file(s) before writing or modifying Teardown Lua code. If you're unsure which category a function belongs to, check _index.md for the full category listing.

Mod Types

Global mods (no main.xml): Active during all gameplay (Campaign, Sandbox, other Content mods) whenever enabled. The player enables/disables them in the Mod Manager.

Content mods (has main.xml): Standalone playable environments with missions or sandbox levels. The player clicks "Play" in the Mod Manager to launch them.

In almost every case, you will be writing a global mod.

Building a Mod

Source, with extra non-scripting reference material: https://teardowngame.com/modding

A mod is a folder inside Documents/Teardown/mods/. Only use Latin alphanumeric characters (a-z, 0-9, and space) in the folder name. Key files go in the mod root:

MyMod/
├── info.txt          -- Required: mod metadata
├── main.lua          -- Script that runs when mod is active (optional)
├── main.xml          -- Level definition (Content mods only)
├── options.lua       -- Options UI shown in Mod Manager (optional)
├── preview.jpg       -- Thumbnail for Mod Manager (optional)
├── spawn.txt         -- Spawnable asset list (optional)
├── images/           -- (optional)
├── scripts/          -- (extra scripts referenced by main.lua or gamemodes, optional)
├── sound/            -- (optional)
└── vox/              -- (optional)

info.txt

Required for all mods. Displayed in the Mod Manager.

name = Laser Gun
author = Tuxedo Labs
description = Custom tool example mod. Laser gun that cuts through most materials
tags = Tool

• name — mod title
• author — creator name
• description — brief overview
• tags — optional, comma-separated. Valid values: Map, Gameplay, Asset, Vehicle, Tool

main.lua

Runs whenever the mod is active — during all gameplay for global mods, or when the content mod is played. See the callback reference below and the API reference in reference/ for available functions.

options.lua

If present, an Options button appears when the mod is selected in the Mod Manager. Must contain a draw() function that renders the options UI. See the built-in Speedometer mod for an example.

spawn.txt

Exports prefabs as spawnable items in the built-in spawn menu. Each line maps a prefab path (relative to mod root) to a menu category and name:

path/to/mycar.xml : Cars/My car

Static objects are automatically converted to dynamic when spawned. Prefabs must first be converted from groups in the editor.

Quick Reference: Callbacks

Client/server architecture (multiplayer-compatible):

function server.init()          -- Called once at load (server)
function server.tick(dt)        -- Called every frame (server, variable dt)
function server.update(dt)      -- Called at fixed 60Hz (server, dt = 0.0167)
function server.postUpdate()    -- Called after physics (server)
function server.destroy()       -- Called when game mode stops (server)

function client.init()          -- Called once at load (client)
function client.tick(dt)        -- Called every frame (client, variable dt)
function client.update(dt)      -- Called at fixed 60Hz (client, dt = 0.0167)
function client.postUpdate()    -- Called after physics (client)
function client.draw()          -- Called every frame, UI functions only work here
function client.render(dt)      -- Called right before screen draw
function client.destroy()       -- Called when game mode stops (client)

Plain callbacks (only for reference, prefer newer callbacks):

function init()       -- Called once at load
function tick(dt)     -- Called every frame (variable dt)
function update(dt)   -- Called at fixed 60Hz (dt = 0.0167)
function draw(dt)     -- Called every frame, UI functions only work here

Use server.* for game logic, physics, and authoritative state. Use client.* for rendering, UI, and visual effects. The shared table auto-syncs data from server to all clients (read-only on client). In single-player, the host acts as both server and client.

mplib — Official multiplayer library: For multiplayer gamemode mods, use mplib from Tuxedo Labs (the Teardown developers). It provides battle-tested modules for match flow, team management, tool/loot spawning, HUD, scoring, spectator mode, and client/server coordination. It powers the built-in "Multiplayer Classics" game modes. Copy mplib/ into your mod and #include the modules you need.

Key Gotchas

• User input-related APIs can be found in Script control
• Teardown uses Lua 5.1 — no goto, no ::labels::, no bitwise operators
• #include is textual insertion, not require() — all files share global scope
• Compile errors give no line numbers
• io, os, sockets are all blocked — no file I/O or networking
• UI functions (Ui*) only work inside draw()
• Don't name tables after built-in functions (e.g., Spawn = {} shadows Spawn())

Key Paths

What	Path
Game log	C:\Users\<USER>\AppData\Local\Teardown\log.txt (overwritten each launch)
Savegame / registry	C:\Users\<USER>\AppData\Local\Teardown\savegame.xml
Local mods	C:\Users\<USER>\Documents\Teardown\mods\
Workshop mods	<STEAM>\steamapps\workshop\content\1167630\ (each subfolder is a mod by Steam ID)
Built-in mods	<STEAM>\steamapps\common\Teardown\mods\ (official examples: lasergun, smokegun, etc.)
Game install	<STEAM>\steamapps\common\Teardown\

The built-in mods and workshop mods are excellent references for working API patterns. Browse them freely to learn idiomatic Teardown Lua, or request the user to make reference workshop mods available.