War.app Wiki - User contributions [en]

Feature Request Forum

2024-08-21T19:13:01Z

Kaninchen: /* Feature Requests and Mods */ Invite Revision: Changed it to be the same one as listed in https://www.warzone.com/wiki/Mod_Developers_Guide

The '''Feature Request Forum''' is your place to vote on what features you think Warzone should implement.

==How it works ==

Any player can create a thread on this forum, which is then called a ''feature request'' or an ''idea''. Any player with votes can then vote on this idea, and the ideas with the most votes are displayed at the top of the forum by default. You can also sort ideas by how recently they were added, or the most recent discussion reply.

Like any other Warzone forum, players can also give thumbs-up and thumbs-down to feature requests. However, these only affect its visibility and aren't official votes for it to be implemented.

Players have votes based on their level, with votes unlocking at level 5, 10, 20, 30, 40, 50, 60, 62, 64, 66, and a bonus vote for members. You can place up to three votes for any one idea. Votes you cast are tied to your Warzone account and are public, so you can always see who voted on each individual feature request.

At any time, you can always change your mind and take votes out of one idea and put them into another.

If a feature you voted for is implemented or declined by Warzone, then you'll get your votes back and are free to put them into another idea.

Note that any replies to a feature request are not considered part of the core idea. When you vote, you're only voting for the features outlined in the top post of the forum. Any replies are just considered discussion surrounding the idea. If you need to augment or later change an idea after it's posted, you should create a new thread and encourage players to move their votes into the new one if they like that one more.

Any Warzone account that is inactive for more than 30 days will automatically have its votes removed from all ideas. If they sign in again, they're free to put their votes back.

==Criteria for a new feature==

While it would be great to implement every feature suggested, this simply isn't possible. There's no magic number of votes that a feature needs to get accepted; the point of voting is to see which features are most in-demand. This is also important to avoid design-by-committee syndrome, since sometimes trying to please everyone ends up pleasing no one.

Features are typically judged based on these criteria:

* How good of a fit the feature is for Warzone's theme and direction.
* How much effort the feature takes to implement and maintain.
* How many votes the feature gets (i.e. how in-demand it is).
* Additionally, sometimes a feature can get implemented just because it happens to fall into an area of code that is being worked on for something else.

== Multi-Ideas ==

A single idea on the Feature Request forum should generally contain a single idea/feature/improvement. Sometimes players create an idea that mentions multiple features. Doing this is not disallowed, however, it is risky, and may not get you what you want.

The advantage of creating a single idea with multiple features is that it appears more attractive to other voters. If any one of your features appeals to a player, they're likely to vote on it, and therefore you're likely to get more votes.

The problem comes when one or some of the features is implemented, but not all. After this is done, the Warzone developers will simply mark it as Completed, even though only part of it was done.

The reasoning is that if they leave the idea as it is, it would leave features up for voting that are completed. If they edited the idea to remove the features implemented, leaving the ones not implemented, it would invalidate the vote numbers since there's no way of knowing what features people really wanted when they put their votes into that idea.

Therefore, these ideas will just be closed as completed if any part of them is implemented. After this is done, everyone who voted for them will get their votes back. If the voters still desire a part of the idea that was not implemented, they can create a new idea specific to that part, and put their freshly acquired votes into that one one.

== Feature Requests and Mods ==

Sometimes, people submit ideas to the forum that can be implemented with Warzone's [[Mod Framework Capabilities|mod framework]]. This section outlines guideline for whether or not your idea belongs on the Feature Request Forum:

First, if your idea ''cannot'' be implemented using the mod framework, then it's OK to submit to it the Feature Request forum. You can either word it as a normal feature, or word it as an idea to add support to the mod framework.

If your idea ''can'' be implemented using the mod framework, next determine if a mod already exists to accomplish it. If a mod already exists, then it's OK to submit it to the Feature Request forum as an idea to convert a mod into a built-in feature. Be sure to note in the description that your idea is to convert an existing mod into a built-in feature. Note that these types of ideas will only be considered if the mod is already pretty popular.

If your idea can be implemented using the mod framework, but no mod exists yet, you should ''not'' submit it as an idea to the Feature Request forum. The next step in getting your idea to become reality is to get it created as a mod. the Feature Request forum is not the appropriate place to pitch to mod developers, as the Feature Request forum is aimed at pitching your idea to the Warzone developers. Instead, if you can't create the mod yourself or need help doing so, try the [https://www.warzone.com/Forum/f6-Programming Warzone Programming Forums] or [https://discord.com/invite/hqGkVXagyt Wazone Mod-Making Discord].

== Multi-account voting is not allowed ==

If you have multiple Warzone accounts, be sure to only cast votes from your main account and never your alts. If you are caught voting on multiple accounts, you may face punishment up to and including having all of your accounts banned.

[[Category:Warzone]]

Feature Request Forum

2024-08-21T15:27:00Z

Kaninchen: /* Feature Requests and Mods */ Added links to Programming Forum and Mod Making Discord

The '''Feature Request Forum''' is your place to vote on what features you think Warzone should implement.

==How it works ==

Any player can create a thread on this forum, which is then called a ''feature request'' or an ''idea''. Any player with votes can then vote on this idea, and the ideas with the most votes are displayed at the top of the forum by default. You can also sort ideas by how recently they were added, or the most recent discussion reply.

Like any other Warzone forum, players can also give thumbs-up and thumbs-down to feature requests. However, these only affect its visibility and aren't official votes for it to be implemented.

Players have votes based on their level, with votes unlocking at level 5, 10, 20, 30, 40, 50, 60, 62, 64, 66, and a bonus vote for members. You can place up to three votes for any one idea. Votes you cast are tied to your Warzone account and are public, so you can always see who voted on each individual feature request.

At any time, you can always change your mind and take votes out of one idea and put them into another.

If a feature you voted for is implemented or declined by Warzone, then you'll get your votes back and are free to put them into another idea.

Note that any replies to a feature request are not considered part of the core idea. When you vote, you're only voting for the features outlined in the top post of the forum. Any replies are just considered discussion surrounding the idea. If you need to augment or later change an idea after it's posted, you should create a new thread and encourage players to move their votes into the new one if they like that one more.

Any Warzone account that is inactive for more than 30 days will automatically have its votes removed from all ideas. If they sign in again, they're free to put their votes back.

==Criteria for a new feature==

While it would be great to implement every feature suggested, this simply isn't possible. There's no magic number of votes that a feature needs to get accepted; the point of voting is to see which features are most in-demand. This is also important to avoid design-by-committee syndrome, since sometimes trying to please everyone ends up pleasing no one.

Features are typically judged based on these criteria:

* How good of a fit the feature is for Warzone's theme and direction.
* How much effort the feature takes to implement and maintain.
* How many votes the feature gets (i.e. how in-demand it is).
* Additionally, sometimes a feature can get implemented just because it happens to fall into an area of code that is being worked on for something else.

== Multi-Ideas ==

A single idea on the Feature Request forum should generally contain a single idea/feature/improvement. Sometimes players create an idea that mentions multiple features. Doing this is not disallowed, however, it is risky, and may not get you what you want.

The advantage of creating a single idea with multiple features is that it appears more attractive to other voters. If any one of your features appeals to a player, they're likely to vote on it, and therefore you're likely to get more votes.

The problem comes when one or some of the features is implemented, but not all. After this is done, the Warzone developers will simply mark it as Completed, even though only part of it was done.

The reasoning is that if they leave the idea as it is, it would leave features up for voting that are completed. If they edited the idea to remove the features implemented, leaving the ones not implemented, it would invalidate the vote numbers since there's no way of knowing what features people really wanted when they put their votes into that idea.

Therefore, these ideas will just be closed as completed if any part of them is implemented. After this is done, everyone who voted for them will get their votes back. If the voters still desire a part of the idea that was not implemented, they can create a new idea specific to that part, and put their freshly acquired votes into that one one.

== Feature Requests and Mods ==

Sometimes, people submit ideas to the forum that can be implemented with Warzone's [[Mod Framework Capabilities|mod framework]]. This section outlines guideline for whether or not your idea belongs on the Feature Request Forum:

First, if your idea ''cannot'' be implemented using the mod framework, then it's OK to submit to it the Feature Request forum. You can either word it as a normal feature, or word it as an idea to add support to the mod framework.

If your idea ''can'' be implemented using the mod framework, next determine if a mod already exists to accomplish it. If a mod already exists, then it's OK to submit it to the Feature Request forum as an idea to convert a mod into a built-in feature. Be sure to note in the description that your idea is to convert an existing mod into a built-in feature. Note that these types of ideas will only be considered if the mod is already pretty popular.

