evennia.commands.default.building

Building and world design commands

class evennia.commands.default.building.ObjManipCommand(**kwargs)

Bases: MuxCommand

This is a parent class for some of the defining objmanip commands since they tend to have some more variables to define new objects.

Each object definition can have several components. First is always a name, followed by an optional alias list and finally an some optional data, such as a typeclass or a location. A comma ‘,’ separates different objects. Like this:

name1;alias;alias;alias:option, name2;alias;alias …

Spaces between all components are stripped.

A second situation is attribute manipulation. Such commands are simpler and offer combinations

objname/attr/attr/attr, objname/attr, …

default_typeclasses = {'character': 'typeclasses.characters.Character', 'exit': 'typeclasses.exits.Exit', 'object': 'typeclasses.objects.Object', 'room': 'typeclasses.rooms.Room'}

parse()

We need to expand the default parsing to get all the cases, see the module doc.

get_object_typeclass(obj_type: str = 'object', typeclass: str = None, method: str = 'cmd_create', **kwargs) → tuple[Typeclass | None, list[str]]

This hook is called by build commands to determine which typeclass to use for a specific purpose.

Parameters:

• obj_type (str, optional) – The type of object that is being created. Defaults to “object”. Evennia provides “room”, “exit”, and “character” by default, but this can be extended.

• typeclass (str, optional) – The typeclass that was requested by the player. Defaults to None. Can also be an actual class.

• method (str, optional) – The method that is calling this hook. Defaults to “cmd_create”. Others are “cmd_dig”, “cmd_open”, “cmd_tunnel”, etc.

Returns:

tuple –

A tuple containing the typeclass to use and a list of errors. (which might be

empty.)

Notes

Although intended to be used with typeclasses, as long as this hook returns a class with a create method, which accepts the same API as DefaultObject.create(), build commands and other places should take it. While not used by default, one could picture using this for things like autodetecting which room to build next based on the current location.

aliases = []

help_category = 'general'

key = 'command'

lock_storage = 'cmd:all();'

search_index_entry = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': "\nThis is a parent class for some of the defining objmanip commands\nsince they tend to have some more variables to define new objects.\n\nEach object definition can have several components. First is\nalways a name, followed by an optional alias list and finally an\nsome optional data, such as a typeclass or a location. A comma ','\nseparates different objects. Like this:\n\n    name1;alias;alias;alias:option, name2;alias;alias ...\n\nSpaces between all components are stripped.\n\nA second situation is attribute manipulation. Such commands\nare simpler and offer combinations\n\n    objname/attr/attr/attr, objname/attr, ...\n\n"}

class evennia.commands.default.building.CmdSetObjAlias(**kwargs)

Bases: MuxCommand

adding permanent aliases for object

Usage:

alias <obj> [= [alias[,alias,alias,…]]] alias <obj> = alias/category <obj> = [alias[,alias,…]:<category> alias/delete <obj> = <alias>

Switches:

category - requires ending input with :category, to store the

given aliases with the given category.

delete - deletes all occurrences of the given alias, regardless

of category

Assigns aliases to an object so it can be referenced by more than one name. Assign empty to remove all aliases from object. If assigning a category, all aliases given will be using this category.

Observe that this is not the same thing as personal aliases created with the ‘nick’ command! Aliases set with alias are changing the object in question, making those aliases usable by everyone.

key = '@alias'

aliases = ['setobjalias']

switch_options = ('category', 'delete')

locks = 'cmd:perm(setobjalias) or perm(Builder)'

help_category = 'building'

method_type = 'cmd_create'

func()

Set the aliases.

lock_storage = 'cmd:perm(setobjalias) or perm(Builder)'

search_index_entry = {'aliases': 'setobjalias', 'category': 'building', 'key': '@alias', 'no_prefix': 'alias setobjalias', 'tags': '', 'text': "\nadding permanent aliases for object\n\nUsage:\n  alias <obj> [= [alias[,alias,alias,...]]]\n  alias <obj> =\n  alias/category <obj> = [alias[,alias,...]:<category>\n  alias/delete <obj> = <alias>\n\nSwitches:\n  category - requires ending input with :category, to store the\n    given aliases with the given category.\n  delete - deletes all occurrences of the given alias, regardless\n    of category\n\nAssigns aliases to an object so it can be referenced by more\nthan one name. Assign empty to remove all aliases from object. If\nassigning a category, all aliases given will be using this category.\n\nObserve that this is not the same thing as personal aliases\ncreated with the 'nick' command! Aliases set with alias are\nchanging the object in question, making those aliases usable\nby everyone.\n"}

class evennia.commands.default.building.CmdCopy(**kwargs)

Bases: ObjManipCommand

copy an object and its properties

Usage:

copy <original obj> [= <new_name>][;alias;alias..] [:<new_location>] [,<new_name2> …]

Create one or more copies of an object. If you don’t supply any targets, one exact copy of the original object will be created with the name *_copy.

key = '@copy'

locks = 'cmd:perm(copy) or perm(Builder)'

help_category = 'building'

func()

Uses ObjManipCommand.parse()

aliases = []

lock_storage = 'cmd:perm(copy) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@copy', 'no_prefix': 'copy ', 'tags': '', 'text': "\ncopy an object and its properties\n\nUsage:\n  copy <original obj> [= <new_name>][;alias;alias..]\n  [:<new_location>] [,<new_name2> ...]\n\nCreate one or more copies of an object. If you don't supply any targets,\none exact copy of the original object will be created with the name *_copy.\n"}

class evennia.commands.default.building.CmdCpAttr(**kwargs)

Bases: ObjManipCommand

copy attributes between objects

Usage:

cpattr[/switch] <obj>/<attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,…] cpattr[/switch] <obj>/<attr> = <obj1> [,<obj2>,<obj3>,…] cpattr[/switch] <attr>[:category] = <obj1>/<attr1>[:category] [,<obj2>/<attr2>,<obj3>/<attr3>,…] cpattr[/switch] <attr> = <obj1>[,<obj2>,<obj3>,…]

Switches:

move - delete the attribute from the source object after copying.

Example

cpattr coolness = Anna/chillout, Anna/nicety, Tom/nicety -> copies the coolness attribute (defined on yourself), to attributes on Anna and Tom.

cpattr box/width:dimension = tube/width:dimension -> copies the box’s width attribute in the dimension category, to be the tube’s width attribute in the dimension category

Copy the attribute one object to one or more attributes on another object. If you don’t supply a source object, yourself is used.

key = '@cpattr'

switch_options = ('move',)

locks = 'cmd:perm(cpattr) or perm(Builder)'

help_category = 'building'

check_from_attr(obj, attr, category=None, clear=False)

Hook for overriding on subclassed commands. Checks to make sure a caller can copy the attr from the object in question. If not, return a false value and the command will abort. An error message should be provided by this function.

If clear is True, user is attempting to move the attribute.

check_to_attr(obj, attr, category=None)

Hook for overriding on subclassed commands. Checks to make sure a caller can write to the specified attribute on the specified object. If not, return a false value and the attribute will be skipped. An error message should be provided by this function.

check_has_attr(obj, attr, category=None)

Hook for overriding on subclassed commands. Do any preprocessing required and verify an object has an attribute.

get_attr(obj, attr, category=None)

Hook for overriding on subclassed commands. Do any preprocessing required and get the attribute from the object.

func()

Do the copying.

aliases = []

lock_storage = 'cmd:perm(cpattr) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@cpattr', 'no_prefix': 'cpattr ', 'tags': '', 'text': "\ncopy attributes between objects\n\nUsage:\n  cpattr[/switch] <obj>/<attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,...]\n  cpattr[/switch] <obj>/<attr> = <obj1> [,<obj2>,<obj3>,...]\n  cpattr[/switch] <attr>[:category] = <obj1>/<attr1>[:category] [,<obj2>/<attr2>,<obj3>/<attr3>,...]\n  cpattr[/switch] <attr> = <obj1>[,<obj2>,<obj3>,...]\n\nSwitches:\n  move - delete the attribute from the source object after copying.\n\nExample:\n  cpattr coolness = Anna/chillout, Anna/nicety, Tom/nicety\n  ->\n  copies the coolness attribute (defined on yourself), to attributes\n  on Anna and Tom.\n\n  cpattr box/width:dimension = tube/width:dimension\n  ->\n  copies the box's width attribute in the dimension category, to be the\n  tube's width attribute in the dimension category\n\nCopy the attribute one object to one or more attributes on another object.\nIf you don't supply a source object, yourself is used.\n"}

class evennia.commands.default.building.CmdMvAttr(**kwargs)

Bases: ObjManipCommand

move attributes between objects

Usage:

mvattr[/switch] <obj>/<attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,…] mvattr[/switch] <obj>/<attr> = <obj1> [,<obj2>,<obj3>,…] mvattr[/switch] <attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,…] mvattr[/switch] <attr> = <obj1>[,<obj2>,<obj3>,…]

Switches:

copy - Don’t delete the original after moving.

Move an attribute from one object to one or more attributes on another object. If you don’t supply a source object, yourself is used.

key = '@mvattr'

switch_options = ('copy',)

locks = 'cmd:perm(mvattr) or perm(Builder)'

help_category = 'building'

func()

Do the moving

aliases = []

lock_storage = 'cmd:perm(mvattr) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@mvattr', 'no_prefix': 'mvattr ', 'tags': '', 'text': "\nmove attributes between objects\n\nUsage:\n  mvattr[/switch] <obj>/<attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,...]\n  mvattr[/switch] <obj>/<attr> = <obj1> [,<obj2>,<obj3>,...]\n  mvattr[/switch] <attr> = <obj1>/<attr1> [,<obj2>/<attr2>,<obj3>/<attr3>,...]\n  mvattr[/switch] <attr> = <obj1>[,<obj2>,<obj3>,...]\n\nSwitches:\n  copy - Don't delete the original after moving.\n\nMove an attribute from one object to one or more attributes on another\nobject. If you don't supply a source object, yourself is used.\n"}

class evennia.commands.default.building.CmdCreate(**kwargs)

Bases: ObjManipCommand

create new objects

Usage:

create[/drop] <objname>[;alias;alias…][:typeclass], <objname>…

switch:

drop - automatically drop the new object into your current

location (this is not echoed). This also sets the new object’s home to the current location rather than to you.

Creates one or more new objects. If typeclass is given, the object is created as a child of this typeclass. The typeclass script is assumed to be located under types/ and any further directory structure is given in Python notation. So if you have a correct typeclass ‘RedButton’ defined in types/examples/red_button.py, you could create a new object of this type like this:

