Dev/activationBestPractises

= Activation Best Practices = This page discusses use-cases and best practices for game activators.

Table Lifetimes and the Activator
The activator only has direct access to object creation and destruction and it does not have access to the object data. Because Firebase may run over a cluster the activator can never directly access the objects, as they may reside on a remote server.

This causes some confusion when tables need to have "lifetime" methods, eg. "init" / "destroy". Tournaments have automatic initialization and destruction performed by the system, but tables do not.

Current best practice is to keep a record of a tables "state" in the lobby. For example:


 * "created" - The table is created but not yet open for business.
 * "open" - The table is open for business and is accepting players.
 * "closed" - The table is about to close, no new players accepted.

The switch between different states is controlled by the activator.

A table will be called "dormant" below if it is empty and legible for removal.

The activator keeps a scheduled task for maintaining the tables and does the following:


 * 1) Determine if any tables need to be created, "Creating Tables" below.
 * 2) Scan all available tables, and for each table:
 * 3) If the table is "created" send it an event to tell it to open.
 * 4) If the table is dormant send it an event to tell it to close.
 * 5) If a table is "closed" destroy it.

Creating Tables
The activator scheduled task must contain a specification of the rules for creating tables. When a table is created the activator sets the state to "created" using the LobbyTableAttributeAccessor it gets via the creation participant, it also sets initial state and creates the lobby path etc.

NB: Tables which are "created" should not be visible in any client lobby list, only "open" tables can be joined.

Opening Tables
When the activator finds a table which is set to "created" the table is not yet open and the activator should send an "open event" to the table.

When a table receives the open event it should:


 * Setup any resources such as scheduled actions etc.
 * Make sure the interceptors accepts watch and join requests.
 * Set the state in the lobby to "open".

NB:  The client application should recognize that the table is now open and display it in its lobby lists.

Closing Tables
If a table is determined by the activator to be dormant, ie. empty and legible for removal, the activator sends a "close event" to the table.

When a table receives a close event it it should do the following:


 * If there are seated players - do nothing.
 * If there are players watching, send them an event telling the clients that the table is now closing.
 * Set the interceptors to deny all subsequent watch and join requests.
 * Set the state in the lobby to "closed".

NB:  Tables which are "closed" should not be visible in any client lobby list, only "open" tables can be joined.

Destroying Tables
When the activator finds a table which is set as "closed" that table can now be safely destoyed. Alternatevly, the activator may re-open the table by sending an open event, even though this may be too ambitious.

The Client

 * Only tables marked as "open" should be visible in the lobby.
 * It is possible, due to the asynchronous lobby communication, that a user manages to open a table before the client realizes that the table is actually closed. So the client application must be able to recognize independently that a table should be closed if it is set to "closed" in the lobby but still open in the client.