Update example code snippet provided in the Wiki, and corresponding example plugins

[DeviousNull]

(I am unable to submit a PR for the Wiki, hence this issue)

This page:

• https://github.com/Yaribz/SPADS/wiki/SPADS-plugin-development-(Python)#user-content-Writing_plugin_code-2

... contains the following:

However, if SPADS is disconnected from the lobby due to network problems for example, all lobby handlers are automatically removed. So we must re-add them each time we connect to lobby server. This can be done using the [http://planetspads.free.fr/spads/doc/spadsPluginApiDoc.html#onLobbyConnected-self-lobbyInterface onLobbyConnected] event-based callback as follows:

   # This callback is called each time we (re)connect to the lobby server
   def onLobbyConnected(self,lobbyInterface):
       
       # When we are disconnected from the lobby server, all lobby command
       # handlers are automatically removed, so we (re)set up our command
       # handler here.
       spads.addLobbyCommandHandler({'SAIDBATTLE': hLobbySaidBattle})

However, based on advice provided by Yaribz, some commands may be missed if handlers are registered in onLobbyConnected(...) instead of onLobbyLogin(...). So, I believe this page should be updated to switch which callback is used.

Similarly, the example plugins which use onLobbyConnected(...) should probably be updated as well:

• SPADS/plugins/tutorials/forbiddenwords.py

  Line 55 in c11f4cc

  def onLobbyConnected(self,lobbyInterface):

• SPADS/plugins/tutorials/ForbiddenWords.pm

  Line 58 in c11f4cc

  sub onLobbyConnected {

[Yaribz]

Yes, current state is unfortunate regarding the names of these two callbacks.

Initially, only the onLobbyConnected existed. And here "Connected" actually meant connected (TCP connection established) and logged in (authentication successful) and synchronized (all initial lobby state synchronization commands ADDUSER/BATTLEOPENED/JOINEDBATTLE received).

Then the need for a new callback called during authentication arose for the AutoRegister plugin (to modify SPADS core behavior when login fails due to unexisting account). That's why the onLobbyLogin callback was added. This callback is called just after the login is attempted and before the answer is received from the server. Consequently, this callback is called before the onLobbyConnected callback which is indeed misleading...

Here is what I think I will do:

1. add a new onLobbyLoggedIn callback, called just after a successful authentication, before lobby state synchronization commands are received
2. rename the onLobbyConnected callback to onLobbySynchronized (but onLobbyConnected will still work, to keep backward compatibility...)

I will see what is best regarding plugin documentation / examples, but I will update them for sure with the new callbacks. Most plugins don't actually need to register their callbacks before lobby state is synchronized, because no action can be performed before lobby is synchronized anyway, and all synchronization data are already automatically processed by SPADS to provide the initial lobby state available through the SpringLobbyInterface module. One case where it can be useful though, as in BarManager plugin case, is when one wants to add a verification layer in addition to the SpringLobbyinterface module, to check it works as expected and/or alter its behavior. Indeed in this case you can't rely on the data provided by this module and it makes perfect sense to handle the initial lobby state synchronization commands yourself in the plugin.

[Yaribz]

Done in SPADS 0.13.35 ( 9947d12 ).

Documentation for onLobbyLogin and onLobbySynchronized (formerly onLobbyConnected) have been made clearer (hopefully)

Documentation for addLobbyCommandHandler has been extended to add information about handlers being automatically removed when disconnections occur, and about the recommended usage of onLobbySynchronized and onLobbyLoggedIn to add lobby handlers.

I also took the opportunity to add lobby state constants to ease lobby state management from plugins (see getLobbyState documentation).

Finally, while I was there I also extended the documentation of the getParams configuration callback, to explain the difference between global plugin settings and preset plugin settings, and to explain how plugins can implement their own setting value checking functions instead of being restricted to the predefined types (previously undocumented feature).

Regarding the plugin development tutorials/examples/templates, unfortunately I think I will have to wait until SPADS 0.13.35 is in the stable branch before updating them, because the new onLobbySynchronized and onLobbyLoggedIn callbacks won't work with previous SPADS versions...