Added more overloading modules and cleaned up the template some more.

evennia/__init__.py

@@ -153,6 +153,7 @@ class DefaultCmds(_EvContainer):
     from commands.default.cmdset_character import CharacterCmdSet
     from commands.default.cmdset_player import PlayerCmdSet
     from commands.default.cmdset_unloggedin import UnloggedinCmdSet
+    from commands.default.cmdset_session import SessionCmdSet
     from commands.default.muxcommand import MuxCommand, MuxPlayerCommand
 
     def __init__(self):

evennia/commands/cmdparser.py

@@ -1,6 +1,6 @@
 """
 The default command parser. Use your own by assigning
-settings.ALTERNATE_PARSER to a Python path to a module containing the
+settings.COMMAND_PARSER to a Python path to a module containing the
 replacing cmdparser function. The replacement parser must matches
 on the sme form as the default cmdparser.
 """

evennia/settings_default.py

@@ -202,14 +202,14 @@ DATABASES = {
 
 # The command parser module to use. See the default module for which
 # functions it must implement
-COMMAND_PARSER = "commands.cmdparser"
+COMMAND_PARSER = "evennia.commands.cmdparser.cmdparser"
 # The handler that outputs errors when searching
 # objects using object.search().
-SEARCH_AT_RESULT = "commands.at_search_result"
+SEARCH_AT_RESULT = "evennia.commands.cmdparser.at_search_result"
 # The parser used in order to separate multiple
 # object matches (so you can separate between same-named
 # objects without using dbrefs).
-SEARCH_AT_MULTIMATCH_INPUT = "commands.at_multimatch_input"
+SEARCH_AT_MULTIMATCH_INPUT = "evennia.commands.cmdparser.at_multimatch_input"
 # The module holding text strings for the connection screen.
 # This module should contain one or more variables
 # with strings defining the look of the screen.
@@ -235,7 +235,7 @@ SERVER_SERVICES_PLUGIN_MODULES = ["server.conf.server_services_plugins"]
 PORTAL_SERVICES_PLUGIN_MODULES = ["server.conf.portal_services_plugins"]
 # Module holding MSSP meta data. This is used by MUD-crawlers to determine
 # what type of game you are running, how many players you have etc.
-MSSP_META_MODULE = ""
+MSSP_META_MODULE = "server.conf.mssp"
 # Tuple of modules implementing lock functions. All callable functions
 # inside these modules will be available as lock functions.
 LOCK_FUNC_MODULES = ("evennia.locks.lockfuncs", "server.conf.lockfuncs",)
@@ -350,7 +350,7 @@ INLINEFUNC_ENABLED = False
 # Only functions defined globally (and not starting with '_') in
 # these modules will be considered valid inlinefuncs. The list
 # is loaded from left-to-right, same-named functions will overload
-INLINEFUNC_MODULES = ["server.conf.inlinefunc"]
+INLINEFUNC_MODULES = ["evennia.utils.inlinefunc", "server.conf.inlinefunc"]
 
 ######################################################################
 # Default Player setup and access

game_template/commands/command.py

@@ -1,16 +1,12 @@
 """
-Example command module template
+Commands
 
-Copy this module up one level to gamesrc/commands/ and name it as
+Commands describe the input the player can do to the game.
-befits your use.  You can then use it as a template to define your new
-commands. To use them you also need to group them in a CommandSet (see
-examples/cmdset.py)
 
 """
 
 from evennia import Command as BaseCommand
 from evennia import default_cmds
-from evennia import utils
 
 
 class Command(BaseCommand):
@@ -31,13 +27,14 @@ class Command(BaseCommand):
     locks = "cmd:all()"
     help_category = "General"
 
+    # optional
     # auto_help = False      # uncomment to deactive auto-help for this command.
     # arg_regex = r"\s.*?|$" # optional regex detailing how the part after
                              # the cmdname must look to match this command.
 
     # (we don't implement hook method access() here, you don't need to
     #  modify that unless you want to change how the lock system works
-    #  (in that case see src.commands.command.Command))
+    #  (in that case see evennia.commands.command.Command))
 
     def at_pre_cmd(self):
         """

game_template/server/conf/at_initial_setup.py

@@ -1,12 +1,6 @@
 """
 At_initial_setup module template
 
-Copy this module up one level to /gamesrc/conf, name it what you like
-and then use it as a template to modify.
-
-Then edit settings.AT_INITIAL_SETUP_HOOK_MODULE to point to your new
-module.
-
 Custom at_initial_setup method. This allows you to hook special
 modifications to the initial server startup process. Note that this
 will only be run once - when the server starts up for the very first

game_template/server/conf/at_search.py

@@ -0,0 +1,90 @@
+"""
+Search and multimatch handling
+
+This module allows for overloading two functions used by Evennia's
+search functionality:
+
+    at_search_result:
+        This is called whenever a result is returned from an object
+        search (a common operation in commands).  It should (together
+        with at_multimatch_input below) define some way to present and
+        differentiate between multiple matches (by default these are
+        presented as 1-ball, 2-ball etc)
+    at_multimatch_input:
+        This is called with a search term and should be able to
+        identify if the user wants to separate a multimatch-result
+        (such as that from a previous search). By default, this
+        function understands input on the form 1-ball, 2-ball etc as
+        indicating that the 1st or 2nd match for "ball" should be
+        used.
+
+This module is not called by default. To overload the defaults, add
+one or both of the following lines to your settings.py file:
+
+    SEARCH_AT_RESULT = "server.conf.at_search.at_search_result"
+    SEARCH_AT_MULTIMATCH_INPUT = "server.conf.at_search.at_multimatch_input"
+
+"""
+
+def at_search_result(msg_obj, ostring, results, global_search=False,
+                     nofound_string=None, multimatch_string=None, quiet=False):
+    """
+    Called by search methods after a result of any type has been found.
+
+    Takes a search result (a list) and
+    formats eventual errors.
+
+    msg_obj - object to receive feedback.
+    ostring - original search string
+    results - list of found matches (0, 1 or more)
+    global_search - if this was a global_search or not
+            (if it is, there might be an idea of supplying
+            dbrefs instead of only numbers)
+    nofound_string - optional custom string for not-found error message.
+    multimatch_string - optional custom string for multimatch error header
+    quiet - work normally, but don't echo to caller, just return the
+            results.
+
+    Multiple matches are returned to the searching object
+    as a list of results ["1-object", "2-object","3-object",...]
+    A single match is returned on its own.
+    """
+    pass
+
+
+def at_multimatch_input(ostring):
+    """
+    This parser will be called by the engine when a user supplies
+    a search term. The search term must be analyzed to determine
+    if the user wants to differentiate between multiple matches
+    (usually found during a previous search).
+
+    This method should separate out any identifiers from the search
+    string used to differentiate between same-named objects. The
+    result should be a tuple (index, search_string) where the index
+    gives which match among multiple matches should be used (1 being
+    the lowest number, rather than 0 as in Python).
+
+    The default parser will intercept input on the following form:
+
+      2-object
+
+    This will be parsed to (2, "object") and, if applicable, will tell
+    the engine to pick the second from a list of same-named matches of
+    objects called "object".
+
+    Ex for use in a game session:
+
+     > look
+    You see: ball, ball, ball and ball.
+     > get ball
+    There where multiple matches for ball:
+        1-ball
+        2-ball
+        3-ball
+        4-ball
+     > get 3-ball
+     You get the ball.
+
+    """
+    pass

game_template/server/conf/at_server_startstop.py

@@ -1,21 +1,11 @@
 """
+Server startstop hooks
 
-At_server_startstop module template
+This module contains functions called by Evennia at various
+points during its startup, reload and shutdown sequence. It
+allows for customizing the server operation as desired.
 
-Copy this module one level up, to gamesrc/conf/, name it what you
+This module must contain at least these global functions:
-will and use it as a template for your modifications.
-
-Then edit settings.AT_SERVER_STARTSTOP_MODULE to point to your new
-module.
-
-This module contains functions that are imported and called by the
-server whenever it changes its running status. At the point these
-functions are run, all applicable hooks on individual objects have
-already been executed. The main purpose of this is module is to have a
-safe place to initialize eventual custom modules that your game needs
-to start up or load.
-
-The module should define at least these global functions:
 
 at_server_start()
 at_server_stop()
@@ -37,8 +27,8 @@ def at_server_start():
 
 def at_server_stop():
     """
-    This is called just before a server is shut down, regardless
+    This is called just before the server is shut down, regardless
-    of it is fore a reload, reset or shutdown.
+    of it is for a reload, reset or shutdown.
     """
     pass
 
@@ -67,6 +57,7 @@ def at_server_cold_start():
 
 def at_server_cold_stop():
     """
-    This is called only when the server goes down due to a shutdown or reset.
+    This is called only when the server goes down due to a shutdown or
+    reset.
     """
     pass

game_template/server/conf/cmdparser.py

@@ -0,0 +1,54 @@
+"""
+Changing the default command parser
+
+The cmdparser is responsible for parsing the raw text inserted by the
+user, identifying which command/commands match and return one or more
+matching command objects. It is called by Evennia's cmdhandler and
+must accept input and return results on the same form. The default
+handler is very generic so you usually don't need to overload this
+unless you have very exotic parsing needs; advanced parsing is best
+done at the Command.parse level.
+
+The default cmdparser understands the following command combinations
+(where [] marks optional parts.)
+
+[cmdname[ cmdname2 cmdname3 ...] [the rest]
+
+A command may consist of any number of space-separated words of any
+length, and contain any character. It may also be empty.
+
+The parser makes use of the cmdset to find command candidates. The
+parser return a list of matches. Each match is a tuple with its first
+three elements being the parsed cmdname (lower case), the remaining
+arguments, and the matched cmdobject from the cmdset.
+
+
+This module is not accessed by default. To tell Evennia to use it
+instead of the default command parser, add the following line to
+your settings file:
+
+    COMMAND_PARSER = "server.conf.cmdparser.cmdparser"
+
+"""
+
+def cmdparser(raw_string, cmdset, caller, match_index=None):
+    """
+    This function is called by the cmdhandler once it has
+    gathered and merged all valid cmdsets valid for this particular parsing.
+
+    raw_string - the unparsed text entered by the caller.
+    cmdset - the merged, currently valid cmdset
+    caller - the caller triggering this parsing
+    match_index - an optional integer index to pick a given match in a
+                  list of same-named command matches.
+
+    Returns:
+     list of tuples: [(cmdname, args, cmdobj, cmdlen, mratio), ...]
+            where cmdname is the matching command name and args is
+            everything not included in the cmdname. Cmdobj is the actual
+            command instance taken from the cmdset, cmdlen is the length
+            of the command name and the mratio is some quality value to
+            (possibly) separate multiple matches.
+
+    """
+    # Your implementation here

game_template/server/conf/connection_screens.py

@@ -1,58 +1,33 @@
 # -*- coding: utf-8 -*-
 """
-Connect screen module template
+Connection screen
 
-Copy this module one level up, to gamesrc/conf/, name it what
+Texts in this module will be shown to the user at login-time.
-you want and modify it to your liking.
 
-Then you set settings.CONNECTION_SCREEN_MODULE to point to your
+Evennia will look at global string variables (variables defined
-new module.
+at the "outermost" scope of this module and use it as the
+connection screen. If there are more than one, Evennia will
+randomize which one it displays.
 
-
+The commands available to the user when the connection screen is shown
- This module holds textual connection screen definitions. All global
+are defined in commands.default_cmdsets.UnloggedinCmdSet and the
- string variables (only) in this module are read by Evennia and
+screen is read and displayed by the unlogged-in "look" command.
- assumed to define a Connection screen.
-
- The names of the string variables doesn't matter (but names starting
- with an underscore will be ignored), but each should hold a string
- defining a connection screen - as seen when first connecting to the
- game (before having logged in).
-
- OBS - If there are more than one global string variable in this
- module, a random one is picked!
-
- After adding new connection screens to this module you must either
- reboot or reload the server to make them available.
 
 """
 
-# comment this out if wanting to completely remove the default screen
+from django.conf import settings
-from src.commands.connection_screen import DEFAULT_SCREEN
+from evennia import utils
 
-## uncomment these for showing the name and version
+CONNECTION_SCREEN = \
-# from django.conf import settings
+"""{b=============================================================={n
-# from src.utils import utils
+ Welcome to {g%s{n, version %s!
 
-## A copy of the default screen to modify
+ If you have an existing account, connect to it by typing:
+      {wconnect <username> <password>{n
+ If you need to create an account, type (without the <>'s):
+      {wcreate <username> <password>{n
 
-# CUSTOM_SCREEN = \
+ If you have spaces in your username, enclose it in quotes.
-#"""{b=============================================================={n
+ Enter {whelp{n for more info. {wlook{n will re-show this screen.
-# Welcome to {g%s{n, version %s!
+{b=============================================================={n""" \
-#
+ % (settings.SERVERNAME, utils.get_evennia_version())
-# If you have an existing account, connect to it by typing:
-#      {wconnect <username> <password>{n
-# If you need to create an account, type (without the <>'s):
-#      {wcreate <username> <password>{n
-#
-# If you have spaces in your username, enclose it in quotes.
-# Enter {whelp{n for more info. {wlook{n will re-show this screen.
-#{b=============================================================={n""" \
-# % (settings.SERVERNAME, utils.get_evennia_version())
-
-## Minimal header for use with contrib/menu_login.py
-
-# MENU_SCREEN = \
-# """{b=============================================================={n
-#  Welcome to {g%s{n, version %s!
-# {b=============================================================={n""" \
-# % (settings.SERVERNAME, utils.get_evennia_version())

game_template/server/conf/lockfuncs.py

@@ -1,33 +1,30 @@
 """
 
-Lockfuncs module template
+Lockfuncs
 
-Copy this module one level up, to gamesrc/conf/, name it what
+Lock functions are functions available when defining lock strings,
-you will and edit it to your liking.
+which in turn limits access to various game systems.
-
-Then add the new module's path to the end of the tuple
-defined in settings.LOCK_FUNC_MODULES.
 
 All functions defined globally in this module are assumed to be
-available for use in lockstrings to determine access. See
+available for use in lockstrings to determine access. See the
-http://code.google.com/p/evennia/wiki/Locks
+Evennia documentation for more info on locks.
 
 A lock function is always called with two arguments, accessing_obj and
 accessed_obj, followed by any number of arguments. All possible
-arguments should be handled (excess ones calling magic (*args,
+arguments should be handled with *args, **kwargs. The lock function
-**kwargs) to avoid errors). The lock function should handle all
+should handle all eventual tracebacks by logging the error and
-eventual tracebacks by logging the error and returning False.
+returning False.
 
-See many more examples of lock functions in src.locks.lockfuncs.
+Lock functions in this module extend (and will overload same-named)
+lock functions from evennia.locks.lockfuncs.
 
 """
 
-
+#def myfalse(accessing_obj, accessed_obj, *args, **kwargs):
-def myfalse(accessing_obj, accessed_obj, *args, **kwargs):
+#    """
-    """
+#    called in lockstring with myfalse().
-    called in lockstring with myfalse().
+#    A simple logger that always returns false. Prints to stdout
-    A simple logger that always returns false. Prints to stdout
+#    for simplicity, should use utils.logger for real operation.
-    for simplicity, should use utils.logger for real operation.
+#    """
-    """
+#    print "%s tried to access %s. Access denied." % (accessing_obj, accessed_obj)
-    print "%s tried to access %s. Access denied." % (accessing_obj, accessed_obj)
+#    return False
-    return False

game_template/server/conf/mssp.py

@@ -1,22 +1,16 @@
 """
 
-MSSP module template
+MSSP (Mud Server Status Protocol) meta information
 
-Copy this module one level up, to gamesrc/conf/, name it
+MUD website listings (that you have registered with) can use this
-what you want and edit it to your satisfaction.
+information to keep up-to-date with your game stats as you change
+them. Also number of currently active players and uptime will
+automatically be reported. You don't have to fill in everything
+(and most are not used by all crawlers); leave the default
+if so needed. You need to @reload the game before updated
+information is made available to crawlers (reloading does not
+affect uptime).
 
-Then change settings.MSSP_META_MODULE to point to your new module.
-
- MSSP (Mud Server Status Protocol) meta information
-
- MUD website listings (that you have registered with) can use this
- information to keep up-to-date with your game stats as you change
- them. Also number of currently active players and uptime will
- automatically be reported. You don't have to fill in everything
- (and most are not used by all crawlers); leave the default
- if so needed. You need to @reload the game before updated
- information is made available to crawlers (reloading does not
- affect uptime).
 """
 
 MSSPTable =  {

game_template/server/conf/portal_services_plugin.py

@@ -1,24 +1,23 @@
 """
+Start plugin services
 
-This plugin module can define user-created services for the Server to start.
+This plugin module can define user-created services for the Portal to
+start.
 
-To use, copy this module up one level to game/gamesrc/conf/ and set
+This module must handle all imports and setups required to start
-settings.SERVER_SERVICES_PLUGIN_MODULE to point to this module.
+twisted services (see examples in src/server/server.py). It must also
-
+contain a function start_plugin_services(application). Evennia will
-This module must handle all imports and setups required to start a twisted
+call this function with the main Portal application (so your services
-services (see examples in src/server/server.py). It must also contain a
+can be added to it). The function should not return anything. Plugin
-function start_plugin_services(application). Evennia will call this function
+services are started last in the Portal startup process.
-with the main Server application (so your services can be added to it). The
-function should not return anything. Plugin services are started last in
-the Server startup process.
 
 """
 
 
-def start_plugin_services(server):
+def start_plugin_services(portal):
     """
-    This hook is called by Evennia, last in the Server startup process.
+    This hook is called by Evennia, last in the Portal startup process.
 
-    server - a reference to the main server application.
+    portal - a reference to the main portal application.
     """
     pass

game_template/server/conf/server_services_plugin.py

@@ -1,24 +1,23 @@
 """
 
-This plugin module can define user-created services for the Portal to start.
+Server plugin services
 
-To use, copy this module up one level to game/gamesrc/conf/ and set
+This plugin module can define user-created services for the Server to start.
-settings.PORTAL_SERVICES_PLUGIN_MODULE to point to this module.
 
 This module must handle all imports and setups required to start a twisted
 service (see examples in src/server/server.py). It must also contain a
 function start_plugin_services(application). Evennia will call this function
-with the main Portal application (so your services can be added to it). The
+with the main Server application (so your services can be added to it). The
 function should not return anything. Plugin services are started last in
-the Portal startup process.
+the Server startup process.
 
 """
 
 
-def start_plugin_services(portal):
+def start_plugin_services(server):
     """
-    This hook is called by Evennia, last in the Portal startup process.
+    This hook is called by Evennia, last in the Server startup process.
 
-    portal - a reference to the main portal application.
+    server - a reference to the main server application.
     """
     pass

game_template/types/character.py

@@ -1,31 +1,20 @@
 """
+Characters
 
-Template for Characters
+Characters are (by default) Objects setup to be puppeted by Players.
-
+They are what you "see" in game. The Character class in this module
-Copy this module up one level and name it as you like, then
+is setup to be the "default" character type created by the default
-use it as a template to create your own Character class.
+creation commands.
-
-To make new logins default to creating characters
-of your new type, change settings.BASE_CHARACTER_TYPECLASS to point to
-your new class, e.g.
-
-settings.BASE_CHARACTER_TYPECLASS = "game.gamesrc.objects.mychar.MyChar"
-
-Note that objects already created in the database will not notice
-this change, you have to convert them manually e.g. with the
-@typeclass command.
 
 """
 from evennia import DefaultCharacter
 
-
 class Character(DefaultCharacter):
     """
-    The Character is like any normal Object (see example/object.py for
+    The Character defaults to implementing some of its hook methods with the
-    a list of properties and methods), except it actually implements
+    following standard functionality:
-    some of its hook methods to do some work:
 
-    at_basetype_setup - always assigns the default_cmdset to this object type
+    at_basetype_setup - always assigns the DefaultCmdSet to this object type
                     (important!)sets locks so character cannot be picked up
                     and its commands only be called by itself, not anyone else.
                     (to change things, use at_object_creation() instead)

game_template/types/exit.py

@@ -1,24 +1,13 @@
 """
+Exits
 
-Template module for Exits
+Exits are connectors between Rooms. An exit always has a destination property
-
+set and has a single command defined on itself with the same name as its key,
-Copy this module up one level and name it as you like, then
+for allowing Characters to traverse the exit to its destination.
-use it as a template to create your own Exits.
-
-To make the default commands (such as @dig/@open) default to creating exits
-of your new type, change settings.BASE_EXIT_TYPECLASS to point to
-your new class, e.g.
-
-settings.BASE_EXIT_TYPECLASS = "game.gamesrc.objects.myexit.MyExit"
-
-Note that objects already created in the database will not notice
-this change, you have to convert them manually e.g. with the
-@typeclass command.
 
 """
 from evennia import DefaultExit
 
-
 class Exit(DefaultExit):
     """
     Exits are connectors between rooms. Exits are normal Objects except

game_template/types/object.py

@@ -1,25 +1,17 @@
 """
+Object
 
-Template for Objects
+The Object is the "naked" base class for things in the game world.
 
-Copy this module up one level and name it as you like, then
+Note that the default Character, Room and Exit does not inherit from
-use it as a template to create your own Objects.
+this Object, but from their respective default implementations in the
-
+evennia library. If you want to use this class as a parent to change
-To make the default commands default to creating objects of your new
+the other types, you can do so by adding this as a multiple
-type (and also change the "fallback" object used when typeclass
+inheritance.
-creation fails), change settings.BASE_OBJECT_TYPECLASS to point to
-your new class, e.g.
-
-settings.BASE_OBJECT_TYPECLASS = "game.gamesrc.objects.myobj.MyObj"
-
-Note that objects already created in the database will not notice
-this change, you have to convert them manually e.g. with the
-@typeclass command.
 
 """
 from evennia import DefaultObject
 
-
 class Object(DefaultObject):
     """
     This is the root typeclass object, implementing an in-game Evennia

game_template/types/player.py

@@ -1,21 +1,13 @@
+"""
+Player
+
+The Player represents the game "account" and each login has only one
+Player object. A Player is what chats on default channels but has no
+other in-game-world existance. Rather the Player puppets Objects (such
+as Characters) in order to actually participate in the game world.
+
 """
 
-Template module for Players
-
-Copy this module up one level and name it as you like, then
-use it as a template to create your own Player class.
-
-To make the default account login default to using a Player
-of your new type, change settings.BASE_PLAYER_TYPECLASS to point to
-your new class, e.g.
-
-settings.BASE_PLAYER_TYPECLASS = "game.gamesrc.objects.myplayer.MyPlayer"
-
-Note that objects already created in the database will not notice
-this change, you have to convert them manually e.g. with the
-@typeclass command.
-
-"""
 from evennia import DefaultPlayer
 
 

game_template/types/room.py

@@ -1,19 +1,7 @@
 """
+Room
 
-Template module for Rooms
+Rooms are simple containers that has no location of their own.
-
-Copy this module up one level and name it as you like, then
-use it as a template to create your own Objects.
-
-To make the default commands (such as @dig) default to creating rooms
-of your new type, change settings.BASE_ROOM_TYPECLASS to point to
-your new class, e.g.
-
-settings.BASE_ROOM_TYPECLASS = "game.gamesrc.objects.myroom.MyRoom"
-
-Note that objects already created in the database will not notice
-this change, you have to convert them manually e.g. with the
-@typeclass command.
 
 """
 

game_template/types/script.py

@@ -1,22 +1,14 @@
 """
+Scripts
 
-Template module for Scripts
+Scripts are powerful jacks-of-all-trades. They have no in-game
+existence and can be used to represent persistent game systems in some
+circumstances. Scripts can also have a time component that allows them
+to "fire" regularly or a limited number of times.
 
-Copy this module up one level to gamesrc/scripts and name it
+There is generally no "tree" of Scripts inheriting from each other.
-appropriately, then use that as a template to create your own script.
+Rather, each script tends to inherit from the base Script class and
-
+just overloads its hooks to have it perform its function.
-Test scripts in-game e.g. with the @script command. In code you can
-create new scripts of a given class with
-  script = ev.create.script("path.to.module.and.class")
-
-Scripts are objects that handle everything in the game having
-a time-component (i.e. that may change with time, with or without
-a player being involved in the change). Scripts can work like "events",
-in that they are triggered at regular intervals to do a certain script,
-but an Script set on an object can also be responsible for silently
-checking if its state changes, so as to update it. Evennia use several
-in-built scripts to keep track of things like time, to clean out
-dropped connections etc.
 
 """