Basic Modding Guide

Setup tooling

You can open the .lua files in any editor you like; however, here is a guide for how to set up Visual Studio Code for getting auto suggestion related to Trailmakers API while coding.

1. Download, install and open Visual Studio Code
2. Go to File -> Preferences -> Extensions
3. Search for lua and install the the Lua extension by sumneko (https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
4. Go to File -> Preferences -> Settings
5. Search for workspace library
6. Click Add Item for the Lua > Workspace: Library entry. And enter the path for your chosen API doc file (Ex. trailmakers/mods/trailmakers_docs.lua)
7. You are done, your code editor will now make auto suggestions for all our library functions in Trailmakers!

An alternative guide and Lua API definitions can also be found in ALVAROPING's Github Repository, which supports more features.

Your first mod: Hello World!

This is a short guide for printing a basic "Hello World!" message in the mod log. It serves as a basic starter for getting you started with trailmakers modding.

1. Create a folder in the mods directory, e.g. C:\Program Files (x86)\Steam\steamapps\common\Trailmakers\mods. Let us call it helloworld.
2. Open the folder and create a file named main.lua. Note: For the mod to work, the main.lua file needs to exist, as it is the entry point for the game.
3. Open the main.lua file and write tm.os.Log("Hello World!")
4. Open trailmakers and activate the helloworld mod (See Modding#Installing and using Mods for how to activate mods).
5. There should now be a file trailmakers/mods/helloworld.log, that should contain the "Hello World!" text that was printed to the log from the mod.

Notes

Server Authority

All the lua code is ran on the server and then passed to the clients.

The clients never “run” the scripts. The server ensures the mod update is ran, and all the API functions ensures to inform the clients about the updates. This does create some limitations in most of the functionality that can be created for modding API is (mostly) server-based only.

Hot Reload

Every time you save changes the the mod folder, the game will detect it and reload the mod script automatically while the game is running.

Folder Structure

Usually mods folder look something like this:

mod root
|- main.lua          -- Where code gets executed
|- data_static/      -- Assets/Data shipped with the mod, can only read from during runtime
|- data_dynamic/     -- Data dynamic that can be read/write from during runtime

Multiple Mods

You can have multiple mods activated at once.

The script executions between mods are run seperately and can not access eachother (Physical objects will still interact with each other though)

Maps

Technically, there is no “map” feature in the current API. But, the community has made Map mods using serialising lists of spawnable objects into the data_static folder that can be loaded by the mod -- This was not something we expected, but we do love it! (We even added a Steam Tag for it).

But, this means that the mods are not detected as “maps” and will not get included in the list of Maps when you start a server.

This would require us to create some kind of metadata for mods that specify that they are “maps”, that the game can detect – we do currently not have any plans on doing this, but we are keeping a keen eye on this!

Sandbox

Due to security, we sandboxed what Lua functions you can use. Mainly OS and File related functionality, you can still read and write to files, but only using the API that we have created that interacts inside the modding folder.

Creating custom maps

A comprehensive Video guide has been made by TerrorSoul which can be watched here:

Load video

YouTube

YouTube might collect personal data. Privacy Policy

ContinueDismiss