evennia.contrib.rpsystem

Roleplaying base system for Evennia

Contribution - Griatch, 2015

This module contains the ContribRPObject, ContribRPRoom and ContribRPCharacter typeclasses. If you inherit your objects/rooms/character from these (or make them the defaults) from these you will get the following features:

• Objects/Rooms will get the ability to have poses and will report

the poses of items inside them (the latter most useful for Rooms). - Characters will get poses and also sdescs (short descriptions) that will be used instead of their keys. They will gain commands for managing recognition (custom sdesc-replacement), masking themselves as well as an advanced free-form emote command.

To use, simply import the typclasses you want from this module and use them to create your objects, or set them to default.

In more detail, This RP base system introduces the following features to a game, common to many RP-centric games:

• emote system using director stance emoting (names/sdescs).

  This uses a customizable replacement noun (/me, @ etc) to represent you in the emote. You can use /sdesc, /nick, /key or /alias to reference objects in the room. You can use any number of sdesc sub-parts to differentiate a local sdesc, or use /1-sdesc etc to differentiate them. The emote also identifies nested says.

• sdesc obscuration of real character names for use in emotes

  and in any referencing such as object.search(). This relies on an SdescHandler sdesc being set on the Character and makes use of a custom Character.get_display_name hook. If sdesc is not set, the character’s key is used instead. This is particularly used in the emoting system.

• recog system to assign your own nicknames to characters, can then

  be used for referencing. The user may recog a user and assign any personal nick to them. This will be shown in descriptions and used to reference them. This is making use of the nick functionality of Evennia.

• masks to hide your identity (using a simple lock).

• pose system to set room-persistent poses, visible in room

  descriptions and when looking at the person/object. This is a simple Attribute that modifies how the characters is viewed when in a room as sdesc + pose.

• in-emote says, including seamless integration with language

  obscuration routine (such as contrib/rplanguage.py)

Examples:

> look Tavern The tavern is full of nice people

A tall man is standing by the bar.

Above is an example of a player with an sdesc “a tall man”. It is also an example of a static pose: The “standing by the bar” has been set by the player of the tall man, so that people looking at him can tell at a glance what is going on.

> emote /me looks at /tall and says “Hello!”

I see:

Griatch looks at Tall man and says “Hello”.

Tall man (assuming his name is Tom) sees:

The godlike figure looks at Tom and says “Hello”.

Verbose Installation Instructions:

1. In typeclasses/character.py: Import the ContribRPCharacter class:

   from evennia.contrib.rpsystem import ContribRPCharacter

   Inherit ContribRPCharacter:

   Change “class Character(DefaultCharacter):” to class Character(ContribRPCharacter):

   If you have any overriden calls in at_object_creation(self):

   Add super().at_object_creation() as the top line.

2. In typeclasses/rooms.py:

   Import the ContribRPRoom class: from evennia.contrib.rpsystem import ContribRPRoom

   Inherit ContribRPRoom:

   Change class Room(DefaultRoom): to class Room(ContribRPRoom):

3. In typeclasses/objects.py

   Import the ContribRPObject class: from evennia.contrib.rpsystem import ContribRPObject

   Inherit ContribRPObject:

   Change class Object(DefaultObject): to class Object(ContribRPObject):

4. Reload the server (@reload or from console: “evennia reload”)

5. Force typeclass updates as required. Example for your character:

   @type/reset/force me = typeclasses.characters.Character

exception evennia.contrib.rpsystem.EmoteError

Bases: Exception

exception evennia.contrib.rpsystem.SdescError

Bases: Exception

exception evennia.contrib.rpsystem.RecogError

Bases: Exception

exception evennia.contrib.rpsystem.LanguageError

Bases: Exception

evennia.contrib.rpsystem.ordered_permutation_regex(sentence)

Builds a regex that matches ‘ordered permutations’ of a sentence’s words.

Parameters

sentence (str) – The sentence to build a match pattern to

Returns

regex (re object) –

Compiled regex object represented the

possible ordered permutations of the sentence, from longest to shortest.

Example

