Updated ReST documentation.

docs/sphinx/source/wiki/AddingCommandTutorial.rst

@@ -15,9 +15,9 @@ new additional commands of your own.
 
 #. Go to ``game/gamesrc/commands``.
 #. There is a subfolder here named ``examples``. *Copy* the files
-   ``examples/command.py`` and ``examples/cmdset.py`` to where you are.
+   ``examples/command.py`` and ``examples/cmdset.py`` to your current
-   You can rename them as you please, but in this example we assume you
+   directory (game/gamesrc/commands). You can rename them as you please,
-   don't.
+   but in this example we assume you don't.
 #. Edit ``game/settings.py``, adding the following line:
 
     ``CMDSET_DEFAULT="game.gamesrc.commands.cmdset.DefaultCmdSet"``
@@ -45,7 +45,7 @@ Creating a custom command
 
     # file game/gamesrc/commands/command.py
     #[...]
-    class CmdEcho(MuxCommand):
+    class CmdEcho(default_cmds.MuxCommand):
         """
         Simple command example
 
@@ -75,8 +75,8 @@ command set we already prepared.
 #. Edit your recently copied ``game/gamesrc/commands/cmdset.py``
 #. In this copied module you will find the ``DefaultCmdSet`` class
    already imported and prepared for you. Import your new command module
-   here with ``from game.gamesrc.commands import echo``.
+   here with ``from game.gamesrc.commands.command import CmdEcho``.
-#. Add a line ``self.add(echo.CmdEcho())`` to ``DefaultCmdSet``, in the
+#. Add a line ``self.add(CmdEcho())`` to ``DefaultCmdSet``, in the
    ``at_cmdset_creation`` method (the template tells you where). This is
    approximately how it should look at this point:
 
@@ -84,7 +84,7 @@ command set we already prepared.
 
     # file gamesrc/commands/examples/cmdset.py
     #[...]
-    from game.gamesrc.commands import echo
+    from game.gamesrc.commands.command import CmdEcho
     #[...]
     class DefaultCmdSet(default_cmds.DefaultCmdSet):
         
@@ -97,7 +97,7 @@ command set we already prepared.
 
             # all commands added after this point will extend or 
             # overwrite the default commands.       
-            self.add(echo.CmdEcho())
+            self.add(CmdEcho())
 
 #. Reboot/restart Evennia (``@reload`` from inside the game). You should
    now be able to use your new ``echo`` command from inside the game.
@@ -107,8 +107,11 @@ If you have trouble, make sure to check the log for error messages
 (probably due to syntax errors in your command definition).
 
 Adding new commands to the default cmdset in the future now only
-involves creating the function class and adding it to the same place. If
+involves creating the function class and adding it to the cmdset in the
-you want to overload existing default commands (such as ``look`` or
+same place. If you want to overload existing default commands (such as
-``get``), just add your new command with the same key as the old one -
+``look`` or ``get``), just add your new command with the same key as the
-it will overload the default one. Just remember that you must
+old one - it will overload the default one. Just remember that you must
 ``@reload`` the server before you see any changes.
+
+See `Commands <Commands.html>`_ for many more details and possibilities
+when defining Commands and using Cmdsets in various ways.

docs/sphinx/source/wiki/AsyncProcess.rst

@@ -1,8 +1,7 @@
 Asynchronous code
 =================
 
-*This is considered an advanced topic, probably not useful for most
+*This is considered an advanced topic.*
-users.*
 
 Synchronous versus Asynchronous
 -------------------------------
@@ -68,9 +67,7 @@ call to try to deal with the result from ``long_running_function`` above
 for processing any data from the function. Instead one has to use
 *callbacks*.
 
-``utils.run_async`` takes two optional arguments, ``at_return`` and
+``utils.run_async`` takes reserved arguments.
-``at_err``. Both of these should be function defitions. Each will be
-called automatically.
 
 -  ``at_return(r)`` (the *callback*) is called when the asynchronous
    function (``long_running_function`` above) finishes successfully. The
@@ -82,6 +79,8 @@ called automatically.
          def at_return(r):
              print r    
 
+-  ``at_return_kwargs`` - an optional dictionary that will be fed as
+   keyword arguments to the ``at_return`` callback.
 -  ``at_err(e)`` (the *errback*) is called if the asynchronous function
    fails and raises an exception. This exception is passed to the
    errback wrapped in a *Failure* object ``e``. If you do not supply an
@@ -94,6 +93,9 @@ called automatically.
         def at_err(e):   
             print "There was an error:", str(e)    
 
+-  ``at_err_kwargs`` - an optional dictionary that will be fed as
+   keyword arguments to the ``at_err`` errback.
+
 An example of making an asynchronous call from inside a
 `Command <Commands.html>`_ definition:
 
@@ -126,6 +128,83 @@ and go on with what else need to be done. *Whenever* it finishes, the
 ``at_return`` function will be called and the final value will pop up
 for us to see. If not we will see an error message.
 
+Process Pool
+------------
+
+The ``ProcPool`` is an Evennia subsystem that launches a pool of
+processes based on the `ampoule <https://launchpad.net/ampoule>`_
+package (included with Evennia). When active, ``run_async`` will use
+this pool to offload its commands. ``ProcPool`` is deactivated by
+default, it can be turned on with ``settings.PROCPOOL_ENABLED``. *It
+should be noted that the default SQLite3 database is not suitable for
+for multiprocess operation. So if you use ``ProcPool`` you should
+consider switching to another database such as MySQL or PostgreSQL.*
+
+The Process Pool makes several additional options available to
+``run_async``.
+
+The following keyword arguments make sense when ``ProcPool`` is active:
+
+-  ``use_thread`` - this force-reverts back to thread operation (as
+   above). It effectively deactivates all additional features
+   ``ProcPool`` offers.
+-  ``proc_timeout`` - this enforces a timeout for the running process in
+   seconds; after this time the process will be killed.
+-  ``at_return``, ``at_err`` - these work the same as above.
+
+In addition to feeding a single callable to ``run_async``, the first
+argument may also be a source string. This is a piece of python source
+code that will be executed in a subprocess via ``ProcPool``. Any extra
+keyword arguments to ``run_async`` that are not one of the reserved ones
+will be used to specify what will be available in the execution
+environment.
+
+There is one special variable used in the remove execution: ``_return``.
+This is a function, and all data fed to ``_return`` will be returned
+from the execution environment and appear as input to your ``at_return``
+callback (if it is defined). You can call ``_return`` multiple times in
+your code - the return value will then be a list.
+
+Example:
+
+::
+
+    from src.utils.utils import run_async
+
+    source = """
+    from time import sleep
+    sleep(5) # sleep five secs
+    val = testvar + 5
+    _return(val)
+    _return(val + 5)
+    """
+
+    # we assume myobj is a character retrieved earlier
+    # these callbacks will just print results/errors
+    def callback(ret):
+        myobj.msg(ret)
+    def errback(err):
+        myobj.msg(err)
+    testvar = 3
+
+    # run async
+    run_async(source, at_return=callback, at_err=errback, testvar=testvar)
+
+    # this will return '[8, 13]'
+
+You can also test the async mechanism from in-game using the ``@py``
+command:
+
+::
+
+     @py from src.utils.utils import run_async;run_async("_return(1+2)",at_return=self.msg)
+
+Note: The code execution runs without any security checks, so it should
+not be available to unprivileged users. Try
+``contrib.evlang.evlang.limited_exec`` for running a more restricted
+version of Python for untrusted users. This will use ``run_async`` under
+the hood.
+
 Assorted notes
 --------------
 

docs/sphinx/source/wiki/Attributes.rst

@@ -78,6 +78,10 @@ behaviour.
 Fast assignment
 ---------------
 
+*Depracation Warning: Fast assigment is deprecated and should not be
+used - it will be removed in the future. Use the ``db`` operator
+explicitly when saving to the database.*
+
 For quick testing you can in principle skip the ``db`` operator and
 assign Attributes like you would any normal Python property:
 

docs/sphinx/source/wiki/BuildingQuickstart.rst

@@ -215,9 +215,9 @@ button is meant to be pushed. You know you want to.
 Creating a room called 'house'
 ------------------------------
 
-The main command for shaping the game world is ``@dig``. If you for
+The main command for shaping the game world is ``@dig``. For example, if
-example are standing in Limbo, you can in one go dig a route 'north' to
+you are standing in Limbo you can dig a route to your new house location
-your new house location like this:
+like this:
 
 ::
 

docs/sphinx/source/wiki/Commands.rst

@@ -335,18 +335,19 @@ server, or you run
 
     @py self.cmdset.delete('game.gamesrc.commands.mycmdset.MyCmdSet')
 
-For more permanent addition, read the
+For a quick tutorial on setting up things more permanently read the
-[Commands#Adding\_a\_new\_command\_-*a\_step\_by\_step\_guide
+`Step by step
-step-by-step guide] below. Generally you can customize which command
+tutorial <http://code.google.com/p/evennia/wiki/AddingCommandTutorial>`_
-sets are added to your objects by using ``self.cmdset.add()`` or
+for a different way of approaching it. Generally you can customize which
-``self.cmdset.add_default()``.*
+command sets are added to your objects by using ``self.cmdset.add()`` or
+``self.cmdset.add_default()``.
 
 Adding and merging command sets
 -------------------------------
 
-\_Note: This is an advanced topic. It's useful to know about, but you
+*Note: This is an advanced topic. It's useful to know about, but you
 might want to skip it if this is your first time learning about
-commands.
+commands.*
 
 CmdSets have the special ability that they can be *merged* together into
 new sets. This would happen if you, for example, did

docs/sphinx/source/wiki/ConnectionScreen.rst

@@ -7,14 +7,16 @@ tells you how to connect.
 
 ::
 
+
     ==============================================================
-     Welcome to Evennia, version HG-Beta!
+     Welcome to Evennia, version Beta-ra4d24e8a3cab+!
 
      If you have an existing account, connect to it by typing:
-          connect <email> <password>
+          connect <username> <password>
      If you need to create an account, type (without the <>'s):
-          create "<username>" <email> <password>
+          create <username> <password>
 
+     If you have spaces in your username, enclose it in quotes.
      Enter help for more info. look will re-show this screen.
     ==============================================================
 

docs/sphinx/source/wiki/Contributing.rst

@@ -8,10 +8,14 @@ Contributing with Documentation
 
 Evennia depends heavily on good documentation and we are always looking
 for extra eyes and hands to improve it. Even small things such as fixing
-typos is a great help. To edit the wiki yourself you need contributor
+typos are a great help!
-access. Otherwise, it goes a long way just pointing out wiki errors so
+
-devs can fix them (in an Issue or just over chat/forum). You can also
+The documentation is a wiki and to edit it you need wiki-contributor
-commit wiki changes over Mercurial - just go to the wiki repository
+access. We are happy to give this - just ask (on the forum/mailing list
+or in the chat channel) if you want to help out. Otherwise, it goes a
+long way just pointing out wiki errors so devs can fix them (in an Issue
+or just over chat/forum). You can also commit wiki changes over
+Mercurial - just go to the wiki repository
 `here <http://code.google.com/p/evennia/source/checkout?repo=wiki>`_ and
 then continue from point ``2`` below.
 

docs/sphinx/source/wiki/DefaultCommandHelp.rst

@@ -137,7 +137,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/adm
 ~~~~~
 
 -  ``key`` = ``@emit``
--  ``aliases`` = ``@pemit, @remit``
+-  ``aliases`` = ``@remit, @pemit``
 -  `locks <Locks.html>`_ = ``cmd:perm(emit) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``Admin``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -319,7 +319,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ~~~~~~~~~~~~~~
 
 -  ``key`` = ``@batchcommands``
--  ``aliases`` = ``@batchcommand, @batchcmd``
+-  ``aliases`` = ``@batchcmd, @batchcommand``
 -  `locks <Locks.html>`_ = ``cmd:perm(batchcommands) or superuser()``
 -  `help\_category <HelpSystem.html>`_ = ``Building``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -510,7 +510,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ~~~~~~~~
 
 -  ``key`` = ``@destroy``
--  ``aliases`` = ``@delete, @del``
+-  ``aliases`` = ``@del, @delete``
 -  `locks <Locks.html>`_ = ``cmd:perm(destroy) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``Building``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -570,7 +570,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ~~~~~~~~
 
 -  ``key`` = ``@examine``
--  ``aliases`` = ``@ex, ex, exam, examine``
+-  ``aliases`` = ``examine, @ex, ex, exam``
 -  `locks <Locks.html>`_ = ``cmd:perm(examine) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``Building``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -600,7 +600,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ~~~~~
 
 -  ``key`` = ``@find``
--  ``aliases`` = ``find, @search, search, @locate, locate``
+-  ``aliases`` = ``locate, @locate, search, @search, find``
 -  `locks <Locks.html>`_ = ``cmd:perm(find) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``Building``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -721,7 +721,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ~~~~~
 
 -  ``key`` = ``@lock``
--  ``aliases`` = ``@locks, lock, locks``
+-  ``aliases`` = ``lock, @locks, locks``
 -  `locks <Locks.html>`_ = ``cmd: perm(@locks) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``Building``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1173,7 +1173,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/com
 
 -  ``key`` = ``@channels``
 -  ``aliases`` =
-   ``@clist, channels, comlist, chanlist, channellist, all channels``
+   ``comlist, channellist, all channels, channels, @clist, chanlist``
 -  `locks <Locks.html>`_ = ``cmd: not pperm(channel_banned)``
 -  `help\_category <HelpSystem.html>`_ = ``Comms``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1270,7 +1270,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/com
 ~~~~~~~~~~~~~~~~~~~~~~
 
 -  ``key`` = ``@imcinfo``
--  ``aliases`` = ``@imcchanlist, @imclist, @imcwhois``
+-  ``aliases`` = ``@imcchanlist, @imcwhois, @imclist``
 -  `locks <Locks.html>`_ =
    ``cmd: serversetting(IMC2_ENABLED) and pperm(Wizards)``
 -  `help\_category <HelpSystem.html>`_ = ``Comms``
@@ -1436,7 +1436,7 @@ imctell (OOC command)
 ~~~~~~~~~~~~~~~~~~~~~
 
 -  ``key`` = ``imctell``
--  ``aliases`` = ``imcpage, imc2tell, imc2page``
+-  ``aliases`` = ``imc2tell, imc2page, imcpage``
 -  `locks <Locks.html>`_ = ``cmd: serversetting(IMC2_ENABLED)``
 -  `help\_category <HelpSystem.html>`_ = ``Comms``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1609,7 +1609,7 @@ access
 ~~~~~~
 
 -  ``key`` = ``access``
--  ``aliases`` = ``groups, hierarchy``
+-  ``aliases`` = ``hierarchy, groups``
 -  `locks <Locks.html>`_ = ``cmd:all()``
 -  `help\_category <HelpSystem.html>`_ = ``General``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1738,7 +1738,7 @@ inventory
 ~~~~~~~~~
 
 -  ``key`` = ``inventory``
--  ``aliases`` = ``inv, i``
+-  ``aliases`` = ``i, inv``
 -  `locks <Locks.html>`_ = ``cmd:all()``
 -  `help\_category <HelpSystem.html>`_ = ``General``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1805,7 +1805,7 @@ nick
 ~~~~
 
 -  ``key`` = ``nick``
--  ``aliases`` = ``nickname, nicks, @nick, alias``
+-  ``aliases`` = ``@nick, nicks, nickname, alias``
 -  `locks <Locks.html>`_ = ``cmd:all()``
 -  `help\_category <HelpSystem.html>`_ = ``General``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -1942,7 +1942,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/sys
 ~~~~~~~~
 
 -  ``key`` = ``@objects``
--  ``aliases`` = ``@listobjects, @listobjs, @stats, @db``
+-  ``aliases`` = ``@listobjects, @stats, @db, @listobjs``
 -  `locks <Locks.html>`_ = ``cmd:perm(listobjects) or perm(Builders)``
 -  `help\_category <HelpSystem.html>`_ = ``System``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -2041,7 +2041,7 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/sys
 ~~~~~~~~
 
 -  ``key`` = ``@scripts``
--  ``aliases`` = ``@globalscript, @listscripts``
+-  ``aliases`` = ``@listscripts, @globalscript``
 -  `locks <Locks.html>`_ = ``cmd:perm(listscripts) or perm(Wizards)``
 -  `help\_category <HelpSystem.html>`_ = ``System``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -2203,7 +2203,7 @@ connect (Unloggedin command)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  ``key`` = ``connect``
--  ``aliases`` = ``conn, con, co``
+-  ``aliases`` = ``co, conn, con``
 -  `locks <Locks.html>`_ = ``cmd:all()``
 -  `help\_category <HelpSystem.html>`_ = ``Unloggedin``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -2214,16 +2214,19 @@ connect (Unloggedin command)
         Connect to the game.
 
         Usage (at login screen):
-          connect <email> <password>
+          connect playername password
+          connect "player name" "pass word"
 
         Use the create command to first create an account before logging in.
 
+        If you have spaces in your name, enclose it in quotes.
+        
 
 create (Unloggedin command)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  ``key`` = ``create``
--  ``aliases`` = ``cre, cr``
+-  ``aliases`` = ``cr, cre``
 -  `locks <Locks.html>`_ = ``cmd:all()``
 -  `help\_category <HelpSystem.html>`_ = ``Unloggedin``
 -  [`HelpSystem <HelpSystem.html>`_\ #Auto-help\_system Auto-help]
@@ -2234,10 +2237,12 @@ create (Unloggedin command)
         Create a new account.
 
         Usage (at login screen):
-          create "playername" <email> <password>
+          create <playername> <password>
+          create "player name" "pass word"
 
         This creates a new player account.
 
+        If you have spaces in your name, enclose it in quotes.
         
 
 help (Unloggedin command)

docs/sphinx/source/wiki/DeveloperCentral.rst

@@ -2,8 +2,8 @@ Developer Central
 =================
 
 This page serves as a central nexus for useful information regarding
-coding using the Evennia codebase, and also for development of the
+coding using the Evennia codebase or developing the codebase itself.
-codebase itself. Everyone is welcome to `help
+Everyone is welcome to `help
 out <http://code.google.com/p/evennia/wiki/Contributing>`_! If you have
 any questions, please feel free to ask them in the `Forum/Discussion
 Group <http://www.evennia.com/discussions>`_. If you want more docs on a
@@ -19,8 +19,8 @@ General Evennia development information
 -  `Introduction to coding with Evennia <CodingIntroduction.html>`_
 -  `Evennia Licensing FAQ <Licensing.html>`_
 -  `Contributing to Evennia <Contributing.html>`_
--  `Evennia Code Style
+-  `Code Style
-   Guide <http://evennia.googlecode.com/svn/trunk/CODING_STYLE>`_
+   Guide <http://code.google.com/p/evennia/source/browse/CODING_STYLE.txt>`_
    (Important!)
 -  `Policy for 'MUX-like' default commands <UsingMUXAsAStandard.html>`_
 -  `Setting up a Mercurial environment for
@@ -47,6 +47,7 @@ Evennia Component Documentation
 -  `Help System <HelpSystem.html>`_
 -  `Nicks <Nicks.html>`_
 -  `Sessions and Protocols <SessionProtocols.html>`_
+-  `Caches <Caches.html>`_
 -  `Web features <WebFeatures.html>`_
 -  `Configuration and module plugins <ServerConf.html>`_
 

docs/sphinx/source/wiki/ExecutePythonCode.rst

@@ -86,20 +86,20 @@ entries found in ``ev.search_*``.
 (Note that since this becomes a simple statement, we don't have to wrap
 it in ``self.msg()`` to get the output). You can also use the database
 model managers directly (accessible through the ``objects`` properties
-of database models or as ``ev.db_*``). This is a bit more flexible since
+of database models or as ``ev.managers.*``). This is a bit more flexible
-it gives you access to the full range of database search methods defined
+since it gives you access to the full range of database search methods
-in each manager.
+defined in each manager.
 
 ::
 
-    @py ev.db_scripts.script_search("sys_game_time")
+    @py ev.managers.scripts.script_search("sys_game_time")
     <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
 
 The managers are useful for all sorts of database studies.
 
 ::
 
-    @py ev.db_configvalues.all()
+    @py ev.managers.configvalues.all()
     <<< [<ConfigValue: default_home]>, <ConfigValue:site_name>, ...]
 
 In doing so however, keep in mind the difference between `Typeclasses
@@ -114,12 +114,12 @@ most situations.
 
     # this uses Evennia's manager method get_id(). 
     # It returns a Character typeclass instance
-    @py ev.db_objects.get_id(1).__class__
+    @py ev.managers.objects.get_id(1).__class__
     <<< Character
 
     # this uses the standard Django get() query. 
     # It returns a django database model instance.
-    @py ev.db_objects.get(id=1).__class__
+    @py ev.managers.objects.get(id=1).__class__
     <<< <class 'src.objects.models.ObjectDB'>
 
 Running a Python Parser outside the game
@@ -152,6 +152,6 @@ tab-completion and ``__doc__``-string reading.
     ...
 
     In [1]: import ev
-    In [2]: ev.db_objects.all()
+    In [2]: ev.managers.objects.all()
     Out[3]: [<ObjectDB: Harry>, <ObjectDB: Limbo>, ...]
 

docs/sphinx/source/wiki/GamePlanning.rst

@@ -18,12 +18,12 @@ your work fun for you, or motivation will falter. Making a full game is
 a lot of work as it is, you'll need all your motivation to make it a
 reality.
 
-Remember that *99.99999% of all great game ideas never leads to an
+Remember that *99.99999% of all great game ideas never lead to an online
-online game*. So your first all overshadowing goal is to beat those odds
+game*. So your first all overshadowing goal is to beat those odds and
-and get *something* out the door! *Even* if it's a scaled-down version
+get *something* out the door! *Even* if it's a scaled-down version of
-of your dream game, lacking many "must-have" features! It's better to
+your dream game, lacking many "must-have" features! It's better to get
-get it out there and expand on it later than to code in isolation
+it out there and expand on it later than to code in isolation forever
-forever until you burn out, loose interest or your hard drive crashes.
+until you burn out, lose interest or your hard drive crashes.
 
 Like is common with online games, getting a game out the door does not
 mean you are going to be "finished" with the game - most MUDs add
@@ -49,7 +49,7 @@ game and what they need to be able to do.
    simple description enough? Can it be dark (description
    changed/hidden)? Should it have smells, sounds? Weather? Different
    terrain? How are those to be conveyed? Are there special "magic"
-   rooms that does things to people entering? Can a person hide in the
+   rooms that do things to people entering? Can a person hide in the
    room? Should all rooms have the ability to be this complex or should
    there be different types of rooms? Evennia allows you to change the
    very concept of rooms should you be very ambitious, but is that a
@@ -67,7 +67,7 @@ game and what they need to be able to do.
    object. For a role playing game, you need to define chances of
    success ("rolls") for example. Will weather messages be random in
    every room or should it follow some sort of realistic pattern over
-   all rooms? Do you have an game-wide economy - if so, how is that
+   all rooms? Do you have a game-wide economy - if so, how is that
    supposed to work? If magic is dependent on the position of the
    planets, the planets must change with time. What about spreading
    rumors? Mail boxes? Bulletin boards?

docs/sphinx/source/wiki/GettingStarted.rst

@@ -49,51 +49,41 @@ platform, please let us know.
 You'll need the following packages and minimum versions in order to run
 Evennia:
 
--  **Python** (`http://www.python.org <http://www.python.org>`_)
+-  **`Python <http://www.python.org>`_** (v2.6+, not supporting v3.x)
 
-   -  Version 2.6+. Obs- Python3.x is not supported.
+   -  Windows users are recommended to use
-   -  Windows users are recommended to use ActivePython
+      `ActivePython <http://www.activestate.com/activepython/downloads>`_
-      (`http://www.activestate.com/activepython/downloads <http://www.activestate.com/activepython/downloads>`_)
+      instead.
 
--  **Twisted** (`http://twistedmatrix.com <http://twistedmatrix.com>`_)
+-  **`Twisted <http://twistedmatrix.com>`_** (v10.0+)
 
-   -  Version 10.0+
+   -  `ZopeInterface <http://www.zope.org/Products/ZopeInterface>`_
-   -  Twisted also requires:
+      (v3.0+) - usually included in Twisted packages
+   -  Windows users might also need
+      `pywin32 <http://sourceforge.net/projects/pywin32>`_.
 
-      -  ZopeInterface 3.0+
+-  **`Django <http://www.djangoproject.com>`_** (v1.3+ or latest dev
-         (`http://www.zope.org/Products/ZopeInterface <http://www.zope.org/Products/ZopeInterface>`_)
+   build recommended)
-      -  For Windows only: pywin32
-         (`http://sourceforge.net/projects/pywin32 <http://sourceforge.net/projects/pywin32>`_)
 
--  **Django**
+   -  `PIL <http://www.pythonware.com/products/pil>`_ (Python Image
-   (`http://www.djangoproject.com <http://www.djangoproject.com>`_)
+      Library) - often distributed with Django.
-
-   -  Version 1.3+ or latest development versions highly recommended.
-   -  PIL (Python Imaging Library)
-      (`http://www.pythonware.com/products/pil <http://www.pythonware.com/products/pil>`_)
-      - not strictly required unless you use images in Django.
 
 To download/update Evennia:
 
--  **Mercurial**
+-  **`Mercurial <http://mercurial.selenic.com/>`_**
-   (`http://mercurial.selenic.com/ <http://mercurial.selenic.com/>`_)
-
-   -  This is needed to download and update Evennia itself.
 
 Optional packages:
 
--  **South**
+-  **`South <http://south.aeracode.org/>`_** (v0.7+)
-   (`http://south.aeracode.org/ <http://south.aeracode.org/>`_)
 
-   -  Version 0.7+
+   -  Optional, but highly recommended. Makes it easy to keep up with
-   -  Optional, but highly recommended. Used for database migrations.
+      Evennia updates to the database schema.
 
--  **Apache2** (`http://httpd.apache.org <http://httpd.apache.org>`_)
+-  **`Apache2 <http://httpd.apache.org>`_**
 
-   -  Optional. Most likely you'll not need to bother with this since
+   -  Optional. Only use if you don't want to use Evennia's own threaded
-      Evennia runs its own threaded web server based on Twisted. Other
+      webserver. Other equivalent web servers with a Python interpreter
-      equivalent web servers with a Python interpreter module can also
+      module can also be used.
-      be used.
 
 Installing pre-requisites
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,6 +105,10 @@ Debian-derived systems (such as Ubuntu) you can do something like this
 
      apt-get install python python-django python-twisted mercurial python-django-south
 
+(Gentoo note: Gentoo (and maybe other distros?) seems to distribute
+Twisted in multiple packages. Beyond the main twisted package you will
+also need to get at least twisted-conch and twisted-web too).\ **
+
 Few distros actually keep the latest updated security updates (notably
 django and twisted) in their repos though. So it might be worth to use
 Python's
@@ -159,11 +153,11 @@ circumvent this bug for now. This affects also Unix/Linux systems, but
 those usually have the locale set out of the box.
 
 **Windows** users should first and foremost recognize that the Evennia
-server is run from the command line, something which they might not be
+server is run from the command line, something which some might not be
-familiar with. In the Windows launch menu, just start *All Programs ->
+familiar with (based on the questions we have received). In the Windows
-Accessories -> command prompt* and you will get the Windows command line
+launch menu, just start *All Programs -> Accessories -> command prompt*
-interface. There are plenty of online tutorials on using the Windows
+and you will get the Windows command line interface. There are plenty of
-command line, one example is found
+online tutorials on using the Windows command line, one example is found
 `here <http://www.bleepingcomputer.com/tutorials/windows-command-prompt-introduction/>`_.
 
 Windows users may want to install

docs/sphinx/source/wiki/Licensing.rst

@@ -4,7 +4,7 @@ Evennia Licence FAQ
 Evennia is licensed under the very friendly *Modified Clarified Artistic
 License*. You can find the license as ``LICENCE`` in the Evennia root
 directory. You can also read the full license file
-`here <http://code.google.com/p/evennia/source/browse/trunk/LICENSE>`_.
+`here <http://code.google.com/p/evennia/source/browse/LICENSE.txt>`_.
 
 You should read the full license text to know what it says exactly, but
 here are some answers to common questions.

docs/sphinx/source/wiki/Links.rst

@@ -56,6 +56,12 @@ General mud/game development ideas and discussions
    Realities <http://disinterest.org/resource/imaginary-realities/>`_ is
    an e-magazine on game/MUD design which were active 1998-2001.
    Interesting articles.
+-  `Mud-dev wiki <http://mud-dev.wikidot.com/>`_ is a slowly growing
+   resource on MUD creation
+-  `Nick Gammon's hints
+   thread <http://www.gammon.com.au/forum/bbshowpost.php?bbsubject_id=5959>`_
+   holds a very useful list of things to think about when starting your
+   new MUD.
 
 -  `Lost Garden <http://www.lostgarden.com/>`_ is a game development
    blog with long and interesting articles (not MUD-specific)
@@ -66,6 +72,8 @@ General mud/game development ideas and discussions
    discussion about rule systems and game balance that could be
    applicable also for MUDs.
 
+x
+
 Frameworks
 ----------
 

docs/sphinx/source/wiki/Locks.rst

@@ -87,9 +87,8 @@ special *lock functions* available to the lock system.
 So, a lockstring consists of the type of restriction (the
 ``access_type``), a colon (``:``) and then a list of function calls that
 determine what is needed to pass the lock. Each function returns either
-``True`` or ``False``. AND/OR and NOT works like normal Python to
+``True`` or ``False``. AND, OR and NOT work as they do normally in
-combine several function checks. If the total result is True, the lock
+Python. If the total result is True, the lock is passed.
-is passed.
 
 You can create several lock types one after the other by separating them
 with a semicolon (``;``) in the lockstring. The string below is

docs/sphinx/source/wiki/RemovingColour.rst

@@ -30,7 +30,7 @@ Create a new module in ``game/gamesrc/objects`` named, for example,
 ``mycharacter.py``.
 
 In your new module, create a new `typeclass <Typeclasses.html>`_
-inheriting from ``game.gamesrc.objects.baseobjecs.Character``.
+inheriting from ``ev.Character``.
 
 ::
 
@@ -44,7 +44,7 @@ inheriting from ``game.gamesrc.objects.baseobjecs.Character``.
 Above we set a simple config value as an `attribute <Attributes.html>`_.
 
 Let's make sure that new characters are created of this type. Edit your
-``game/settings.py`` file and change ``BASE_CHARACTER_TYPECLASS`` to
+``game/settings.py`` file and add/change ``BASE_CHARACTER_TYPECLASS`` to
 point to your new character class. Observe that this will only affect
 *new* characters, not those already created. You have to convert already
 created characters to the new typeclass by using the ``@typeclass``
@@ -67,101 +67,8 @@ Overload the \`msg()\` method
 -----------------------------
 
 Next we need to overload the ``msg()`` method. What we want is to check
-the configuration value before calling the main function. The original
+the configuration value before calling the main function. The ``msg``
-``msg`` method is found on ``src.objects.models.ObjectDB`` and is called
+method call is found in
-like this:
+``src/objects/objects.py' and is called like this:  {{{ msg(message, from_obj=None, data=None) }}} As long as we define a method on our custom object with the same name and keep the same number of arguments/keywords we will overload the original. Here's how it could look: {{{ from ev import ansi  msg(self, message, from_obj=None, data=None):     "our custom msg()"     if not self.db.config_colour:         # if config_colour is False, strip ansi colour         message = ansi.parse_ansi(message, strip_ansi=True)     self.dbobj.msg(message, from_obj, data) }}} Above we create a custom version of the ``\ msg()\ `` method that cleans all ansi characters if the config value is not set to True. Once that's done, we pass it all on to the normal ``\ msg()\ `` on the database object (``\ ObjectDB\ ``) to do its thing. The colour strip is done by the ansi module itself by giving the ``\ strip\_ansi\ `` keyword to ``\ ansi.parse\_ansi\ ``.  Since we put this custom ``\ msg()\ `` in our typeclass ``\ ColourableCharacter\ ``, it will be searched for and called rather than the default method on ``\ ObjectDB\ `` (which we now instead call manually).  There we go! Just flip the attribute ``\ config\_colour\ `` to False and your users will not see any colour. As superuser (assuming you use the Typeclass ``\ ColourableCharacter\ ``) you can test this with the ``\ @py\ `` command:  {{{  @py self.db.config_colour = False }}}   ==Custom colour config command ==  For completeness, let's add a custom command so users can turn off their colour display themselves if they want.  In ``\ game/gamesrc/commands\ ``, reate a new file, call it for example  ``\ configcmds.py\ `` (it's likely that you'll want to add other commands for configuration down the line). You can also copy/rename the command template from ``\ game/gamesrc/commands/examples\ ``.  {{{ from ev import default_cmds class ConfigColourCmd(default_cmds.MuxCommand):     """     Configures your colour      Usage:       @setcolour on|off      This turns ansii-colours on/off.      Default is on.      """      key = "@setcolour"     aliases = ["@setcolor"]      def func(self):         "Implements the command"          if not self.args or not self.args in ("on", "off"):             self.caller.msg("Usage: @setcolour on|off")              return         if self.args == "on":             self.caller.db.config_colour = True         else:             self.caller.db.config_colour = False           self.caller.msg("Colour was turned %s." % self.args) }}} Lastly, we make this command available to the user by adding it to the default command set. Easiest is to add it to copy the template file from ``\ gamesrc/commands/examples\ ``, set ``\ settings.CMDSET\_DEFAULT\ `` to point to, and then add your module to the end of ``\ DefaultCmdSet\ `` in that new module.  {{{ from game.gamesrc.commands import configcmds class DefaultCmdSet(cmdset_default.DefaultCmdSet):         key = "DefaultMUX"          def at_cmdset_creation(self):                super(DefaultCmdSet, self).at_cmdset_creation()                 self.add(configcmds.ConfigColourCmd())              }}} When adding a new command to a cmdset like this you need to run the ``\ @reload\ ````
-
+command (or reboot the server). From here on out, your users should be
-::
+able to turn on or off their colour as they please.
-
-    msg(message, from_obj=None, data=None)
-
-As long as we define a method on our custom object with the same name
-and keep the same number of arguments/keywords we will overload the
-original. Here's how it could look:
-
-::
-
-    from ev import ansi
-
-    msg(self, message, from_obj=None, data=None):
-        "our custom msg()"
-        if not self.db.config_colour:
-            message = ansi.parse_ansi(message, strip_ansi=True)
-        self.dbobj.msg(message, from_obj, data)
-
-Above we create a custom version of the ``msg()`` method that cleans all
-ansi characters if the config value is not set to True. Once that's
-done, we pass it all on to the normal ``msg()`` on the database object
-(``ObjectDB``) to do its thing.
-
-Since we put this custom ``msg()`` in our typeclass
-``ColourableCharacter``, it will be searched for and called rather than
-the default method on ``ObjectDB`` (which we now instead call manually).
-
-There we go! Just flip the attribute ``config_colour`` to False and your
-users will not see any colour. As superuser (assuming you use the
-Typeclass ``ColourableCharacter``) you can test this with the ``@py``
-command:
-
-::
-
-     @py self.db.config_colour = False
-
-Custom colour config command
-----------------------------
-
-For completeness, let's add a custom command so users can turn off their
-colour display themselves if they want.
-
-In game/gamesrc/commands, create a new file, call it for example
-``configcmds.py`` (it's likely that you'll want to add other commands
-for configuration down the line).
-
-::
-
-    from ev import default_cmds
-    class ConfigColourCmd(default_cmds.MuxCommand):
-        """
-        Configures your colour
-
-        Usage:
-          @setcolour on|off
-
-        This turns ansii-colours on/off. 
-        Default is on. 
-        """
-
-        key = "@setcolour"
-        aliases = ["@setcolor"]
-
-        def func(self):
-            "Implements the command" 
-            if not self.args or not self.args in ("on", "off"):
-                self.caller.msg("Usage: @setcolour on|off") 
-                return
-            if self.args == "on":
-                self.caller.db.config_colour = True
-            else:
-                self.caller.db.config_colour = False  
-            self.caller.msg("Colour was turned %s." % self.args)
-
-Lastly, we make this command available to the user by adding it to the
-default command set. Easiest is to add it to copy the template file from
-``gamesrc/commands/examples``, set ``settings.CMDSET_DEFAULT`` to point
-to, and then add your module to the end of ``DefaultCmdSet`` in that new
-module.
-
-::
-
-    from game.gamesrc.commands import configcmds
-    class DefaultCmdSet(cmdset_default.DefaultCmdSet):
-       
-        key = "DefaultMUX"
-        
-        def at_cmdset_creation(self):       
-            super(DefaultCmdSet, self).at_cmdset_creation()        
-            self.add(configcmds.ConfigColourCmd())             
-
-When adding a new command to a cmdset like this you need to run the
-``@reload`` command (or reboot the server). From here on out, your users
-should be able to turn on or off their colour as they please.

docs/sphinx/source/wiki/Scripts.rst

@@ -1,8 +1,24 @@
 Scripts
 =======
 
-*Scripts* are the way to implement everything in Evennia that may change
+*Scripts* are the out-of-character siblings to the in-character
-with time.
+`Objects <Objects.html>`_. The name "Script" might suggest that they can
+only be used to script the game but this is only part of their
+usefulness (in the end we had to pick a single name for them). Scripts
+are full Typeclassed database entities, just like Objects - with all the
+advantages this entails. Likewise they can also store arbitrary
+*Attributes*.
+
+Scripts can be used for many different things in Evennia:
+
+-  They can attach to Objects to influence them in various ways - or
+   exist independently of any one in-game entity.
+-  They can work as timers and tickers - anything that may change with
+   Time. But they can also have no time dependence at all.
+-  They can describe State changes.
+-  They can act as data stores for storing game data persistently in the
+   database
+-  They can be used to shared data between groups of objects
 
 The most obvious use of Scripts may be to use them as *timers* or
 *Events*. Consider a script running on the object ``Grandfather Clock``.
@@ -12,16 +28,17 @@ clock must be rewound so it won't stop.
 
 Scripts may act as changeable *States*. Consider for example creating a
 'dark' room. It has two scripts assigned on it - one ``DarkState``
-script, and one ``BrightState`` script. When characters enters the dark
+script, and one ``BrightState`` script. When characters enter the dark
-room, it assigns a custom `Cmdset <Commands.html>`_ to them - this
+room, it assigns a custom `Cmdset <Commands.html>`_ to them. This
-command set (say) limits their actions because of the darkness. After
+command set defines the parameters of the state they describe. In this
-the characters have stumbled around for a while, someone brings up a
+case it limits their actions because of the darkness. After the
-torch. As a light source is now in the room, ``DarkState`` reacts to
+characters have stumbled around for a while, someone brings up a torch.
-this by shutting down itself and handing over control to the
+As a light source is now in the room, ``DarkState`` reacts to this by
-``BrightState`` script that restores normal commands. Finally, when the
+shutting down itself and handing over control to the ``BrightState``
-character with the torch leaves the room, the ``BrightState`` script
+script that restores normal commands. Finally, when the character with
-detects this and obediently hands control back to the ``DarkState``,
+the torch leaves the room, the ``BrightState`` script detects this and
-leaving the remaining poor characters in darkness once again.
+obediently hands control back to the ``DarkState``, leaving the
+remaining poor characters in darkness once again.
 
 By combining state-changes with timers one can make a room look
 different during nighttime than it does during the day. Weather and
@@ -29,9 +46,11 @@ seasons might come and go. But one can also achieve more complex things
 such as state-AI systems that make mobs move around and possibly pursue
 characters between rooms.
 
-... In short, Scripts make the game world *tick*. Scripts are
+Scripts are also excellent places to store game data in an OOC way. A
-database-persistent objects and are `TypeClassed <Typeclasses.html>`_
+groupd of objects may share date by use of a Script object they all hold
-entities, with all the advantages that this entails.
+references to.
+
+In short, Scripts can be used for a lot of things.
 
 How to create your own Script types
 -----------------------------------

docs/sphinx/source/wiki/ServerConf.rst

@@ -26,7 +26,7 @@ In code, the settings is accessed through
     from django.conf import settings
      # or (shorter):
     from ev import settings
-     # 
+     # example:
     servername = settings.SERVER_NAME
 
 Each setting appears as a property on the imported ``settings`` object.
@@ -73,6 +73,16 @@ for Evennia to be able to locate it.
    by MUD search engines (which you often have to register with) in
    order to display what kind of game you are running along with
    statistics such as number of online players and online status.
+-  ``portal_services_plugin.py`` - this allows for adding your own
+   custom servies/protocols to the Portal. It must define one particular
+   function that will be called by Evennia at startup. There can be any
+   number of service plugin modules, all will be imported and used if
+   defined. More info can be found
+   `here <http://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols>`_.
+-  ``server_services_plugin.py`` - this is equivalent to the previous
+   one, but used for adding new services to the Server instead. More
+   info can be found
+   `here <http://code.google.com/p/evennia/wiki/SessionProtocols#Adding_custom_Protocols>`_.
 
 Some other Evennia systems can be customized by plugin modules but has
 no explicit template in ``conf/examples``:

docs/sphinx/source/wiki/SessionProtocols.rst

@@ -236,6 +236,72 @@ Loop over all relevant sessions. The Server will treat this like a
 Portal call and data will be sent back to be handled by the portal as
 normal.
 
+Adding custom Protocols
+=======================
+
+Evennia has a plugin-system that allows you to add new custom Protocols
+without editing any files in ``src/``. To do this you need to add the
+protocol as a new "service" to the application.
+
+Take a look at for example ``src/server/portal.py``, notably the
+sections towards the end of that file. These are where the various
+in-built services like telnet, ssh, webclient etc are added to the
+Portal (there is an equivalent but shorter list in
+``src/server.server.py``.
+
+To add a new service of your own (for example your own custom client
+protocol) to e.g. the Portal, create a new module in
+``game/gamesrc/conf/``. Let's call it ``myproc_plugin.py``. We need to
+tell the Server or Portal that they need to import this module. In
+``game/settings.py``, add one of the following:
+
+::
+
+    # add to the Server
+    SERVER_SERVICES_PLUGIN_MODULES.append('game.gamesrc.conf.myproc_plugin')
+    # or, if you want to add to the Portal
+    PORTAL_SERVICES_PLUGIN_MODULES.append('game.gamesrc.conf.myproc_plugin')
+
+This module can contain whatever you need to define your protocol, but
+it *must* contain a function ``start_plugin_services(app)``. This is
+called by the Portal as part of its upstart. The function
+``start_plugin_services`` must contain all startup code the server need.
+The ``app`` argument is a reference to the Portal application itself so
+the custom service can be added to it. The function should not return
+anything.
+
+This is how it can look:
+
+::
+
+    # game/gamesrc/conf/myproc_plugin.py
+
+    # here the new Portal Twisted protocol is defined
+    class MyOwnFactory( ... ):
+       [...]
+
+    # some configs
+    MYPROC_ENABLED = True # convenient off-flag to avoid having to edit settings all the time
+    MY_PORT = 6666
+
+    def start_plugin_services(portal):
+        "This is called by the Portal during startup"
+         if not MYPROC_ENABLED:
+             return 
+         # output to list this with the other services at startup
+         print "  myproc: %s" % MY_PORT
+
+         # some setup (simple example)
+         factory = MyOwnFactory()
+         my_service = internet.TCPServer(MY_PORT, factory)
+         # all Evennia services must be uniquely named
+         my_service.setName("MyService")
+         # add to the main portal application
+         portal.services.addService(my_service)
+
+One the module is defined and targeted in settings, just reload the
+server and your new protocol/services should start with the others.
+
 Assorted notes
 ==============
 

docs/sphinx/source/wiki/TutorialWorldIntroduction.rst

@@ -44,7 +44,8 @@ install, log into the server as the superuser (user #1) and run:
 
     @batchcommand contrib.tutorial_world.build
 
-The world will be built (there will be a lot of text output) and you
+The world will be built (this might take a while, so don't rerun the
+command even if it seems the system has frozen). After finishing you
 will end up back in Limbo with a new exit called ``tutorial``.
 
 An alternative is
@@ -73,7 +74,7 @@ together with her powerful magical weapon - a valuable prize, if it's
 true. Of course this is a chance to adventure that you cannot turn
 down!*
 
-*You reach the coast in the midst of a raging thunderstorm. With wind
+*You reach the ocean in the midst of a raging thunderstorm. With wind
 and rain screaming in your face you stand where the moor meets the sea
 along a high, rocky coast ...*
 

docs/sphinx/source/wiki/Tutorials.rst

@@ -7,17 +7,28 @@ or tutorial-like format.
 Building
 --------
 
+More building details are found in the `Builder
+Docs <BuilderDocs.html>`_.
+
 -  `Tutorial: Building Quick-start <BuildingQuickstart.html>`_
 
 Coding basics
 -------------
 
+More details about coding with Evennia is found in the `Developer
+Central <DeveloperCentral.html>`_.
+
 -  `Tutorial: Adding a new default
    command <AddingCommandTutorial.html>`_
 
 Implementation ideas
 --------------------
 
+Before starting to code your own game we recommend you read the
+`Planning Your own game <GamePlanning.html>`_ page for some ideas of
+organizing your workflow. There is also plenty of more information in
+the `Developer Central <DeveloperCentral.html>`_.
+
 -  `Tutorial: Removing Colour from your game (typeclass method
    overloading) <RemovingColour.html>`_
 -  `Tutorial: Adding a Command prompt <CommandPrompt.html>`_
@@ -28,6 +39,9 @@ Implementation ideas
 Examples
 --------
 
+See also ``evennia/contrib/`` and the example directories under
+``game/gamesrc/``.
+
 -  `The Tutorial
    World <http://code.google.com/p/evennia/wiki/TutorialWorldIntroduction>`_
 

docs/sphinx/source/wiki/VersionControl.rst

@@ -162,7 +162,7 @@ Sharing your code with the world
 The most common case of this is when you have fixed an Evennia bug and
 want to make the fix available to Evennia maintainers. But you can also
 share your work with other people on your game-development team if you
-don't worry about the changes being publicly visible.
+aren't worried about the changes being publicly visible.
 
 Let's take the example of debugging Evennia. Go online and create an
 "online clone" of Evennia as described `here <Contributing.html>`_. Pull