Understanding multiplayer events, GUI, and desyncs

[hyperthalamus]

Hi everyone,
disclaimer: I'm super new to writing mods, so expect a couple of noob questions:
I want to write a mod that builds entities, triggered by various events (GUI and other).
I'm trying to understand how exactly GUI events and events in general work in multiplayer context and how to avoid desyncs.

Let's say I have a GUI button which on_click will build some entity right besides the player.
What does actually happen here in mp?
What is being sent over to other clients?

Do other clients get some message to build that entity?
Or do they also just get the GUI on_click event and essentially the same mod needs to "replicate" the behavior of building an entity as a result?
I'm trying to wrap my head around this determinism that is mentioned everywhere... is that what is meant?

I'm also a bit confused about the raise_built parameter in LuaSurface.create_entity() and the events that deal with building.
For events I found on_built_entity as well as script_raised_built.
Why are there two different events here for entities being built?
Why does for example on_entity_renamed have a by_script flag instead?

The script_raised_built is described as static event, what does that mean?
I have a feeling that this has something to do with how multiplayer works...

Is the on_built_entity event ever raised when building an entity from a script?
I was thinking if a player triggers some entity building by clicking the GUI, if I couldn't have this registered as the player having built the entity.

[Qon]

I'm trying to understand how exactly GUI events and events in general work in multiplayer context and how to avoid desyncs.

In your other thread boskid answered this already

Here there is the most important concept to understand: "Part of game state". Whenever you see "part of game state" that means its a variable which can be obtained on all instances and it has the same value on all of them. Under assumption of a program determinism, if your script is deterministic and uses only data that are part of game state, you can make changes in the game state keeping the invariant safe. If it would not be maintained, a client will desync and a player will be unhappy way more than if a game would be running slow.
[...]
You may notice in almost all lua-api, that we never expose anything that is not part of the game state just for that reason: if there would be anything exposed which is not part of the game state, mods will use it and they will desync immediately.

A thing which is the closest one to being a "not part of game state" is the script loading. When a client joins we do not want every client to discard state of all of its mods and reload it as the newly joining client does. That means that there is one specific event raised on a client which is joining: its the on_load event. Its sole purpose is to tell the mod "you are just loaded, all your metatables are gone, all your global variables (not the table named `global`) are gone, you may want to fix them so your state is exactly the same as on the other clients". So the purpose of the "on_load" event is to notify mods that they need to do extra action to make their state consistent with other clients as that way it is easier to avoid desyncs. And then modders think they know what they are doing, they are setting flag during the on_load event, that flag alone is now non deterministic and they are surprised that a desync happened.

Read that as many times as you need and ask specific questions about that. As long as you use on_load correctly then all the code will run on all clients in the same way. All inputs (includes settings changes, keypresses, "actions" done by mouse, shortcuts etc) from all players gets to all clients, the code will just execute it the same and all clients will stay in sync. It doesn't matter if it's multiplayer or not for pretty much everything you do.

Also read the documentation on data lifecycle, especially the on_load part.

[hyperthalamus]

Thanks! I think I understood the part about the on_load event and I have read the data lifecycle docs... I think what I was missing so far was:

All inputs (includes settings changes, keypresses, "actions" done by mouse, shortcuts etc) from all players gets to all clients, the code will just execute it the same and all clients will stay in sync.

I was a bit confused that the lifecycle docs don't say anything about the lifecycle during the actual execution time of the mods, i.e. what happens while the game is running, in all the event handlers. I'll read these docs and previous answers a couple of times again and will start experimenting with the API.

Thanks again!