create/drop button;red : examples.red_button.RedButton

key = '@create'

switch_options = ('drop',)

locks = 'cmd:perm(create) or perm(Builder)'

help_category = 'building'

func()

Creates the object.

aliases = []

lock_storage = 'cmd:perm(create) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@create', 'no_prefix': 'create ', 'tags': '', 'text': "\ncreate new objects\n\nUsage:\n  create[/drop] <objname>[;alias;alias...][:typeclass], <objname>...\n\nswitch:\n   drop - automatically drop the new object into your current\n          location (this is not echoed). This also sets the new\n          object's home to the current location rather than to you.\n\nCreates one or more new objects. If typeclass is given, the object\nis created as a child of this typeclass. The typeclass script is\nassumed to be located under types/ and any further\ndirectory structure is given in Python notation. So if you have a\ncorrect typeclass 'RedButton' defined in\ntypes/examples/red_button.py, you could create a new\nobject of this type like this:\n\n   create/drop button;red : examples.red_button.RedButton\n\n"}

class evennia.commands.default.building.CmdDesc(**kwargs)

Bases: MuxCommand

describe an object or the current room.

Usage:

desc [<obj> =] <description>

Switches:

edit - Open up a line editor for more advanced editing.

Sets the “desc” attribute on an object. If an object is not given, describe the current room.

key = '@desc'

switch_options = ('edit',)

locks = 'cmd:perm(desc) or perm(Builder)'

help_category = 'building'

edit_handler()

func()

Define command

aliases = []

lock_storage = 'cmd:perm(desc) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@desc', 'no_prefix': 'desc ', 'tags': '', 'text': '\ndescribe an object or the current room.\n\nUsage:\n  desc [<obj> =] <description>\n\nSwitches:\n  edit - Open up a line editor for more advanced editing.\n\nSets the "desc" attribute on an object. If an object is not given,\ndescribe the current room.\n'}

class evennia.commands.default.building.CmdDestroy(**kwargs)

Bases: MuxCommand

permanently delete objects

Usage:

destroy[/switches] [obj, obj2, obj3, [dbref-dbref], …]

Switches:

override - The destroy command will usually avoid accidentally

destroying account objects. This switch overrides this safety.

force - destroy without confirmation.

Examples

destroy house, roof, door, 44-78 destroy 5-10, flower, 45 destroy/force north

Destroys one or many objects. If dbrefs are used, a range to delete can be given, e.g. 4-10. Also the end points will be deleted. This command displays a confirmation before destroying, to make sure of your choice. You can specify the /force switch to bypass this confirmation.

key = '@destroy'

aliases = ['@del', '@delete']

switch_options = ('override', 'force')

locks = 'cmd:perm(destroy) or perm(Builder)'

help_category = 'building'

confirm = True

default_confirm = 'yes'

func()

Implements the command.

lock_storage = 'cmd:perm(destroy) or perm(Builder)'

search_index_entry = {'aliases': '@del @delete', 'category': 'building', 'key': '@destroy', 'no_prefix': 'destroy del delete', 'tags': '', 'text': '\npermanently delete objects\n\nUsage:\n   destroy[/switches] [obj, obj2, obj3, [dbref-dbref], ...]\n\nSwitches:\n   override - The destroy command will usually avoid accidentally\n              destroying account objects. This switch overrides this safety.\n   force - destroy without confirmation.\nExamples:\n   destroy house, roof, door, 44-78\n   destroy 5-10, flower, 45\n   destroy/force north\n\nDestroys one or many objects. If dbrefs are used, a range to delete can be\ngiven, e.g. 4-10. Also the end points will be deleted. This command\ndisplays a confirmation before destroying, to make sure of your choice.\nYou can specify the /force switch to bypass this confirmation.\n'}

class evennia.commands.default.building.CmdDig(**kwargs)

Bases: ObjManipCommand

build new rooms and connect them to the current location

Usage:

dig[/switches] <roomname>[;alias;alias…][:typeclass]

[= <exit_to_there>[;alias][:typeclass]]

[, <exit_to_here>[;alias][:typeclass]]

Switches:

tel or teleport - move yourself to the new room

Examples

dig kitchen = north;n, south;s dig house:myrooms.MyHouseTypeclass dig sheer cliff;cliff;sheer = climb up, climb down

This command is a convenient way to build rooms quickly; it creates the new room and you can optionally set up exits back and forth between your current room and the new one. You can add as many aliases as you like to the name of the room and the exits in question; an example would be ‘north;no;n’.

key = '@dig'

switch_options = ('teleport',)

locks = 'cmd:perm(dig) or perm(Builder)'

help_category = 'building'

method_type = 'cmd_dig'

new_room_lockstring = 'control:id({id}) or perm(Admin); delete:id({id}) or perm(Admin); edit:id({id}) or perm(Admin)'

func()

Do the digging. Inherits variables from ObjManipCommand.parse()

aliases = []

lock_storage = 'cmd:perm(dig) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@dig', 'no_prefix': 'dig ', 'tags': '', 'text': "\nbuild new rooms and connect them to the current location\n\nUsage:\n  dig[/switches] <roomname>[;alias;alias...][:typeclass]\n        [= <exit_to_there>[;alias][:typeclass]]\n           [, <exit_to_here>[;alias][:typeclass]]\n\nSwitches:\n   tel or teleport - move yourself to the new room\n\nExamples:\n   dig kitchen = north;n, south;s\n   dig house:myrooms.MyHouseTypeclass\n   dig sheer cliff;cliff;sheer = climb up, climb down\n\nThis command is a convenient way to build rooms quickly; it creates the\nnew room and you can optionally set up exits back and forth between your\ncurrent room and the new one. You can add as many aliases as you\nlike to the name of the room and the exits in question; an example\nwould be 'north;no;n'.\n"}

class evennia.commands.default.building.CmdTunnel(**kwargs)

Bases: MuxCommand

create new rooms in cardinal directions only

Usage:

tunnel[/switch] <direction>[:typeclass] [= <roomname>[;alias;alias;…][:typeclass]]

Switches:

oneway - do not create an exit back to the current location tel - teleport to the newly created room

Example

tunnel n tunnel n = house;mike’s place;green building

This is a simple way to build using pre-defined directions:

|wn,ne,e,se,s,sw,w,nw|n (north, northeast etc) |wu,d|n (up and down) |wi,o|n (in and out)

The full names (north, in, southwest, etc) will always be put as main name for the exit, using the abbreviation as an alias (so an exit will always be able to be used with both “north” as well as “n” for example). Opposite directions will automatically be created back from the new room unless the /oneway switch is given. For more flexibility and power in creating rooms, use dig.

key = '@tunnel'

aliases = ['@tun']

switch_options = ('oneway', 'tel')

locks = 'cmd:all();cmd: perm(tunnel) or perm(Builder)'

help_category = 'building'

method_type = 'cmd_tunnel'

directions = {'d': ('down', 'u'), 'e': ('east', 'w'), 'i': ('in', 'o'), 'n': ('north', 's'), 'ne': ('northeast', 'sw'), 'nw': ('northwest', 'se'), 'o': ('out', 'i'), 's': ('south', 'n'), 'se': ('southeast', 'nw'), 'sw': ('southwest', 'ne'), 'u': ('up', 'd'), 'w': ('west', 'e')}

func()

Implements the tunnel command

lock_storage = 'cmd:all();cmd: perm(tunnel) or perm(Builder)'

search_index_entry = {'aliases': '@tun', 'category': 'building', 'key': '@tunnel', 'no_prefix': 'tunnel tun', 'tags': '', 'text': '\ncreate new rooms in cardinal directions only\n\nUsage:\n  tunnel[/switch] <direction>[:typeclass] [= <roomname>[;alias;alias;...][:typeclass]]\n\nSwitches:\n  oneway - do not create an exit back to the current location\n  tel - teleport to the newly created room\n\nExample:\n  tunnel n\n  tunnel n = house;mike\'s place;green building\n\nThis is a simple way to build using pre-defined directions:\n |wn,ne,e,se,s,sw,w,nw|n (north, northeast etc)\n |wu,d|n (up and down)\n |wi,o|n (in and out)\nThe full names (north, in, southwest, etc) will always be put as\nmain name for the exit, using the abbreviation as an alias (so an\nexit will always be able to be used with both "north" as well as\n"n" for example). Opposite directions will automatically be\ncreated back from the new room unless the /oneway switch is given.\nFor more flexibility and power in creating rooms, use dig.\n'}

class evennia.commands.default.building.CmdLink(**kwargs)

Bases: MuxCommand

link existing rooms together with exits

Usage:

link[/switches] <object> = <target> link[/switches] <object> = link[/switches] <object>

Switch:

twoway - connect two exits. For this to work, BOTH <object>

and <target> must be exit objects.

If <object> is an exit, set its destination to <target>. Two-way operation instead sets the destination to the locations of the respective given arguments. The second form (a lone =) sets the destination to None (same as the unlink command) and the third form (without =) just shows the currently set destination.

key = '@link'

locks = 'cmd:perm(link) or perm(Builder)'

help_category = 'building'

func()

Perform the link

aliases = []

lock_storage = 'cmd:perm(link) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@link', 'no_prefix': 'link ', 'tags': '', 'text': '\nlink existing rooms together with exits\n\nUsage:\n  link[/switches] <object> = <target>\n  link[/switches] <object> =\n  link[/switches] <object>\n\nSwitch:\n  twoway - connect two exits. For this to work, BOTH <object>\n           and <target> must be exit objects.\n\nIf <object> is an exit, set its destination to <target>. Two-way operation\ninstead sets the destination to the *locations* of the respective given\narguments.\nThe second form (a lone =) sets the destination to None (same as\nthe unlink command) and the third form (without =) just shows the\ncurrently set destination.\n'}

class evennia.commands.default.building.CmdUnLink(**kwargs)

Bases: CmdLink

remove exit-connections between rooms

Usage:

unlink <Object>

Unlinks an object, for example an exit, disconnecting it from whatever it was connected to.

key = 'unlink'

locks = 'cmd:perm(unlink) or perm(Builder)'

help_key = 'Building'

func()

All we need to do here is to set the right command and call func in CmdLink

aliases = []

help_category = 'building'

lock_storage = 'cmd:perm(unlink) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': 'unlink', 'no_prefix': ' ', 'tags': '', 'text': '\nremove exit-connections between rooms\n\nUsage:\n  unlink <Object>\n\nUnlinks an object, for example an exit, disconnecting\nit from whatever it was connected to.\n'}

