Editing Mod Developers Guide

This page describes information necessary for making [[Mods]].

This guide assumes that you know the Lua programming language.  If you've worked with other languages, such as Javascript, Lua should be very easy to learn.  Many tutorials are available on the internet if you search for them.

Note that you must be a Warzone [[member]] to develop mods, as mods are a member feature.

== Getting started creating a mod ==

There are two ways to load mod code into Warzone: Using the Standalone Client, or directly uploading from your editor.  Uploading from your editor is the preferred way since it allows for more rapid iteration.  However, it also requires an extension to your editor, which only exists for VS Code.  If you want to develop from an editor other than VS Code, or if you want to develop without an active internet connection, you should use the Standalone Client method.

=== Developing with the Standalone Client ===

# Open the page https://www.warzone.com/EnableModDevelopment to enable mod development for your Warzone account.
# Download the [[Standalone Client]] and run it.
# Obtain the source code to an example mod, such as the Randomized Wastelands Mod from https://github.com/FizzerWL/ExampleMods/tree/master/RandomizedWastelandsMod.  Download the lua files to a folder on your device. (The easiest way is to use Github's "Download zip" button if you're not a git user)
# Launch the Standalone Client, sign in.  Click the "Mod Development Console" button.  You can also use the hotkey Ctrl+Shift+M to bring up this dialog any time, and also note that this dialog can be docked to sides of your screen if you wish.
# Click the "Create New Mod" button and give your mod a name.
# Provide path to your folder with lua files that you downloaded in step 3.
# Click Submit to create the mod.
# From the single-player main menu, click "Custom Game", then scroll down and click Change Mods.
# You should see the mod you created here.  Check the box to turn it on and click Submit.
# If you've cloned the Randomized Wastelands mod, you'll also need to turn on wastelands if you want it to do anything.  You can also turn off fog to more easily see its effects.  Create the game, and see the wastelands be adjusted!

Now you can make modifications to the lua code, press the "Reload code" button and try them out! 

=== Developing with direct upload from your editor ===

# Open the page https://www.warzone.com/EnableModDevelopment to enable mod development for your Warzone account.
# Install VS Code from https://code.visualstudio.com/ 
# Obtain the source code to an example mod, such as the Randomized Wastelands Mod from https://github.com/FizzerWL/ExampleMods/tree/master/RandomizedWastelandsMod.  Download the lua files to a folder on your device. (The easiest way is to use Github's "Download zip" button if you're not a git user)
# Download the Warzone Mod Helper VS Code extension VSIX file from https://github.com/FizzerWL/WarzoneModHelper/releases.  Install it by launching VS Code, pressing Ctrl+Shift+P, entering "Install from VSIX" and selecting the VSIX file you downloaded.
# (optional) Install the Lua IDE extension: https://marketplace.visualstudio.com/items?itemName=sumneko.lua
# Open the Mod Development Console at https://www.warzone.com/Mods/Develop
# Click the "Create New Mod" button and give your mod a name.  Ensure the "Development" box is checked.  After creating it, click "Edit" next to it and make note of your Mod ID.
# In VS Code, open the RandomizedWastelandsMod folder you downloaded earlier.  Open one of the lua files in this folder.
# Visit https://www.warzone.com/API/GetAPIToken and copy your API Token to the clipboard.
# In VS Code, press Ctrl+Shift+P and select "Upload Mod".  Enter your Mod ID you noted earlier, and paste your API Token when prompted.  Ensure it says "Mod updated successfully" in the bottom right corner.
# Now that your mod is updated, let's run it. Visit https://www.warzone.com/SinglePlayer?CustomGame=1 and click Change Mods.  You should see the mod you created here.  Check the box to turn it on and click Submit.
# If you've cloned the Randomized Wastelands mod, you'll also need to turn on wastelands if you want it to do anything.  You can also turn off fog to more easily see its effects.  Create the game, and see the wastelands be adjusted!

Now you can make modifications to the lua code, press and invoke the "Upload Mod" feature again to try them out!

Be sure to read the rest of this page for essential information on mod development.

== Video Tutorial == 

If you prefer to learn via video, check out this YouTube tutorial on how to make a mod:  https://www.youtube.com/watch?v=mwVDv5PXyrg

== Hooks ==

Warzone will call into a mod's lua code using what are called '''hooks'''.  For example, it will call a hook named <code>Server_StartGame</code> when a game is beginning and give your mod an opportunity to change things about how the map is set up.

For full details on what hooks are available, see [[Mod Hooks]].

== Sharing code with "require" ==

You can call the "require" function to share code between different lua files.  

For example, if you have utility functions in a file named 'Utilities.lua', simply write <code>require('Utilities')</code> at the top of another file to include it (omit the <code>.lua</code>).

Note that all lua files must be in the same directory (subdirectories are currently not supported).

== Printing Output ==

In lua, you can print output with lua's <code>print</code> function.  For example: <code>print("Hello, world!")</code>

To see this output, open the Mod Development Console (Ctrl+Shift+M) and click View Mod Output.  Then create a single-player game using that mod, and when the print statement runs, you'll see the output appear in this window in real-time.

This is useful to assist in debugging.

In multi-player games, the output of mods that run on the server is currently not viewable anywhere, unless the mod crashes which will display recently printed lines in a report in the Mod Development Console.  For this reason, it's easier to debug mods in single-player before moving to multi-player.

== Global State ==

Never assume any state will persist, unless specifically called out in the documentation.  For example, don't write to a global variable in one hook and access it in another.

If you try to in a single-player game, you may find that global state does persist.  However, don't be tempted to rely on this, since globals are always wiped in multi-player, and globals will also get wiped in single-player if someone saves and re-loads their game.  Therefore, ensure you code as if globals will never persist between hook calls, except where explicitly allowed.

== Data Storage ==

Mods can store public, private, or player-specific data within a game.  See [[Mod Game Data Storage]] for details.

== Mod Timeout ==

Note that if a game takes more than a minute to advance, the mods will time out and the game will not advance.  This time counts all mods enabled for that game combined, so mod authors should work to ensure their mods are efficient as possible.

If a game times out more than 10 times in a row, Warzone will end the game automatically.

== Tips ==

Be sure to test in multi-player!  When running Server code in multi-player, your lua code runs on the Warzone server which uses a different lua engine.  In theory, everything should be the same, but there is still an opportunity for differences.  To ensure everything you're doing works, it's recommended you test in multi-player, not only before you're ready to go public, but also occasionally during your development process.

Note that all mods uploaded to Warzone must use the MIT license, or something equally or more permissable.  Any mods without a license specified are assumed to be using MIT.

== See Also ==
* [[Mod Security]]
* [[Mod API Reference]]
* [[Mod Backwards Compatibility]]
* [[Public Mods]]
* [[Mod Hooks]]
* [[Mod Game Data Storage]]
* [https://discord.gg/hqGkVXagyt Warzone Mod Makers Discord]

[[Category:Mod Developers Guide]]