evennia.prototypes.protfuncs

Protfuncs are function-strings embedded in a prototype and allows for a builder to create a prototype with custom logics without having access to Python. The Protfunc is parsed using the inlinefunc parser but is fired at the moment the spawning happens, using the creating object’s session as input.

In the prototype dict, the protfunc is specified as a string inside the prototype, e.g.:

{ …

“key”: “$funcname(arg1, arg2, …)”

… }

and multiple functions can be nested (no keyword args are supported). The result will be used as the value for that prototype key for that individual spawn.

Available protfuncs are callables in one of the modules of settings.PROT_FUNC_MODULES. They are specified as functions

def funcname (*args, **kwargs)

where *args are the arguments given in the prototype, and **kwargs are inserted by Evennia:

• session (Session): The Session of the entity spawning using this prototype.

• prototype (dict): The dict this protfunc is a part of.

• current_key (str): The active key this value belongs to in the prototype.

• testing (bool): This is set if this function is called as part of the prototype validation; if

  set, the protfunc should take care not to perform any persistent actions, such as operate on objects or add things to the database.

Any traceback raised by this function will be handled at the time of spawning and abort the spawn before any object is created/updated. It must otherwise return the value to store for the specified prototype key (this value must be possible to serialize in an Attribute).

evennia.prototypes.protfuncs.base_random()

random() -> x in the interval [0, 1).

evennia.prototypes.protfuncs.random(*args, **kwargs)

Usage: $random() Returns a random value in the interval [0, 1)

evennia.prototypes.protfuncs.randint(*args, **kwargs)

Usage: $randint(start, end) Returns random integer in interval [start, end]

evennia.prototypes.protfuncs.left_justify(*args, **kwargs)

Usage: $left_justify(<text>) Returns <text> left-justified.

evennia.prototypes.protfuncs.right_justify(*args, **kwargs)

Usage: $right_justify(<text>) Returns <text> right-justified across screen width.

evennia.prototypes.protfuncs.center_justify(*args, **kwargs)

Usage: $center_justify(<text>) Returns <text> centered in screen width.

evennia.prototypes.protfuncs.choice(*args, **kwargs)

Usage: $choice(val, val, val, …) Returns one of the values randomly

evennia.prototypes.protfuncs.full_justify(*args, **kwargs)

Usage: $full_justify(<text>) Returns <text> filling up screen width by adding extra space.

evennia.prototypes.protfuncs.protkey(*args, **kwargs)

Usage: $protkey(<key>) Returns the value of another key in this prototoype. Will raise an error if

the key is not found in this prototype.

evennia.prototypes.protfuncs.add(*args, **kwargs)

Usage: $add(val1, val2) Returns the result of val1 + val2. Values must be

valid simple Python structures possible to add, such as numbers, lists etc.

evennia.prototypes.protfuncs.sub(*args, **kwargs)

Usage: $del(val1, val2) Returns the value of val1 - val2. Values must be

valid simple Python structures possible to subtract.

evennia.prototypes.protfuncs.mult(*args, **kwargs)

Usage: $mul(val1, val2) Returns the value of val1 * val2. The values must be

valid simple Python structures possible to multiply, like strings and/or numbers.

evennia.prototypes.protfuncs.div(*args, **kwargs)

Usage: $div(val1, val2) Returns the value of val1 / val2. Values must be numbers and

the result is always a float.

evennia.prototypes.protfuncs.toint(*args, **kwargs)

Usage: $toint(<number>) Returns <number> as an integer.

evennia.prototypes.protfuncs.eval(*args, **kwargs)

Usage $eval(<expression>) Returns evaluation of a simple Python expression. The string may only consist of the following

Python literal structures: strings, numbers, tuples, lists, dicts, booleans, and None. The strings can also contain #dbrefs. Escape embedded protfuncs as $$protfunc(..) - those will then be evaluated after $eval.

evennia.prototypes.protfuncs.obj(*args, **kwargs)

Usage $obj(<query>) Returns one Object searched globally by key, alias or #dbref. Error if more than one.

evennia.prototypes.protfuncs.objlist(*args, **kwargs)

Usage $objlist(<query>) Returns list with one or more Objects searched globally by key, alias or #dbref.

evennia.prototypes.protfuncs.dbref(*args, **kwargs)

Usage $dbref(<#dbref>) Validate that a #dbref input is valid.