class evennia.commands.default.building.CmdSetHome(**kwargs)

Bases: CmdLink

set an object’s home location

Usage:

sethome <obj> [= <home_location>] sethome <obj>

The “home” location is a “safety” location for objects; they will be moved there if their current location ceases to exist. All objects should always have a home location for this reason. It is also a convenient target of the “home” command.

If no location is given, just view the object’s home location.

key = '@sethome'

locks = 'cmd:perm(sethome) or perm(Builder)'

help_category = 'building'

func()

implement the command

aliases = []

lock_storage = 'cmd:perm(sethome) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@sethome', 'no_prefix': 'sethome ', 'tags': '', 'text': '\nset an object\'s home location\n\nUsage:\n  sethome <obj> [= <home_location>]\n  sethome <obj>\n\nThe "home" location is a "safety" location for objects; they\nwill be moved there if their current location ceases to exist. All\nobjects should always have a home location for this reason.\nIt is also a convenient target of the "home" command.\n\nIf no location is given, just view the object\'s home location.\n'}

class evennia.commands.default.building.CmdListCmdSets(**kwargs)

Bases: MuxCommand

list command sets defined on an object

Usage:

cmdsets <obj>

This displays all cmdsets assigned to a user. Defaults to yourself.

key = '@cmdsets'

locks = 'cmd:perm(listcmdsets) or perm(Builder)'

help_category = 'building'

func()

list the cmdsets

aliases = []

lock_storage = 'cmd:perm(listcmdsets) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@cmdsets', 'no_prefix': 'cmdsets ', 'tags': '', 'text': '\nlist command sets defined on an object\n\nUsage:\n  cmdsets <obj>\n\nThis displays all cmdsets assigned\nto a user. Defaults to yourself.\n'}

class evennia.commands.default.building.CmdName(**kwargs)

Bases: ObjManipCommand

change the name and/or aliases of an object

Usage:

name <obj> = <newname>;alias1;alias2

Rename an object to something new. Use *obj to rename an account.

key = '@name'

aliases = ['@rename']

locks = 'cmd:perm(rename) or perm(Builder)'

help_category = 'building'

func()

change the name

lock_storage = 'cmd:perm(rename) or perm(Builder)'

search_index_entry = {'aliases': '@rename', 'category': 'building', 'key': '@name', 'no_prefix': 'name rename', 'tags': '', 'text': '\nchange the name and/or aliases of an object\n\nUsage:\n  name <obj> = <newname>;alias1;alias2\n\nRename an object to something new. Use *obj to\nrename an account.\n\n'}

class evennia.commands.default.building.CmdOpen(**kwargs)

Bases: ObjManipCommand

open a new exit from the current room

Usage:

open <new exit>[;alias;alias..][:typeclass] [,<return exit>[;alias;..][:typeclass]]] = <destination>

Handles the creation of exits. If a destination is given, the exit will point there. The <return exit> argument sets up an exit at the destination leading back to the current room. Destination name can be given both as a #dbref and a name, if that name is globally unique.

key = '@open'

locks = 'cmd:perm(open) or perm(Builder)'

help_category = 'building'

method_type = 'cmd_open'

new_obj_lockstring = 'control:id({id}) or perm(Admin);delete:id({id}) or perm(Admin)'

create_exit(exit_name, location, destination, exit_aliases=None, typeclass=None)

Helper function to avoid code duplication. At this point we know destination is a valid location

parse()

We need to expand the default parsing to get all the cases, see the module doc.

func()

This is where the processing starts. Uses the ObjManipCommand.parser() for pre-processing as well as the self.create_exit() method.

aliases = []

lock_storage = 'cmd:perm(open) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@open', 'no_prefix': 'open ', 'tags': '', 'text': '\nopen a new exit from the current room\n\nUsage:\n  open <new exit>[;alias;alias..][:typeclass] [,<return exit>[;alias;..][:typeclass]]] = <destination>\n\nHandles the creation of exits. If a destination is given, the exit\nwill point there. The <return exit> argument sets up an exit at the\ndestination leading back to the current room. Destination name\ncan be given both as a #dbref and a name, if that name is globally\nunique.\n\n'}

class evennia.commands.default.building.CmdSetAttribute(**kwargs)

Bases: ObjManipCommand

set attribute on an object or account

Usage:

set[/switch] <obj>/<attr>[:category] = <value> set[/switch] <obj>/<attr>[:category] = # delete attribute set[/switch] <obj>/<attr>[:category] # view attribute set[/switch] *<account>/<attr>[:category] = <value>

Switch:

edit: Open the line editor (string values only) script: If we’re trying to set an attribute on a script channel: If we’re trying to set an attribute on a channel account: If we’re trying to set an attribute on an account room: Setting an attribute on a room (global search) exit: Setting an attribute on an exit (global search) char: Setting an attribute on a character (global search) character: Alias for char, as above.

Example

