Badosus list of random guides

I'll use an example from BAR, BAR in this example in many places has code that does what you need on a higher level, this is not a problem in fact it's a good thing. I just want you to keep in mind this is not exactly what we'd do in terms of pure Recoil usage, the important bit is identifying the problem ("I need to send a notification something happened in synced code to UI") and what kind of things are involved in getting a solution.

BAR wants to notify UI that it received from engine that units were given from a team to another here
To do that, in the synced part of the gadget, it uses SendToUnsynced("NotificationEvent", "UnitsReceived", tostring(player)), I won't explain this usage, read the second link I sent you on the recoil engine guide. Or look for other places in BAR code where this is used.
Notice in the unsynced part of the gadget it does gadgetHandler:AddSyncAction("NotificationEvent", BroadcastEvent), this is basically boilerplate from BAR gadgetmanager to handle these messages automatically, but it's importante here to notice the pattern of synced sends a message -> receives still on gadget env but unsynced (could be handled in another gadget, but on the unsynced env)
On the handler it specified above BroadcastEvent it does: Script.LuaUI.NotificationEvent(event.." "..player). Basically it's telling now LuaUI (where widgets live) a message in the format event.." "..player (I guess "UnitsReceived "). What this does is to basically require some global NotificationEvent to exist in the LuaUI environment that will receive this message.
See that in sound notifications widget we do listen to NotificationEvent and handle it however we see fit (we still need to parse the string so the arguments can be used, e.g. decouple the event from the args <someevent> <someargs>)
Maybe that widget does something with UnitsReceived event or not, what matters is that we finally figured out how to make a widget to receive a synced environment message.

So in very broad conceptual terms:

There exists synced/unsynced luarules, and luaui (luaui is always unsynced)
If we need to send a message from synced to luaui first we send the message from luarules synced to luarules unsynced with sendtounsynced
Then if we still want to send from luarules unsynced to luaui:
- Use Script.LuaUI.X in luarules unsynced and define a global function called X that handles this message in LuaUI.
- Use SendLuaUIMsg in unsynced luarules and implement function widget:RecvLuaMsg(msg)

You might not need to send to LuaUI, you can do it in luarules unsynced (the unsynced part of gadgets), in fact many places in BAR do so, it's a matter of what exactly you want to achieve (solve a problem LuaUI needs to be unaware of or not).

Again, might be a little bit hard to read, but all this is kinda explained in this article its just not easy to figure this out without some context (and basic knowledge on what synced/unsynced luarules/luaui are and what they are concerned with)

badosu/how_to_send_messages_from_synced_to_ui.markdown