MultiplayerContent

Creator's Guide

Add-on Structure • Maps • Scenarios • Campaigns • Multiplayer • Units • Distributing Content

This page is dedicated to the syntax modifications necessary to enable a scenario or campaign to work in multiplayer mode. Only the differences between multiplayer and singleplayer are are documented here, so you might want to read BuildingScenarios and BuildingCampaigns first.

Note: This page assumes you have a basic add-on set up as described in AddonStructure, as well as some coded content.

Multiplayer scenarios

You can play standalone scenarios in multiplayer mode without setting up a campaign (this isn't possible in singleplayer). Simply make the following modifications:

In the _main.cfg file, use #ifdef MULTIPLAYER as the load conditional
In the scenario configuration file, use a toplevel [multiplayer] tag instead of [scenario] tag

Multiplayer campaigns

Note: This section is relevant for version 1.11.6 and higher. A page about multiplayer campaigns on older versions can be found here.

Wesnoth has basic support for campaigns that can be played in multiplayer mode, with your friends, or even with an AI. There will still be some things that don't work as expected since some functionality for multiplayer campaigns is still being developed. While you can and should test your work in hotseat mode, there are a number of things that might behave differently under real network conditions (mostly affecting scenario and side parameters). Keep this in mind and make sure to test your campaign over the net, too.

The Campaign Tag

Multiplayer campaigns use the [campaign] tag, thus allowing the same campaign to work both in both modes. The only difference is that game also checks for a couple optional tags when campaign is used in multiplayer. They could be found on the CampaignWML page. Additionally, the type attribute should be explicitly set to mp or hybrid or otherwise a campaign would not be visible in multiplayer.

The Scenario File

A scenario in a multiplayer campaign is almost identical to a scenario in a singleplayer campaign. You only need to change the following:

Every scenario which should not be available to start directly, should have allow_new_game=no inside the [scenario] tag. This will prevent it from showing as an "entry point" in the multiplayer configuration screen.
For scenarios that don't use allow_new_game=no, one could make use of new_game_title to have a custom title. This is useful if the campaign is supposed to have multiple entry points such as chapters.
Each human-controlled side needs to have a controller=human key defined in its [side] tag to work in network mode.
Each human-controlled side also needs to have a save_id defined inside its [side] tag. Each side's save_id should be unique, and it should be the same in every scenario. Without this, your recall lists and leaders will not carry over from one scenario to the next.
If you want to carry over information for ai sides, they need to have a save_id defined and persistent=yes in their [side] tags.

Other Notes

To ensure that your scenario settings won't get overwritten by the settings from the multiplayer configure dialog, you can set force_use_map_settings=true. However, if your campaign is not intended to be played strictly with default settings, you can set it to false.

If any settings are still taken from the multiplayer configure dialog, it is possible to overwrite them in the prestart event. Useful tags include [set_recruit], [modify_side], [modify_turns] and [remove_shroud]. There is currently no way to remove fog. You might also want to use experience_modifier=100 in the [scenario] tag.

Synchronization

When creating multiplayer content, you should be cautious of code that might change on one client but not the other players'. Not doing so can result in an OOS_(Out_of_Sync) error.

Most [event]s are synched across all clients, but a few still have issues. A full list of safe events can be found on the [| EventsWML] page.

It's possible to randomize variables in MP scenarios, but there are a few caveats to keep in mind. The problem is that random is initialized once and needs to be kept in sync on all clients. That means that if random gets called more often on one client than on the others, they get out-of-sync. This happens in all select and ai turn events (so you cannot use random here). There are other situations not related to the type of event where code might not execute on all clients, an example of this follows:

[event]
   name = turn 3
   [message]
     side_for=2
     message= _ "Play the casino!"
     [option]
       message="Yes, I'll bet 100 gold."
       [command]
         {RANDOM 0..200}
         {MY_ADJUST_SIDE_GOLD_MACRO 2 $random}
       [/command]
     [/option]
     [option]
       message= _ "Not interested."
     [/option]
   [/message]
[/event]

Player 2 gets the chance to get his client's rand out of sync. Even if the message and options were displayed for all players, they could still make different choices (leading to {RANDOM} getting executed or not)! Moved out of the message, it would work:

[event]
   name = turn 3
   {RANDOM 0..200}
   [message]
     side_for=2
     message= _ "Play the casino!"
     [option]
       message="Yes, I'll bet 100 gold."
       [command]
         {MY_ADJUST_SIDE_GOLD_MACRO 2 $random}
       [/command]
     [/option]
     [option]
       message= _ "Not interested."
     [/option]
   [/message]
[/event]

The {RANDOM} is now used by all players, but only used by player 2 if he makes the corresponding choice.