If your idea can be implemented using the mod framework, but no mod exists yet, you should ''not'' submit it as an idea to the Feature Request forum. The next step in getting your idea to become reality is to get it created as a mod. the Feature Request forum is not the appropriate place to pitch to mod developers, as the Feature Request forum is aimed at pitching your idea to the Warzone developers. Instead, if you can't create the mod yourself or need help doing so, try the [https://www.warzone.com/Forum/f6-Programming Warzone Programming Forums] or [https://discord.gg/p5BuCQBtMH Wazone Mod-Making Discord].

== Multi-account voting is not allowed ==

If you have multiple Warzone accounts, be sure to only cast votes from your main account and never your alts. If you are caught voting on multiple accounts, you may face punishment up to and including having all of your accounts banned.

[[Category:Warzone]]

Mod Security

2024-06-01T14:35:58Z

Kaninchen: /* SendGameCustomMessage */ grammatical error fixed

In a [https://en.wikipedia.org/wiki/Client%E2%80%93server_model Client-Server Relationship] it is very important that the Server checks '''everything''' the client sends to it.
This is because someone who is proficient in programming (a Hacker for example) can modify any data the client sends to the server.
It's therefore important to employ a [https://en.wikipedia.org/wiki/Zero_trust_security_model zero trust policy] when creating mods

== Possible security weak points ==
=== SendGameCustomMessage ===
[[Mod_API_Reference:ClientGame|Main article]] 
An attacker can modify the payload in any way they desire. Let's take a Diplomacy Mod for example, where the Host can decide which player should win at any time. A naive approach using [[Mod_Hooks#Server Hooks|Server_GameCustomMessage(...)]] would be
<pre>
function Server_GameCustomMessage(game, playerID, payload, setReturn)
if payload.type == "makePlayerWin" then
makePlayerWin(game, payload.playerid)
-- makePlayerWin(game, playerid) could be a function that later on adds an order which sets the territory owner of every territory to the player associated with the supplied playerid
elseif ... -- other functionality
end
</pre>
An attacker with the associated playerid of (for example) '''12345''' who analyzed the source code of the mod (remember, the source code of every mod is publicly available on [https://github.com/ Github]) can now see that the Hook never actually checks if the client who sent the CustomServerMessage is really the host (indicated by the '''playerID''' parameter of the '''Server_GameCustomMessage''' function). The attacker could therefore send following Lua table to the Server:
<pre>
{
type = "makePlayerWin",
playerid = 12345
}
</pre>
and automatically win as soon as the turn advances. The actual process is more complicated but that's about how an attacker could use the security vulnerability to gain a decisive advantage. 
The obvious and right solution is to additionally check inside the ''if condition'' if the '''playerID''' supplied to '''Server_GameCustomMessage''' belongs to the host.
<pre>
function Server_GameCustomMessage(game, playerID, payload, setReturn)
if payload.type == "makePlayerWin" and game.ServerGame.Settings.StartedBy == playerID then
makePlayerWin(game, payload.playerid)
elseif ... -- other functionality
end
</pre>
this now makes the functionality secure against custom client data crafted by an attacker

===GameOrderCustom===
[[Mod_API_Reference:GameOrderCustom|Main article]] 
The Server [[Mod Hooks]] which accept the '''GameOrderCustom''' should only depend on the payload, as hackers may, as with '''SendGameCustomMessage''', modify all fields ('''Message''', '''Payload''', '''CostOpt''' and '''OccursInPhaseOpt''') to gain an advantage. Note that, since hackers can modify '''Payload''' too, it is essential to verify that it was even possible for the player to send the received '''Payload''' in the first place. All other Fields should be recreated by the Server. 

[[Category:Mod Developers Guide]]

Mod Developers Guide

2024-04-18T17:07:31Z

Kaninchen: added Mod Security to See Also, please see discussion to discuss if it should get its own section

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, 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]]

Talk:Mod Developers Guide

2024-04-18T17:07:18Z

Kaninchen: added talk + question

== Should [[Mod Security]] have it's own section? ==
I have linked the [[Mod Security]] wiki page, but since safety is usually priority number one, I wanted to ask if we should add its own section for it with a short description and link to the main article.

Mod API Reference:GameOrderCustom

2024-04-18T16:58:22Z

Kaninchen: Forgot to remove that part yesterday

'''GameOrderCustom''': Subclass of [[Mod API Reference:GameOrder|GameOrder]]. This order does nothing on its own, but it can be used by mods for custom orders. GameOrderCustom is typically sent up from clients to the server, in contrast to [[Mod API Reference:GameOrderEvent|GameOrderEvent]] which is typically sent down from the server to clients.

In order to make sure your mod doesn't break when used in conjunction with other mods, you should prepend a unique string (such as the name of your mod plus an underscore) to the Payload. When reading a GameOrderCustom, check if the payload starts with your unique string, and if it doesn't it means this order isn't one your mod made and you should ignore it. If you act on another mod's messages, or skip them, it will create unexpected behavior for your mod or another mod.

* '''Message''' ''string'': The message that will appear in the orders list. This is what players see.
* '''Payload''' ''string'': Data the mod wishes to store along with this order, but does not want players to see.
* '''CostOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'': Defines how much gold the order will cost the player in a [[Commerce]] game. This should only be set in commerce games. If CostOpt is set to nil, then it's assumed to be the same as having a cost of 0. The game will take care of taking the player's resources away correctly, both on the client and server, when inserting an order with a cost into their orders list.
* '''OccursInPhaseOpt''' ''[[Mod API Reference:Nullable|Nullable]]<[[Mod API Reference:TurnPhase|TurnPhase]] (enum)>'': If not nil, then orders will be forced to be placed in this phase. Players will not be able to move this order above an order of a lower phase, or below an order of a higher phase. Added in v5.22.0.

[[Mod_Security|Mod security]] should be applied to [[Mod_Hooks|Mod Hooks]] working with this card

* '''WL.GameOrderCustom.Create'''('''playerID''' ''[[Mod API Reference:PlayerID|PlayerID]]'', '''message''' ''string'', '''payload''' ''string'', '''costOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'') (static) returns [[Mod API Reference:GameOrderCustom|GameOrderCustom]]:
[[Category:Mod API Reference]]

Mod Hooks

2024-04-18T16:55:03Z

Kaninchen: /* Server Hooks */ changed the location for the Mod Security hint so there isn't a random dot floating around

Warzone will call into a [[Mods|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.

If you provide a function with the name listed here, and in a file with the name listed here, it will be called as explained. Note that both the function name and the file name are case-sensitive.

== Server Hooks ==

*Server_Created (Server_Created.lua)
** Called in every game when the game is first created. In multi-player, this means it's called before players even accept or join the request for the game. This is the only place that game settings can be changed.
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameSettings|GameSettings]]: (writable) Allows your mod to change the game's settings.

* Server_StartDistribution (Server_StartDistribution.lua)
** Called in any game set to manual territory distribution before players select their picks. This hook is not called in any game configured to automatic territory distribution. This is called after the standing has been built (wastelands and pickable territories have already been placed and initial cards have already been given out.)
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameStanding|Standing]]: (writable) Allows your mod to change the standing before players see it. For example, a mod could change the number of armies on any territory, control which territories are pickable, or define what cards each player starts with.

* Server_StartGame (Server_StartGame.lua)
** Called when the game starts the first turn. In a manual territory distribution game, this is called after all players have entered their picks. In an automatic territory distribution game, this is called when the game starts. This is called after the standing has been built (picks have been given out)
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameStanding|Standing]]: (writable) Allows your mod to change the the standing before players see it. For example, a mod could change the number of armies on any territory, control which players control which territories, or define what cards each player starts with.

* Server_AdvanceTurn_Start (Server_AdvanceTurn.lua)
** Called whenever the server begins processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the start of a turn, before any player's orders are added. All of the Server_AdvanceTurn_* hooks share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

