Mod Developers Guide: Difference between revisions
No edit summary |
No edit summary |
||
(17 intermediate revisions by 3 users not shown) | |||
Line 7: | Line 7: | ||
To make your own mod, follow these steps: | To make your own mod, follow these steps: | ||
# Open the page https://www. | # Open the page https://www.warzone.com/EnableModDevelopment to enable mod development for your Warzone account. | ||
# Obtain the source code to an example mod, such as the Randomized Wastelands Mod from https://github.com/FizzerWL/RandomizedWastelandsMod. Download the lua files to a folder on your device. | # Download the [[Standalone Client]] and run it. | ||
# Launch the | # 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. | # 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 2. | # Provide path to your folder with lua files that you downloaded in step 2. | ||
# Click Submit to create the mod. | # Click Submit to create the mod. | ||
# From the main menu, click "Custom | # 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. | # 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! | # 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! | ||
Line 20: | Line 21: | ||
Be sure to read the rest of this page for essential information on mod development. | 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 == | == 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]]. | For full details on what hooks are available, see [[Mod Hooks]]. | ||
Line 43: | Line 48: | ||
This is useful to assist in debugging. | 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. For this reason, it's easier to debug mods in single-player before moving to multi-player. | 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 == | == Global State == | ||
Line 49: | Line 54: | ||
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. | 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. | 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 expliclty 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 == | == Tips == | ||
Be sure to test in multi-player! When running Server code in multi-player, your lua code runs on the | 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 | == See Also == | ||
* [[Mod API Reference]] | * [[Mod API Reference]] | ||
* [[Mod Backwards Compatibility]] | |||
* [[Promoted Mods]] | |||
* [[Mod Hooks]] | |||
* [[Mod Game Data Storage]] | |||
[[Category:Mod Developers Guide]] |
Revision as of 22:33, 17 September 2019
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.
Getting started creating a mod
To make your own mod, follow these steps:
- 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 2.
- 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!
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 Server_StartGame
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 require('Utilities')
at the top of another file to include it (omit the .lua
).
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 print
function. For example: print("Hello, world!")
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 expliclty 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.