The sdesc_regex for an sdesc of ” very tall man” will result in the following allowed permutations, regex-matched in inverse order of length (case-insensitive): “the very tall man”, “the very tall”, “very tall man”, “very tall”, “the very”, “tall man”, “the”, “very”, “tall”, and “man”. We also add regex to make sure it also accepts num-specifiers, like /2-tall.

evennia.contrib.rpsystem.regex_tuple_from_key_alias(obj)

This will build a regex tuple for any object, not just from those with sdesc/recog handlers. It’s used as a legacy mechanism for being able to mix this contrib with objects not using sdescs, but note that creating the ordered permutation regex dynamically for every object will add computational overhead.

Parameters

obj (Object) – This object’s key and eventual aliases will be used to build the tuple.

Returns

regex_tuple (tuple) –

A tuple

(ordered_permutation_regex, obj, key/alias)

evennia.contrib.rpsystem.parse_language(speaker, emote)

Parse the emote for language. This is used with a plugin for handling languages.

Parameters

• speaker (Object) – The object speaking.

• emote (str) – An emote possibly containing language references.

Returns

(emote, mapping) (tuple) –

A tuple where the

emote is the emote string with all says (including quotes) replaced with reference markers on the form {##n} where n is a running number. The mapping is a dictionary between the markers and a tuple (langname, saytext), where langname can be None.

Raises

rplanguage.LanguageError – If an invalid language was specified.

Notes

Note that no errors are raised if the wrong language identifier is given. This data, together with the identity of the speaker, is intended to be used by the “listener” later, since with this information the language skill of the speaker can be offset to the language skill of the listener to determine how much information is actually conveyed.

evennia.contrib.rpsystem.parse_sdescs_and_recogs(sender, candidates, string, search_mode=False)

Read a raw emote and parse it into an intermediary format for distributing to all observers.

Parameters

• sender (Object) – The object sending the emote. This object’s recog data will be considered in the parsing.

• candidates (iterable) – A list of objects valid for referencing in the emote.

string (str): The string (like an emote) we want to analyze for keywords. search_mode (bool, optional): If True, the “emote” is a query string

we want to analyze. If so, the return value is changed.

Returns

(emote, mapping) (tuple) –

If search_mode is False

(default), a tuple where the emote is the emote string, with all references replaced with internal-representation {#dbref} markers and mapping is a dictionary {“#dbref”:obj, …}.

result (list): If search_mode is True we are

performing a search query on string, looking for a specific object. A list with zero, one or more matches.

Raises

EmoteException – For various ref-matching errors.

Notes

The parser analyzes and should understand the following _PREFIX-tagged structures in the emote: - self-reference (/me) - recogs (any part of it) stored on emoter, matching obj in candidates. - sdesc (any part of it) from any obj in candidates. - N-sdesc, N-recog separating multi-matches (1-tall, 2-tall) - says, “…” are

evennia.contrib.rpsystem.send_emote(sender, receivers, emote, anonymous_add='first', **kwargs)

Main access function for distribute an emote.

Parameters

• sender (Object) – The one sending the emote.

• receivers (iterable) – Receivers of the emote. These will also form the basis for which sdescs are ‘valid’ to use in the emote.

• emote (str) – The raw emote string as input by emoter.

• anonymous_add (str or None, optional) – If sender is not self-referencing in the emote, this will auto-add sender’s data to the emote. Possible values are - None: No auto-add at anonymous emote - ‘last’: Add sender to the end of emote as [sender] - ‘first’: Prepend sender to start of emote.

class evennia.contrib.rpsystem.SdescHandler(obj)

Bases: object

This Handler wraps all operations with sdescs. We need to use this since we do a lot preparations on sdescs when updating them, in order for them to be efficient to search for and query.

The handler stores data in the following Attributes

_sdesc - a string _regex - an empty dictionary

__init__(obj)

Initialize the handler

Parameters

obj (Object) – The entity on which this handler is stored.

add(sdesc, max_length=60)

Add a new sdesc to object, replacing the old one.

Parameters

• sdesc (str) – The sdesc to set. This may be stripped of control sequences before setting.

• max_length (int, optional) – The max limit of the sdesc.

Returns

sdesc (str) – The actually set sdesc.

Raises

• SdescError – If the sdesc is empty, can not be set or is

• longer than max_length. –

get()

Simple getter. The sdesc should never be allowed to be empty, but if it is we must fall back to the key.

get_regex_tuple()

Return data for sdesc/recog handling

Returns

tup (tuple) – tuple (sdesc_regex, obj, sdesc)

class evennia.contrib.rpsystem.RecogHandler(obj)

Bases: object

This handler manages the recognition mapping of an Object.

The handler stores data in Attributes as dictionaries of the following names:

_recog_ref2recog _recog_obj2recog _recog_obj2regex

__init__(obj)

Initialize the handler

Parameters

obj (Object) – The entity on which this handler is stored.

add(obj, recog, max_length=60)

Assign a custom recog (nick) to the given object.

Parameters

• obj (Object) – The object ot associate with the recog string. This is usually determined from the sdesc in the room by a call to parse_sdescs_and_recogs, but can also be given.

• recog (str) – The replacement string to use with this object.

• max_length (int, optional) – The max length of the recog string.

Returns

recog (str) – The (possibly cleaned up) recog string actually set.

Raises

SdescError – When recog could not be set or sdesc longer than max_length.

get(obj)

Get recog replacement string, if one exists, otherwise get sdesc and as a last resort, the object’s key.

Parameters

obj (Object) – The object, whose sdesc to replace

Returns

recog (str) – The replacement string to use.

Notes

This method will respect a “enable_recog” lock set on obj (True by default) in order to turn off recog mechanism. This is useful for adding masks/hoods etc.

all()

Get a mapping of the recogs stored in handler.

Returns

recogs (dict) – A mapping of {recog: obj} stored in handler.

remove(obj)

Clear recog for a given object.

Parameters

obj (Object) – The object for which to remove recog.

get_regex_tuple(obj)

Returns

rec (tuple) – Tuple (recog_regex, obj, recog)

class evennia.contrib.rpsystem.RPCommand(**kwargs)

Bases: evennia.commands.command.Command

simple parent

parse()

strip extra whitespace

aliases = []

help_category = 'general'

key = 'command'

lock_storage = 'cmd:all();'

class evennia.contrib.rpsystem.CmdEmote(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

Emote an action, allowing dynamic replacement of text in the emote.

Usage:

emote text

Example

emote /me looks around. emote With a flurry /me attacks /tall man with his sword. emote “Hello”, /me says.

Describes an event in the world. This allows the use of /ref markers to replace with the short descriptions or recognized strings of objects in the same room. These will be translated to emotes to match each person seeing it. Use “…” for saying things and langcode”…” without spaces to say something in a different language.

key = 'emote'

aliases = [':']

locks = 'cmd:all()'

func()

Perform the emote.

help_category = 'general'

lock_storage = 'cmd:all()'

class evennia.contrib.rpsystem.CmdSay(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

speak as your character

Usage:

say <message>

Talk to those in your current location.

key = 'say'

aliases = ["'", '"']

locks = 'cmd:all()'

func()

Run the say command

help_category = 'general'

lock_storage = 'cmd:all()'

class evennia.contrib.rpsystem.CmdSdesc(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

Assign yourself a short description (sdesc).

Usage:

sdesc <short description>

Assigns a short description to yourself.

key = 'sdesc'

locks = 'cmd:all()'

func()

Assign the sdesc

aliases = []

help_category = 'general'

lock_storage = 'cmd:all()'

class evennia.contrib.rpsystem.CmdPose(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

Set a static pose

Usage:

pose <pose> pose default <pose> pose reset pose obj = <pose> pose default obj = <pose> pose reset obj =

Examples

pose leans against the tree pose is talking to the barkeep. pose box = is sitting on the floor.

Set a static pose. This is the end of a full sentence that starts with your sdesc. If no full stop is given, it will be added automatically. The default pose is the pose you get when using pose reset. Note that you can use sdescs/recogs to reference people in your pose, but these always appear as that person’s sdesc in the emote, regardless of who is seeing it.

key = 'pose'

parse()

Extract the “default” alternative to the pose.

func()

Create the pose

aliases = []

help_category = 'general'

lock_storage = 'cmd:all();'

class evennia.contrib.rpsystem.CmdRecog(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

Recognize another person in the same room.

Usage:

recog recog sdesc as alias forget alias

Example

recog tall man as Griatch forget griatch

This will assign a personal alias for a person, or forget said alias. Using the command without arguments will list all current recogs.

key = 'recog'

aliases = ['forget', 'recognize']

parse()

Parse for the sdesc as alias structure

func()

Assign the recog

help_category = 'general'

lock_storage = 'cmd:all();'

class evennia.contrib.rpsystem.CmdMask(**kwargs)

Bases: evennia.contrib.rpsystem.RPCommand

Wear a mask

Usage:

mask <new sdesc> unmask

This will put on a mask to hide your identity. When wearing a mask, your sdesc will be replaced by the sdesc you pick and people’s recognitions of you will be disabled.

key = 'mask'

aliases = ['unmask']

func()

This is the actual executing part of the command. It is called directly after self.parse(). See the docstring of this module for which object properties are available (beyond those set in self.parse())

help_category = 'general'

lock_storage = 'cmd:all();'

class evennia.contrib.rpsystem.RPSystemCmdSet(cmdsetobj=None, key=None)

Bases: evennia.commands.cmdset.CmdSet

Mix-in for adding rp-commands to default cmdset.

at_cmdset_creation()

Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

path = 'evennia.contrib.rpsystem.RPSystemCmdSet'

class evennia.contrib.rpsystem.ContribRPObject(*args, **kwargs)

Bases: evennia.objects.objects.DefaultObject

This class is meant as a mix-in or parent for objects in an rp-heavy game. It implements the base functionality for poses.

at_object_creation()

Called at initial creation.

search(searchdata, global_search=False, use_nicks=True, typeclass=None, location=None, attribute_name=None, quiet=False, exact=False, candidates=None, nofound_string=None, multimatch_string=None, use_dbref=None)

Returns an Object matching a search string/condition, taking sdescs into account.

Perform a standard object search in the database, handling multiple results and lack thereof gracefully. By default, only objects in the current location of self or its inventory are searched for.

Parameters

• searchdata (str or obj) –

  Primary search criterion. Will be matched against object.key (with object.aliases second) unless the keyword attribute_name specifies otherwise. Special strings: - #<num>: search by unique dbref. This is always

  a global search.

  • me,self: self-reference to this object

  • <num>-<string> - can be used to differentiate

    between multiple same-named matches

• global_search (bool) – Search all objects globally. This is overruled by location keyword.

• use_nicks (bool) – Use nickname-replace (nicktype “object”) on searchdata.

• typeclass (str or Typeclass, or list of either) – Limit search only to Objects with this typeclass. May be a list of typeclasses for a broader search.

• location (Object or list) – Specify a location or multiple locations to search. Note that this is used to query the contents of a location and will not match for the location itself - if you want that, don’t set this or use candidates to specify exactly which objects should be searched.

• attribute_name (str) – Define which property to search. If set, no key+alias search will be performed. This can be used to search database fields (db_ will be automatically appended), and if that fails, it will try to return objects having Attributes with this name and value equal to searchdata. A special use is to search for “key” here if you want to do a key-search without including aliases.

• quiet (bool) – don’t display default error messages - this tells the search method that the user wants to handle all errors themselves. It also changes the return value type, see below.

• exact (bool) – if unset (default) - prefers to match to beginning of string rather than not matching at all. If set, requires exact matching of entire string.

• candidates (list of objects) – this is an optional custom list of objects to search (filter) between. It is ignored if global_search is given. If not set, this list will automatically be defined to include the location, the contents of location and the caller’s contents (inventory).

• nofound_string (str) – optional custom string for not-found error message.

• multimatch_string (str) – optional custom string for multimatch error header.

• use_dbref (bool or None) – If None, only turn off use_dbref if we are of a lower permission than Builder. Otherwise, honor the True/False value.

Returns

match (Object, None or list) –

will return an Object/None if quiet=False,

otherwise it will return a list of 0, 1 or more matches.

Notes

To find Accounts, use eg. evennia.account_search. If quiet=False, error messages will be handled by settings.SEARCH_AT_RESULT and echoed automatically (on error, return will be None). If quiet=True, the error messaging is assumed to be handled by the caller.

get_display_name(looker, **kwargs)

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

Parameters

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

Keyword Arguments

pose (bool) – Include the pose (if available) in the return.

Returns

name (str) – A string of the sdesc containing the name of the object, if this is defined.

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

Notes

The RPObject version doesn’t add color to its display.

return_appearance(looker)

This formats a description. It is the hook a ‘look’ command should call.

Parameters

looker (Object) – Object doing the looking.

exception DoesNotExist

Bases: evennia.objects.objects.DefaultObject.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultObject.MultipleObjectsReturned

path = 'evennia.contrib.rpsystem.ContribRPObject'

typename = 'ContribRPObject'

class evennia.contrib.rpsystem.ContribRPRoom(*args, **kwargs)

Bases: evennia.contrib.rpsystem.ContribRPObject

Dummy inheritance for rooms.

exception DoesNotExist

Bases: evennia.contrib.rpsystem.ContribRPObject.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.contrib.rpsystem.ContribRPObject.MultipleObjectsReturned

path = 'evennia.contrib.rpsystem.ContribRPRoom'

typename = 'ContribRPRoom'

class evennia.contrib.rpsystem.ContribRPCharacter(*args, **kwargs)

Bases: evennia.objects.objects.DefaultCharacter, evennia.contrib.rpsystem.ContribRPObject

This is a character class that has poses, sdesc and recog.

sdesc

recog

get_display_name(looker, **kwargs)

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

Parameters

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

Keyword Arguments

pose (bool) – Include the pose (if available) in the return.

Returns

name (str) – A string of the sdesc containing the name of the object, if this is defined.

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

Notes

The RPCharacter version of this method colors its display to make characters stand out from other objects.

at_object_creation()

Called at initial creation.

at_before_say(message, **kwargs)

Called before the object says or whispers anything, return modified message.

Parameters

message (str) – The suggested say/whisper text spoken by self.

Keyword Arguments

whisper (bool) – If True, this is a whisper rather than a say.

process_sdesc(sdesc, obj, **kwargs)

Allows to customize how your sdesc is displayed (primarily by changing colors).

Parameters

• sdesc (str) – The sdesc to display.

• obj (Object) – The object to which the adjoining sdesc belongs. If this object is equal to yourself, then you are viewing yourself (and sdesc is your key). This is not used by default.

Returns

sdesc (str) –

The processed sdesc ready

for display.

process_recog(recog, obj, **kwargs)

Allows to customize how a recog string is displayed.

Parameters

• recog (str) – The recog string. It has already been translated from the original sdesc at this point.

• obj (Object) – The object the recog:ed string belongs to. This is not used by default.

Returns

recog (str) – The modified recog string.

process_language(text, speaker, language, **kwargs)

Allows to process the spoken text, for example by obfuscating language based on your and the speaker’s language skills. Also a good place to put coloring.

Parameters

• text (str) – The text to process.

• speaker (Object) – The object delivering the text.

• language (str) – An identifier string for the language.

Returns

text (str) – The optionally processed text.

Notes

This is designed to work together with a string obfuscator such as the obfuscate_language or obfuscate_whisper in the evennia.contrib.rplanguage module.

exception DoesNotExist

Bases: evennia.objects.objects.DefaultCharacter.DoesNotExist, evennia.contrib.rpsystem.ContribRPObject.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.objects.objects.DefaultCharacter.MultipleObjectsReturned, evennia.contrib.rpsystem.ContribRPObject.MultipleObjectsReturned

path = 'evennia.contrib.rpsystem.ContribRPCharacter'

typename = 'ContribRPCharacter'