Difference between revisions of "MultiplayerContent"

Latest revision as of 04:58, 10 December 2023

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 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.

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. (Version 1.13.? and later only) This is no longer true, allow_new_game=no is now the default
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. (Version 1.13.? and later only) This is no longer true, save_id defaults to id, just like in sp
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. (The same is true for singleplayer campaigns)
(Version 1.13.? and later only) You can use previous_save_id to tell the engine which player shodul control which side. For example if you have a multiplayer campaign and in scenario1 you have two sides with ids Kalenz and Landar, and in scenario2 you have sides with ids Konrad and Delfador you can use previous_save_id=Kalenz and previous_save_id=Landar in scenario2 to make sure that the player that previously controlled Kalenz now controls Konrad and the player that previously controlled Landar now controlls Delfador.

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],[remove_shroud], and [lift_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 Out of Sync error. Most [event]s are synced across all clients, but a few still have issues. A full list of safe events can be found on the EventWML page.

@@ Line 1: / Line 1: @@
-== Building multiplayer campaigns ==
+{{Translations}}
+{{Create}}
-Both the stable and development versions of wesnoth have basic support for campaigns that can be played in multiplayer mode, with your friends, or even with an AI. Since version 1.1.8, more features and support have been added so we recommend a versions 1.1.8+. There will still be some things that don't work as expected as multiplayer campaigns are an area for exploration. 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.
+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 documented here, so you might want to read [[BuildingScenarios]] and [[BuildingCampaigns]] first.
-This page only documents the differences between writing multiplayer campaigns and single player campaigns, so you might want to read up on [[BuildingCampaigns]] and [[BuildingMultiplayer]] first.
-=== The campaign file ===
+<b>Note:</b> This page assumes you have a basic add-on set up as described in [[AddonStructure]], as well as some coded content.
-Multiplayer campaigns do not use the [campaign] tag. As a result of this, multiplayer campaigns only support one difficulty level, though you could support more with enough WML, if you're feeling ambitious. The "campaign file" should look something like this:
+== Multiplayer scenarios ==
- #ifdef MULTIPLAYER
+You can play standalone scenarios in multiplayer mode without setting up a campaign (this isn't possible in singleplayer). Simply make the following modifications:
- {@campaigns/My_Campaign/scenarios}
- #endif
-Anything that you would normally put in the campaign tag now goes into the first scenario, if it's supported there. The order of scenarios is determined by next_scenario tags, just like in single player.
+* In the _main.cfg file, use <b>#ifdef MULTIPLAYER</b> as the load conditional
+* In the scenario configuration file, use a toplevel <b>[multiplayer]</b> tag instead of <b>[scenario]</b> tag
-=== Scenarios ===
+== Multiplayer campaigns ==
-A scenario in a multiplayer campaign is almost identical to a scenario in a single player campaign. You only need to change the following:
+<b>Note:</b> This section is relevant for version '''1.11.6 and higher'''.
-* The [scenario] tag should be replaced with a [multiplayer] tag.
+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 '''next_scenario''' key points to the id of the next scenario.
-* Every scenario after the first should have '''allow_new_game=no''' inside the [multiplayer] tag. This will prevent it from showing up in the map selection menu. ''This does not work in v1.1'', but it causes no harm, and it will work in the future. ''(This still doesn't work in 1.2.2, and even prevents your campaign from working. I suggest you leave this commented out until the bug gets fixed.)''
-* In v1.1, every scenario in the campaign will appear on the map selection menu, so be sure to include your campaign's name in the [multiplayer] tag's name key. Alternatively, include a warning like "DO NOT PLAY".
-* Each human-controlled side needs to have a '''controller=human''' key defined in their [side] tag to work in network mode.
-* Each human-controlled side also needs to have a '''save_id''' defined inside their [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.
-* Each human-controlled side has to have a leader '''type=''' definition in every scenario except the first one . It doesn't matter which type you choose cause the type set here gets replaced by the actual leader in the recall list.
-* Each AI-controlled side should have '''allow_player=no''' in their [side] tag.
-* The [story] tag will only display for the first player (or maybe it's the host player). You'll have to use [message] tags in the start event if you want everyone to read the story.
-* If you have a file containing macros, it must be referenced by every scenario, since there is no proper campaign file to include it from.
-=== The first scenario ===
+==== The Campaign Tag ====
-The first scenario might need some extra work, because the settings from the multiplayer dialog will override the settings in the scenario. However, most of the multiplayer settings can be overridden in the prestart event.
+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.
-Use a macro like this to force a side to have a particular type of leader.
+==== The Scenario File ====
- #define MP_SIDE SIDENO TYPE DESC
-         [store_unit]
-         variable=oldunit
-         kill=yes
-                 [filter]
-                 side={SIDENO}
-                 [/filter]
-         [/store_unit]
-         [unit]
-         type={TYPE}
-         description={DESC}
-         unrenameable=yes
-         side={SIDENO}
-         x,y=$oldunit.x,$oldunit.y
-         canrecruit=1
-         [/unit]
-         [clear_variable]
-         name=oldunit
-         [/clear_variable]
- #enddef
-Other 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 [multiplayer] tag.
+A scenario in a multiplayer campaign is almost identical to a scenario in a singleplayer campaign. You only need to change the following:
-=== Custom units ===
+* 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. {{DevFeature1.13|?}} This is no longer true, '''allow_new_game=no''' is now the default
+* 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. {{DevFeature1.13|?}} This is no longer true, '''save_id''' defaults to '''id''', just like in sp
+* 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. (The same is true for singleplayer campaigns)
+* {{DevFeature1.13|?}} You can use '''previous_save_id''' to tell the engine which player shodul control which side. For example if you have a multiplayer campaign and in scenario1 you have two sides with ids Kalenz and Landar, and in scenario2 you have sides with ids Konrad and Delfador you can use '''previous_save_id=Kalenz''' and '''previous_save_id=Landar''' in scenario2 to make sure that the player that previously controlled Kalenz now controls Konrad and the player that previously controlled Landar now controlls Delfador.
-Since there is no [campaign] tag, there is no natural way to include custom units in a multiplayer campaign. However, there are two workarounds. One way is to use [[EffectWML]] or [store_unit] to modify a mainline unit. The other way is to make your custom units available via an [[EraWML|era]], or by dropping them into ~wesnoth/data/units. If you go this route, using an era is better, because you can keep the units in your campaign directory.
+== 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],[remove_shroud], and [lift_fog]. You might also want to use <b>experience_modifier=100</b> 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) | Out of Sync]] error. Most [event]s are synced across all clients, but a few still have issues. A full list of safe events can be found on the [[EventWML#Multiplayer_safety | EventWML]] page.
 == See Also ==
-* [http://www.wesnoth.org/forum/viewtopic.php?t=11349 Multiplayer Campaigns HOWTO forum post]
+* [[Create]]
 * [[BuildingScenarios]]
-* [[BuildingMultiplayer]]
+* [[BuildingCampaigns]]
+[[Category:Create]]