Signals

This is feature available from evennia 0.9 and onward.

There are multiple ways for you to plug in your own functionality into Evennia. The most common way to do so is through hooks - methods on typeclasses that gets called at particular events. Hooks are great when you want a game entity to behave a certain way when something happens to it. Signals complements hooks for cases when you want to easily attach new functionality without overriding things on the typeclass.

When certain events happen in Evennia, a Signal is fired. The idea is that you can “attach” any number of event-handlers to these signals. You can attach any number of handlers and they’ll all fire whenever any entity triggers the signal.

Evennia uses the Django Signal system.

Attaching a handler to a signal

First you create your handler


def myhandler(sender, **kwargs):
  # do stuff

The **kwargs is mandatory. Then you attach it to the signal of your choice:

from evennia.server import signals

signals.SIGNAL_OBJECT_POST_CREATE.connect(myhandler)

This particular signal fires after (post) an Account has connected to the game. When that happens, myhandler will fire with the sender being the Account that just connected.

If you want to respond only to the effects of a specific entity you can do so like this:

from evennia import search_account
from evennia import signals

account = search_account("foo")[0]
signals.SIGNAL_ACCOUNT_POST_CONNECT.connect(myhandler, account)

Available signals

All signals (including some django-specific defaults) are available in the module evennia.server.signals (with a shortcut evennia.signals). Signals are named by the sender type. So SIGNAL_ACCOUNT_* returns Account instances as senders, SIGNAL_OBJECT_* returns Objects etc. Extra keywords (kwargs) should be extracted from the **kwargs dict in the signal handler.

  • SIGNAL_ACCOUNT_POST_CREATE - this is triggered at the very end of Account.create(). Note that calling evennia.create.create_account (which is called internally by Account.create) will not trigger this signal. This is because using Account.create() is expected to be the most commonly used way for users to themselves create accounts during login. It passes and extra kwarg ip with the client IP of the connecting account.

  • SIGNAL_ACCOUNT_POST_LOGIN - this will always fire when the account has authenticated. Sends extra kwarg session with the new Session object involved.

  • SIGNAL_ACCCOUNT_POST_FIRST_LOGIN - this fires just before SIGNAL_ACCOUNT_POST_LOGIN but only if this is the first connection done (that is, if there are no previous sessions connected). Also passes the session along as a kwarg.

  • SIGNAL_ACCOUNT_POST_LOGIN_FAIL - sent when someone tried to log into an account by failed. Passes the session as an extra kwarg.

  • SIGNAL_ACCOUNT_POST_LOGOUT - always fires when an account logs off, no matter if other sessions remain or not. Passes the disconnecting session along as a kwarg.

  • SIGNAL_ACCOUNT_POST_LAST_LOGOUT - fires before SIGNAL_ACCOUNT_POST_LOGOUT, but only if this is the last Session to disconnect for that account. Passes the session as a kwarg.

  • SIGNAL_OBJECT_POST_PUPPET - fires when an account puppets this object. Extra kwargs session and account represent the puppeting entities. SIGNAL_OBJECT_POST_UNPUPPET - fires when the sending object is unpuppeted. Extra kwargs are session and account.

  • SIGNAL_ACCOUNT_POST_RENAME - triggered by the setting of Account.username. Passes extra kwargs old_name, new_name.

  • SIGNAL_TYPED_OBJECT_POST_RENAME - triggered when any Typeclassed entity’s key is changed. Extra kwargs passed are old_key and new_key.

  • SIGNAL_SCRIPT_POST_CREATE - fires when a script is first created, after any hooks.

  • SIGNAL_CHANNEL_POST_CREATE - fires when a Channel is first created, after any hooks.

  • SIGNAL_HELPENTRY_POST_CREATE - fires when a help entry is first created.

The evennia.signals module also gives you conveneient access to the default Django signals (these use a different naming convention).

  • pre_save - fired when any database entitiy’s .save method fires, before any saving has happened.

  • post_save - fires after saving a database entity.

  • pre_delete - fires just before a database entity is deleted.

  • post_delete - fires after a database entity was deleted.

  • pre_init - fires before a typeclass’ __init__ method (which in turn happens before the at_init hook fires).

  • post_init - triggers at the end of __init__ (still before the at_init hook).

These are highly specialized Django signals that are unlikely to be useful to most users. But they are included here for completeness.

  • m2m_changed - fires after a Many-to-Many field (like db_attributes) changes.

  • pre_migrate - fires before database migration starts with evennia migrate.

  • post_migrate - fires after database migration finished.

  • request_started - sent when HTTP request begins.

  • request_finished - sent when HTTP request ends.

  • settings_changed - sent when changing settings due to @override_settings decorator (only relevant for unit testing)

  • template_rendered - sent when test system renders http template (only useful for unit tests).

  • connection_creation - sent when making initial connection to database.