Map Scripting

This is a introductory guide to creating a map script that runs along your config. A map script is essentially just a Lua script that runs along with your config.

This will require Garry's Mod Lua knowledge.

Refer to the Garry's Mod wiki for functions, reference, and tutorials.

A map script can be used to make easter eggs, modify how the game is ran, edit music, or even adding your very own spawning system.

---

Table of Contents

• Setting Up
• Hooks, functions, and variables
• Tips and Tricks
• Advanced Map Scripting
• Reference/Copy-paste snippets

---

Setting Up

A map script is a single .lua file that will run when the config tied to it is loaded and the loader pressed Yes to load map script. The Lua file must be called the same thing as your map, with the exception of the Workshop ID. It needs to be placed in /lua/nzmapscripts/ It should look something like:

lua/nzmapscripts/gm_map_name;ConfigName.lua

The base contents of the file should look something like this:

local mapscript = {}

-- Any function added to this table will automatically get hooked to the hook with the same name
function mapscript.OnGameBegin()
	-- E.g. this function will run with the OnGameBegin hook
end

-- Always return the mapscript table. This gives it on to the gamemode so it can use it.
return mapscript

Remember to ALWAYS return the mapscript table on which all your functions are stored!

You will need to enable Map Script in the Map Settings Tool for the map script to load next time the config is loaded.

---

Hooks, Functions, Variables

When the map script table is returned, any and all functions in it are hooked to their corresponding hooks. If you do not know what hooks do, look on the official Garry's Mod wiki.

E.g. a function like this:

mapscript.PlayerSpawn(ply)

end

will run every time a player spawns. It is the exact same as doing

hook.Add("PlayerSpawn", "SomeID", function(ply)

end)

Except it is automatically hooked and unhooked as the map script is loaded and unloaded. It is recommended you do not use hook.Add, but instead create functions on the mapscript table instead. This ensures the hooks are not randomly left over, even after the map script is unloaded, which could potentially harm the next config loaded.

Note that only functions on the table returned are hooked. Variables are not, so storing variables like mapscript.Var = 2 is completely safe, however it is recommended to use local var = 2 instead.

There are some specific fields on the map script table that will behave in a special way.

• mapscript.ScriptLoad() & mapscript.ScriptUnload()

These functions run the moment the script is loaded and unloaded respectively. The ScriptLoad function isn't recommended to be used for spawning entities, as they will just be cleaned up when the game cleans up the map, however ScriptUnload is really useful for cleaning up entities, hooks, or timers etc. that might be left over. Make sure your script properly cleans up after itself!

---

Tips and Tricks

• Map Scripts should always clean up after themselves.

Hooks (hook.Add's), timers, global functions, and changes to global variables will persist after the script is unloaded. Make sure to clean these up in the ScriptUnload function! This includes changes made to global variables, such as nZombies gamemode data.

• Map Scripts provide full Lua freedom

This means that you can script anything you want into it, even an entire gamemode. However it also means that you will get the ability to kick, ban, use HTTP, and other potentially malicious utilities. Make sure to make your code easy to read and provide an accurate description in the Map Script Description in the Map Settings Tool!

• Utilize the various nZombies map script features

You can use the nzEE.Major system to make a multi-step Easter Egg, use nz_script_soulcatchers, create items players can find and pick up, or even add buildables such as the shield! See Advanced Map Scripting for guides on how to do these things, or Reference/Copy-paste Snippets for quick reference and templates.

---

Advanced Map Scripting

Reference/Copy-paste Snippets