OOS (Out of Sync) - Revision history

Soliton: /* Game becomes out of sync */ typo fixes

2024-10-11T16:50:29Z

‎Game becomes out of sync: typo fixes

Egallager: /* Found dependent command */ cleanup

2023-04-19T08:03:50Z

‎Found dependent command: cleanup

Octalot: /* Hints To Debug OOS Errors */ Note 1.15.4 disabling of inactive add-ons

2020-10-24T08:02:45Z

‎Hints To Debug OOS Errors: Note 1.15.4 disabling of inactive add-ons

Gfgtdf: /* List of Non Mp/Replay safe Wml/Lua functions */

2019-02-12T03:19:06Z

‎List of Non Mp/Replay safe Wml/Lua functions

Celtic Minstrel: /* List of Non Mp/Replay safe Wml/Lua functions */ Note on unsafe uses of filters

2019-02-10T21:47:18Z

‎List of Non Mp/Replay safe Wml/Lua functions: Note on unsafe uses of filters

Celtic Minstrel: /* List of Non Mp/Replay safe Wml/Lua functions */ Clarifications, punctuation, typos, other misc cleanup

2019-01-15T04:15:59Z

‎List of Non Mp/Replay safe Wml/Lua functions: Clarifications, punctuation, typos, other misc cleanup

Celtic Minstrel: /* List of Non Mp/Replay safe Wml/Lua functions */ Remove duplicated passage from previous edit

2019-01-15T04:09:33Z

‎List of Non Mp/Replay safe Wml/Lua functions: Remove duplicated passage from previous edit

Gfgtdf: /* List of Non Mp/Replay safe Wml/Lua functions */

2019-01-14T16:19:25Z

‎List of Non Mp/Replay safe Wml/Lua functions

Gfgtdf: /* Hints To Debug OOS Erros */

2018-09-17T23:16:15Z

‎Hints To Debug OOS Erros

Gfgtdf: /* Some examples */

2018-09-17T23:15:20Z

‎Some examples

@@ Line 14: / Line 14: @@
 === Game becomes out of sync ===