* Server_AdvanceTurn_Order (Server_AdvanceTurn.lua)
** Called whenever the server processes a player's order during a normal turn (not territory picking). This gives mods an opportunity to skip the order, modify it, or let it process normally. This hook is called after the results of the order have been computed, but before it has been applied to the [[Mod API Reference:GameStanding|standing]]. For example, when looking at an [[Mod API Reference:GameOrderAttackTransfer|Attack/Transfer order]] that represents a territory being captured, the standing will still show the territory as uncaptured. All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameOrder|GameOrder]]: The order being processed. (read-only)
# [[Mod API Reference:GameOrderResult|GameOrderResult]]: The result of the order being processed. This is writable, so mods can change the result. Currently, only [[Mod API Reference:GameOrderAttackTransferResult|GameOrderAttackTransferResult]] has writable fields.
# skipThisOrder: A function that you can call to indicate that this order should be skipped. This should be called with one of three values, listed below. If it is called multiple times, the last call overrides the previous calls.
## WL.ModOrderControl.Keep: Indicates this order should be processed normally. This is the default value, and all orders will default to Keep if skipThisOrder is not called.
## WL.ModOrderControl.Skip: Indicates this order should be skipped. It won't appear in the orders list at all and it will be as if the order never existed. A [[Mod API Reference:GameOrderEvent|GameOrderEvent]] will be written into the orders list to tell the player who entered this order that their order was skipped.
## WL.ModOrderControl.SkipAndSupressSkippedMessage: Same as Skip, except that the GameOrderEvent is not written. This should be used with care, as players will want to know why their order didn't appear in the orders list. This should only be used if you use some other mechanism to explain to the player why their order was not present, or if this is an order that your mod inserted and therefore no players were expecting it.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function. Optionally, you can also pass "true" as a second argument to this function to make your new order get skipped if the order this hook was called on gets skipped, either by your mod or another mod. This second argument was added in [[Mod_API_Reference:IsVersionOrHigher|5.17.0]].

* Server_AdvanceTurn_End (Server_AdvanceTurn.lua)
** Called whenever the server finishes processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the end of a turn, after all player's orders are added. All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

* Server_GameCustomMessage (Server_GameCustomMessage.lua)
** Called whenever your mod calls [[Mod API Reference:ClientGame|ClientGame]].SendGameCustomMessage. This gives mods a way to communicate between the client and server outside of a turn advancing. Note that if a mod changes Mod.PublicGameData or Mod.PlayerGameData, the clients that can see those changes and have the game open will automatically receive a refresh event with the updated data, so this message can also be used to push data from the server to clients.
** [[Mod_Security|Mod security]] should be applied when working with this Hook
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:PlayerID|PlayerID]]: The ID of the player who invoked this call.
# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.
# setReturn: Optionally, a function that sets what data will be returned back to the client. If you wish to return data, pass a table as the sole argument to this function. Not calling this function will result in an empty table being returned.

== Client Hooks ==

* Client_PresentConfigureUI (Client_PresentConfigureUI.lua)
** Called when a player checks your mod on the Create Game page. If your mod has any configurable settings, you should create UI controls on the screen to allow players to configure them using the [[Mod API Reference:UI|UI API]]. Mods should also check the <code>[https://www.warzone.com/wiki/Mod_Game_Data_Storage Mod.Settings]</code> global to see if any settings are already defined, and if they are, default their UI state to match that.
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.

* Client_SaveConfigureUI (Client_SaveConfigureUI.lua)
** Called when a player submits the Create Game Mod page with your mod checked. If your mod presented any UI in Client_PresentConfigureUI, your mod should persist any settings into the <code>Mod.Settings</code> global during this hook. This is the only place that <code>Mod.Settings</code> should ever be written to.
** Arguments:
# alert: A function callback that takes a string. If the user has configured anything wrong with your UI, you can call this to notify them of their mistake. Calling this function will also abort the save.

* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)
** Called when a player opens the Game Settings panel of a game that has your mod included. If your mod has any configurable settings, you should read them out of the global <code>Mod.Settings</code> and show them to the player here using the [[Mod API Reference:UI|UI API]].
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.

* Client_PresentMenuUI (Client_PresentMenuUI.lua)
** If present, games with this mod enabled will have a new button on the menu. When the player clicks that button, this mod hook is invoked and the resulting UI will be shown to the player in a dialog. See [[Mod API Reference:UI|UI API]].
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.
# setMaxSize: Function mods can call to set the maximum size of the dialog. Pass two numbers: the width and the height. Note that screen sizes can vary a lot, so you can never be sure you'll get the size you request, so plan on making your UI work in all sizes.
# setScrollable: Function mods can call to set whether the dialog is scrollable horizontally or vertically. Pass two booleans: the first determines if it's horizontally scrollable, and the second determines if it's vertically scrollable. The default is false, true.
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.
# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

* Client_GameRefresh (Client_GameRefresh.lua)
** Invoked whenever the client gets data about this game from the server. This can be used to check for updated Mod.PublicGameData or Mod.PlayerGameData, documented at [[Mod Game Data Storage]]. The client refresh timing is different between single-player and multi-player, and in multi-player can also vary depending on the user's internet connection (such as whether they're connected by websocket, long polling socket, or normal polling). Therefore, a mod should never write code that breaks if Client_GameRefresh is called at unexpected times.
** Arguments:
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.

* Client_PresentCommercePurchaseUI (Client_PresentCommercePurchaseUI.lua)
** Invoked whenever the player clicks the "Build" button in a commerce game. This can be used to present UI to allow the player to spend their gold on things.
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.
# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

== Notes ==

Any hooks that start with <code>Server_</code> are run on the server in multi-player games, and on the client in single-player games.

No hooks have return values. Meaning, it doesn't matter if you return any values from your hook functions. Instead, the mod framework gives you callbacks to call to affect things. This is preferred over return values for a few reasons. First, it allows mods to call the callbacks early on or late on in their function, which can be easier than a return statement which must come at the end. Second, it allows mods to simply not call the callback, which can signal to Warzone that the mod doesn't care about the result of this. This can be important in some cases where multiple mods that define the same hook. Sometimes the mods instructions can conflict and Warzone must decide which to obey.

== See Also ==
* [[Mod Developers Guide]]
* [[Mod Game Data Storage]]
[[Category:Mod Developers Guide]]

Mod Hooks

2024-04-17T21:13:02Z

Kaninchen: /* Server Hooks */

Warzone will call into a [[Mods|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.

If you provide a function with the name listed here, and in a file with the name listed here, it will be called as explained. Note that both the function name and the file name are case-sensitive.

== Server Hooks ==

*Server_Created (Server_Created.lua)
** Called in every game when the game is first created. In multi-player, this means it's called before players even accept or join the request for the game. This is the only place that game settings can be changed.
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameSettings|GameSettings]]: (writable) Allows your mod to change the game's settings.

* Server_StartDistribution (Server_StartDistribution.lua)
** Called in any game set to manual territory distribution before players select their picks. This hook is not called in any game configured to automatic territory distribution. This is called after the standing has been built (wastelands and pickable territories have already been placed and initial cards have already been given out.)
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameStanding|Standing]]: (writable) Allows your mod to change the standing before players see it. For example, a mod could change the number of armies on any territory, control which territories are pickable, or define what cards each player starts with.

* Server_StartGame (Server_StartGame.lua)
** Called when the game starts the first turn. In a manual territory distribution game, this is called after all players have entered their picks. In an automatic territory distribution game, this is called when the game starts. This is called after the standing has been built (picks have been given out)
** Return value: None.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameStanding|Standing]]: (writable) Allows your mod to change the the standing before players see it. For example, a mod could change the number of armies on any territory, control which players control which territories, or define what cards each player starts with.

* Server_AdvanceTurn_Start (Server_AdvanceTurn.lua)
** Called whenever the server begins processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the start of a turn, before any player's orders are added. All of the Server_AdvanceTurn_* hooks share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

* Server_AdvanceTurn_Order (Server_AdvanceTurn.lua)
** Called whenever the server processes a player's order during a normal turn (not territory picking). This gives mods an opportunity to skip the order, modify it, or let it process normally. This hook is called after the results of the order have been computed, but before it has been applied to the [[Mod API Reference:GameStanding|standing]]. For example, when looking at an [[Mod API Reference:GameOrderAttackTransfer|Attack/Transfer order]] that represents a territory being captured, the standing will still show the territory as uncaptured. All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:GameOrder|GameOrder]]: The order being processed. (read-only)
# [[Mod API Reference:GameOrderResult|GameOrderResult]]: The result of the order being processed. This is writable, so mods can change the result. Currently, only [[Mod API Reference:GameOrderAttackTransferResult|GameOrderAttackTransferResult]] has writable fields.
# skipThisOrder: A function that you can call to indicate that this order should be skipped. This should be called with one of three values, listed below. If it is called multiple times, the last call overrides the previous calls.
## WL.ModOrderControl.Keep: Indicates this order should be processed normally. This is the default value, and all orders will default to Keep if skipThisOrder is not called.
## WL.ModOrderControl.Skip: Indicates this order should be skipped. It won't appear in the orders list at all and it will be as if the order never existed. A [[Mod API Reference:GameOrderEvent|GameOrderEvent]] will be written into the orders list to tell the player who entered this order that their order was skipped.
## WL.ModOrderControl.SkipAndSupressSkippedMessage: Same as Skip, except that the GameOrderEvent is not written. This should be used with care, as players will want to know why their order didn't appear in the orders list. This should only be used if you use some other mechanism to explain to the player why their order was not present, or if this is an order that your mod inserted and therefore no players were expecting it.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function. Optionally, you can also pass "true" as a second argument to this function to make your new order get skipped if the order this hook was called on gets skipped, either by your mod or another mod. This second argument was added in [[Mod_API_Reference:IsVersionOrHigher|5.17.0]].