set self/foo = “bar” set/delete self/foo set self/foo = $dbref(#53)

Sets attributes on objects. The second example form above clears a previously set attribute while the third form inspects the current value of the attribute (if any). The last one (with the star) is a shortcut for operating on a player Account rather than an Object.

If you want <value> to be an object, use $dbef(#dbref) or $search(key) to assign it. You need control or edit access to the object you are adding.

The most common data to save with this command are strings and numbers. You can however also set Python primitives such as lists, dictionaries and tuples on objects (this might be important for the functionality of certain custom objects). This is indicated by you starting your value with one of |c’|n, |c”|n, |c(|n, |c[|n or |c{ |n.

Once you have stored a Python primitive as noted above, you can include |c[<key>]|n in <attr> to reference nested values in e.g. a list or dict.

Remember that if you use Python primitives like this, you must write proper Python syntax too - notably you must include quotes around your strings or you will get an error.

key = '@set'

locks = 'cmd:perm(set) or perm(Builder)'

help_category = 'building'

nested_re = re.compile('\\[.*?\\]')

not_found = <object object>

check_obj(obj)

This may be overridden by subclasses in case restrictions need to be placed on whether certain objects can have attributes set by certain accounts.

This function is expected to display its own error message.

Returning False will abort the command.

check_attr(obj, attr_name, category)

This may be overridden by subclasses in case restrictions need to be placed on what attributes can be set by who beyond the normal lock.

This functions is expected to display its own error message. It is run once for every attribute that is checked, blocking only those attributes which are not permitted and letting the others through.

split_nested_attr(attr)

Yields tuples of (possible attr name, nested keys on that attr). For performance, this is biased to the deepest match, but allows compatibility with older attrs that might have been named with []’s.

> list(split_nested_attr(“nested[‘asdf’][0]”)) [

(‘nested’, [‘asdf’, 0]), (“nested[‘asdf’]”, [0]), (“nested[‘asdf’][0]”, []),

]

do_nested_lookup(value, *keys)

view_attr(obj, attr, category)

Look up the value of an attribute and return a string displaying it.

rm_attr(obj, attr, category)

Remove an attribute from the object, or a nested data structure, and report back.

set_attr(obj, attr, value, category)

edit_handler(**kwargs)

search_for_obj(objname)

Searches for an object matching objname. The object may be of different typeclasses. :param objname: Name of the object we’re looking for

Returns:

A typeclassed object, or None if nothing is found.

func()

Implement the set attribute - a limited form of py.

aliases = []

lock_storage = 'cmd:perm(set) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@set', 'no_prefix': 'set ', 'tags': '', 'text': '\nset attribute on an object or account\n\nUsage:\n  set[/switch] <obj>/<attr>[:category] = <value>\n  set[/switch] <obj>/<attr>[:category] =                  # delete attribute\n  set[/switch] <obj>/<attr>[:category]                    # view attribute\n  set[/switch] *<account>/<attr>[:category] = <value>\n\nSwitch:\n    edit: Open the line editor (string values only)\n    script: If we\'re trying to set an attribute on a script\n    channel: If we\'re trying to set an attribute on a channel\n    account: If we\'re trying to set an attribute on an account\n    room: Setting an attribute on a room (global search)\n    exit: Setting an attribute on an exit (global search)\n    char: Setting an attribute on a character (global search)\n    character: Alias for char, as above.\n\nExample:\n    set self/foo = "bar"\n    set/delete self/foo\n    set self/foo = $dbref(#53)\n\nSets attributes on objects. The second example form above clears a\npreviously set attribute while the third form inspects the current value of\nthe attribute (if any). The last one (with the star) is a shortcut for\noperating on a player Account rather than an Object.\n\nIf you want <value> to be an object, use $dbef(#dbref) or\n$search(key) to assign it. You need control or edit access to\nthe object you are adding.\n\nThe most common data to save with this command are strings and\nnumbers. You can however also set Python primitives such as lists,\ndictionaries and tuples on objects (this might be important for\nthe functionality of certain custom objects).  This is indicated\nby you starting your value with one of |c\'|n, |c"|n, |c(|n, |c[|n\nor |c{ |n.\n\nOnce you have stored a Python primitive as noted above, you can include\n|c[<key>]|n in <attr> to reference nested values in e.g. a list or dict.\n\nRemember that if you use Python primitives like this, you must\nwrite proper Python syntax too - notably you must include quotes\naround your strings or you will get an error.\n\n'}

class evennia.commands.default.building.CmdTypeclass(**kwargs)

Bases: MuxCommand

set or change an object’s typeclass

Usage:

typeclass[/switch] <object> [= typeclass.path] typeclass/prototype <object> = prototype_key

typeclasses or typeclass/list/show [typeclass.path] swap - this is a shorthand for using /force/reset flags. update - this is a shorthand for using the /force/reload flag.

Switch:

show, examine - display the current typeclass of object (default) or, if

given a typeclass path, show the docstring of that typeclass.

update - only re-run at_object_creation on this object

meaning locks or other properties set later may remain.

reset - clean out all the attributes and properties on the

object - basically making this a new clean object. This will also reset cmdsets!

force - change to the typeclass also if the object

already has a typeclass of the same name.

list - show available typeclasses. Only typeclasses in modules actually

imported or used from somewhere in the code will show up here (those typeclasses are still available if you know the path)

prototype - clean and overwrite the object with the specified

prototype key - effectively making a whole new object.

Example

type button = examples.red_button.RedButton type/prototype button=a red button

If the typeclass_path is not given, the current object’s typeclass is assumed.

View or set an object’s typeclass. If setting, the creation hooks of the new typeclass will be run on the object. If you have clashing properties on the old class, use /reset. By default you are protected from changing to a typeclass of the same name as the one you already have - use /force to override this protection.

The given typeclass must be identified by its location using python dot-notation pointing to the correct module and class. If no typeclass is given (or a wrong typeclass is given). Errors in the path or new typeclass will lead to the old typeclass being kept. The location of the typeclass module is searched from the default typeclass directory, as defined in the server settings.

key = '@typeclass'

aliases = ['@update', '@typeclasses', '@swap', '@parent', '@type']

switch_options = ('show', 'examine', 'update', 'reset', 'force', 'list', 'prototype')

locks = 'cmd:perm(typeclass) or perm(Builder)'

help_category = 'building'

func()

Implements command

lock_storage = 'cmd:perm(typeclass) or perm(Builder)'

search_index_entry = {'aliases': '@update @typeclasses @swap @parent @type', 'category': 'building', 'key': '@typeclass', 'no_prefix': 'typeclass update typeclasses swap parent type', 'tags': '', 'text': "\nset or change an object's typeclass\n\nUsage:\n  typeclass[/switch] <object> [= typeclass.path]\n  typeclass/prototype <object> = prototype_key\n\n  typeclasses or typeclass/list/show [typeclass.path]\n  swap - this is a shorthand for using /force/reset flags.\n  update - this is a shorthand for using the /force/reload flag.\n\nSwitch:\n  show, examine - display the current typeclass of object (default) or, if\n        given a typeclass path, show the docstring of that typeclass.\n  update - *only* re-run at_object_creation on this object\n          meaning locks or other properties set later may remain.\n  reset - clean out *all* the attributes and properties on the\n          object - basically making this a new clean object. This will also\n          reset cmdsets!\n  force - change to the typeclass also if the object\n          already has a typeclass of the same name.\n  list - show available typeclasses. Only typeclasses in modules actually\n         imported or used from somewhere in the code will show up here\n         (those typeclasses are still available if you know the path)\n  prototype - clean and overwrite the object with the specified\n           prototype key - effectively making a whole new object.\n\nExample:\n  type button = examples.red_button.RedButton\n  type/prototype button=a red button\n\nIf the typeclass_path is not given, the current object's typeclass is\nassumed.\n\nView or set an object's typeclass. If setting, the creation hooks of the\nnew typeclass will be run on the object. If you have clashing properties on\nthe old class, use /reset. By default you are protected from changing to a\ntypeclass of the same name as the one you already have - use /force to\noverride this protection.\n\nThe given typeclass must be identified by its location using python\ndot-notation pointing to the correct module and class. If no typeclass is\ngiven (or a wrong typeclass is given). Errors in the path or new typeclass\nwill lead to the old typeclass being kept. The location of the typeclass\nmodule is searched from the default typeclass directory, as defined in the\nserver settings.\n\n"}

class evennia.commands.default.building.CmdWipe(**kwargs)

Bases: ObjManipCommand

clear all attributes from an object

Usage:

wipe <object>[/<attr>[/<attr>…]]

Example

wipe box wipe box/colour

Wipes all of an object’s attributes, or optionally only those matching the given attribute-wildcard search string.

key = '@wipe'

locks = 'cmd:perm(wipe) or perm(Builder)'

help_category = 'building'

func()

inp is the dict produced in ObjManipCommand.parse()

aliases = []

lock_storage = 'cmd:perm(wipe) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'building', 'key': '@wipe', 'no_prefix': 'wipe ', 'tags': '', 'text': "\nclear all attributes from an object\n\nUsage:\n  wipe <object>[/<attr>[/<attr>...]]\n\nExample:\n  wipe box\n  wipe box/colour\n\nWipes all of an object's attributes, or optionally only those\nmatching the given attribute-wildcard search string.\n"}

class evennia.commands.default.building.CmdLock(**kwargs)

Bases: ObjManipCommand

assign a lock definition to an object

Usage:

lock <object or *account>[ = <lockstring>] or lock[/switch] <object or *account>/<access_type>

Switch:

del - delete given access type view - view lock associated with given access type (default)

If no lockstring is given, shows all locks on object.

Lockstring is of the form

access_type:[NOT] func1(args)[ AND|OR][ NOT] func2(args) …]

Where func1, func2 … valid lockfuncs with or without arguments. Separator expressions need not be capitalized.

For example:

‘get: id(25) or perm(Admin)’

The ‘get’ lock access_type is checked e.g. by the ‘get’ command. An object locked with this example lock will only be possible to pick up by Admins or by an object with id=25.

You can add several access_types after one another by separating them by ‘;’, i.e:

‘get:id(25); delete:perm(Builder)’

key = '@lock'

aliases = ['@locks']

locks = 'cmd:all();cmd: perm(locks) or perm(Builder)'

help_category = 'building'

func()

Sets up the command

lock_storage = 'cmd:all();cmd: perm(locks) or perm(Builder)'

search_index_entry = {'aliases': '@locks', 'category': 'building', 'key': '@lock', 'no_prefix': 'lock locks', 'tags': '', 'text': "\nassign a lock definition to an object\n\nUsage:\n  lock <object or *account>[ = <lockstring>]\n  or\n  lock[/switch] <object or *account>/<access_type>\n\nSwitch:\n  del - delete given access type\n  view - view lock associated with given access type (default)\n\nIf no lockstring is given, shows all locks on\nobject.\n\nLockstring is of the form\n   access_type:[NOT] func1(args)[ AND|OR][ NOT] func2(args) ...]\nWhere func1, func2 ... valid lockfuncs with or without arguments.\nSeparator expressions need not be capitalized.\n\nFor example:\n   'get: id(25) or perm(Admin)'\nThe 'get' lock access_type is checked e.g. by the 'get' command.\nAn object locked with this example lock will only be possible to pick up\nby Admins or by an object with id=25.\n\nYou can add several access_types after one another by separating\nthem by ';', i.e:\n   'get:id(25); delete:perm(Builder)'\n"}

class evennia.commands.default.building.CmdExamine(**kwargs)

Bases: ObjManipCommand

get detailed information about an object

Usage:

examine [<object>[/attrname]] examine [*<account>[/attrname]]

Switch:

account - examine an Account (same as adding *) object - examine an Object (useful when OOC) script - examine a Script channel - examine a Channel

The examine command shows detailed game info about an object and optionally a specific attribute on it. If object is not specified, the current location is examined.

Append a * before the search string to examine an account.

key = '@examine'

aliases = ['@ex', '@exam']

locks = 'cmd:perm(examine) or perm(Builder)'

help_category = 'building'

arg_regex = re.compile('(/\\w+?(\\s|$))|\\s|$', re.IGNORECASE)

switch_options = ['account', 'object', 'script', 'channel']

object_type = 'object'

detail_color = '|c'

header_color = '|w'

quell_color = '|r'

separator = '-'

msg(text)

Central point for sending messages to the caller. This tags the message as ‘examine’ for eventual custom markup in the client.

text

The text to send.

Type:

str

format_key(obj)

format_aliases(obj)

format_typeclass(obj)

format_sessions(obj)

format_email(obj)

format_last_login(obj)

format_account_key(account)

format_account_typeclass(account)

format_account_permissions(account)

format_location(obj)

format_home(obj)

format_destination(obj)

format_permissions(obj)

format_locks(obj)

format_scripts(obj)

format_single_tag(tag)

format_tags(obj)

format_single_cmdset_options(cmdset)

format_single_cmdset(cmdset)

format_stored_cmdsets(obj)

format_merged_cmdsets(obj, current_cmdset)

format_current_cmds(obj, current_cmdset)

format_single_attribute_detail(obj, attr)

format_single_attribute(attr)

format_attributes(obj)

format_nattributes(obj)

format_exits(obj)

format_chars(obj)

format_things(obj)

format_script_desc(obj)

format_script_is_persistent(obj)

format_script_timer_data(obj)

format_channel_sub_totals(obj)

format_channel_account_subs(obj)

format_channel_object_subs(obj)

get_formatted_obj_data(obj, current_cmdset)

Calls all other format_* methods.

format_output(obj, current_cmdset)

Formats the full examine page return.

parse()

We need to expand the default parsing to get all the cases, see the module doc.

func()

Process command

lock_storage = 'cmd:perm(examine) or perm(Builder)'

search_index_entry = {'aliases': '@ex @exam', 'category': 'building', 'key': '@examine', 'no_prefix': 'examine ex exam', 'tags': '', 'text': '\nget detailed information about an object\n\nUsage:\n  examine [<object>[/attrname]]\n  examine [*<account>[/attrname]]\n\nSwitch:\n  account - examine an Account (same as adding *)\n  object - examine an Object (useful when OOC)\n  script - examine a Script\n  channel - examine a Channel\n\nThe examine command shows detailed game info about an\nobject and optionally a specific attribute on it.\nIf object is not specified, the current location is examined.\n\nAppend a * before the search string to examine an account.\n\n'}

class evennia.commands.default.building.CmdFind(**kwargs)

Bases: MuxCommand

search the database for objects

Usage:

find[/switches] <name or dbref or *account> [= dbrefmin[-dbrefmax]] locate - this is a shorthand for using the /loc switch.

Switches:

room - only look for rooms (location=None) exit - only look for exits (destination!=None) char - only look for characters (BASE_CHARACTER_TYPECLASS) exact - only exact matches are returned. loc - display object location if exists and match has one result startswith - search for names starting with the string, rather than containing

Searches the database for an object of a particular name or exact #dbref. Use *accountname to search for an account. The switches allows for limiting object matches to certain game entities. Dbrefmin and dbrefmax limits matches to within the given dbrefs range, or above/below if only one is given.

key = '@find'

aliases = ['@locate', '@search']

switch_options = ('room', 'exit', 'char', 'exact', 'loc', 'startswith')

locks = 'cmd:perm(find) or perm(Builder)'

help_category = 'building'

func()

Search functionality

lock_storage = 'cmd:perm(find) or perm(Builder)'

search_index_entry = {'aliases': '@locate @search', 'category': 'building', 'key': '@find', 'no_prefix': 'find locate search', 'tags': '', 'text': '\nsearch the database for objects\n\nUsage:\n  find[/switches] <name or dbref or *account> [= dbrefmin[-dbrefmax]]\n  locate - this is a shorthand for using the /loc switch.\n\nSwitches:\n  room       - only look for rooms (location=None)\n  exit       - only look for exits (destination!=None)\n  char       - only look for characters (BASE_CHARACTER_TYPECLASS)\n  exact      - only exact matches are returned.\n  loc        - display object location if exists and match has one result\n  startswith - search for names starting with the string, rather than containing\n\nSearches the database for an object of a particular name or exact #dbref.\nUse *accountname to search for an account. The switches allows for\nlimiting object matches to certain game entities. Dbrefmin and dbrefmax\nlimits matches to within the given dbrefs range, or above/below if only\none is given.\n'}

class evennia.commands.default.building.CmdTeleport(**kwargs)

Bases: MuxCommand

teleport object to another location

Usage:

tel/switch [<object> to||=] <target location>

Examples

tel Limbo tel/quiet box = Limbo tel/tonone box

Switches:

quiet - don’t echo leave/arrive messages to the source/target

locations for the move.

intoexit - if target is an exit, teleport INTO

the exit object instead of to its destination

tonone - if set, teleport the object to a None-location. If this

switch is set, <target location> is ignored. Note that the only way to retrieve an object from a None location is by direct #dbref reference. A puppeted object cannot be moved to None.

loc - teleport object to the target’s location instead of its contents

Teleports an object somewhere. If no object is given, you yourself are teleported to the target location.

To lock an object from being teleported, set its teleport lock, it will be checked with the caller. To block a destination from being teleported to, set the destination’s teleport_here lock - it will be checked with the thing being teleported. Admins and higher permissions can always teleport.

key = '@teleport'

aliases = ['@tel']

switch_options = ('quiet', 'intoexit', 'tonone', 'loc')

rhs_split = ('=', ' to ')

locks = 'cmd:perm(teleport) or perm(Builder)'

help_category = 'building'

parse()

Breaking out searching here to make this easier to override.

func()

Performs the teleport

lock_storage = 'cmd:perm(teleport) or perm(Builder)'

search_index_entry = {'aliases': '@tel', 'category': 'building', 'key': '@teleport', 'no_prefix': 'teleport tel', 'tags': '', 'text': "\nteleport object to another location\n\nUsage:\n  tel/switch [<object> to||=] <target location>\n\nExamples:\n  tel Limbo\n  tel/quiet box = Limbo\n  tel/tonone box\n\nSwitches:\n  quiet  - don't echo leave/arrive messages to the source/target\n           locations for the move.\n  intoexit - if target is an exit, teleport INTO\n             the exit object instead of to its destination\n  tonone - if set, teleport the object to a None-location. If this\n           switch is set, <target location> is ignored.\n           Note that the only way to retrieve\n           an object from a None location is by direct #dbref\n           reference. A puppeted object cannot be moved to None.\n  loc - teleport object to the target's location instead of its contents\n\nTeleports an object somewhere. If no object is given, you yourself are\nteleported to the target location.\n\nTo lock an object from being teleported, set its `teleport` lock, it will be\nchecked with the caller. To block\na destination from being teleported to, set the destination's `teleport_here`\nlock - it will be checked with the thing being teleported. Admins and\nhigher permissions can always teleport.\n\n"}

class evennia.commands.default.building.CmdScripts(**kwargs)

Bases: MuxCommand

List and manage all running scripts. Allows for creating new global scripts.

Usage:

script[/switches] [script-#dbref, key, script.path] script[/start||stop] <obj> = [<script.path or script-key>]

Switches:

start - start/unpause an existing script’s timer. stop - stops an existing script’s timer pause - pause a script’s timer delete - deletes script. This will also stop the timer as needed

Examples

script - list all scripts script key:foo.bar.Script - create a new global Script with typeclass

and key ‘key’

script foo.bar.Script - create a new global Script with typeclass

(key taken from typeclass or auto-generated)

script/pause foo.bar.Script - pause global script script typeclass|name|#dbref - examine named existing global script script/delete #dbref[-#dbref] - delete script or range by #dbref

script myobj = - list all scripts on object script myobj = foo.bar.Script - create and assign script to object script/stop myobj = name|#dbref - stop named script on object script/delete myobj = name|#dbref - delete script on object script/delete myobj = - delete ALL scripts on object

When given with an <obj> as left-hand-side, this creates and assigns a new script to that object. Without an <obj>, this manages and inspects global scripts.

If no switches are given, this command just views all active scripts. The argument can be either an object, at which point it will be searched for all scripts defined on it, or a script name or #dbref. For using the /stop switch, a unique script #dbref is required since whole classes of scripts often have the same name.

Use the script build-level command for managing scripts attached to objects.

key = '@scripts'

aliases = ['@script']

switch_options = ('start', 'stop', 'pause', 'delete')

locks = 'cmd:perm(scripts) or perm(Builder)'

help_category = 'system'

excluded_typeclass_paths = ['evennia.prototypes.prototypes.DbPrototype']

switch_mapping = {'delete': '|rDeleted|n', 'pause': '|Paused|n', 'start': '|gStarted|n', 'stop': '|RStopped|n'}

hide_script_paths = ('evennia.prototypes.prototypes.DbPrototype',)

parse()

This method is called by the cmdhandler once the command name has been identified. It creates a new set of member variables that can be later accessed from self.func() (see below)

The following variables are available for our use when entering this method (from the command definition, and assigned on the fly by the cmdhandler):

self.key - the name of this command (‘look’) self.aliases - the aliases of this cmd (‘l’) self.permissions - permission string for this command self.help_category - overall category of command

self.caller - the object calling this command self.cmdstring - the actual command name used to call this

(this allows you to know which alias was used,

for example)

self.args - the raw input; everything following self.cmdstring. self.cmdset - the cmdset from which this command was picked. Not

often used (useful for commands like ‘help’ or to list all available commands etc)

self.obj - the object on which this command was defined. It is often

the same as self.caller.

A MUX command has the following possible syntax:

name[ with several words][/switch[/switch..]] arg1[,arg2,…] [[=|,] arg[,..]]

The ‘name[ with several words]’ part is already dealt with by the cmdhandler at this point, and stored in self.cmdname (we don’t use it here). The rest of the command is stored in self.args, which can start with the switch indicator /.

Optional variables to aid in parsing, if set:

self.switch_options - (tuple of valid /switches expected by this

command (without the /))

self.rhs_split - Alternate string delimiter or tuple of strings

to separate left/right hand sides. tuple form gives priority split to first string delimiter.

This parser breaks self.args into its constituents and stores them in the following variables:

self.switches = [list of /switches (without the /)] self.raw = This is the raw argument input, including switches self.args = This is re-defined to be everything except the switches self.lhs = Everything to the left of = (lhs:’left-hand side’). If

no = is found, this is identical to self.args.

self.rhs: Everything to the right of = (rhs:’right-hand side’).

If no ‘=’ is found, this is None.

self.lhslist - [self.lhs split into a list by comma] self.rhslist - [list of self.rhs split into a list by comma] self.arglist = [list of space-separated args (stripped, including ‘=’ if it exists)]

All args and list members are stripped of excess whitespace around the strings, but case is preserved.

func()

implement method

lock_storage = 'cmd:perm(scripts) or perm(Builder)'

search_index_entry = {'aliases': '@script', 'category': 'system', 'key': '@scripts', 'no_prefix': 'scripts script', 'tags': '', 'text': "\nList and manage all running scripts. Allows for creating new global\nscripts.\n\nUsage:\n  script[/switches] [script-#dbref, key, script.path]\n  script[/start||stop] <obj> = [<script.path or script-key>]\n\nSwitches:\n  start  - start/unpause an existing script's timer.\n  stop   - stops an existing script's timer\n  pause  - pause a script's timer\n  delete - deletes script. This will also stop the timer as needed\n\nExamples:\n    script                             - list all scripts\n    script key:foo.bar.Script         - create a new global Script with typeclass\n                                         and key 'key'\n    script foo.bar.Script              - create a new global Script with typeclass\n                                         (key taken from typeclass or auto-generated)\n    script/pause foo.bar.Script        - pause global script\n    script typeclass|name|#dbref       - examine named existing global script\n    script/delete #dbref[-#dbref]      - delete script or range by #dbref\n\n    script myobj =                    - list all scripts on object\n    script myobj = foo.bar.Script     - create and assign script to object\n    script/stop myobj = name|#dbref   - stop named script on object\n    script/delete myobj = name|#dbref - delete script on object\n    script/delete myobj =             - delete ALL scripts on object\n\nWhen given with an `<obj>` as left-hand-side, this creates and\nassigns a new script to that object. Without an `<obj>`, this\nmanages and inspects global scripts.\n\nIf no switches are given, this command just views all active\nscripts. The argument can be either an object, at which point it\nwill be searched for all scripts defined on it, or a script name\nor #dbref. For using the /stop switch, a unique script #dbref is\nrequired since whole classes of scripts often have the same name.\n\nUse the `script` build-level command for managing scripts attached to\nobjects.\n\n"}

class evennia.commands.default.building.CmdObjects(**kwargs)

Bases: MuxCommand

statistics on objects in the database

Usage:

objects [<nr>]

Gives statictics on objects in database as well as a list of <nr> latest objects in database. If not given, <nr> defaults to 10.

key = '@objects'

locks = 'cmd:perm(listobjects) or perm(Builder)'

help_category = 'system'

func()

Implement the command

aliases = []

lock_storage = 'cmd:perm(listobjects) or perm(Builder)'

search_index_entry = {'aliases': '', 'category': 'system', 'key': '@objects', 'no_prefix': 'objects ', 'tags': '', 'text': '\nstatistics on objects in the database\n\nUsage:\n  objects [<nr>]\n\nGives statictics on objects in database as well as\na list of <nr> latest objects in database. If not\ngiven, <nr> defaults to 10.\n'}

class evennia.commands.default.building.CmdTag(**kwargs)

Bases: MuxCommand

handles the tags of an object

Usage:

tag[/del] <obj> [= <tag>[:<category>]] tag/search <tag>[:<category]

Switches:

search - return all objects with a given Tag del - remove the given tag. If no tag is specified,

clear all tags on object.

Manipulates and lists tags on objects. Tags allow for quick grouping of and searching for objects. If only <obj> is given, list all tags on the object. If /search is used, list objects with the given tag. The category can be used for grouping tags themselves, but it should be used with restrain - tags on their own are usually enough to for most grouping schemes.

key = '@tag'

aliases = ['@tags']

switch_options = ('search', 'del')

locks = 'cmd:perm(tag) or perm(Builder)'

help_category = 'building'

arg_regex = re.compile('(/\\w+?(\\s|$))|\\s|$', re.IGNORECASE)

func()

Implement the tag functionality

lock_storage = 'cmd:perm(tag) or perm(Builder)'

search_index_entry = {'aliases': '@tags', 'category': 'building', 'key': '@tag', 'no_prefix': 'tag tags', 'tags': '', 'text': '\nhandles the tags of an object\n\nUsage:\n  tag[/del] <obj> [= <tag>[:<category>]]\n  tag/search <tag>[:<category]\n\nSwitches:\n  search - return all objects with a given Tag\n  del - remove the given tag. If no tag is specified,\n        clear all tags on object.\n\nManipulates and lists tags on objects. Tags allow for quick\ngrouping of and searching for objects.  If only <obj> is given,\nlist all tags on the object.  If /search is used, list objects\nwith the given tag.\nThe category can be used for grouping tags themselves, but it\nshould be used with restrain - tags on their own are usually\nenough to for most grouping schemes.\n'}

class evennia.commands.default.building.CmdSpawn(**kwargs)

Bases: MuxCommand

spawn objects from prototype

Usage:

spawn[/noloc] <prototype_key> spawn[/noloc] <prototype_dict>

spawn/search [prototype_keykey][;tag[,tag]] spawn/list [tag, tag, …] spawn/list modules - list only module-based prototypes spawn/show [<prototype_key>] spawn/update <prototype_key>

spawn/save <prototype_dict> spawn/edit [<prototype_key>] olc - equivalent to spawn/edit

Switches:

noloc - allow location to be None if not specified explicitly. Otherwise,

location will default to caller’s current location.

search - search prototype by name or tags. list - list available prototypes, optionally limit by tags. show, examine - inspect prototype by key. If not given, acts like list. raw - show the raw dict of the prototype as a one-line string for manual editing. save - save a prototype to the database. It will be listable by /list. delete - remove a prototype from database, if allowed to. update - find existing objects with the same prototype_key and update

them with latest version of given prototype. If given with /save, will auto-update all objects with the old version of the prototype without asking first.

edit, menu, olc - create/manipulate prototype in a menu interface.

Example

spawn GOBLIN spawn {“key”:”goblin”, “typeclass”:”monster.Monster”, “location”:”#2”} spawn/save {“key”: “grunt”, prototype: “goblin”};;mobs;edit:all()

Dictionary keys:

|wprototype_parent |n - name of parent prototype to use. Required if typeclass is

not set. Can be a path or a list for multiple inheritance (inherits left to right). If set one of the parents must have a typeclass.

|wtypeclass |n - string. Required if prototype_parent is not set. |wkey |n - string, the main object identifier |wlocation |n - this should be a valid object or #dbref |whome |n - valid object or #dbref |wdestination|n - only valid for exits (object or dbref) |wpermissions|n - string or list of permission strings |wlocks |n - a lock-string |waliases |n - string or list of strings. |wndb_|n<name> - value of a nattribute (ndb_ is stripped)

|wprototype_key|n - name of this prototype. Unique. Used to store/retrieve from db

and update existing prototyped objects if desired.

|wprototype_desc|n - desc of this prototype. Used in listings |wprototype_locks|n - locks of this prototype. Limits who may use prototype |wprototype_tags|n - tags of this prototype. Used to find prototype

any other keywords are interpreted as Attributes and their values.

The available prototypes are defined globally in modules set in settings.PROTOTYPE_MODULES. If spawn is used without arguments it displays a list of available prototypes.

key = '@spawn'

aliases = ['@olc']

switch_options = ('noloc', 'search', 'list', 'show', 'raw', 'examine', 'save', 'delete', 'menu', 'olc', 'update', 'edit')

locks = 'cmd:perm(spawn) or perm(Builder)'

help_category = 'building'

func()

Implements the spawner

lock_storage = 'cmd:perm(spawn) or perm(Builder)'

search_index_entry = {'aliases': '@olc', 'category': 'building', 'key': '@spawn', 'no_prefix': 'spawn olc', 'tags': '', 'text': '\nspawn objects from prototype\n\nUsage:\n  spawn[/noloc] <prototype_key>\n  spawn[/noloc] <prototype_dict>\n\n  spawn/search [prototype_keykey][;tag[,tag]]\n  spawn/list [tag, tag, ...]\n  spawn/list modules    - list only module-based prototypes\n  spawn/show [<prototype_key>]\n  spawn/update <prototype_key>\n\n  spawn/save <prototype_dict>\n  spawn/edit [<prototype_key>]\n  olc     - equivalent to spawn/edit\n\nSwitches:\n  noloc - allow location to be None if not specified explicitly. Otherwise,\n          location will default to caller\'s current location.\n  search - search prototype by name or tags.\n  list - list available prototypes, optionally limit by tags.\n  show, examine - inspect prototype by key. If not given, acts like list.\n  raw - show the raw dict of the prototype as a one-line string for manual editing.\n  save - save a prototype to the database. It will be listable by /list.\n  delete - remove a prototype from database, if allowed to.\n  update - find existing objects with the same prototype_key and update\n           them with latest version of given prototype. If given with /save,\n           will auto-update all objects with the old version of the prototype\n           without asking first.\n  edit, menu, olc - create/manipulate prototype in a menu interface.\n\nExample:\n  spawn GOBLIN\n  spawn {"key":"goblin", "typeclass":"monster.Monster", "location":"#2"}\n  spawn/save {"key": "grunt", prototype: "goblin"};;mobs;edit:all()\n\x0c\nDictionary keys:\n  |wprototype_parent  |n - name of parent prototype to use. Required if typeclass is\n                    not set. Can be a path or a list for multiple inheritance (inherits\n                    left to right). If set one of the parents must have a typeclass.\n  |wtypeclass  |n - string. Required if prototype_parent is not set.\n  |wkey        |n - string, the main object identifier\n  |wlocation   |n - this should be a valid object or #dbref\n  |whome       |n - valid object or #dbref\n  |wdestination|n - only valid for exits (object or dbref)\n  |wpermissions|n - string or list of permission strings\n  |wlocks      |n - a lock-string\n  |waliases    |n - string or list of strings.\n  |wndb_|n<name>  - value of a nattribute (ndb_ is stripped)\n\n  |wprototype_key|n   - name of this prototype. Unique. Used to store/retrieve from db\n                        and update existing prototyped objects if desired.\n  |wprototype_desc|n  - desc of this prototype. Used in listings\n  |wprototype_locks|n - locks of this prototype. Limits who may use prototype\n  |wprototype_tags|n  - tags of this prototype. Used to find prototype\n\n  any other keywords are interpreted as Attributes and their values.\n\nThe available prototypes are defined globally in modules set in\nsettings.PROTOTYPE_MODULES. If spawn is used without arguments it\ndisplays a list of available prototypes.\n\n'}

evennia.commands.default.building.COMMAND_DEFAULT_CLASS

alias of MuxCommand

class evennia.commands.default.building.EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)

Bases: object

This defines a line editor object. It creates all relevant commands and tracks the current state of the buffer. It also cleans up after itself.

__init__(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)

Launches a full in-game line editor, mimicking the functionality of VIM.

Parameters:

• caller (Object) – Who is using the editor.

• loadfunc (callable, optional) – This will be called as loadfunc(caller) when the editor is first started. Its return will be used as the editor’s starting buffer.

• savefunc (callable, optional) – This will be called as savefunc(caller, buffer) when the save-command is given and is used to actually determine where/how result is saved. It should return True if save was successful and also handle any feedback to the user.

• quitfunc (callable, optional) – This will optionally be called as quitfunc(caller) when the editor is exited. If defined, it should handle all wanted feedback to the user.

• quitfunc_args (tuple, optional) – Optional tuple of arguments to supply to quitfunc.

• key (str, optional) – An optional key for naming this session and make it unique from other editing sessions.

• persistent (bool, optional) – Make the editor survive a reboot. Note that if this is set, all callables must be possible to pickle

• codefunc (bool, optional) – If given, will run the editor in code mode. This will be called as codefunc(caller, buf).

Notes

In persistent mode, all the input callables (savefunc etc) must be possible to be pickled, this excludes e.g. callables that are class methods or functions defined dynamically or as part of another function. In non-persistent mode no such restrictions exist.

decrease_indent()

Decrease automatic indentation by 1 level.

deduce_indent(line, buffer)

Try to deduce the level of indentation of the given line.

display_buffer(buf=None, offset=0, linenums=True, options={'raw': False})

This displays the line editor buffer, or selected parts of it.

Parameters:

• buf (str, optional) – The buffer or part of buffer to display.

• offset (int, optional) – If buf is set and is not the full buffer, offset should define the actual starting line number, to get the linenum display right.

• linenums (bool, optional) – Show line numbers in buffer.

• options – raw (bool, optional): Tell protocol to not parse formatting information.

display_help()

Shows the help entry for the editor.

get_buffer()

Returns:

buffer (str) – The current buffer.

increase_indent()

Increase automatic indentation by 1 level.

load_buffer()

Load the buffer using the load function hook.

quit()

Cleanly exit the editor.

save_buffer()

Saves the content of the buffer.

swap_autoindent()

Swap automatic indentation on or off.

update_buffer(buf)

This should be called when the buffer has been changed somehow. It will handle unsaved flag and undo updating.

Parameters:

buf (str) – The text to update the buffer with.

update_undo(step=None)

This updates the undo position.

Parameters:

step (int, optional) – The amount of steps to progress the undo position to. This may be a negative value for undo and a positive value for redo.

class evennia.commands.default.building.EvMore(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Bases: object

The main pager object

__init__(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Initialization of the EvMore pager.

Parameters:

• caller (Object or Account) – Entity reading the text.

• inp (str, EvTable, Paginator or iterator) –

  The text or data to put under paging.

  • If a string, paginage normally. If this text contains one or more \f format symbol, automatic pagination and justification are force-disabled and page-breaks will only happen after each \f.

  • If EvTable, the EvTable will be paginated with the same setting on each page if it is too long. The table decorations will be considered in the size of the page.

  • Otherwise inp is converted to an iterator, where each step is expected to be a line in the final display. Each line will be run through iter_callable.

• always_page (bool, optional) – If False, the pager will only kick in if inp is too big to fit the screen.

• session (Session, optional) – If given, this session will be used to determine the screen width and will receive all output.

• justify (bool, optional) – If set, auto-justify long lines. This must be turned off for fixed-width or formatted output, like tables. It’s force-disabled if inp is an EvTable.

• justify_kwargs (dict, optional) – Keywords for the justify function. Used only if justify is True. If this is not set, default arguments will be used.

• exit_on_lastpage (bool, optional) – If reaching the last page without the page being completely filled, exit pager immediately. If unset, another move forward is required to exit. If set, the pager exit message will not be shown.

• exit_cmd (str, optional) – If given, this command-string will be executed on the caller when the more page exits. Note that this will be using whatever cmdset the user had before the evmore pager was activated (so none of the evmore commands will be available when this is run).

• kwargs (any, optional) – These will be passed on to the caller.msg method. Notably, one can pass additional outputfuncs this way. There is one special kwarg: - text_kwargs - extra kwargs to pass with the text outputfunc, e.g. text_kwargs={“type”: “help”} would result to each page being sent to msg as text=(pagetxt, {“type”: “help”}).

Examples

super_long_text = " ... "
EvMore(caller, super_long_text)

Paginator

from django.core.paginator import Paginator
query = ObjectDB.objects.all()
pages = Paginator(query, 10)  # 10 objs per page
EvMore(caller, pages)

Every page an EvTable

from evennia import EvTable
def _to_evtable(page):
    table = ... # convert page to a table
    return EvTable(*headers, table=table, ...)
EvMore(caller, pages, page_formatter=_to_evtable)

display(show_footer=True)

Pretty-print the page.

init_django_paginator(pages)

The input is a django Paginator object.

init_evtable(table)

The input is an EvTable.

init_f_str(text)

The input contains f markers. We use f to indicate the user wants to enforce their line breaks on their own. If so, we do no automatic line-breaking/justification at all.

Parameters:

text (str) – The string to format with f-markers.

init_iterable(inp)

The input is something other than a string - convert to iterable of strings

init_pages(inp)

Initialize the pagination. By default, will analyze input type to determine how pagination automatically.

Parameters:

inp (any) – Incoming data to be paginated. By default, handles pagination of strings, querysets, django.Paginator, EvTables and any iterables with strings.

Notes

If overridden, this method must perform the following actions:

• read and re-store self._data (the incoming data set) if needed for pagination to work.

• set self._npages to the total number of pages. Default is 1.

• set self._paginator to a callable that will take a page number 1…N and return the data to display on that page (not any decorations or next/prev buttons). If only wanting to change the paginator, override self.paginator instead.

• set self._page_formatter to a callable that will receive the page from self._paginator and format it with one element per line. Default is str. Or override self.page_formatter directly instead.

By default, helper methods are called that perform these actions depending on supported inputs.

init_queryset(qs)

The input is a queryset

init_str(text)

The input is a string

page_back()

Scroll the text back up, at the most to the top.

page_end()

Display the bottom page.

page_formatter(page)

Page formatter. Every page passes through this method. Override it to customize behavior per-page. A common use is to generate a new EvTable for every page (this is more efficient than to generate one huge EvTable across many pages and feed it into EvMore all at once).

Parameters:

page (any) – A piece of data representing one page to display. This must

Returns:

str –

A ready-formatted page to display. Extra footer with help about

switching to the next/prev page will be added automatically

page_next()

Scroll the text to the next page. Quit if already at the end of the page.

page_quit(quiet=False)

Quit the pager

page_top()

Display the top page

paginator(pageno)

Paginator. The data operated upon is in self._data.

Parameters:

pageno (int) – The page number to view, from 0…N-1

Returns:

str –

The page to display (without any decorations, those are added

by EvMore).

paginator_django(pageno)

Paginate using the django queryset Paginator API. Note that his is indexed from 1.

paginator_index(pageno)

Paginate to specific, known index

paginator_slice(pageno)

Paginate by slice. This is done with an eye on memory efficiency (usually for querysets); to avoid fetching all objects at the same time.

start()

Starts the pagination

class evennia.commands.default.building.EvTable(*args, **kwargs)

Bases: object

The table class holds a list of EvColumns, each consisting of EvCells so that the result is a 2D matrix.

__init__(*args, **kwargs)

Parameters:

table. (Header texts for the)

Keyword Arguments:

• table (list of lists or list of EvColumns, optional) – This is used to build the table in a quick way. If not given, the table will start out empty and add_ methods need to be used to add rows/columns.

• header (bool, optional) – True/False - turn off the header texts (*args) being treated as a header (such as not adding extra underlining)

• pad_width (int, optional) – How much empty space to pad your cells with (default is 1)

• border (str, optional)) – The border style to use. This is one of - None - No border drawing at all. - “table” - only a border around the whole table. - “tablecols” - table and column borders. (default) - “header” - only border under header. - “cols” - only vertical borders. - “incols” - vertical borders, no outer edges. - “rows” - only borders between rows. - “cells” - border around all cells.

• border_width (int, optional) – Width of table borders, if border is active. Note that widths wider than 1 may give artifacts in the corners. Default is 1.

• corner_char (str, optional) – Character to use in corners when border is active. Default is +.

• corner_top_left_char (str, optional) – Character used for “nw” corner of table. Defaults to corner_char.

• corner_top_right_char (str, optional) – Character used for “ne” corner of table. Defaults to corner_char.

• corner_bottom_left_char (str, optional) – Character used for “sw” corner of table. Defaults to corner_char.

• corner_bottom_right_char (str, optional) – Character used for “se” corner of table. Defaults to corner_char.

• pretty_corners (bool, optional) – Use custom characters to make the table corners look “rounded”. Uses UTF-8 characters. Defaults to False for maximum compatibility with various displays that may occationally have issues with UTF-8 characters.

• header_line_char (str, optional) – Character to use for underlining the header row (default is ‘~’). Requires border to not be None.

• width (int, optional) – Fixed width of table. If not set, width is set by the total width of each column. This will resize individual columns in the vertical direction to fit.

• height (int, optional) – Fixed height of table. Defaults to being unset. Width is still given precedence. If given, table cells will crop text rather than expand vertically.

• evenwidth (bool, optional) – Used with the width keyword. Adjusts columns to have as even width as possible. This often looks best also for mixed-length tables. Default is False.

• maxwidth (int, optional) – This will set a maximum width of the table while allowing it to be smaller. Only if it grows wider than this size will it be resized by expanding horizontally (or crop height is given). This keyword has no meaning if width is set.

Raises:

Exception – If given erroneous input or width settings for the data.

Notes

Beyond those table-specific keywords, the non-overlapping keywords of EvCell.__init__ are also available. These will be passed down to every cell in the table.

add_column(*args, **kwargs)

Add a column to table. If there are more rows in new column than there are rows in the current table, the table will expand with empty rows in the other columns. If too few, the new column with get new empty rows. All filling rows are added to the end.

Parameters:

• args (EvColumn or multiple strings) – Either a single EvColumn instance or a number of data string arguments to be used to create a new column.

• header (str, optional) – The header text for the column

• xpos (int, optional) – Index position in table before which to input new column. If not given, column will be added to the end of the table. Uses Python indexing (so first column is xpos=0)

Keyword Arguments:

Cell.__init__. (Other keywords as per)

add_header(*args, **kwargs)

Add header to table. This is a number of texts to be put at the top of the table. They will replace an existing header.

Parameters:

args (str) – These strings will be used as the header texts.

Keyword Arguments:

• applied (Same keywords as per EvTable.__init__. Will be)

• cells. (to the new header's)

add_row(*args, **kwargs)

Add a row to table (not a header). If there are more cells in the given row than there are cells in the current table the table will be expanded with empty columns to match. These will be added to the end of the table. In the same way, adding a line with too few cells will lead to the last ones getting padded.

Parameters:

• args (str) – Any number of string argumnets to use as the data in the row (one cell per argument).

• ypos (int, optional) – Index position in table before which to input new row. If not given, will be added to the end of the table. Uses Python indexing (so first row is ypos=0)

Keyword Arguments:

EvCell.__init__. (Other keywords are as per)

get()

Return lines of table as a list.

Returns:

table_lines (list) – The lines of the table, in order.

reformat(**kwargs)

Force a re-shape of the entire table.

Keyword Arguments:

EvTable.__init__. (Table options as per)

reformat_column(index, **kwargs)

Sends custom options to a specific column in the table.

Parameters:

index (int) – Which column to reformat. The column index is given from 0 to Ncolumns-1.

Keyword Arguments:

EvCell.__init__. (Column options as per)

Raises:

Exception – if an invalid index is found.

exception evennia.commands.default.building.InterruptCommand

Bases: Exception

Cleanly interrupt a command.

exception evennia.commands.default.building.LockException

Bases: Exception

Raised during an error in a lock.

class evennia.commands.default.building.Max(*args, **kwargs)

Bases: Aggregate

arity = 1

function = 'MAX'

name = 'Max'

class evennia.commands.default.building.Min(*args, **kwargs)

Bases: Aggregate

arity = 1

function = 'MIN'

name = 'Min'

class evennia.commands.default.building.ObjectDB(*args, **kwargs)

Bases: TypedObject

All objects in the game use the ObjectDB model to store data in the database. This is handled transparently through the typeclass system.

Note that the base objectdb is very simple, with few defined fields. Use attributes to extend your type class with new database-stored variables.

The TypedObject supplies the following (inherited) properties:

• key - main name

• name - alias for key

• db_typeclass_path - the path to the decorating typeclass

• db_date_created - time stamp of object creation

• permissions - perm strings

• locks - lock definitions (handler)

• dbref - #id of object

• db - persistent attribute storage

• ndb - non-persistent attribute storage

The ObjectDB adds the following properties:

• account - optional connected account (always together with sessid)

• sessid - optional connection session id (always together with account)

• location - in-game location of object

• home - safety location for object (handler)

• scripts - scripts assigned to object (handler from typeclass)

• cmdset - active cmdset on object (handler from typeclass)

• aliases - aliases for this object (property)

• nicks - nicknames for other things in Evennia (handler)

• sessions - sessions connected to this object (see also account)

• has_account - bool if an active account is currently connected

• contents - other objects having this object as location

• exits - exits from this object

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property account

A wrapper for getting database field db_account.

at_db_location_postsave(new)

This is called automatically after the location field was saved, no matter how. It checks for a variable _safe_contents_update to know if the save was triggered via the location handler (which updates the contents cache) or not.

Parameters:

new (bool) – Set if this location has not yet been saved before.

property cmdset_storage

getter

contents_cache

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_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_cmdset_storage

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

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_destination

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_destination_id

db_home

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_home_id

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_location

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_location_id

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_sessid

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 destination

A wrapper for getting database field db_destination.

destinations_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

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)

hide_from_objects_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 home

A wrapper for getting database field db_home.

homes_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

id

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

property location

Get location

locations_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

object_subscription_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.

objects = <evennia.objects.manager.ObjectDBManager object>

path = 'evennia.objects.models.ObjectDB'

receiver_object_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.

scriptdb_set

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

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

**Parent.children** is a **ReverseManyToOneDescriptor** instance.

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

sender_object_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 sessid

A wrapper for getting database field db_sessid.

typename = 'SharedMemoryModelBase'

class evennia.commands.default.building.Paginator(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)

Bases: object

ELLIPSIS = '…'

__init__(object_list, per_page, orphans=0, allow_empty_first_page=True, error_messages=None)

count

Return the total number of objects, across all pages.

default_error_messages = {'invalid_page': 'That page number is not an integer', 'min_page': 'That page number is less than 1', 'no_results': 'That page contains no results'}

get_elided_page_range(number=1, *, on_each_side=3, on_ends=2)

Return a 1-based range of pages with some values elided.

If the page range is larger than a given size, the whole range is not provided and a compact form is returned instead, e.g. for a paginator with 50 pages, if page 43 were the current page, the output, with the default arguments, would be:

1, 2, …, 40, 41, 42, 43, 44, 45, 46, …, 49, 50.

get_page(number)

Return a valid page, even if the page argument isn’t a number or isn’t in range.

num_pages

Return the total number of pages.

page(number)

Return a Page object for the given 1-based page number.

property page_range

Return a 1-based range of pages for iterating through within a template for loop.

validate_number(number)

Validate the given 1-based page number.

class evennia.commands.default.building.Q(*args, _connector=None, _negated=False, **kwargs)

Bases: Node

Encapsulate filters as objects that can then be combined logically (using & and |).

AND = 'AND'

OR = 'OR'

XOR = 'XOR'

__init__(*args, _connector=None, _negated=False, **kwargs)

Construct a new Node. If no connector is given, use the default.

check(against, using='default')

Do a database query to check if the expressions of the Q instance matches against the expressions.

conditional = True

deconstruct()

default = 'AND'

flatten()

Recursively yield this Q object and all subexpressions, in depth-first order.

identity

referenced_base_fields

Retrieve all base fields referenced directly or through F expressions excluding any fields referenced through joins.

replace_expressions(replacements)

resolve_expression(query=None, allow_joins=True, reuse=None, summarize=False, for_save=False)

class evennia.commands.default.building.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

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property account

A wrapper for getting database field db_account.

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_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_desc

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

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_is_active

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

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_obj_id

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_repeats

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_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.

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.

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

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'

class evennia.commands.default.building.ScriptEvMore(caller, inp, always_page=False, session=None, justify=False, justify_kwargs=None, exit_on_lastpage=False, exit_cmd=None, page_formatter=<class 'str'>, **kwargs)

Bases: EvMore

Listing 1000+ Scripts can be very slow and memory-consuming. So we use this custom EvMore child to build en EvTable only for each page of the list.

init_pages(scripts)

Prepare the script list pagination

page_formatter(scripts)

Takes a page of scripts and formats the output into an EvTable.

evennia.commands.default.building.ansi_raw(string)

Escapes a string into a form which won’t be colorized by the ansi parser.

Returns:

string (str) – The raw, escaped string.

evennia.commands.default.building.class_from_module(path, defaultpaths=None, fallback=None)

Return a class from a module, given the class’ full python path. This is primarily used to convert db_typeclass_path:s to classes.

Parameters:

• path (str) – Full Python dot-path to module.

• defaultpaths (iterable, optional) – If a direct import from path fails, try subsequent imports by prepending those paths to path.

• fallback (str) – If all other attempts fail, use this path as a fallback. This is intended as a last-resort. In the example of Evennia loading, this would be a path to a default parent class in the evennia repo itself.

Returns:

class (Class) – An uninstantiated class recovered from path.

Raises:

ImportError – If all loading failed.

evennia.commands.default.building.crop(text, width=None, suffix='[...]')

Crop text to a certain width, throwing away text from too-long lines.

Parameters:

• text (str) – Text to crop.

• width (int, optional) – Width of line to crop, in characters.

• suffix (str, optional) – This is appended to the end of cropped lines to show that the line actually continues. Cropping will be done so that the suffix will also fit within the given width. If width is too small to fit both crop and suffix, the suffix will be dropped.

Returns:

text (str) – The cropped text.

evennia.commands.default.building.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.commands.default.building.deserialize(obj)

Make sure to fully decouple a structure from the database, by turning all _Saver*-mutables inside it back into their normal Python forms.

evennia.commands.default.building.display_len(target)

Calculate the ‘visible width’ of text. This is not necessarily the same as the number of characters in the case of certain asian characters. This will also strip MXP patterns.

Parameters:

target (any) – Something to measure the length of. If a string, it will be measured keeping asian-character and MXP links in mind.

Returns:

int – The visible width of the target.

evennia.commands.default.building.format_grid(elements, width=78, sep='  ', verbatim_elements=None, line_prefix='')

This helper function makes a ‘grid’ output, where it distributes the given string-elements as evenly as possible to fill out the given width. will not work well if the variation of length is very big!

Parameters:

• elements (iterable) – A 1D list of string elements to put in the grid.

• width (int, optional) – The width of the grid area to fill.

• sep (str, optional) – The extra separator to put between words. If set to the empty string, words may run into each other.

• verbatim_elements (list, optional) – This is a list of indices pointing to specific items in the elements list. An element at this index will not be included in the calculation of the slot sizes. It will still be inserted into the grid at the correct position and may be surrounded by padding unless filling the entire line. This is useful for embedding decorations in the grid, such as horizontal bars.

• ignore_ansi (bool, optional) – Ignore ansi markups when calculating white spacing.

• line_prefix (str, optional) – A prefix to add at the beginning of each line. This can e.g. be used to preserve line color across line breaks.

Returns:

list – The grid as a list of ready-formatted rows. We return it like this to make it easier to insert decorations between rows, such as horizontal bars.

evennia.commands.default.building.generate_cmdset_providers(called_by, session=None)

evennia.commands.default.building.get_all_typeclasses(parent=None)

List available typeclasses from all available modules.

Parameters:

parent (str, optional) – If given, only return typeclasses inheriting (at any distance) from this parent.

Returns:

dict – On the form {“typeclass.path”: typeclass, …}

Notes

This will dynamically retrieve all abstract django models inheriting at any distance from the TypedObject base (aka a Typeclass) so it will work fine with any custom classes being added.

evennia.commands.default.building.get_and_merge_cmdsets(caller, cmdset_providers, callertype, raw_string, report_to=None, cmdid=None)

Gather all relevant cmdsets and merge them.

Parameters:

• caller (Session, Account or Object) – The entity executing the command. Which type of object this is depends on the current game state; for example when the user is not logged in, this will be a Session, when being OOC it will be an Account and when puppeting an object this will (often) be a Character Object. In the end it depends on where the cmdset is stored.

• cmdset_providers (list) – A list of sorted objects which provide cmdsets.

• callertype (str) – This identifies caller as either “account”, “object” or “session” to avoid having to do this check internally.

• raw_string (str) – The input string. This is only used for error reporting.

• report_to (Object, optional) – If given, this object will receive error messages

Returns:

cmdset (Deferred) – This deferred fires with the merged cmdset result once merger finishes.

Notes

The cdmsets are merged in order or generality, so that the Object’s cmdset is merged last (and will thus take precedence over same-named and same-prio commands on Account and Session).

evennia.commands.default.building.inherits_from(obj, parent)

Takes an object and tries to determine if it inherits at any distance from parent.

Parameters:

• obj (any) – Object to analyze. This may be either an instance or a class.

• parent (any) – Can be either an instance, a class or the python path to the class.

Returns:

inherits_from (bool) – If parent is a parent to obj or not.

Notes

What differentiates this function from Python’s isinstance() is the flexibility in the types allowed for the object and parent being compared.

evennia.commands.default.building.interactive(func)

Decorator to make a method pausable with yield(seconds) and able to ask for user-input with response=yield(question). For the question-asking to work, one of the args or kwargs to the decorated function must be named ‘caller’.

Raises:

• ValueError – If asking an interactive question but the decorated function has no arg or kwarg named ‘caller’.

• ValueError – If passing non int/float to yield using for pausing.

Examples

@interactive
def myfunc(caller):
    caller.msg("This is a test")
    # wait five seconds
    yield(5)
    # ask user (caller) a question
    response = yield("Do you want to continue waiting?")
    if response == "yes":
        yield(5)
    else:
        # ...

Notes

This turns the decorated function or method into a generator.

evennia.commands.default.building.list_to_string(iterable, sep=',', endsep=', and', addquote=False)

This pretty-formats an iterable list as string output, adding an optional alternative separator to the second to last entry. If addquote is True, the outgoing strings will be surrounded by quotes.

Parameters:

• iterable (any) – Usually an iterable to print. Each element must be possible to present with a string. Note that if this is a generator, it will be consumed by this operation.

• sep (str, optional) – The string to use as a separator for each item in the iterable.

• endsep (str, optional) – The last item separator will be replaced with this value.

• addquote (bool, optional) – This will surround all outgoing values with double quotes.

Returns:

str – The list represented as a string.

Notes

Default is to use ‘Oxford comma’, like 1, 2, 3, and 4.

Examples

>>> iter_to_string([1,2,3], endsep=',')
'1, 2, 3'
>>> iter_to_string([1,2,3], endsep='')
'1, 2 3'
>>> iter_to_string([1,2,3], ensdep='and')
'1, 2 and 3'
>>> iter_to_string([1,2,3], sep=';', endsep=';')
'1; 2; 3'
>>> iter_to_string([1,2,3], addquote=True)
'"1", "2", and "3"'

evennia.commands.default.building.variable_from_module(module, variable=None, default=None)

Retrieve a variable or list of variables from a module. The variable(s) must be defined globally in the module. If no variable is given (or a list entry is None), all global variables are extracted from the module.

Parameters:

• module (string or module) – Python path, absolute path or a module.

• variable (string or iterable, optional) – Single variable name or iterable of variable names to extract. If not given, all variables in the module will be returned.

• default (string, optional) – Default value to use if a variable fails to be extracted. Ignored if variable is not given.

Returns:

variables (value or list) – A single value or a list of values depending on if variable is given or not. Errors in lists are replaced by the default argument.