Modding Guide

This article may be out of date. It was last updated for 1.1.5.

This article is a Stub. You can help by expanding it

File Structure & Overrides

You can create a mod by placing files that mimic the directory structure of the game in the mod directory. The game will load these files in preference to the the normal ones.

So to create a mod called "TestMod" that replaces /textures/blocks/tex0.tga , create a file called tex0.tga (or .png or .jpg for textures) and place it in /mods/MODNAME/textures/blocks/tex0.tga . Done!

A notable exception is .lua files which will not be replaced. Instead you will have to inject your code. This is done so that updates to the base game don't break script mods, and that modders don't have to reimplement base game code. Also user settings files in the settings/ will not be replaced

Injecting Lua Code

When making a mod script you must make a mods/MODNAME/scripts/server_scripts.txt

and/or a mods/MODNAME/scripts/client_scripts.txt
for scripts to be executed on the client/server respectively. This file is just a list of the script files that you want in your mod in the order you want them to be loaded. Scripts are executed immediately when loaded.

Many functions in the base game have hooks that you can access by adding a function to a relevant table. For instance, in scripts/common/define_weapons.lua

there is a section that reads:

	-- Call the user callbacks
	if (defineWeaponsUserCallback) then
		for i = 1,#defineWeaponsUserCallback do
			if (type(defineWeaponsUserCallback[i][2]) == 'function') then
				defineWeaponsUserCallback[i][2](BlockTypes, ItemTypes);
			end
		end
	end

This means in your mod you can write your own function and have it accessed when the callback is called by the base game:

function myWeaponMod (BlockTypes, ItemTypes)
	-- Your mod goes here
end

-- Add it to the callbacks table
if (defineWeaponsUserCallback == nil) then defineWeaponsUserCallback = {} end
defineWeaponsUserCallback[#defineWeaponsUserCallback+1] = { "myWeaponMod | my description/documentation ", myWeaponMod };

Also note that the server has "--strictlua" set to on, but the client has it set to off. This means that if the server hits a lua error it'll shutdown and log the error in your logs directory. The client will not shutdown.

This section is a Stub. You can help by expanding it

Adding new Buildings - Lotpacks

Main article: LotPack

You can make your own buildings and save them as templates but these are only available to you.

The idea behind LotPacks is that you can bundle heaps of buildings together in one easy package that can be grabbed off the workshop. LotPacks don't change your game's checksum so you can play in multiplayer with players that have different LotPacks installed. You can only use buildings that are installed on the server though.

The game comes with a LotPack already - vanilla, and can be found in /lots/packs/vanilla . A pack consists of a text file with definitions and a directory full of .lot files.

To generate a .lot file stand in the lot you want to save and enter: /lot save DIR FILENAME

where DIR is the current facing of the lot (N,S,E,W) For example: /lot save n test

Will create a test.lot in your lots/ directory

You can also use lots created from saved templates! Go into /lots/template/player<your steamId32>/

and there is already a .lot file and a text file with the lines you need to copy into a definition file!

Nikolai's LotPack Guide

Nikolai has made a *very* detailed LotPack guide here: https://steamcommunity.com/sharedfiles/filedetails/?id=1399694457

General Curmudgeon's Video

A video of General Curmudgeon creating and uploading a LotPack to the workshop https://www.youtube.com/watch?v=L3DVhESic20

Uploading to Steam Workshop

Smack your mod into the /mods/upload directory and edit upload.txt. Then run Voxel Turf from Steam, this will upload the mod on startup. If you are using a preview image it is best to put it in the same directory as upload.txt and invoke it directly.

Links

Voxel Turf Workshop on Steam