kxg.messages.Message

class kxg.messages.Message

Bases: object

Event Handlers:

on_check(world)	Confirm that the message is consistent with the World.
on_prepare_sync(world, memento)	Determine how on_check failures on the server should be handled.
on_execute(world)	Update the world with the information stored in the message.
on_sync(world, memento)	Handle soft synchronization errors.
on_undo(world)	Handle hard synchronization errors.

Public Methods:

__repr__()	Return repr(self).
was_sent()
was_sent_by(actor_or_id)
was_sent_by_referee()
tokens_to_add()
tokens_to_remove()
tokens_referenced()	Return a list of all the tokens that are referenced in this message.

Private Methods:

_set_sender_id(id_factory)
_set_server_response_id(id)
_get_server_response_id()
_set_server_response(server_response)
_get_server_response()
_assign_token_ids(id_factory)	Assign id numbers to any tokens that will be added to the world by this message.
_check(world)
_prepare_sync(world, server_response)
_execute(world)
_sync(world)
_undo(world)

class ErrorState

Bases: object

HARD_SYNC_ERROR = 1

SOFT_SYNC_ERROR = 0

__repr__()

Return repr(self).

_assign_token_ids(id_factory)

Assign id numbers to any tokens that will be added to the world by this message.

This method is called by Actor but not by ServerActor, so it’s guaranteed to be called exactly once. In fact, this method is not really different from the constructor, except that an IdFactory instance is nicely provided. That’s useful for assigning ids to tokens but probably nothing else. This method is called before _check so that _check can make sure that valid ids were assigned (although by default it doesn’t).

_check(world)

_execute(world)

_get_server_response()

_get_server_response_id()

_prepare_sync(world, server_response)

_set_sender_id(id_factory)

_set_server_response(server_response)

_set_server_response_id(id)

_sync(world)

_undo(world)

on_check(world)

Confirm that the message is consistent with the World.

This handler is called by actors. If no MessageCheck exception is raised, the message will be sent as usual. Otherwise, the behavior will depend on what kind of actor is handling the message. Actor (uniplayer and multiplayer clients) will simply not send the message. ServerActor (multiplayer server) will decide if the error should be handled by undoing the message or asking the clients to sync themselves.

on_execute(world)

Update the world with the information stored in the message.

This handler is called by the forum on every machine running the game, before any signal-handling callbacks. It is allowed to make changes to the game world, but should not change the message itself.

on_prepare_sync(world, memento)

Determine how on_check failures on the server should be handled.

When on_check fails on the server, it means that the client which sent the message is out of sync (since had it been in sync, it would’ve rejected the message locally). There are two ways to handle this situation, and the role of this handler is to decide which to use.

The first is to reject the message. This is considered a “hard sync error”. In this case, the out-of-sync client will be instructed to undo this message, and the rest of the clients will never be sent the message in the first place. This approach ensures that messages sent by the server are consistent with the server’s World, but at the cost of requiring some messages to be undone, which may be jarring for the players. To indicate a hard sync error, return False from this handler. This is the default behavior.

The second is to send the message with extra instructions on how to re-synchronize the clients. This is considered a “soft sync error”. In this case, the message will be relayed to all clients as usual, but each client will call the on_sync handler upon receipt. Any extra information that might be helpful in resynchronizing the clients can be assigned to the memento argument, which will be sent to each client along with the message, and then passed to on_sync. To indicate a soft sync error, return True from this handler.

on_sync(world, memento)

Handle soft synchronization errors.

See on_prepare_sync for more details on hard/soft synchronization errors. This handler should use any information put in the memento by on_prepare_sync to quietly re-synchronize the client with the server.

on_undo(world)

Handle hard synchronization errors.

See on_prepare_sync for more details or hard/soft synchronization error. This handler should undo whatever changes were made to the world in on_execute, preferably in a way that is as minimally disruptive to the player as possible. This handler will only called on the client that originally sent this message.

tokens_referenced()

Return a list of all the tokens that are referenced in this message.

Tokens that haven’t been assigned an id yet are searched recursively for tokens. So this method may return fewer results after the message is sent. This information is used by the game engine to catch mistakes like forgetting to add a token to the world or keeping a stale reference to a token after its been removed.

tokens_to_add()

tokens_to_remove()

was_sent()

was_sent_by(actor_or_id)

was_sent_by_referee()