* Server_AdvanceTurn_End (Server_AdvanceTurn.lua)
** Called whenever the server finishes processing a normal turn (not territory picking). This gives mods an opportunity to insert orders at the end of a turn, after all player's orders are added. All of the Server_AdvanceTurn_* turns share global state within a single turn, so global variables can be read and written reliably by mods.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# addNewOrder: A function that you can call to add a [[Mod API Reference:GameOrder|GameOrder]] to the start of the turn. You may call this function multiple times if you wish to add multiple orders. Pass a single GameOrder as the first argument to this function.

* Server_GameCustomMessage (Server_GameCustomMessage.lua)
** Called whenever your mod calls [[Mod API Reference:ClientGame|ClientGame]].SendGameCustomMessage. This gives mods a way to communicate between the client and server outside of a turn advancing. Note that if a mod changes Mod.PublicGameData or Mod.PlayerGameData, the clients that can see those changes and have the game open will automatically receive a refresh event with the updated data, so this message can also be used to push data from the server to clients.
** Arguments:
# [[Mod API Reference:Game|Game]]: Provides read-only information about the game.
# [[Mod API Reference:PlayerID|PlayerID]]: The ID of the player who invoked this call.
# payload: The data passed as the ''payload'' parameter to SendGameCustomMessage. Must be a lua table.
# setReturn: Optionally, a function that sets what data will be returned back to the client. If you wish to return data, pass a table as the sole argument to this function. Not calling this function will result in an empty table being returned.
**[[Mod_Security|Mod security]] should be applied when working with this Hook

== Client Hooks ==

* Client_PresentConfigureUI (Client_PresentConfigureUI.lua)
** Called when a player checks your mod on the Create Game page. If your mod has any configurable settings, you should create UI controls on the screen to allow players to configure them using the [[Mod API Reference:UI|UI API]]. Mods should also check the <code>[https://www.warzone.com/wiki/Mod_Game_Data_Storage Mod.Settings]</code> global to see if any settings are already defined, and if they are, default their UI state to match that.
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.

* Client_SaveConfigureUI (Client_SaveConfigureUI.lua)
** Called when a player submits the Create Game Mod page with your mod checked. If your mod presented any UI in Client_PresentConfigureUI, your mod should persist any settings into the <code>Mod.Settings</code> global during this hook. This is the only place that <code>Mod.Settings</code> should ever be written to.
** Arguments:
# alert: A function callback that takes a string. If the user has configured anything wrong with your UI, you can call this to notify them of their mistake. Calling this function will also abort the save.

* Client_PresentSettingsUI (Client_PresentSettingsUI.lua)
** Called when a player opens the Game Settings panel of a game that has your mod included. If your mod has any configurable settings, you should read them out of the global <code>Mod.Settings</code> and show them to the player here using the [[Mod API Reference:UI|UI API]].
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.

* Client_PresentMenuUI (Client_PresentMenuUI.lua)
** If present, games with this mod enabled will have a new button on the menu. When the player clicks that button, this mod hook is invoked and the resulting UI will be shown to the player in a dialog. See [[Mod API Reference:UI|UI API]].
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.
# setMaxSize: Function mods can call to set the maximum size of the dialog. Pass two numbers: the width and the height. Note that screen sizes can vary a lot, so you can never be sure you'll get the size you request, so plan on making your UI work in all sizes.
# setScrollable: Function mods can call to set whether the dialog is scrollable horizontally or vertically. Pass two booleans: the first determines if it's horizontally scrollable, and the second determines if it's vertically scrollable. The default is false, true.
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.
# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

* Client_GameRefresh (Client_GameRefresh.lua)
** Invoked whenever the client gets data about this game from the server. This can be used to check for updated Mod.PublicGameData or Mod.PlayerGameData, documented at [[Mod Game Data Storage]]. The client refresh timing is different between single-player and multi-player, and in multi-player can also vary depending on the user's internet connection (such as whether they're connected by websocket, long polling socket, or normal polling). Therefore, a mod should never write code that breaks if Client_GameRefresh is called at unexpected times.
** Arguments:
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.

* Client_PresentCommercePurchaseUI (Client_PresentCommercePurchaseUI.lua)
** Invoked whenever the player clicks the "Build" button in a commerce game. This can be used to present UI to allow the player to spend their gold on things.
** Arguments:
# rootParent: Pass this as an argument to the top-level UI element your mod creates. See the [[Mod API Reference:UI|UI API]] for details.
# [[Mod API Reference:ClientGame|ClientGame]]: Information about the game.
# close: Function that, when called, will close the current dialog. Takes no arguments and returns nothing.

== Notes ==

Any hooks that start with <code>Server_</code> are run on the server in multi-player games, and on the client in single-player games.

No hooks have return values. Meaning, it doesn't matter if you return any values from your hook functions. Instead, the mod framework gives you callbacks to call to affect things. This is preferred over return values for a few reasons. First, it allows mods to call the callbacks early on or late on in their function, which can be easier than a return statement which must come at the end. Second, it allows mods to simply not call the callback, which can signal to Warzone that the mod doesn't care about the result of this. This can be important in some cases where multiple mods that define the same hook. Sometimes the mods instructions can conflict and Warzone must decide which to obey.

== See Also ==
* [[Mod Developers Guide]]
* [[Mod Game Data Storage]]
[[Category:Mod Developers Guide]]

Mod API Reference:GameOrderCustom

2024-04-17T21:10:55Z

Kaninchen: removed text about hackers, replaced with a link to the Mod Security wiki page

'''GameOrderCustom''': Subclass of [[Mod API Reference:GameOrder|GameOrder]]. This order does nothing on its own, but it can be used by mods for custom orders. GameOrderCustom is typically sent up from clients to the server, in contrast to [[Mod API Reference:GameOrderEvent|GameOrderEvent]] which is typically sent down from the server to clients.

In order to make sure your mod doesn't break when used in conjunction with other mods, you should prepend a unique string (such as the name of your mod plus an underscore) to the Payload. When reading a GameOrderCustom, check if the payload starts with your unique string, and if it doesn't it means this order isn't one your mod made and you should ignore it. If you act on another mod's messages, or skip them, it will create unexpected behavior for your mod or another mod.

* '''Message''' ''string'': The message that will appear in the orders list. This is what players see.
* '''Payload''' ''string'': Data the mod wishes to store along with this order, but does not want players to see.
* '''CostOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'': Defines how much gold the order will cost the player in a [[Commerce]] game. This should only be set in commerce games. If CostOpt is set to nil, then it's assumed to be the same as having a cost of 0. The game will take care of taking the player's resources away correctly, both on the client and server, when inserting an order with a cost into their orders list.
* '''OccursInPhaseOpt''' ''[[Mod API Reference:Nullable|Nullable]]<[[Mod API Reference:TurnPhase|TurnPhase]] (enum)>'': If not nil, then orders will be forced to be placed in this phase. Players will not be able to move this order above an order of a lower phase, or below an order of a higher phase. Added in v5.22.0.
'''Important to note'''

[[Mod_Security|Mod security]] should be applied to [[Mod_Hooks|Mod Hooks]] working with this card

* '''WL.GameOrderCustom.Create'''('''playerID''' ''[[Mod API Reference:PlayerID|PlayerID]]'', '''message''' ''string'', '''payload''' ''string'', '''costOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'') (static) returns [[Mod API Reference:GameOrderCustom|GameOrderCustom]]:
[[Category:Mod API Reference]]

Mod Security

2024-04-17T21:07:26Z

Kaninchen: Created page with "In a [https://en.wikipedia.org/wiki/Client%E2%80%93server_model Client-Server Relationship] it is very important that the Server checks '''everything''' the client sends to it..."

