Desynchronization - Revision history

PennyJim: Repair API links

2025-03-03T02:41:27Z

Repair API links

← Older revision		Revision as of 02:41, 3 March 2025
Line 39:		Line 39:

	==== Code that causes desyncs ====		==== Code that causes desyncs ====
	There are a number of ways mod and scenario code can cause desyncs, such as due to incorrect variable scoping, requiring or API event handling. Examples of these can be found in [[Tutorial:Modding tutorial/Gangsir#Multiplayer_and_desyncs\|Gangsir's modding tutorial multiplayer and desyncs section]], with the full technical definition of usage constraints for API events in the [https://lua-api.factorio.com/latest/~~Data~~-~~Lifecycle~~.html Factorio API data lifecycle]. Not all instances of non-compliance will lead to desyncs or errors, but most will. For this reason, it is recommended to always maintain compliance to avoid risk and time-consuming testing. Instances of non-compliance found should be raised to the code author.		There are a number of ways mod and scenario code can cause desyncs, such as due to incorrect variable scoping, requiring or API event handling. Examples of these can be found in [[Tutorial:Modding tutorial/Gangsir#Multiplayer_and_desyncs\|Gangsir's modding tutorial multiplayer and desyncs section]], with the full technical definition of usage constraints for API events in the [https://lua-api.factorio.com/latest/auxiliary/data-lifecycle.html Factorio API data lifecycle]. Not all instances of non-compliance will lead to desyncs or errors, but most will. For this reason, it is recommended to always maintain compliance to avoid risk and time-consuming testing. Instances of non-compliance found should be raised to the code author.

	==== Comparing game state & save files ====		==== Comparing game state & save files ====
Line 48:		Line 48:
	Within each savegame's zip in the desync report are a number of files that when compared can show data changes. As the server copy of the save is obtained after the desync there may be genuine differences between the files. So differences aren't hard evidence of the cause of a desync, but only a pointer on where to investigate further.		Within each savegame's zip in the desync report are a number of files that when compared can show data changes. As the server copy of the save is obtained after the desync there may be genuine differences between the files. So differences aren't hard evidence of the cause of a desync, but only a pointer on where to investigate further.

	* script.dat - contains the scenario and mods [https://lua-api.factorio.com/latest/~~Global~~.html Factorio ~~global~~ tables]. Generally, the save's persistent data should be the same between the 2 saves. On rare occasions, there can be a difference due to how the information is written out to the file. Should a mod causes a player's game to desync it can cause the player's game to stop processing other mod activity mid tick. This can lead those mod's global tables to have differences between the player and the server copies despite having no code defects themselves.		* script.dat - contains the scenario and mods [https://lua-api.factorio.com/latest/auxiliary/storage.html Factorio storage tables]. Generally, the save's persistent data should be the same between the 2 saves. On rare occasions, there can be a difference due to how the information is written out to the file. Should a mod causes a player's game to desync it can cause the player's game to stop processing other mod activity mid tick. This can lead those mod's global tables to have differences between the player and the server copies despite having no code defects themselves.
	* level_with_tags_tick_XXXX.dat - contains the current game state together with additional saving tags to aid human readability. This can show if entity states or chat messages differ. ''level.dat'' is the same information, but without the descriptive tags for data values.		* level_with_tags_tick_XXXX.dat - contains the current game state together with additional saving tags to aid human readability. This can show if entity states or chat messages differ. ''level.dat'' is the same information, but without the descriptive tags for data values.

Curiosity: /* Factorio multiplayer architecture */ fixed spelling

2024-11-27T10:34:45Z

Factorio multiplayer architecture: fixed spelling

← Older revision		Revision as of 10:34, 27 November 2024
Line 9:		Line 9:

	=== Factorio multiplayer architecture ===		=== Factorio multiplayer architecture ===
	Factorio multiplayer code uses deterministic lockstep to synchronize clients. This is a method of synchronizing a game from one computer to another by sending only the user inputs that control that game, rather than networking the state of the objects in the game itself. It means that all ~~player~~'s games need to simulate every single tick of the game identically. If any computer does something ever-so-slightly different, a desynchronization (desync) occurs. The game includes processes to ensure any issues with network traffic do not cause desyncs.		Factorio multiplayer code uses deterministic lockstep to synchronize clients. This is a method of synchronizing a game from one computer to another by sending only the user inputs that control that game, rather than networking the state of the objects in the game itself. It means that all players' games need to simulate every single tick of the game identically. If any computer does something ever-so-slightly different, a desynchronization (desync) occurs. The game includes processes to ensure any issues with network traffic do not cause desyncs.

	=== Player experience of desyncs ===		=== Player experience of desyncs ===

Bilka: formatting, thank you very much for the edits!

2024-08-07T15:43:46Z

formatting, thank you very much for the edits!

← Older revision		Revision as of 15:43, 7 August 2024
Line 6:		Line 6:
	* a bug in a mod/scenario		* a bug in a mod/scenario
	* a miscalculation on server or client hardware		* a miscalculation on server or client hardware
	Networking-, latency or performance problems do ~~NOT~~ cause desyncs.		Networking-, latency or performance problems do ''not'' cause desyncs.

	=== Factorio multiplayer architecture ===		=== Factorio multiplayer architecture ===

Loewchen: /* Desync Investigations */ fixed link

2024-08-05T23:22:35Z

Desync Investigations: fixed link

← Older revision		Revision as of 23:22, 5 August 2024
Line 25:		Line 25:

	== Desync Investigations ==		== Desync Investigations ==
	In most cases when desyncs occur and mods or scenarios are being used they are the cause and need to be handled first. If they are found to not be the cause then it should be reported as a [[#~~Desync_reporting_with_only_base_game~~\|core Factorio desync ~~error~~]]. In both cases identifying the activity that triggers the desync is an important step. For example, whether it is tied to a player's action or activity that happens in the game (i.e. a train arriving at a station) or is a time-related event. In some cases, the desync may not be reproducible and so only a code investigation can work towards a fix.		In most cases when desyncs occur and mods or scenarios are being used they are the cause and need to be handled first. If they are found to not be the cause then it should be reported as a [[#Desync_reporting_of_core_Factorio_game\|core Factorio desync]]. In both cases identifying the activity that triggers the desync is an important step. For example, whether it is tied to a player's action or activity that happens in the game (i.e. a train arriving at a station) or is a time-related event. In some cases, the desync may not be reproducible and so only a code investigation can work towards a fix.

	When desyncs occur and mods/scenarios are in the use there are 2 different approaches that can be taken to help get the issue fixed. The code investigation approach requires you to be familiar with Factorio modding and its coding rules. The less technical method is to identify the mod and activity that causes the desync through trial and error so it can be reported to the mod author.		When desyncs occur and mods/scenarios are in the use there are 2 different approaches that can be taken to help get the issue fixed. The code investigation approach requires you to be familiar with Factorio modding and its coding rules. The less technical method is to identify the mod and activity that causes the desync through trial and error so it can be reported to the mod author.

Loewchen: separate meaning/causes, move info to correct paragraph, clean up and simplify language

2024-08-05T21:25:09Z

separate meaning/causes, move info to correct paragraph, clean up and simplify language

← Older revision		Revision as of 21:25, 5 August 2024
Line 1:		Line 1:
	A desynchronization (desync) is ~~when during multiplayer~~ a ~~player's~~ game ~~becomes desynchronized from~~ the ~~Factorio~~ server~~. Their~~ game ~~has become different from~~ the ~~server's game~~.		A desynchronization (desync) is a disagreement of the game state between the server and at least one client in a multiplayer game, this means the parties no longer run the simulation identically.

	== ~~What are~~ desyncs ==		== How desyncs happen ==
	Desyncs can be caused ~~either~~ by a bug in ~~the core~~ Factorio ~~game~~ code ~~or by~~ a bug in a mod/scenario~~. They should not occur during regular play~~.		Desyncs are errors and should not occur during regular play, they can be caused by:
			* a bug in Factorio code
			* a bug in a mod/scenario
			* a miscalculation on server or client hardware
			Networking-, latency or performance problems do NOT cause desyncs.

	=== Factorio multiplayer architecture ===		=== Factorio multiplayer architecture ===
Line 8:		Line 12:

	=== Player experience of desyncs ===		=== Player experience of desyncs ===
	~~Upon~~ a ~~player's game detecting~~ a desync ~~to the server~~, it ~~immediately~~ disconnects ~~from~~ the ~~server~~ and ~~re-downloads the save game. This~~ download ~~isn't to allow the player to play the game, but to obtain~~ the server~~'s current copy of the save game~~ (map and game state) to include in ~~a desync~~ report. After the download is ~~complete~~ and a desync report has been generated the player is offered the options to view the report, quit or reconnect to the ~~server to play~~.		When a client detects a desync, it disconnects the player and starts to download files from the server (map and game state information) to include them in the [[#Desync_report\|Desync report]], this will take longer than the normal map download. After the download is finished and the desync report has been generated the player is offered the options to view the report, quit or reconnect to continue playing. Depending on the cause of the desync, the client might immediately desync again when reconnecting.

	[[File:Desync report notification.jpg]]		[[File:Desync report notification.jpg]]

	~~The desync report can be provided to either the mod/scenario makers or the Factorio game developers to help them resolve the bug.~~
	~~Depending upon the exact cause of the desync, the player's game may be able to reconnect to the server to play, or they may find it immediately desyncs on reconnection.~~

	=== Desync report ===		=== Desync report ===
	The desync report contains both the player's and server's copy of the save game (map and game state). The player's copy is from when the desync occurred and titled ''desynced-level''. With the server's copy being from when the automatic reconnection was made and titled ''reference-level.zip''. A copy of the players Factorio log file is included titled ''log.txt''. As the report contains two copies of the save game it may have a large file size. Furthermore, the save files that are made for the desync report contain more data than normal save files, further increasing their size.		The desync report will help mod/scenario makers or Factorio developers to fix the underlying bug, it contains both the player's and server's copy of the save game (map and game state). The player's copy is from when the desync occurred and titled ''desynced-level''. With the server's copy being from when the automatic reconnection was made and titled ''reference-level.zip''. A copy of the players Factorio log file is included titled ''log.txt''. As the report contains two copies of the save game it may have a large file size. Furthermore, the save files that are made for the desync report contain more data than normal save files, further increasing their size.

	The desync report does not state the cause of the desync but rather is a record of the game state at the time of the desync.		The desync report does not state the cause of the desync but rather is a record of the game state at the time of the desync.

Ickputzdirwech: Removed {{Languages}}

2023-11-12T09:04:20Z

Removed {{Languages}}

← Older revision		Revision as of 09:04, 12 November 2023
Line 1:		Line 1:
	~~{{Languages}}~~
	A desynchronization (desync) is when during multiplayer a player's game becomes desynchronized from the Factorio server. Their game has become different from the server's game.		A desynchronization (desync) is when during multiplayer a player's game becomes desynchronized from the Factorio server. Their game has become different from the server's game.

	== What are desyncs ==		== What are desyncs ==

	Desyncs can be caused either by a bug in the core Factorio game code or by a bug in a mod/scenario. They should not occur during regular play.		Desyncs can be caused either by a bug in the core Factorio game code or by a bug in a mod/scenario. They should not occur during regular play.

Muppet9010: /* Comparing game state & save files */ clarify the less human readable numbers

2019-08-10T23:12:09Z

Comparing game state & save files: clarify the less human readable numbers

← Older revision		Revision as of 23:12, 10 August 2019
Line 43:		Line 43:

	==== Comparing game state & save files ====		==== Comparing game state & save files ====
	The desync report files and heavy mode dumps contain a number of files that can be compared by any text comparison tool to look for differences. These files are generally sequelized dumps of Lua tables or c++ game objects and so are only partially human readable. The ~~non-~~human readable ~~item~~ can include ~~table ids~~ (0x.~~NUMBER~~) and ''magic'' numbers ~~related to~~ the c++ game state. These ids ~~and references~~ should generally be the same between files as the in-game entity they reference normally won't have changed between the 2 save game states being obtained.		The desync report files and heavy mode dumps contain a number of files that can be compared by any text comparison tool to look for differences. These files are generally sequelized dumps of Lua tables or c++ game objects and so are only partially human readable. The less human readable items can include floating point numbers serilaised (0x.HEXp+HEX) and ''magic'' unique identifier numbers for prototype instances in the c++ game state. These numbers and reference ids should generally be the same between files as the in-game entity they reference normally won't have changed between the 2 save game states being obtained.
	When the data differs between files the source code of that mod/scenario must be examined for all interactions with that data item for any instances of non-compliance.		When the data differs between files the source code of that mod/scenario must be examined for all interactions with that data item for any instances of non-compliance.

Bilka: added link to FFF about heavy mode

2019-04-25T15:10:48Z

added link to FFF about heavy mode

← Older revision		Revision as of 15:10, 25 April 2019
Line 60:		Line 60:
	=== Desync reporting of core Factorio game ===		=== Desync reporting of core Factorio game ===
	If no mod or scenario were involved in the desync, the desync report and activity information should be posted to the [https://forums.factorio.com/53851 Factorio forums bug report section].		If no mod or scenario were involved in the desync, the desync report and activity information should be posted to the [https://forums.factorio.com/53851 Factorio forums bug report section].

			== See also ==
			* [https://www.factorio.com/blog/post/fff-63 FFF 63] - How heavy mode works

	[[Category:Technical]]		[[Category:Technical]]

Muppet9010: /* Player experience of desyncs */ correct usage of re-connect to save game download

2019-03-11T00:40:03Z

Player experience of desyncs: correct usage of re-connect to save game download

← Older revision		Revision as of 00:40, 11 March 2019
Line 10:		Line 10:

	=== Player experience of desyncs ===		=== Player experience of desyncs ===
	Upon a player's game detecting a desync to the server, it immediately disconnects from the server and ~~starts to reconnect~~. This ~~reconnection~~ isn't to allow the player to play the game, but to obtain the server's copy of the save game (map and game state) to include in a desync report. After the ~~reconnection~~ is complete the player is offered the options to view the report, quit or reconnect to the server to play.		Upon a player's game detecting a desync to the server, it immediately disconnects from the server and re-downloads the save game. This download isn't to allow the player to play the game, but to obtain the server's current copy of the save game (map and game state) to include in a desync report. After the download is complete and a desync report has been generated the player is offered the options to view the report, quit or reconnect to the server to play.

	[[File:Desync report notification.jpg]]		[[File:Desync report notification.jpg]]

Muppet9010: clarify "player" to "player's game" where appropriate. replace "client" to "player" type wording for consistency

2019-03-06T15:38:20Z

clarify "player" to "player's game" where appropriate. replace "client" to "player" type wording for consistency

← Older revision		Revision as of 15:38, 6 March 2019
Line 7:		Line 7:

	=== Factorio multiplayer architecture ===		=== Factorio multiplayer architecture ===
	Factorio multiplayer code uses deterministic lockstep to synchronize clients. This is a method of synchronizing a game from one computer to another by sending only the user inputs that control that game, rather than networking the state of the objects in the game itself. It means that all ~~players~~ need to simulate every single tick of the game identically. If any computer does something ever-so-slightly different, a desynchronization (desync) occurs. The game includes processes to ensure any issues with network traffic do not cause desyncs.		Factorio multiplayer code uses deterministic lockstep to synchronize clients. This is a method of synchronizing a game from one computer to another by sending only the user inputs that control that game, rather than networking the state of the objects in the game itself. It means that all player's games need to simulate every single tick of the game identically. If any computer does something ever-so-slightly different, a desynchronization (desync) occurs. The game includes processes to ensure any issues with network traffic do not cause desyncs.

	=== Player experience of desyncs ===		=== Player experience of desyncs ===
	Upon a desync ~~between a player and~~ server ~~occurring~~, ~~that player~~ immediately ~~is disconnected~~ from the server and starts to reconnect. This reconnection isn't to allow the player to play the game, but to obtain the server's copy of the save game (map and game state) to include in a desync report. After the reconnection is complete the player is offered the options to view the report, quit or reconnect to the server to play.		Upon a player's game detecting a desync to the server, it immediately disconnects from the server and starts to reconnect. This reconnection isn't to allow the player to play the game, but to obtain the server's copy of the save game (map and game state) to include in a desync report. After the reconnection is complete the player is offered the options to view the report, quit or reconnect to the server to play.

	[[File:Desync report notification.jpg]]		[[File:Desync report notification.jpg]]

	The desync report can be provided to either the mod/scenario makers or the Factorio game developers to help them resolve the bug.		The desync report can be provided to either the mod/scenario makers or the Factorio game developers to help them resolve the bug.
	Depending upon the exact cause of the desync the player may be able to reconnect to the server ~~and continue playing~~, or they may find ~~they~~ immediately ~~desync~~ on ~~reconnecting again~~.		Depending upon the exact cause of the desync, the player's game may be able to reconnect to the server to play, or they may find it immediately desyncs on reconnection.

	=== Desync report ===		=== Desync report ===
Line 49:		Line 49:
	Within each savegame's zip in the desync report are a number of files that when compared can show data changes. As the server copy of the save is obtained after the desync there may be genuine differences between the files. So differences aren't hard evidence of the cause of a desync, but only a pointer on where to investigate further.		Within each savegame's zip in the desync report are a number of files that when compared can show data changes. As the server copy of the save is obtained after the desync there may be genuine differences between the files. So differences aren't hard evidence of the cause of a desync, but only a pointer on where to investigate further.

	* script.dat - contains the scenario and mods [https://lua-api.factorio.com/latest/Global.html Factorio global tables]. Generally, the save's persistent data should be the same between the 2 saves. On rare occasions, there can be a difference due to how the information is written out to the file. Should a mod causes a ~~client~~ to desync it can cause the ~~clients~~ game to stop processing other mod activity mid tick. This can lead those mod's global tables to have differences between the ~~client~~ and the server despite having no code defects themselves.		* script.dat - contains the scenario and mods [https://lua-api.factorio.com/latest/Global.html Factorio global tables]. Generally, the save's persistent data should be the same between the 2 saves. On rare occasions, there can be a difference due to how the information is written out to the file. Should a mod causes a player's game to desync it can cause the player's game to stop processing other mod activity mid tick. This can lead those mod's global tables to have differences between the player and the server copies despite having no code defects themselves.
	* level_with_tags_tick_XXXX.dat - contains the current game state together with additional saving tags to aid human readability. This can show if entity states or chat messages differ. ''level.dat'' is the same information, but without the descriptive tags for data values.		* level_with_tags_tick_XXXX.dat - contains the current game state together with additional saving tags to aid human readability. This can show if entity states or chat messages differ. ''level.dat'' is the same information, but without the descriptive tags for data values.