evennia.scripts.models

Scripts are entities that perform some sort of action, either only once or repeatedly. They can be directly linked to a particular Evennia Object or be stand-alonw (in the latter case it is considered a ‘global’ script). Scripts can indicate both actions related to the game world as well as pure behind-the-scenes events and effects. Everything that has a time component in the game (i.e. is not hard-coded at startup or directly created/controlled by players) is handled by Scripts.

Scripts have to check for themselves that they should be applied at a particular moment of time; this is handled by the is_valid() hook. Scripts can also implement at_start and at_end hooks for preparing and cleaning whatever effect they have had on the game object.

Common examples of uses of Scripts:

• Load the default cmdset to the account object’s cmdhandler when logging in.

• Switch to a different state, such as entering a text editor, start combat or enter a dark room.

• Merge a new cmdset with the default one for changing which commands are available at a particular time

• Give the account/object a time-limited bonus/effect

class evennia.scripts.models.ScriptDB(*args, **kwargs)

Bases: TypedObject

The Script database representation.

The TypedObject supplies the following (inherited) properties:

key - main name name - alias for key typeclass_path - the path to the decorating typeclass typeclass - auto-linked typeclass date_created - time stamp of object creation permissions - perm strings dbref - #id of object db - persistent attribute storage ndb - non-persistent attribute storage

The ScriptDB adds the following properties:

desc - optional description of script obj - the object the script is linked to, if any account - the account the script is linked to (exclusive with obj) interval - how often script should run start_delay - if the script should start repeating right away repeats - how many times the script should repeat persistent - if script should survive a server reboot is_active - bool if script is currently running

db_desc

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_obj

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

**Child.parent** is a **ForwardManyToOneDescriptor** instance.

db_account

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

**Child.parent** is a **ForwardManyToOneDescriptor** instance.

db_interval

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_start_delay

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_repeats

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_persistent

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_is_active

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <evennia.scripts.manager.ScriptDBManager object>

property obj

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

property object

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property account

A wrapper for getting database field db_account.

db_account_id

db_attributes

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_date_created

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_key

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_lock_storage

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_obj_id

db_tags

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_typeclass_path

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property desc

A wrapper for getting database field db_desc.

get_next_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)

get_previous_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property interval

A wrapper for getting database field db_interval.

property is_active

A wrapper for getting database field db_is_active.

path = 'evennia.scripts.models.ScriptDB'

property persistent

A wrapper for getting database field db_persistent.

receiver_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

property repeats

A wrapper for getting database field db_repeats.

sender_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

property start_delay

A wrapper for getting database field db_start_delay.

typename = 'SharedMemoryModelBase'

exception evennia.scripts.models.ObjectDoesNotExist

Bases: Exception

The requested object does not exist

silent_variable_failure = True

class evennia.scripts.models.ScriptDBManager(*args, **kwargs)

Bases: TypedObjectManager

This Scriptmanager implements methods for searching and manipulating Scripts directly from the database.

Evennia-specific search methods (will return Typeclasses or lists of Typeclasses, whereas Django-general methods will return Querysets or database objects).

dbref (converter) dbref_search get_dbref_range object_totals typeclass_search get_all_scripts_on_obj get_all_scripts delete_script remove_non_persistent validate script_search (equivalent to evennia.search_script) copy_script

copy_script(original_script, new_key=None, new_obj=None, new_locks=None)

Make an identical copy of the original_script.

Parameters:

• original_script (Script) – The Script to copy.

• new_key (str, optional) – Rename the copy.

• new_obj (Object, optional) – Place copy on different Object.

• new_locks (str, optional) – Give copy different locks from the original.

Returns:

script_copy (Script) –

A new Script instance, copied from

the original.

create_script(typeclass=None, key=None, obj=None, account=None, locks=None, interval=None, start_delay=None, repeats=None, persistent=None, autostart=True, report_to=None, desc=None, tags=None, attributes=None)

Create a new script. All scripts are a combination of a database object that communicates with the database, and an typeclass that ‘decorates’ the database object into being different types of scripts. It’s behaviour is similar to the game objects except scripts has a time component and are more limited in scope.

Keyword Arguments:

• typeclass (class or str) – Class or python path to a typeclass.

• key (str) – Name of the new object. If not set, a name of #dbref will be set.

• obj (Object) – The entity on which this Script sits. If this is None, we are creating a “global” script.

• account (Account) – The account on which this Script sits. It is exclusiv to obj.