In a [https://en.wikipedia.org/wiki/Client%E2%80%93server_model Client-Server Relationship] it is very important that the Server checks '''everything''' the client sends to it.
This is because someone who is proficient in programming (a Hacker for example) can modify any data the client sends to the server.
It's therefore important to employ a [https://en.wikipedia.org/wiki/Zero_trust_security_model zero trust policy] when creating mods

== Possible security weak points ==
=== SendGameCustomMessage ===
[[Mod_API_Reference:ClientGame|Main article]] 
An attacker can modify the payload in any way they desire. Let's take a Diplomacy Mod for example, where the Host can decide which player should win at any time. A naive approach using [[Mod_Hooks#Server Hooks|Server_GameCustomMessage(...)]] would be
function Server_GameCustomMessage(game, playerID, payload, setReturn)
if payload.type == "makePlayerWin" then
makePlayerWin(game, payload.playerid)
-- makePlayerWin(game, playerid) could be a function that later on adds a order which sets the territory owner of every territory to the player associated with the supplied playerid
elsif ... -- other functionality
end
An attacker with the associated playerid of (for example) '''12345''' who analyzed the source code of the mod (remember, the source code of every mod is publicly available on [https://github.com/ Github]) can now see that the Hook never actually checks if the client who sent the CustomServerMessage is really the host (indicated by the '''playerID''' parameter of the '''Server_GameCustomMessage''' function). The attacker could therefore send following Lua table to the Server:
{
type = "makePlayerWin",
playerid = 12345
}
and automatically win as soon as the turn advances. The actual process is more complicated but that's about how an attacker could use the security vulnerability to gain a decisive advantage. 
The obvious and right solution is to additionally check inside the ''if condition'' if the '''playerID''' supplied to '''Server_GameCustomMessage''' belongs to the host.
function Server_GameCustomMessage(game, playerID, payload, setReturn)
if payload.type == "makePlayerWin" and game.ServerGame.Settings.StartedBy == playerID then
makePlayerWin(game, payload.playerid)
elsif ... -- other functionality
end
this now makes the functionality secure against custom client data crafted by an attacker

===GameOrderCustom===
[[Mod_API_Reference:GameOrderCustom|Main article]] 
The Server [[Mod Hooks]] which accept the '''GameOrderCustom''' should only depend on the payload, as hackers may, as with '''SendGameCustomMessage''', modify all fields ('''Message''', '''Payload''', '''CostOpt''' and '''OccursInPhaseOpt''') to gain an advantage. Note that, since hackers can modify '''Payload''' too, it is essential to verify that it was even possible for the player to send the received '''Payload''' in the first place. All other Fields should be recreated by the Server.

Mod Developers Guide

2024-03-19T18:16:32Z

Kaninchen: /* Global State */ spelling error

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, 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 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]]

Mod API Reference:GameOrderCustom

2024-03-19T16:31:05Z

Kaninchen: Added a warning due to possible hacking

'''GameOrderCustom''': Subclass of [[Mod API Reference:GameOrder|GameOrder]]. This order does nothing on its own, but it can be used by mods for custom orders. GameOrderCustom is typically sent up from clients to the server, in contrast to [[Mod API Reference:GameOrderEvent|GameOrderEvent]] which is typically sent down from the server to clients.

In order to make sure your mod doesn't break when used in conjunction with other mods, you should prepend a unique string (such as the name of your mod plus an underscore) to the Payload. When reading a GameOrderCustom, check if the payload starts with your unique string, and if it doesn't it means this order isn't one your mod made and you should ignore it. If you act on another mod's messages, or skip them, it will create unexpected behavior for your mod or another mod.

* '''Message''' ''string'': The message that will appear in the orders list. This is what players see.
* '''Payload''' ''string'': Data the mod wishes to store along with this order, but does not want players to see.
* '''CostOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'': Defines how much gold the order will cost the player in a [[Commerce]] game. This should only be set in commerce games. If CostOpt is set to nil, then it's assumed to be the same as having a cost of 0. The game will take care of taking the player's resources away correctly, both on the client and server, when inserting an order with a cost into their orders list.
* '''OccursInPhaseOpt''' ''[[Mod API Reference:Nullable|Nullable]]<[[Mod API Reference:TurnPhase|TurnPhase]] (enum)>'': If not nil, then orders will be forced to be placed in this phase. Players will not be able to move this order above an order of a lower phase, or below an order of a higher phase. Added in v5.22.0.
'''Important to note'''

The Server [[Mod_Hooks]] which accept the '''GameOrderCustom''' should only depend on the payload, as hackers may modify all fields ('''Message''', '''Payload''', '''CostOpt''' and '''OccursInPhaseOpt''') to gain an advantage. Note that, since hackers can modify '''Payload''' too, it is essential to verify that it was even possible for the player to send the received '''Payload''' in the first place. All other Fields should be recreated by the Server.
== Functions ==

* '''WL.GameOrderCustom.Create'''('''playerID''' ''[[Mod API Reference:PlayerID|PlayerID]]'', '''message''' ''string'', '''payload''' ''string'', '''costOpt''' ''Table<[[Mod API Reference:ResourceType|ResourceType]] (enum),integer>'') (static) returns [[Mod API Reference:GameOrderCustom|GameOrderCustom]]:
[[Category:Mod API Reference]]

User:Kaninchen

2019-04-26T22:32:24Z

Kaninchen:

My Ingamename is the same as my Wiki-Name (Kaninchen)

Diplomacy Gametype

2019-04-26T22:27:50Z

Kaninchen: /* PE (Public Enemy) */ Changed a "too" to a "to"

The '''Diplomacy gametype''' is a user created "custom" game with a set of rules in a FFA to be followed to play the game as a real world scenario of deceiving enemies, making valuable alliances, making "declarations" of war, and eventually being the last one standing, however, the game can be [[Vote to end|voted to end]] if an alliance claims "victory".

== '''Rules''' ==
Common rules consist of:

# No attacking other players without declaring war on them in public chat so as to give the enemy a fair chance. Often both Sides have to wait a turn to attack after the war-declaration
# No attacking an player without warning ''(in some games this is known as "[https://en.wikipedia.org/wiki/Blitzkrieg Blitzkrieging]", German for "Lighting War".)''
# Alliances are encouraged. Some games require alliances be made public, some allow it to be private. Allies are a good way of invading successfully or defending from a stronger enemy.
#Maximum Number of Allies a Player can have ''(Even if Alliances are encouraged, there's sometimes a limit so Alliances won't get too big)''

Other possible rules consist of:
#Only Hosts can declare PEs
#Gangbanging forbidden/allowed ''(Gangbanging in this case means that many Players together attack one alone Player (Like a 5vs1). Often a Player alone can't defend himself from several Players, that's why it's often forbidden.)''
#Claims (doesn't) have to be respected ''(Claiming means, that a Player says that a Bonus on Neutral or booted territory is his. Often Claiming doesn't need to be respected)''
#Reasons for war (not) needed ''(Sometimes, there must be a Reason to declare War to reduce War-Mongering. An example could be that somebody didn't respected your Claim or somebody attacked your Ally.)''
#Roleplay mandatory ''(Means, that Players actually have to Roleplay, and don't treat the Diplomacy-Game like any other Warzone-Game)''

If a player breaks the custom rules of the Diplomacy Game, they aren't breaking the actual [[Rules]] of Warzone. They only become a PE for this Diplomacy-game.

==='''PE''' ('''P'''ublic '''E'''nemy)===
Players which break Rules in a Diplomacy Games are often called a "PE", which is short for '''P'''ublic '''E'''nemy.
In many Diplomacy Games only the Hosts can (un)declare PEs, but sometimes the Hosts also allows normal Players to (un)declare PEs.

Often all Players which are adjacent to a PE can attack the PE without warning/permission and even have to attack the PE, if they're able to. Somebody who won't attack a PE or even are helping a PE might become a PE itself.

== '''Origin''' ==
While the exact creator is not known as after its obscure creation other users quickly copied the rules and made spinoffs, the user "Soviet Russia Buddy" takes the most credit for creating the game. His first game was known as "Reality Warfare, A New Way Of Playing", which was then shortened to "Reality Warfare" which its current name is. This can be disputed by Le Count H who was laying the foundation in scenarios in late September of 2012. These were initially unfair due their emphasis on giving nations overwhelming advantages due to their size. His games became extremely popular the following summer. Another user named "Zecit" coined the term "Public Enemy" in his game "Simulation World", which is used in many Diplomacy games. Out of all hosts commonly making these games, he (presumably male) has the most amount of rules and hosts games at least once a day. However, not all of them are rules and rather more creative and realistic additions, one of which is a rule involving capitals, and some are guidelines that can be used to be more "diplomatic". People who have played with him have said they have played that gametype with him for almost 2 years. When asked where he got his possibly original idea, he said he had been playing a 24FFA with no fog when he noticed that everyone had to have secret alliances as no one was attacking anyone.

== '''Current''' ==
Currently, many different players host these games. Most of them are 6FFAs, but Soviet Russia Buddy and others host 24FFAs, or sometimes less for scenario diplomacy games. While many players attribute many different users for its creation, many only use 3-4 of Soviet Russia Buddy's original rules, usually copying them word for word. Alternatively, rules are slacked and public declarations are only required if a player wants to be "trustworthy". Many diplomacy games involve a strong element of roleplay, as players play as if they were a character in whichever world the game is set in. This works especially well with maps of universes from fantasy novels, such as George RR Martin's "Song of Ice and Fire".

== '''Diplomacy mods'''==
The most requested feature from Uservoice, [https://warlight.uservoice.com/forums/77051-warlight-features/suggestions/1088481-peace-treaties Peace Treaties], has been implemented as a [[Mod]]. The [[Advanced Diplomacy Mod]] and [[Diplomacy]] mod remove the need for players to be "trustworthy", as declarations are not needed anymore, since if you are at peace with someone, you cannot attack each other.

Warning: As of November 2018, there are bugs with the Advanced Diplomacy mod. Use the [[Diplomacy]] mod instead

==Other==

Common [[settings]] are "no fog" or "slight fog", so as to know if someone really did blitzkrieg. All [[cards]] are often enabled to allow for interesting storyline twists to occur in the game.

Also most Diplomacy-games are Multi-Day Games, so everyone can react easily and unstressed and because Diplomacy-Games often have many Players. But also some are Real-Time with a high Boot-Time.

Most hosts make the game a [[Ranked versus Practice|practice game]].

Most hosts also use [[custom scenarios]], if they aren't able to use custom scenarios, they usually choose [[manual distribution]].

[[Category:Game Variants]]

Diplomacy Gametype

2019-03-20T17:33:11Z

Kaninchen: Fixed a small typo.

The '''Diplomacy gametype''' is a user created "custom" game with a set of rules in a FFA to be followed to play the game as a real world scenario of deceiving enemies, making valuable alliances, making "declarations" of war, and eventually being the last one standing, however, the game can be [[Vote to end|voted to end]] if an alliance claims "victory".

== '''Rules''' ==
Common rules consist of:

# No attacking other players without declaring war on them in public chat so as to give the enemy a fair chance. Often both Sides have to wait a turn to attack after the war-declaration
# No attacking an player without warning ''(in some games this is known as "[https://en.wikipedia.org/wiki/Blitzkrieg Blitzkrieging]", German for "Lighting War".)''
# Alliances are encouraged. Some games require alliances be made public, some allow it to be private. Allies are a good way of invading successfully or defending from a stronger enemy.
#Maximum Number of Allies a Player can have ''(Even if Alliances are encouraged, there's sometimes a limit so Alliances won't get too big)''

Other possible rules consist of:
#Only Hosts can declare PEs
#Gangbanging forbidden/allowed ''(Gangbanging in this case means that many Players together attack one alone Player (Like a 5vs1). Often a Player alone can't defend himself from several Players, that's why it's often forbidden.)''
#Claims (doesn't) have to be respected ''(Claiming means, that a Player says that a Bonus on Neutral or booted territory is his. Often Claiming doesn't need to be respected)''
#Reasons for war (not) needed ''(Sometimes, there must be a Reason to declare War to reduce War-Mongering. An example could be that somebody didn't respected your Claim or somebody attacked your Ally.)''
#Roleplay mandatory ''(Means, that Players actually have to Roleplay, and don't treat the Diplomacy-Game like any other Warzone-Game)''

If a player breaks the custom rules of the Diplomacy Game, they aren't breaking the actual [[Rules]] of Warzone. They only become a PE for this Diplomacy-game.

==='''PE''' ('''P'''ublic '''E'''nemy)===
Players which break Rules in a Diplomacy Games are often called a "PE", which is short for '''P'''ublic '''E'''nemy.
In many Diplomacy Games only the Hosts can (un)declare PEs, but sometimes the Hosts also allows normal Players to (un)declare PEs.

Often all Players which are adjacent to a PE can attack the PE without warning/permission and even have to attack the PE, if they're able too. Somebody who won't attack a PE or even are helping a PE might become a PE itself.

== '''Origin''' ==
While the exact creator is not known as after its obscure creation other users quickly copied the rules and made spinoffs, the user "Soviet Russia Buddy" takes the most credit for creating the game. His first game was known as "Reality Warfare, A New Way Of Playing", which was then shortened to "Reality Warfare" which its current name is. This can be disputed by Le Count H who was laying the foundation in scenarios in late September of 2012. These were initially unfair due their emphasis on giving nations overwhelming advantages due to their size. His games became extremely popular the following summer. Another user named "Zecit" coined the term "Public Enemy" in his game "Simulation World", which is used in many Diplomacy games. Out of all hosts commonly making these games, he (presumably male) has the most amount of rules and hosts games at least once a day. However, not all of them are rules and rather more creative and realistic additions, one of which is a rule involving capitals, and some are guidelines that can be used to be more "diplomatic". People who have played with him have said they have played that gametype with him for almost 2 years. When asked where he got his possibly original idea, he said he had been playing a 24FFA with no fog when he noticed that everyone had to have secret alliances as no one was attacking anyone.

== '''Current''' ==
Currently, many different players host these games. Most of them are 6FFAs, but Soviet Russia Buddy and others host 24FFAs, or sometimes less for scenario diplomacy games. While many players attribute many different users for its creation, many only use 3-4 of Soviet Russia Buddy's original rules, usually copying them word for word. Alternatively, rules are slacked and public declarations are only required if a player wants to be "trustworthy". Many diplomacy games involve a strong element of roleplay, as players play as if they were a character in whichever world the game is set in. This works especially well with maps of universes from fantasy novels, such as George RR Martin's "Song of Ice and Fire".

== '''Diplomacy mods'''==
The most requested feature from Uservoice, [https://warlight.uservoice.com/forums/77051-warlight-features/suggestions/1088481-peace-treaties Peace Treaties], has been implemented as a [[Mod]]. The [[Advanced Diplomacy Mod]] and [[Diplomacy]] mod remove the need for players to be "trustworthy", as declarations are not needed anymore, since if you are at peace with someone, you cannot attack each other.

Warning: As of November 2018, there are bugs with the Advanced Diplomacy mod. Use the [[Diplomacy]] mod instead

==Other==

Common [[settings]] are "no fog" or "slight fog", so as to know if someone really did blitzkrieg. All [[cards]] are often enabled to allow for interesting storyline twists to occur in the game.

Also most Diplomacy-games are Multi-Day Games, so everyone can react easily and unstressed and because Diplomacy-Games often have many Players. But also some are Real-Time with a high Boot-Time.

Most hosts make the game a [[Ranked versus Practice|practice game]].

Most hosts also use [[custom scenarios]], if they aren't able to use custom scenarios, they usually choose [[manual distribution]].

[[Category:Game Variants]]

Diplomacy Gametype

2019-02-25T13:45:47Z

Kaninchen: Fixed some typos

The '''Diplomacy gametype''' is a user created "custom" game with a set of rules in a FFA to be followed to play the game as a real world scenario of deceiving enemies, making valuable alliances, making "declarations" of war, and eventually being the last one standing, however, the game can be [[Vote to end|voted to end]] if an alliance claims "victory".

== '''Rules''' ==
Common rules consist of:

# No attacking other players without declaring war on them in public chat so as to give the enemy a fair chance. Often both Sides have to wait a turn to attack after the war-declaration
# No attacking an player without warning ''(in some games this is known as "[https://en.wikipedia.org/wiki/Blitzkrieg Blitzkrieging]", German for "Lighting War".)''
# Alliances are encouraged. Some games require alliances be made public, some allow it to be private. Allies are a good way of invading successfully or defending from a stronger enemy.
#Maximum Number of Allies a Player can have ''(Even if Alliances are encouraged, there's sometimes a limit so Alliances won't get too big)''

Other possible rules consist of:
#Only Hosts can declare PEs
#Gangbaning forbidden/allowed ''(Gangbanging in this case means that many Players together attack one alone Player (Like a 5vs1). Often a Player alone can't defend himself from several Players, that's why it's often forbidden.)''
#Claims (doesn't) have to be respected ''(Claiming means, that a Player says that a Bonus on Neutral or booted territory is his. Often Claiming doesn't need to be respected)''
#Reasons for war (not) needed ''(Sometimes, there must be a Reason to declare War to reduce War-Mongering. An example could be that somebody didn't respected your Claim or somebody attacked your Ally.)''
#Roleplay mandatory ''(Means, that Players actually have to Roleplay, and don't treat the Diplomacy-Game like any other Warzone-Game)''

If a player breaks the custom rules of the Diplomacy Game, they aren't breaking the actual [[Rules]] of Warzone. They only become a PE for this Diplomacy-game.

==='''PE''' ('''P'''ublic '''E'''nemy)===
Players which break Rules in a Diplomacy Games are often called a "PE", which is short for '''P'''ublic '''E'''nemy.
In many Diplomacy Games only the Hosts can (un)declare PEs, but sometimes the Hosts also allows normal Players to (un)declare PEs.

Often all Players which are adjacent to a PE can attack the PE without warning/permission and even have to attack the PE, if they're able too. Somebody who won't attack a PE or even are helping a PE might become a PE itself.

== '''Origin''' ==
While the exact creator is not known as after its obscure creation other users quickly copied the rules and made spinoffs, the user "Soviet Russia Buddy" takes the most credit for creating the game. His first game was known as "Reality Warfare, A New Way Of Playing", which was then shortened to "Reality Warfare" which its current name is. This can be disputed by Le Count H who was laying the foundation in scenarios in late September of 2012. These were initially unfair due their emphasis on giving nations overwhelming advantages due to their size. His games became extremely popular the following summer. Another user named "Zecit" coined the term "Public Enemy" in his game "Simulation World", which is used in many Diplomacy games. Out of all hosts commonly making these games, he (presumably male) has the most amount of rules and hosts games at least once a day. However, not all of them are rules and rather more creative and realistic additions, one of which is a rule involving capitals, and some are guidelines that can be used to be more "diplomatic". People who have played with him have said they have played that gametype with him for almost 2 years. When asked where he got his possibly original idea, he said he had been playing a 24FFA with no fog when he noticed that everyone had to have secret alliances as no one was attacking anyone.

== '''Current''' ==
Currently, many different players host these games. Most of them are 6FFAs, but Soviet Russia Buddy and others host 24FFAs, or sometimes less for scenario diplomacy games. While many players attribute many different users for its creation, many only use 3-4 of Soviet Russia Buddy's original rules, usually copying them word for word. Alternatively, rules are slacked and public declarations are only required if a player wants to be "trustworthy". Many diplomacy games involve a strong element of roleplay, as players play as if they were a character in whichever world the game is set in. This works especially well with maps of universes from fantasy novels, such as George RR Martin's "Song of Ice and Fire".

== '''Diplomacy mods'''==
The most requested feature from Uservoice, [https://warlight.uservoice.com/forums/77051-warlight-features/suggestions/1088481-peace-treaties Peace Treaties], has been implemented as a [[Mod]]. The [[Advanced Diplomacy Mod]] and [[Diplomacy]] mod remove the need for players to be "trustworthy", as declarations are not needed anymore, since if you are at peace with someone, you cannot attack each other.

Warning: As of November 2018, there are bugs with the Advanced Diplomacy mod. Use the [[Diplomacy]] mod instead

==Other==

Common [[settings]] are "no fog" or "slight fog", so as to know if someone really did blitzkrieg. All [[cards]] are often enabled to allow for interesting storyline twists to occur in the game.

Also most Diplomacy-games are Multi-Day Games, so everyone can react easily and unstressed and because Diplomacy-Games often have many Players. But also some are Real-Time with a high Boot-Time.

Most hosts make the game a [[Ranked versus Practice|practice game]].

Most hosts also use [[custom scenarios]], if they aren't able to use custom scenarios, they usually choose [[manual distribution]].

[[Category:Game Variants]]

Diplomacy Gametype

2019-02-24T14:16:12Z

Kaninchen: Added Rules; Modified existing Rules; Added Public-Enemy-Section in Rules; Added "Other" Section

The '''Diplomacy gametype''' is a user created "custom" game with a set of rules in a FFA to be followed to play the game as a real world scenario of deceiving enemies, making valuable alliances, making "declarations" of war, and eventually being the last one standing, however, the game can be [[Vote to end|voted to end]] if an alliance claims "victory".

== '''Rules''' ==
Common rules consist of:

# No attacking other players without declaring war on them in public chat so as to give the enemy a fair chance. Often both Sides have to wait a turn to attack after the war-declaration
# No attacking an player without warning ''(in some games this is known as "[https://en.wikipedia.org/wiki/Blitzkrieg Blitzkrieging]", German for "Lighting War".)''
# Alliances are encouraged. Some games require alliances be made public, some allow it to be private. Allies are a good way of invading successfully or defending from a stronger enemy.
#Maximum Number of Allies a Player can have ''(Even if Alliances are encouraged, there's sometimes a limit so Alliances won't get too big)''

Other possible rules consist of:
#Only Hosts can declare PEs
#Gangbaning forbidden/allowed ''(Gangbanging in this case means that many Players together attack one alone Player (Like a 5vs1). Often a Player alone can't defend himself from several Players, that's why it's often forbidden.)''
#Claims (doesn't) have to be respected ''(Claiming means, that a Player says that a Bonus in Neutral or booted terrirory is his. Often Claiming doesn't need to be respected)''
#Reasons for war (not) needed ''(Sometimes, there must be a Reason to declare War to reduce War-Mongering. An example could be that somebody didn't respected your Claim or somebody attacked your Ally.)''
#Roleplay mandatory ''(Means, that Players actually have to Roleplay, and don't treat the Diplomacy-Game like any other Warzone-Game)''

If a player breaks the custom rules of the Diplomacy Game, they aren't breaking the actual [[Rules]] of Warzone. They only become a PE for this Diplomacy-game.

==='''PE''' ('''P'''ublic '''E'''nemy)===
Players which break Rules in a Diplomatic Games are often called a "PE", which is short for '''P'''ublic '''E'''nemy.
In many Diplomatic Games only the Hosts can (un)declare PEs, but sometimes the Hosts also allows normal Players to (un)declare PEs.

Often all Players which are adjected to a PE can attack the PE without warning/permission and even have to attack the PE, if they're able too. Somebody who won't attack a PE or even are helping a PE might become a PE itself.

== '''Origin''' ==
While the exact creator is not known as after its obscure creation other users quickly copied the rules and made spinoffs, the user "Soviet Russia Buddy" takes the most credit for creating the game. His first game was known as "Reality Warfare, A New Way Of Playing", which was then shortened to "Reality Warfare" which its current name is. This can be disputed by Le Count H who was laying the foundation in scenarios in late September of 2012. These were initially unfair due their emphasis on giving nations overwhelming advantages due to their size. His games became extremely popular the following summer. Another user named "Zecit" coined the term "Public Enemy" in his game "Simulation World", which is used in many Diplomacy games. Out of all hosts commonly making these games, he (presumably male) has the most amount of rules and hosts games at least once a day. However, not all of them are rules and rather more creative and realistic additions, one of which is a rule involving capitals, and some are guidelines that can be used to be more "diplomatic". People who have played with him have said they have played that gametype with him for almost 2 years. When asked where he got his possibly original idea, he said he had been playing a 24FFA with no fog when he noticed that everyone had to have secret alliances as no one was attacking anyone.

== '''Current''' ==
Currently, many different players host these games. Most of them are 6FFAs, but Soviet Russia Buddy and others host 24FFAs, or sometimes less for scenario diplomacy games. While many players attribute many different users for its creation, many only use 3-4 of Soviet Russia Buddy's original rules, usually copying them word for word. Alternatively, rules are slacked and public declarations are only required if a player wants to be "trustworthy". Many diplomacy games involve a strong element of roleplay, as players play as if they were a character in whichever world the game is set in. This works especially well with maps of universes from fantasy novels, such as George RR Martin's "Song of Ice and Fire".

== '''Diplomacy mods'''==
The most requested feature from Uservoice, [https://warlight.uservoice.com/forums/77051-warlight-features/suggestions/1088481-peace-treaties Peace Treaties], has been implemented as a [[Mod]]. The [[Advanced Diplomacy Mod]] and [[Diplomacy]] mod remove the need for players to be "trustworthy", as declarations are not needed anymore, since if you are at peace with someone, you cannot attack each other.

Warning: As of November 2018, there are bugs with the Advanced Diplomacy mod. Use the [[Diplomacy]] mod instead

==Other==

Common [[settings]] are "no fog" or "slight fog", so as to know if someone really did blitzkrieg. All [[cards]] are often enabled to allow for interesting storyline twists to occur in the game.

Also most Diplomacy-games are Multi-Day Games, so everyone can react easily and unstressed and because Diplomacy-Games often have many Players. But also some are Real-Time with a high Boot-Time.

Most hosts make the game a [[Ranked versus Practice|practice game]].

Most hosts also use [[custom scenarios]], if they aren't able to use custom scenarios, they usually choose [[manual distribution]].

[[Category:Game Variants]]

Advanced Strategy

2019-02-18T20:59:17Z

Kaninchen: (Hiding your income)Formatted the Text; Added an Image.

{{Stub}}
So you think you have internalized the [[Basic Strategy|basic strategies]] of the game and know your way around? Good.
This page will teach you some advanced techniques and help you understand the subtleties of game-play.
==Picking Territories==
In games with [[manual distribution]] of territories picking the right starting position(s) is essential. Especially ladder games require you to choose wisely.

Aspects to consider:
* Prefer starting spots in smaller [[bonuses]] over those in large ones. Often a 3er completed in turn 1 is worth more than a 5er in turn 3. Aim for those bonuses first that can be completed in the least amount of turns.
* Don't just look for the starting bonus itself, also take further expansion possibilities into consideration. What will your income be in turn 3, 4 or 5?
* Sometimes even larger bonuses can be completed in a single turn when there are 2 or 3 adjacent starting locations. However, you cannot be sure you get all 2 or 3 of these spots, so in those cases you always need a plan B.
* Avoid bonuses with [[wastelands]], at least in the beginning.
* Bonuses only pay off if they generate more income than you lost armies taking them. Example: A bonus worth 4 with 10 [[neutral]]s in it will cost you (neutrals x [[Offense and defense kill rates|defensive kill rate]]) armies, say 10 x 0.7 = ~7 armies on average. It will pay off in the 2nd turn already. Taking a bonus worth 4 with 20 neutrals you may lose ~14 armies, so it will only pay off if you can hold it for at least 4 turns.
* Always place enough picks to avoid ending up with random spots. In a 1v1 with 3 starting spots you need 6 picks. In a 2v2 with 2 starting spots you need at least 6 picks as well, better 8 in case your teammate forgets about coordinating his picks with yours.
* In larger [[Team Games|team games]], always communicate with your team. On large maps pick a general starting area. The closer you start together, the less borders there are to defend. Mind your expansion capabilities though.
* You can check your teammates' orders and see where they intend to start: Click their name in the list, then click "View Teammate's orders".
* ...
* ... (how to place counter picks)
* ... (how to find out your opponents' starting locations)
* Once deployment has taken place if you didnt get any of your first 3 choices you therefore know that your opponent has these territories.

==Deployment==
Think carefully where you will deploy, this can determine whether you win or lose.

Here are some aspects to consider, when deploying:
* Are you attacking neutral or your enemy(ies) or both?
* Will this affect your spread rate? How?
* Do you actually need to deploy there?
* Will your enemy(ies) attack you?
* Do you want to have enough armies to just defend from them or attack them?
* Approximately, how many armies will you lose?
* ...

==Sequence of Commands==

Timing is always of great importance. One single key attack happening too early or too late can turn your rock-solid victory into an embarrassing defeat.

Your means of manipulating the order of events are the [[Orders List|list of orders]] to the right of the game board and the [[order priority card]] and [[order delay card]]. Unfortunately the latter two are not always at your disposal, so primarily you have to concentrate on your order of commands.

Of course there are no rules that apply to all game situations, but here are some general considerations:
* In most games, the kill rates are set slightly in favor of the defendant. So it is a very common situation that you want to delay an attack as long as possible, to make sure your opponents attack happens first (if he attacks!). To achieve that without an order delay card, you have to put as many dummy moves as possible at the top of your list of orders. Move some armies in the rear territories back and forth, or better yet bring them to the front lines. Attack some neutrals in the meantime. Just make that most important attack of yours the very last item on your list.
* When moving reinforcements from the rear to the front lines, move the biggest stack first OR reinforce the most vulnerable position first.
* When attacking neutrals, attack those where you do not expect interference from other players first, if your stack is just big enough to break the neutral. Try to delay those attacks on neutrals where you might encounter other players as much as possible, let your opponent clear those neutrals for you. Just make sure he does not see it coming.
* However, if you attack a neutral with a big stack, most often because you anticipate an encounter with a player there or because you'll knock at her/his bonuses, usually the sooner the better: this way any later move towards your freshly settled stack should crush onto your strong defense. The few casualties suffered breaking the neutral won't be as costly to recover as attacking second yourself on a supposedly equally powerful stack as yours.
* ...

==Probabilities==

The [[Analyzer Tool|analyzer tool]] is your best friend. It allows you to estimate if your attacks will fail or succeed and thus can give you a good first risk assessment.
You can also use it to calculate the chances for multiple attacks combined, but since it only shows one attack at a time you will have to do some simple calculations yourself.

Example:

*You have 10 armies to deploy.
*There are 2 bonuses of equal value you could complete, but you only have armies for one of them.
*So you want to know the odds.

# Bonus 1:
:# You are missing 3 territories, each occupied by 2 neutrals.
:# Since you have 10 armies at your disposal, you can attack two neutral territories with 3 armies each, and one with 4 armies. If you hover your mouse cursor over the dots in the upper graph of the analyzer tool, it will tell you the odds for each attack.
:# For a single 3vs2 attack there is a 71% chance of taking the territory.
:# For a single 4vs2 attack the chance is 93%.
:# To get the extra bonus armies next turn, all 3 attacks have to succeed, so your combined chances of taking that bonus are: 
71% x 71% x 93% = '''~46,8%'''
# Bonus 2:
:# You are missing 2 territories, one with 2 neutrals and the other one with 4 neutrals.
:# Single chance for the 3 vs. 2 attack: 71%
:# Single chance for the 7 vs. 4 attack: 84%
:# Combined odds:
71% x 84% = '''~59,6%'''

So in this case the odds for completing the 2nd bonus are significantly better than for the 1st one.

;Note:In ladder games the [[Luck Modifier|luck modifier]] is lower (16%), so the results look a bit different:

#Bonus 1:
:79% x 79% x 100% = '''~62,4%'''
#Bonus 2:
:79% x 98% = '''~77,4%'''

==Hiding your income==
{{stub|section}}
In large FFAs or team games it isn't all about the hard numbers. The impressions other players have of your relative strength are very important to strong-arming other players into alliances or avoiding coalitions formed against you.

In fog games, taking special notice of the number of troops you deploy that are visible to each player is crucial to influencing other players' impressions.

Reinforcements can also be deployed in territories non-adjacent to the enemy and then airlifted or transferred towards the front lines. In such cases you avoid giving the enemy an assured minimum on your income.

https://i.imgur.com/lZNHDJN.png

==Guides written by other players==

Odin/GG
https://drive.google.com/file/d/0B024HXqzvoGCejhhajNFa1ZOVlE/edit?pref=2&pli=1

Norman/M'Hunters
https://docs.google.com/document/d/1ERn5UL2-K6d5VUmK8zkWA1j1m1GIqPUiHCYmbWBufw4/edit

Benjamin628
https://docs.google.com/document/d/1NyhCpIQKShAbWGXicO_ph9whV_UyMS-3a7_re0C7R8Y/edit

==Bonuses==
{{stub|section}}
==See also==
* [[Basic Strategy]]
* [[Strategic 1 v 1]]

[[Category:Strategies]]

User:Kaninchen

2019-02-18T19:32:51Z

Kaninchen: Created page with "Big Chungus"

Big Chungus

Attack teammates warning

2019-02-17T09:43:46Z

Kaninchen: Updated Image; Removed the Checkbox-Paragraph (It was outdated); Changed the Start and Ending of the 1. Paragraph.

https://i.imgur.com/kH6iAb9.png

The ''Attack teammate?''-warning message pops up when you choose to attack your teammate in a game. It is merely a friendly warning explaining that you are targeting a fellow teammate. This dialog box lets you choose between '''Attack my teammate''' and '''Transfer to my teammate'''.

Whatever selected here will change the "Treat Teammates as Enemies" check-box that exists on the attack/transfer dialog. This checkbox is ultimately what determines whether or not the attack will attack your teammate - this dialog is just a handy way to check or uncheck the box.