evennia.commands.cmdset

A Command Set (CmdSet) holds a set of commands. The Cmdsets can be merged and combined to create new sets of commands in a non-destructive way. This makes them very powerful for implementing custom game states where different commands (or different variations of commands) are available to the accounts depending on circumstance.

The available merge operations are partly borrowed from mathematical Set theory.

• Union The two command sets are merged so that as many commands as

  possible of each cmdset ends up in the merged cmdset. Same-name commands are merged by priority. This is the most common default. Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5

• Intersect - Only commands found in both cmdsets (i.e. which have

  same names) end up in the merged cmdset, with the higher-priority cmdset replacing the lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1

• Replace - The commands of this cmdset completely replaces the

  lower-priority cmdset’s commands, regardless of if same-name commands exist. Ex: A1,A3 + B1,B2,B4,B5 = A1,A3

• Remove - This removes the relevant commands from the

  lower-priority cmdset completely. They are not replaced with anything, so this in effects uses the high-priority cmdset as a filter to affect the low-priority cmdset. Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5

class evennia.commands.cmdset.CmdSet(cmdsetobj=None, key=None)

Bases: object

This class describes a unique cmdset that understands priorities. CmdSets can be merged and made to perform various set operations on each other. CmdSets have priorities that affect which of their ingoing commands gets used.

In the examples, cmdset A always have higher priority than cmdset B.

key - the name of the cmdset. This can be used on its own for game operations

mergetype (partly from Set theory):

Union - The two command sets are merged so that as many

commands as possible of each cmdset ends up in the merged cmdset. Same-name commands are merged by priority. This is the most common default. Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5

Intersect - Only commands found in both cmdsets

(i.e. which have same names) end up in the merged cmdset, with the higher-priority cmdset replacing the lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1

Replace - The commands of this cmdset completely replaces

the lower-priority cmdset’s commands, regardless of if same-name commands exist. Ex: A1,A3 + B1,B2,B4,B5 = A1,A3

Remove - This removes the relevant commands from the

lower-priority cmdset completely. They are not replaced with anything, so this in effects uses the high-priority cmdset as a filter to affect the low-priority cmdset. Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5

Note: Commands longer than 2 characters and starting

with double underscrores, like ‘__noinput_command’ are considered ‘system commands’ and are excempt from all merge operations - they are ALWAYS included across mergers and only affected if same-named system commands replace them.

priority- All cmdsets are always merged in pairs of two so that

the higher set’s mergetype is applied to the lower-priority cmdset. Default commands have priority 0, high-priority ones like Exits and Channels have 10 and 9. Priorities can be negative as well to give default commands preference.

duplicates - determines what happens when two sets of equal

priority merge (only). Defaults to None and has the first of them in the merger (i.e. A above) automatically taking precedence. But if duplicates is true, the result will be a merger with more than one of each name match. This will usually lead to the account receiving a multiple-match error higher up the road, but can be good for things like cmdsets on non-account objects in a room, to allow the system to warn that more than one ‘ball’ in the room has the same ‘kick’ command defined on it, so it may offer a chance to select which ball to kick … Allowing duplicates only makes sense for Union and Intersect, the setting is ignored for the other mergetypes. Note that the duplicates flag is not propagated in a cmdset merger. So A + B = C will result in a cmdset with duplicate commands, but C.duplicates will be None. For duplication to apply to a whole cmdset stack merge, _all_ cmdsets in the stack must have .duplicates=True set.

Finally, if a final cmdset has .duplicates=None (the normal unless created alone with another value), the cmdhandler will assume True for object-based cmdsets and False for all other. This is usually the most intuitive outcome.

key_mergetype (dict) - allows the cmdset to define a unique

mergetype for particular cmdsets. Format is {CmdSetkeystring:mergetype}. Priorities still apply. Example: {‘Myevilcmdset’,’Replace’} which would make sure for this set to always use ‘Replace’ on Myevilcmdset no matter what overall mergetype this set has.

no_objs - don’t include any commands from nearby objects

when searching for suitable commands

no_exits - ignore the names of exits when matching against

commands

no_channels - ignore the name of channels when matching against

commands (WARNING- this is dangerous since the account can then not even ask staff for help if something goes wrong)

mergetype = 'Union'

priority = 0

no_exits = None

no_objs = None

no_channels = None

duplicates = None

persistent = False

key_mergetypes = {}

errmessage = ''

to_duplicate = ('key', 'cmdsetobj', 'no_exits', 'no_objs', 'no_channels', 'persistent', 'mergetype', 'priority', 'duplicates', 'errmessage')

__init__(cmdsetobj=None, key=None)

Creates a new CmdSet instance.

Parameters

• cmdsetobj (Session, Account, Object, optional) – This is the database object to which this particular instance of cmdset is related. It is often a character but may also be a regular object, Account or Session.

• key (str, optional) – The idenfier for this cmdset. This helps if wanting to selectively remov cmdsets.

key = 'Unnamed CmdSet'

add(cmd, allow_duplicates=False)

Add a new command or commands to this CmdSet, a list of commands or a cmdset to this cmdset. Note that this is not a merge operation (that is handled by the + operator).

Parameters

• cmd (Command, list, Cmdset) – This allows for adding one or more commands to this Cmdset in one go. If another Cmdset is given, all its commands will be added.

• allow_duplicates (bool, optional) – If set, will not try to remove duplicate cmds in the set. This is needed during the merge process to avoid wiping commands coming from cmdsets with duplicate=True.

Notes

If cmd already exists in set, it will replace the old one (no priority checking etc happens here). This is very useful when overloading default commands).

If cmd is another cmdset class or -instance, the commands of that command set is added to this one, as if they were part of the original cmdset definition. No merging or priority checks are made, rather later added commands will simply replace existing ones to make a unique set.

remove(cmd)

Remove a command instance from the cmdset.

Parameters

cmd (Command or str) – Either the Command object to remove or the key of such a command.

get(cmd)

Get a command from the cmdset. This is mostly useful to check if the command is part of this cmdset or not.

Parameters

cmd (Command or str) – Either the Command object or its key.

Returns

cmd (Command) – The first matching Command in the set.

count()

Number of commands in set.

Returns

N (int) – Number of commands in this Cmdset.

get_system_cmds()

Get system commands in cmdset

Returns

sys_cmds (list) – The system commands in the set.

Notes

As far as the Cmdset is concerned, system commands are any commands with a key starting with double underscore __. These are excempt from merge operations.

make_unique(caller)

Remove duplicate command-keys (unsafe)

Parameters

caller (object) – Commands on this object will get preference in the duplicate removal.

Notes

This is an unsafe command meant to clean out a cmdset of doublet commands after it has been created. It is useful for commands inheriting cmdsets from the cmdhandler where obj-based cmdsets always are added double. Doublets will be weeded out with preference to commands defined on caller, otherwise just by first-come-first-served.

get_all_cmd_keys_and_aliases(caller=None)

Collects keys/aliases from commands

Parameters

caller (Object, optional) – If set, this is used to check access permissions on each command. Only commands that pass are returned.

Returns

names (list) –

A list of all command keys and aliases in this cmdset. If caller

was given, this list will only contain commands to which caller passed the call locktype check.

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.commands.cmdset.CmdSet'