-
Notifications
You must be signed in to change notification settings - Fork 51
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.
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 mapscriptRemember 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.
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)
endwill 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!
- 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 below to learn how to do these things, or Reference/Copy-paste Snippets for quick reference and templates.
This page contains guides on how to use the various nZombies-specific scripting features and entities. For quick reference and templates, see Reference/Copy-paste Snippets. For guide on how to setup the map script itself, refer to the beginning of this page.
The Item Carry System is the system that handles inventory, similar to objects found in many of the later Zombies Maps that are used for Easter Eggs. It enables you to create objects that act as an item, with icon, text, functions, and registration of items.
An ItemCarry object is created with this constructor:
local item = nzItemCarry:CreateCategory("id")Provide a unique ID for each item that needs to be treated seperately.
The object can then be manipulated with a set of functions (See Reference/ItemCarry). After setting all desired variables, call this function to network it:
item:Update()This will network all changed variables that are needed by the client, such as text and icon. You also need to call this every time you change any of these, if you so choose to do that.
Any item can be registered to the object, meaning these items will display the text that was set in the object, and will, when picked up with E (Unless overwritten with ItemCarry/SetPickupFunction), disappear and give the player the item into his inventory.
An item can be registered like this:
prop = ents.Create("nz_script_prop")
prop:Spawn()
item:RegisterEntity( prop )It is recommended to do this in ItemCarry/SetResetFunction which gets called whenever a player carrying the item leaves and the item is not set to drop. If you spawn the prop in this function, you can trigger it on game begin like this:
function mapscript.OnGameBegin()
item:Reset()
endBuildables ties into the Item Carry System a lot, as each part is defined as a unique ItemCarry object (by ID). It is required to have created those ItemCarry objects as well, if you wish for the buildable to be possible to make.
A buildable is defined by a table which contains a model, a position relative to its own table, an angle relative to the table, and a list of parts. It can also contain functions used to define what the item itself does. This is how it looks:
{
model = "model/of/finished/item.mdl",
pos = Vector(), -- (Relative to tables own pos)
ang = Angle(), -- (Relative too)
parts = {
[id1] = {submaterials}, -- Submaterials to "unhide" when this part is added
[id2] = {submaterials}, -- id's are ItemCarry object IDs
[id3] = {submaterials},
-- You can have as many as you want
},
partadded = function(table, id, ply) -- When a part is added (optional)
end,
finishfunc = function(table) -- When all parts have been added (optional)
end,
usefunc = function(table, ply) -- When it's completed and a player presses E (optional)
end,
text = "string" -- Text to display when player is looking (after finished) (optional)
}It creates a prop by the model defined in the model field, but sets all submaterials to invisible. Then, as a part from the parts subtable is added, the submaterials of the IDs listed in that table gets reset to become visible again. This means you "build" the prop texture-by-texture.