• locks (str) – one or more lockstrings, separated by semicolons.

• interval (int) – The triggering interval for this Script, in seconds. If unset, the Script will not have a timing component.

• start_delay (bool) – If True, will wait interval seconds before triggering the first time.

• repeats (int) – The number of times to trigger before stopping. If unset, will repeat indefinitely.

• persistent (bool) – If this Script survives a server shutdown or not (all Scripts will survive a reload).

• autostart (bool) – If this Script will start immediately when created or if the start method must be called explicitly.

• report_to (Object) – The object to return error messages to.

• desc (str) – Optional description of script

• tags (list) – List of tags or tuples (tag, category).

• attributes (list) – List if tuples (key, value) or (key, value, category) (key, value, lockstring) or (key, value, lockstring, default_access).

Returns:

script (obj) – An instance of the script created

See evennia.scripts.manager for methods to manipulate existing scripts in the database.

delete_script(dbref)

This stops and deletes a specific script directly from the script database.

Parameters:

dbref (int) – Database unique id.

Notes

This might be needed for global scripts not tied to a specific game object

get_all_scripts(key=None)

Get all scripts in the database.

Parameters:

key (str or int, optional) – Restrict result to only those with matching key or dbref.

Returns:

scripts (list) – All scripts found, or those matching key.

get_all_scripts_on_obj(obj, key=None)

Find all Scripts related to a particular object.

Parameters:

• obj (Object) – Object whose Scripts we are looking for.

• key (str, optional) – Script identifier - can be given as a dbref or name string. If given, only scripts matching the key on the object will be returned.

Returns:

matches (list) – Matching scripts.

script_search(ostring, obj=None, only_timed=False, typeclass=None)

Search for a particular script.

Parameters:

• ostring (str) – Search criterion - a script dbef or key.

• obj (Object, optional) – Limit search to scripts defined on this object

• only_timed (bool) – Limit search only to scripts that run on a timer.

• typeclass (class or str) – Typeclass or path to typeclass.

Returns:

Queryset – An iterable with 0, 1 or more results.

search_script(ostring, obj=None, only_timed=False, typeclass=None)

Search for a particular script.

Parameters:

• ostring (str) – Search criterion - a script dbef or key.

• obj (Object, optional) – Limit search to scripts defined on this object

• only_timed (bool) – Limit search only to scripts that run on a timer.

• typeclass (class or str) – Typeclass or path to typeclass.

Returns:

Queryset – An iterable with 0, 1 or more results.

update_scripts_after_server_start()

Update/sync/restart/delete scripts after server shutdown/restart.

class evennia.scripts.models.TypedObject(*args, **kwargs)

Bases: SharedMemoryModel

Abstract Django model.

This is the basis for a typed object. It also contains all the mechanics for managing connected attributes.

The TypedObject has the following properties:

• key - main name

• name - alias for key

• typeclass_path - the path to the decorating typeclass

• typeclass - auto-linked typeclass

• date_created - time stamp of object creation

• permissions - perm strings

• dbref - #id of object

• db - persistent attribute storage

• ndb - non-persistent attribute storage

class Meta

Bases: object

Django setup info.

abstract = False

ordering = ['-db_date_created', 'id', 'db_typeclass_path', 'db_key']

verbose_name = 'Evennia Database Object'

__init__(*args, **kwargs)

The __init__ method of typeclasses is the core operational code of the typeclass system, where it dynamically re-applies a class based on the db_typeclass_path database field rather than use the one in the model.

Parameters:

parent. (Passed through to)

Keyword Arguments:

parent. (Passed through to)

Notes

The loading mechanism will attempt the following steps:

1. Attempt to load typeclass given on command line

2. Attempt to load typeclass stored in db_typeclass_path

3. Attempt to load __settingsclasspath__, which is by the default classes defined to be the respective user-set base typeclass settings, like BASE_OBJECT_TYPECLASS.

4. Attempt to load __defaultclasspath__, which is the base classes in the library, like DefaultObject etc.

5. If everything else fails, use the database model.

Normal operation is to load successfully at either step 1 or 2 depending on how the class was called. Tracebacks will be logged for every step the loader must take beyond 2.

access(accessing_obj, access_type='read', default=False, no_superuser_bypass=False, **kwargs)

Determines if another object has permission to access this one.

Parameters:

• accessing_obj (str) – Object trying to access this one.