-During the actual game all clients have their own local gamesate. The Clients communicate by sending 'player actions' like 'move unit at (3,4) to (5,5) with the route ((3,4),(3,5),(4,5),(5,5))'. These actions are evaluated on the other clients which should lead to the same local gamesate on all clients (asuming that they had the same local gamestate before that action). If at any time clients don't have the same local gamestate we call that OOS. The clients usually send these actions as soon as they know that they cannot be undone. Those actions that are sended to the other clients are called "synced user actions". For example move,recall,recuit ... are such actions. There are also unsynced user action like "select" that only happen on one client and are not sended to other clients. The consequence is that "select" events only run on one client, thus changing the gamestate from inside a select event results in OOS.
+During the actual game all clients have their own local gamestate. The Clients communicate by sending 'player actions' like 'move unit at (3,4) to (5,5) with the route ((3,4),(3,5),(4,5),(5,5))'. These actions are evaluated on the other clients which should lead to the same local gamestate on all clients (assuming that they had the same local gamestate before that action). If at any time clients don't have the same local gamestate we call that OOS. The clients usually send these actions as soon as they know that they cannot be undone. Those actions that are sent to the other clients are called "synced user actions". For example move,recall,recuit ... are such actions. There are also unsynced user action like "select" that only happen on one client and are not sent to other clients. The consequence is that "select" events only run on one client, thus changing the gamestate from inside a select event results in OOS.
 A complete list of unsynchronized events can be found here: [[EventWML#Multiplayer_safety]].
@@ Line 20: / Line 20: @@
 The replay works the same way:
-the replay begins with the start gamesate and then eveluates all the synced user actions it can find on the replay. If the resulted gamesate is different than the original gamesate we have an OOS. That's why in most times replay safety is the same as multiplayer safety.
+the replay begins with the start gamestate and then evaluates all the synced user actions it can find on the replay. If the resulted gamestate is different than the original gamestate we have an OOS. That's why in most times replay safety is the same as multiplayer safety.
 Generally speaking a replay file receives the same kind of information about the game that a multiplayer observer of a game would receive, so any technique which would cause OOS for multiplayer will also cause corrupted replays.
@@ Line 27: / Line 27: @@
 {{DevFeature1.13|0}} You can know whether the current code runs in a synced context by checking wesnoth.current.synced_state.
-In order to get the same local gamesate on all clients you should only make the gamesate depend on deterministic functions that return the same value on all clients, for example side.cotroller s getter or math.rand is no such function. If you want to call these functions you should use wesnoth.syncronize_choice which allows you to run code on one client and then return the result to all clients so all clients are guaranteed to get the same result. But note that becasue the code in synconize_choice only runs one one client it should only calculate the return value and not change the gamestate.
+In order to get the same local gamestate on all clients you should only make the gamestate depend on deterministic functions that return the same value on all clients, for example side.controller s getter or math.rand is no such function. If you want to call these functions you should use wesnoth.synchronize_choice which allows you to run code on one client and then return the result to all clients so all clients are guaranteed to get the same result. But note that because the code in synchronize_choice only runs one one client it should only calculate the return value and not change the gamestate.
 === The rng ===

@@ Line 40: / Line 40: @@
 === Found dependent command ===
-It's posible to get a OOS eror with the message "Found (in-)dependent command" or siilar here is explained what this means: During the game the clients send each other packages ([command] see http://wiki.wesnoth.org/ReplayWML). There are 2 types of these packages: the 'normal' commands that contains new user actions like attack, recruit, recall, move...  . And there are the 'dependent' packages that contains answer to questions asked to specific clients (the results of local choices). For example advancement choices. But also new random seeds (questions asked to the server) and get_global_variable are in this category. If a client received an answer to a local choice when none was expected the games gives a "Found dependent command when is_synced=false" OOS error message. The opposite sitation when a client expectes an answer to a local choice but receives a new user action also gives a OOs message.
+It's possible to get a OOS eror with the message "Found (in-)dependent command" or similar here is explained what this means: During the game the clients send each other packages ([command] see [[ReplayWML]]). There are 2 types of these packages: the 'normal' commands that contains new user actions like attack, recruit, recall, move...  . And there are the 'dependent' packages that contains answer to questions asked to specific clients (the results of local choices). For example advancement choices. But also new random seeds (questions asked to the server) and get_global_variable are in this category. If a client received an answer to a local choice when none was expected the games gives a "Found dependent command when is_synced=false" OOS error message. The opposite situation when a client expects an answer to a local choice but receives a new user action also gives a OOs message.
 == Some examples ==

@@ Line 51: / Line 51: @@
 * What if Player B tried to attack one of Player A's units?  To Player B's client it seems like a normal move, but to Player A's client it seems like an empty hex is trying to attack him.
-== Hints To Debug OOS Erros ==
+== Hints To Debug OOS Errors ==
-As noted before, OOS happens when two clients disagree about the current gamestate, So if ina  game with clients A, B and C, client A got an OOS during the turn of client B it (often, not always) indicates that client A and B disagree about the gamstate, in this situation client C an often be used to decide which client did the wrong calculations, if client C also got an oos errormessage during the turn of client B, it probably client B that did the wrong calculations, otherwise its probably side A. The most common sources of OOS are:
+As noted before, OOS happens when two clients disagree about the current gamestate. So if in a game with clients A, B and C, client A got an OOS during the turn of client B it (often, not always) indicates that client A and B disagree about the gamestate, in this situation client C can often be used to decide which client did the wrong calculations; if client C also got an oos error message during the turn of client B, it's probably client B that did the wrong calculations, otherwise it's probably side A. The most common sources of OOS are:
-. Bad add-ons: in particular you need to be aware of the fact that addons can change the gamestate and cause OOS even if they are not currently active (for example as a modification or a mp scenario ), add-ons can cause OOS by just having them installed even if the seem to be complteley unrelated to the current game.
+. Bad add-ons: in particular you need to be aware of the fact that addons can change the gamestate and cause OOS even if they are not currently active (for example as a modification or a mp scenario ), add-ons can cause OOS by just having them installed even if they seem to be completely unrelated to the current game. Less likely to happen on recent {{DevFeature1.15|4}} versions of the engine, as inactive addons are ignored.
-. User changing the game/addons files : it often unclear to users which part of the data can be changed and which can not be changes without causing OOS. For example some mp scenarios include lua code via macro inclusion ''code={myluafile.lua}'' while others include lua code via dofile/require ''wesnoth.dofile("myluafile.lua")'', in the former case it is usually safe to change the lua files because the hosts sends the other client his version of the lua file along with the other scenario content, while in the later case it fill usually lead to OOS.
+. User changing the game/addons files : it often unclear to users which part of the data can be changed and which can not be changes without causing OOS. For example some mp scenarios include lua code via macro inclusion ''code={myluafile.lua}'' while others include lua code via dofile/require ''wesnoth.dofile("myluafile.lua")'', in the former case it is usually safe to change the lua files because the hosts sends the other client his version of the lua file along with the other scenario content, while in the latter case it will usually lead to OOS.
-. Outdated wesnoth versions. While we try to keep the wesnoth versions mp compatible, it is still important to keep your wesnoth version up to date. In particular to avoid OOS erros casued by engine bug that were fixed in newer versions, you can use the mp server command ''/q version <playername>'' to figure out what wesnoth version another player is using.
+. Outdated wesnoth versions. While we try to keep the wesnoth versions mp compatible, it is still important to keep your wesnoth version up to date. In particular to avoid OOS errors caused by engine bugs that were fixed in newer versions, you can use the mp server command ''/q version <playername>'' to figure out what wesnoth version another player is using.
 . cheating players: not much to say, player can intentionally change wesnoth game files in a stupid way hoping it would give them an advantage when it will actually just cause OOS.
-. Engine bugs: Wesnoth is not always bugfree, the main diffculty in investigating engine OOS errors is that most of the OOS erros reported actually come from one of the other posibilities above, so its somehow hard to find the 'real' oos engine bugs in the wild. Some features in particular 'delayed shroud updates' and 'multiplayer campaigns' have often casued OOS in the past though and it possible they they will be broken agian in the future due to their complex nature.
+. Engine bugs: Wesnoth is not always bugfree, the main difficulty in investigating engine OOS errors is that most of the OOS errors reported actually come from one of the other possibilities above, so it's somehow hard to find the 'real' oos engine bugs in the wild. Some features in particular 'delayed shroud updates' and 'multiplayer campaigns' have often caused OOS in the past though and it's possible they they will be broken again in the future due to their complex nature.
 == How to make your code safe ==

@@ Line 81: / Line 81: @@
 ** unit.name (it is possible for players to rename units, also in mp the leaders names changes whenever a side controller changes, also see the point below about any attribute changing the visual appearance.)
 ** any attribute describing the visual appearance of that unit (unit.overlays, unit.profile etc.). In default wesnoth they may be be the same on all clients, but people usually assume that they can change the visuals of wesnoth by modifying the cfg files or via [modification]s in add-ons without causing OOS.
-* Filters that cause side-effects, especially when used in unit abilities and weapon specials
+* Filters that cause side-effects, especially when used in unit abilities and weapon specials.
-** The <tt>lua_function</tt> key calls an arbitrary Lua function. If the function called causes ''any'' change to the gamestate, you could get an out-of-sync error. This includes simply generating a random number, even using synchronized functions - it's possible the filter may be evaluated a different number of times on different clients. For filters used in synchronized events, the situation is not so bad, and generating random numbers should be safe as long as they are synchronized.
+** Clearly a filter should not change the gamestate in a unsynced context.
-** The <tt>formula</tt> is safe as long as you do not use the dice operator in the formula.
+** In the past the order in which filters are evaluated has been changed even during stable versions, so it is possible that even in a synced context a filter might be skipped on some clients only. In conclusion it is better to not rely on the order in which filters are evaluated or test in each wesnoth version. In particular:
 * Variables/wml tags
 ** side.controller (gained by [store_side] or wesnoth.sides) – this variable will be different for each client. An exception is when controller is "null" which happens if and only if it is "null" on all other clients as well.

@@ Line 81: / Line 81: @@
 ** unit.name (it is possible for players to rename units, also in mp the leaders names changes whenever a side controller changes, also see the point below about any attribute changing the visual appearance.)
 ** any attribute describing the visual appearance of that unit (unit.overlays, unit.profile etc.). In default wesnoth they may be be the same on all clients, but people usually assume that they can change the visuals of wesnoth by modifying the cfg files or via [modification]s in add-ons without causing OOS.
 * Variables/wml tags
 ** side.controller (gained by [store_side] or wesnoth.sides) – this variable will be different for each client. An exception is when controller is "null" which happens if and only if it is "null" on all other clients as well.

@@ Line 72: / Line 72: @@
 === List of Non Mp/Replay safe Wml/Lua functions ===
-These functions/values might return different values on different clients or in replays. To prevent OOS you must use wesnoth.synchronize_choice or {{DevFeature1.13|0}} [sync_variable] so query these values when you want to change the gamestate depending on these values.
+These functions/values might return different values on different clients or in replays. To prevent OOS you must use wesnoth.synchronize_choice or {{DevFeature1.13|0}} [sync_variable] to query these values when you want to change the gamestate depending on these values.
-* Using functions that depend on other installed addons, for example ''#wesnoth.unit_types'' will usually be different on each client.
+* Using functions that depend on other installed addons. For example, ''#wesnoth.unit_types'' will usually be different on each client.
-* Using translatable strings for gamestate calculations, obviously the value of these string depend on the each clients language setting.
+* Using translatable strings for gamestate calculations; obviously the value of these strings depends on each client's language setting.
-* Unsafe events, see https://wiki.wesnoth.org/EventWML#Multiplayer_safety
+* Unsafe events, see [[EventWML#Multiplayer_safety|here]] for more detail
-* Unit attributes (accessible via stored units, lua proxy units of unit filters ([filter_wml]))
+* Unit attributes, accessible via stored units, lua proxy units, or unit filters (via <tt>[filter_wml]</tt>)
 ** unit.goto_x and unit.goto_y (used by the ai and by multi turn moves internally)
 ** unit.facing (in some cases like when unstoring units the unit facing might be set randomly)
@@ Line 82: / Line 82: @@
 ** any attribute describing the visual appearance of that unit (unit.overlays, unit.profile etc.). In default wesnoth they may be be the same on all clients, but people usually assume that they can change the visuals of wesnoth by modifying the cfg files or via [modification]s in add-ons without causing OOS.
 * Variables/wml tags
-** side.controller (gained by [store_side] or wesnoth.sides) this variable will be different for each client. An exception is when controller is "null" which happens if and only if it is "null" on all other clients as well.
+** side.controller (gained by [store_side] or wesnoth.sides) – this variable will be different for each client. An exception is when controller is "null" which happens if and only if it is "null" on all other clients as well.
 ** [set_variable] time=stamp - obviously the result of this operation will be different for all clients
 * Lua functions:
 ** math.random()
 ** wesnoth.game_config.debug, .version have (possibly) different values
-** any dialog wich queries input from a client (wesnoth.show_dialog)
+** any dialog which queries input from a client (eg wesnoth.show_dialog)
 ** wesnoth.sides[i].controller (same as with [store_side]), wesnoth.sides[i].is_local
 ** any non mp-safe wml tag called by lua

@@ Line 55: / Line 55: @@
 As noted before, OOS happens when two clients disagree about the current gamestate, So if ina  game with clients A, B and C, client A got an OOS during the turn of client B it (often, not always) indicates that client A and B disagree about the gamstate, in this situation client C an often be used to decide which client did the wrong calculations, if client C also got an oos errormessage during the turn of client B, it probably client B that did the wrong calculations, otherwise its probably side A. The most common sources of OOS are:
-) Bad add-ons: in particular you need to be aware of the fact that addons can change the gamestate and cause OOS even if they are not currently active (for example as a modification or a mp scenario ), add-ons can cause OOS by just having them installed even if the seem to be complteley unrelated to the current game.
+. Bad add-ons: in particular you need to be aware of the fact that addons can change the gamestate and cause OOS even if they are not currently active (for example as a modification or a mp scenario ), add-ons can cause OOS by just having them installed even if the seem to be complteley unrelated to the current game.
-) User changing the game/addons files : it often unclear to users which part of the data can be changed and which can not be changes without causing OOS. For example some mp scenarios include lua code via macro inclusion ''code={myluafile.lua}'' while others include lua code via dofile/require ''wesnoth.dofile("myluafile.lua")'', in the former case it is usually safe to change the lua files because the hosts sends the other client his version of the lua file along with the other scenario content, while in the later case it fill usually lead to OOS.
-) Outdated wesnoth versions. While we try to keep the wesnoth versions mp compatible, it is still important to keep your wesnoth version up to date. In particular to avoid OOS erros casued by engine bug that were fixed in newer versions, you can use the mp server command ''/q version <playername>'' to figure out what wesnoth version another player is using.
+. User changing the game/addons files : it often unclear to users which part of the data can be changed and which can not be changes without causing OOS. For example some mp scenarios include lua code via macro inclusion ''code={myluafile.lua}'' while others include lua code via dofile/require ''wesnoth.dofile("myluafile.lua")'', in the former case it is usually safe to change the lua files because the hosts sends the other client his version of the lua file along with the other scenario content, while in the later case it fill usually lead to OOS.
-) cheating players: not much to say, player can intentionally change wesnoth game files in a stupid way hoping it would give them an advantage when it will actually just cause OOS.
-) Engine bugs: Wesnoth is not always bugfree, the main diffculty in investigating engine OOS errors is that most of the OOS erros reported actually come from one of the other posibilities above, so its somehow hard to find the 'real' oos engine bugs in the wild. Some features in particular 'delayed shroud updates' and 'multiplayer campaigns' have often casued OOS in the past though and it possible they they will be broken agian in the future due to their complex nature.
+. Outdated wesnoth versions. While we try to keep the wesnoth versions mp compatible, it is still important to keep your wesnoth version up to date. In particular to avoid OOS erros casued by engine bug that were fixed in newer versions, you can use the mp server command ''/q version <playername>'' to figure out what wesnoth version another player is using.
 == How to make your code safe ==