• access_type (str, optional) – Type of access sought.

• default (bool, optional) – What to return if no lock of access_type was found

• no_superuser_bypass (bool, optional) – Turn off the superuser lock bypass (be careful with this one).

Keyword Arguments:

kwar (any) – Ignored, but is there to make the api consistent with the object-typeclass method access, which use it to feed to its hook methods.

aliases

at_idmapper_flush()

This is called when the idmapper cache is flushed and allows customized actions when this happens.

Returns:

do_flush (bool) –

If True, flush this object as normal. If

False, don’t flush and expect this object to handle the flushing on its own.

Notes

The default implementation relies on being able to clear Django’s Foreignkey cache on objects not affected by the flush (notably objects with an NAttribute stored). We rely on this cache being stored on the format “_<fieldname>_cache”. If Django were to change this name internally, we need to update here (unlikely, but marking just in case).

at_init()

Called when this object is loaded into cache. This is more reliable than to override __init__.

at_rename(oldname, newname)

This Hook is called by @name on a successful rename.

Parameters:

• oldname (str) – The instance’s original name.

• newname (str) – The new name for the instance.

attributes

check_permstring(permstring)

This explicitly checks if we hold particular permission without involving any locks.

Parameters:

permstring (str) – The permission string to check against.

Returns:

result (bool) – If the permstring is passed or not.

property date_created

Get the localized date created, based on settings.TIME_ZONE.

property db

Attribute handler wrapper. Allows for the syntax

obj.db.attrname = value
# and
value = obj.db.attrname
# and
del obj.db.attrname
# and
all_attr = obj.db.all()
# (unless there is an attribute
#  named 'all', in which case that will be returned instead).

db_attributes

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_date_created

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_key

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_lock_storage

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_tags

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_typeclass_path

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property dbid

Caches and returns the unique id of the object. Use this instead of self.id, which is not cached.

property dbref

Returns the object’s dbref on the form #NN.

delete()

Cleaning up handlers on the typeclass level

get_absolute_url()

Returns the URI path for a View that allows users to view details for this object.

Returns:

path (str) – URI path to object detail page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$',
    CharDetailView.as_view(), name='character-detail')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

get_display_name(looker, **kwargs)

Displays the name of the object in a viewer-aware manner.

Parameters:

looker (TypedObject, optional) – The object or account that is looking at/getting inforamtion for this object. If not given, some ‘safe’ minimum level should be returned.

Returns:

name (str) –

A string containing the name of the object,

including the DBREF if this user is privileged to control said object.

Notes

This function could be extended to change how object names appear to users in character, but be wary. This function does not change an object’s keys or aliases when searching, and is expected to produce something useful for builders.

get_extra_info(looker, **kwargs)

Used when an object is in a list of ambiguous objects as an additional information tag.

For instance, if you had potions which could have varying levels of liquid left in them, you might want to display how many drinks are left in each when selecting which to drop, but not in your normal inventory listing.

Parameters:

looker (TypedObject) – The object or account that is looking at/getting information for this object.

Returns:

info (str) –

A string with disambiguating information,

conventionally with a leading space.

get_next_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)

get_previous_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)

init_evennia_properties()

Called by creation methods; makes sure to initialize Attribute/TagProperties by fetching them once.

is_typeclass(typeclass, exact=False)

Returns true if this object has this type OR has a typeclass which is an subclass of the given typeclass. This operates on the actually loaded typeclass (this is important since a failing typeclass may instead have its default currently loaded) typeclass - can be a class object or the python path to such an object to match against.

Parameters:

• typeclass (str or class) – A class or the full python path to the class to check.

• exact (bool, optional) – Returns true only if the object’s type is exactly this typeclass, ignoring parents.

Returns:

is_typeclass (bool) –

If this typeclass matches the given

typeclass.

property key

property lock_storage

A wrapper for getting database field db_lock_storage.

locks

property name

nattributes

property ndb

NonDataBase). Everything stored to this is guaranteed to be cleared when a server is shutdown. Syntax is same as for the _get_db_holder() method and property, e.g. obj.ndb.attr = value etc.

Type:

A non-attr_obj store (ndb

objects

path = 'evennia.typeclasses.models.TypedObject'

permissions

classmethod search(query, **kwargs)

Overridden by class children. This implements a common API.

Parameters:

• query (str) – A search query.

• **kwargs – Other search parameters.

Returns:

list – A list of 0, 1 or more matches, only of this typeclass.

set_class_from_typeclass(typeclass_path=None)

swap_typeclass(new_typeclass, clean_attributes=False, run_start_hooks='all', no_default=True, clean_cmdsets=False)

This performs an in-situ swap of the typeclass. This means that in-game, this object will suddenly be something else. Account will not be affected. To ‘move’ an account to a different object entirely (while retaining this object’s type), use self.account.swap_object().

Note that this might be an error prone operation if the old/new typeclass was heavily customized - your code might expect one and not the other, so be careful to bug test your code if using this feature! Often its easiest to create a new object and just swap the account over to that one instead.

Parameters:

• new_typeclass (str or classobj) – Type to switch to.

• clean_attributes (bool or list, optional) – Will delete all attributes stored on this object (but not any of the database fields such as name or location). You can’t get attributes back, but this is often the safest bet to make sure nothing in the new typeclass clashes with the old one. If you supply a list, only those named attributes will be cleared.

• run_start_hooks (str or None, optional) – This is either None, to not run any hooks, “all” to run all hooks defined by at_first_start, or a string with space-separated hook-names to run (for example ‘at_object_creation’). This will always be called without arguments.

• no_default (bool, optiona) – If set, the swapper will not allow for swapping to a default typeclass in case the given one fails for some reason. Instead the old one will be preserved.

• clean_cmdsets (bool, optional) – Delete all cmdsets on the object.

tags

property typeclass_path

A wrapper for getting database field db_typeclass_path.

typename = 'SharedMemoryModelBase'

web_get_admin_url()

Returns the URI path for the Django Admin page for this object.

ex. Account#1 = ‘/admin/accounts/accountdb/1/change/’

Returns:

path (str) – URI path to Django Admin page for object.

classmethod web_get_create_url()

Returns the URI path for a View that allows users to create new instances of this object.

ex. Chargen = ‘/characters/create/’

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-create’ would be referenced by this method.

ex. url(r’characters/create/’, ChargenView.as_view(), name=’character-create’)

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can create new objects is the developer’s responsibility.

Returns:

path (str) – URI path to object creation page, if defined.

web_get_delete_url()

Returns the URI path for a View that allows users to delete this object.

Returns:

path (str) – URI path to object deletion page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/delete/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/delete/$',
CharDeleteView.as_view(), name='character-delete')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can delete this object is the developer’s responsibility.

web_get_detail_url()

Returns the URI path for a View that allows users to view details for this object.

Returns:

path (str) – URI path to object detail page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-detail’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/$',
    CharDetailView.as_view(), name='character-detail')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

web_get_puppet_url()

Returns the URI path for a View that allows users to puppet a specific object.

Returns:

str – URI path to object puppet page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/puppet/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-puppet’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/puppet/$',
    CharPuppetView.as_view(), name='character-puppet')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can view this object is the developer’s responsibility.

web_get_update_url()

Returns the URI path for a View that allows users to update this object.

Returns:

str – URI path to object update page, if defined.

Examples

Oscar (Character) = '/characters/oscar/1/change/'

For this to work, the developer must have defined a named view somewhere in urls.py that follows the format ‘modelname-action’, so in this case a named view of ‘character-update’ would be referenced by this method.

url(r'characters/(?P<slug>[\w\d\-]+)/(?P<pk>[0-9]+)/change/$',
CharUpdateView.as_view(), name='character-update')

If no View has been created and defined in urls.py, returns an HTML anchor.

This method is naive and simply returns a path. Securing access to the actual view and limiting who can modify objects is the developer’s responsibility.

evennia.scripts.models.dbref(inp, reqhash=True)

Converts/checks if input is a valid dbref.

Parameters:

• inp (int, str) – A database ref on the form N or #N.

• reqhash (bool, optional) – Require the #N form to accept input as a valid dbref.

Returns:

dbref (int or None) –

The integer part of the dbref or None

if input was not a valid dbref.

evennia.scripts.models.to_str(text, session=None)

Try to decode a bytestream to a python str, using encoding schemas from settings or from Session. Will always return a str(), also if not given a str/bytes.

Parameters:

• text (any) – The text to encode to bytes. If a str, return it. If also not bytes, convert to str using str() or repr() as a fallback.

• session (Session, optional) – A Session to get encoding info from. Will try this before falling back to settings.ENCODINGS.

Returns:

decoded_text (str) – The decoded text.

Notes

If text is already str, return it as is.