Updated ReST docs, fixed some things in Swedish translation.

contrib/tutorial_world/objects.py

@@ -10,10 +10,12 @@ Objects:
 TutorialObject
 
 Readable 
+Climbable
 Obelisk 
 LightSource 
 CrumblingWall
 Weapon 
+WeaponRack
 
 """
 
@@ -729,6 +731,7 @@ class CmdAttack(Command):
 
         if target.db.combat_parry_mode:
             # target is defensive; even harder to hit!
+            target.msg("{GYou defend, trying to avoid the attack.{n")
             hit *= 0.5
 
         if random.random() <= hit:

contrib/tutorial_world/rooms.py

@@ -545,7 +545,7 @@ class BridgeRoom(TutorialRoom):
         self.db.west_exit     -   -  |  -   -     self.db.east_exit
                               0   1  2  3   4
 
-        The position is handled by a variabled stored on the player when entering and giving
+        The position is handled by a variable stored on the player when entering and giving
         special move commands will increase/decrease the counter until the bridge is crossed.                            
 
     """

docs/sphinx/source/wiki/AdminDocs.rst

@@ -21,6 +21,12 @@ Customizing the server
 -  `Changing text encodings used by the server <TextEncodings.html>`_
 -  `How to connect Evennia to IRC channels <IRC.html>`_
 -  `How to connect Evennia to an IMC2 network <IMC2.html>`_
+-  `How to connect Evennia to RSS feeds <RSS.html>`_
+
+Administrating the running game
+-------------------------------
+
+-  `Banning <Banning.html>`_ Banning and deleting users
 
 Working with Evennia
 --------------------

docs/sphinx/source/wiki/Attributes.rst

@@ -223,27 +223,24 @@ However:
 
 ::
 
-    obj.db.mydict[1][2] = "test" # fails!
+    obj.db.mydict[1][2] = "test" # silently fails!
+    val = obj.db.mydict[1][2] # still returns 3
 
 will not work - trying to edit the nested structure will fail silently
 and nothing will have changed. No, this is not consistent with normal
 Python operation, it's where the database magic fails. Sorry, but there
 does not seem to be a way around this (if you know one, let us know!)
 All is not lost however. In order to change a nested structure, you
-simply need to use a temporary variable:
+simply need to use a temporary variable to update:
 
 ::
 
-    # retrieve old db data into temporary variable
+    temp = obj.db.mydict
-    mydict = obj.db.mydict
+    temp[1][2] = "test"
-    # update temporary variable
+    obj.db.mydict = temp
-    mydict[1][2] = "test"
-    # save back to database
-    obj.db.mydict = mydict
-    # test
     val = obj.db.mydict[1][2] # now correctly returns "test"
 
-mydict was updated and recreated in the database.
+This is cumbersome, but always works as expected.
 
 Notes
 -----

docs/sphinx/source/wiki/ChoosingAnSQLServer.rst

@@ -13,17 +13,19 @@ SQLite
 ------
 
 This is the default database used, and for the vast majority of Evennia
-installs it will probably be more than adequate. No server process is
+installs it will probably be more than adequate for a long time. No
-needed, the administrative overhead is tiny (as is resource
+server process is needed, the administrative overhead is tiny (as is
-consumption). The database will appear as a simple file
+resource consumption). The database will appear as a simple file
-(``game/evennia.db3``). It is not tested how well Evennia performs with
+(``game/evennia.db3``). SQLite is excellent for development and easy
-SQLite under a heavier load, but it should probably be fine for most
+testing. The database is however hampered in speed by not allowing
-normal mud-related usage.
+concurrent reads. For a full production game with many users accessing
+the database, a more fully featured database engine (MySQL, Postgres
+etc) is probably better.
 
 **Note:** If you run Windows and for some reason need to use a
 third-party web server like Apache rather than Evennia's internal web
-server, sqlite is probably not be the best choice. This is due to the
+server, sqlite is probably also not be the best choice. This is due to
-possibility of clashes with file-locking of the database file under
+the possibility of clashes with file-locking of the database file under
 Windows.
 
 Postgres
@@ -34,12 +36,17 @@ aspiring to grow to a larger size. While not as fast as SQLite for
 simple purposes, it will scale infinitely better than SQLite, especially
 if your game has an extensive web presence.
 
+**Warning:** Postgres has issues with Evennia on some installs at the
+moment. "http://code.google.com/p/evennia/issues/detail?id
+
+151">Issue 151 outlines this. If unsure, avoid Postgres for now.
+
 MySQL
 -----
 
 MySQL **may** be slightly faster than Postgres depending on your setup
-and software versions involved. Older versions had some peculiarities
+and software versions involved. Older versions of MySQL had some
-though, so check out Django's `Notes about supported
+peculiarities though, so check out Django's `Notes about supported
 Databases <http://docs.djangoproject.com/en/dev/ref/databases/#ref-databases>`_
 to make sure you use the correct version.
 

docs/sphinx/source/wiki/Commands.rst

@@ -124,6 +124,11 @@ Beyond the properties Evennia always assigns to the command at runtime
 -  ``help_category`` (optional) - setting this helps to structure the
    auto-help into categories. If none is set, this will be set to
    *General*.
+-  ``save_for_next`` (optional). This defaults to ``False``. If
+   ``True``, this command object (along with any changes you have done
+   to it) will be stored by the system and can be accessed by the next
+   command called by retrieving ``self.caller.ndb.last_cmd``. The next
+   run command will either clear or replace the storage.
 
 You should also implement at least two methods, ``parse()`` and
 ``func()`` (You could also implement ``perm()``, but that's not needed
@@ -602,10 +607,9 @@ Here are the exceptional situations that triggers system commands:
 
 -  No input (``cmdhandler.CMD_NOINPUT``) - the player just pressed
    return without any input. Default is to do nothing, but it can be
-
+   useful to do something here for certain implementations such as line
-useful for certain implementations such as line editors that interpret
+   editors that interpret non-commands as text input (an empty line in
-non-commands as text input.
+   the editing buffer).
-
 -  Command not found (``cmdhandler.CMD_NOMATCH``) - No matching command
    was found. Default is to display the "Huh?" error message.
 -  Several matching commands where found (``cmdhandler.CMD_MULTIMATCH``)
@@ -738,3 +742,7 @@ functionality at all by default (all default commands simply returns
 ``None``) and it's probably not relevant to any but the most
 advanced/exotic designs (one might use it to create a "nested" command
 structure for example).
+
+The ``save_for_next`` class variable can be used to implement
+state-persistent commands. For example it can make a command operate on
+"it", where it is determined by what the previous command operated on.

docs/sphinx/source/wiki/DeveloperCentral.rst

@@ -64,6 +64,7 @@ Programming Evennia
 
 -  `Running and Testing Python code from inside the
    game <ExecutePythonCode.html>`_
+-  `Useful coding utilities <CodingUtils.html>`_
 -  `Running and writing unit tests for Evennia <UnitTesting.html>`_
 -  `Removing Colour from your game - tutorial on redefining typeclass
    methods <RemovingColour.html>`_

docs/sphinx/source/wiki/DirectoryOverview.rst

@@ -1,6 +1,15 @@
 Evennia directory overview
 ==========================
 
+::
+
+    evennia/  
+      contrib/
+      docs/   
+      game/
+      locale/ 
+      src/
+
 Evennia's main directory (``evennia``) is divided into five sub
 directories - ``src/``, ``game/``, ``contrib/`` , ``locale`` and
 ``doc/``. The first two are the most important ones. ``game/`` is the
@@ -35,8 +44,8 @@ create a nice browsable web-index of all the sources and comments. In
 the same way you could in theory also create nice ``LaTeX``-formatted
 PDFs of the Evennia source (all 400+ pages of it ...).
 
-The ``locale`` directory
+The ``locale/`` directory
-------------------------
+-------------------------
 
 This contains internationalization strings for translating the Evennia
 core server to different languages. See
@@ -217,8 +226,8 @@ point to your copy.
 ~~~~~~~~~~~~~~
 
 ``src/comms/`` defines all aspects of OOC
-`communication <Communications.html>`_, notably *channels* and the basic
+`communication <Communications.html>`_, notably *channels*, *messages*
-operations for storing listeners to channels.
+and the basic operators for connecting external listeners to channels.
 
 ``src/help/``
 ~~~~~~~~~~~~~
@@ -244,8 +253,8 @@ lock functions are found here.
 ~~~~~~~~~~~~~~~~
 
 The `Player <Players.html>`_ is the OOC-represention of the person
-behind the game character. This directory defines the database handling
+connected to the game. This directory defines the database handling and
-and methods acting on the Player object.
+methods acting on the Player object.
 
 ``src/scripts/``
 ~~~~~~~~~~~~~~~~
@@ -259,9 +268,10 @@ connection timeouts) are also defined here.
 ~~~~~~~~~~~~~~~
 
 This directory is the heart of Evennia. It holds the server process
-itself (started from ``game/evennia.py``) and all `sessions and
+itself (started from ``game/evennia.py``), the portal and all `sessions
-protocols <SessionProtocols.html>`_ that allow users to connect to it.
+and protocols <SessionProtocols.html>`_ that allow users to connect to
-It also knows how to store dynamic server info in the database.
+the game. It also knows how to store dynamic server info in the
+database.
 
 ``src/typeclasses/``
 ~~~~~~~~~~~~~~~~~~~~
@@ -300,10 +310,13 @@ Assorted notes
 
 Whereas ``game/gamesrc/`` contains a set of directories already, you
 might find that another structure suits your development better. For
-example, it could sometimes easier to put all the commands and scripts a
+example, it could sometimes be easier to put all the commands and
-certain object needs in the same module as that object, rather than
+scripts a certain object needs in the same module as that object, rather
-slavishly split them out into their respective directories and import.
+than slavishly split them out into their respective directories and
-Don't be shy to define your own directory structure as needed. A basic
+import. Don't be shy to define your own directory structure as needed. A
-rule of thumb should nevertheless be to avoid code-duplication. So if a
+basic rule of thumb should nevertheless be to avoid code-duplication. So
-certain script or command could be useful for other objects, break it
+if a certain script or command could be useful for other objects, break
-out into its own module and import from it.
+it out into its own module and import from it. Don't forget that if you
+add a new directory, it must contain an ``__init__.py`` file (it can be
+empty) in order for Python to recognize it as a place it can import
+modules from.

docs/sphinx/source/wiki/EvenniaIntroduction.rst

@@ -117,6 +117,7 @@ Standards/Protocols supported
    database as game.
 -  IRC/IMC2 - external IRC and/or IMC2 channels can be connected to
    in-game chat channels
+-  RSS feeds can be echoed to in-game channels
 -  ANSI, xterm256 colours
 -  Several different databases supported (SQLite3, MySQL, ...)
 

docs/sphinx/source/wiki/GettingStarted.rst

@@ -4,20 +4,27 @@ Getting Started
 This will help you download, install and start Evennia for the first
 time.
 
+*Note: You don't need to make anything visible to the 'net in order to
+run and test out Evennia. Apart from installing and updating you don't
+even need to have an internet connection. Of course you'll probably want
+to put your game online once it matures enough, but until then it works
+fine to develop and play around completely in the sanctity and isolation
+of your local machine.*
+
 Quick start
 -----------
 
 For you who are extremely impatient, here's the gist of getting a
 vanilla Evennia install running.
 
-#. *Get the pre-requisites (mainly Python, Django, Twisted and
+#. *Get the pre-requisites (Python, Django, Twisted and Mercurial)*.
-   Mercurial)*.
 #. *Start a command terminal/dos prompt and change directory to where
    you want to have your 'evennia' folder appear*.
 #. ``hg clone https://code.google.com/p/evennia/ evennia``
 #. *Change directory to evennia/game*.
 #. ``python manage.py``
 #. ``python manage.py syncdb``
+#. ``python manage.py migrate`` (only if using South)
 #. ``python evennia.py -i start``
 
 Evennia should now be running and you can connect to it by pointing a
@@ -26,8 +33,8 @@ web browser to ``http://localhost:8000`` or a MUD telnet client to
 
 Read on for more detailed instructions and configurations.
 
-Pre-Requesites
+Prerequisites
---------------
+-------------
 
 As far as operating systems go, any system with Python support should
 work.
@@ -44,9 +51,7 @@ Evennia:
 
 **Python** (http://www.python.org)
 
--  Version 2.5+. Obs- Python3.x is not supported yet.
+-  Version 2.5+. Obs- Python3.x is not supported.
--  The default database system SQLite3 only comes as part of Python2.5
-   and later.
 -  Windows users are recommended to use ActivePython
    (http://www.activestate.com/activepython/downloads)
 
@@ -75,7 +80,7 @@ Optional packages:
 **South** (http://south.aeracode.org/)
 
 -  Version 0.7+
--  Optional. Used for database migrations.
+-  Optional, but highly recommended. Used for database migrations.
 
 **Apache2** (http://httpd.apache.org)
 
@@ -84,16 +89,17 @@ Optional packages:
    equivalent web servers with a Python interpreter module can also be
    used.
 
-*Note: You don't need to make anything visible to the 'net in order to
-run and test out Evennia. Apart from downloading/updating Evennia itself
-you don't even need to have an internet connection. Of course you'll
-probably want that as your game matures, but until then it works nicely
-to develop and play around completely in the sanctity and isolation of
-your local machine.*
-
 Installing pre-requisites
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+**All platforms** can set up an *virtual Python environment* and install
+Evennia to that. All you need pre-installed is Python. Setup is
+described in detail
+`here <GettingStarted#Optional:%3Ci%3EA%3C/i%3Eseparate%3Ci%3Einstallation%3C/i%3Eenvironment%3Ci%3Ewith%3C/i%3Evirtualenv.html>`_.
+Windows users will probably want to go the ActivePython way instead
+though (see below), there are issues with installing certain extensions
+in Windows.
+
 **Linux** package managers should usually handle all this for you.
 Python itself is definitely available through all distributions. On
 Debian-derived systems (such as Ubuntu) you can do something like this
@@ -101,7 +107,7 @@ Debian-derived systems (such as Ubuntu) you can do something like this
 
 ::
 
-    apt-get install python python-django python-twisted mercurial
+    apt-get install python python-django python-twisted mercurial python-django-south
 
 Few distros actually keep the latest updated security updates (notably
 django and twisted) in their repos though. So it might be worth to use
@@ -113,33 +119,43 @@ or all of these instead:
 
 ::
 
-    easy_install django twisted pil mercurial
+    easy_install django twisted pil mercurial south
 
 ::
 
-    pip install django twisted pil mercurial
+    pip install django twisted pil mercurial south
+
+**Mac** users should be able to get most dependencies through
+``easy_install`` or ``pip`` like Linux users do. There are however
+reports that you might need to get the
+`Xcode <https://developer.apple.com/xcode/.html>`_ development system to
+install the packages that requites extension compiling. You can also
+retrieve the dependencies directly and install them through their native
+installers or python setups.
 
 **Windows** users may choose to install
 `ActivePython <http://www.activestate.com/activepython/downloads>`_
 instead of the usual Python. If ActivePython is installed, you can use
 `pypm <http://docs.activestate.com/activepython/2.6/pypm.html>`_ in the
 same manner as ``easy_install``/``pip`` above. This *greatly* simplifies
-getting started on Windows:
+getting started on Windows since that platform is otherwise missing many
+of the background developer systems that Linux users take for granted.
+After installing ActivePython you may need to open a new DOS window to
+make this new command available on the command line:
 
 ::
 
-    pypm install Django Twisted PIL Mercurial
+    pypm install Django Twisted PIL Mercurial South
 
-Another simple alternative (for all platforms) is to set up a *virtual
+This installs everything you need in one go.
-Python environment* and install to that - in that case you can even
-experiment with different library versions without affecting your main
-system configuration. This is covered
-`here <GettingStarted#Optional:%3Ci%3EA%3C/i%3Eseparate%3Ci%3Einstallation%3C/i%3Eenvironment%3Ci%3Ewith%3C/i%3Evirtualenv.html>`_.
 
 Windows users not using ActivePython or virtual environments will have
-to manually download and install the packages in turn - most have normal
+to manually download and install the packages in turn (including their
-Windows installers, but in some cases you'll need to know how to use the
+own dependencies in the list above). Most have normal Windows
-Windows command prompt to execute some python install scripts.
+installers, but in some cases you'll need to know how to use the Windows
+command prompt to execute python install scripts (usually it's not
+harder than running ``python setup.py install`` from the downloaded
+package's folder).
 
 Step 1: Obtaining the Server
 ----------------------------
@@ -227,7 +243,7 @@ need to do this:
 This will migrate the server to the latest version. If you don't use
 ``South``, migrations will not be used and your server will already be
 at the latest version (but your existing database might have to be
-manually edited to match future server changes).
+manually edited to match eventual future schema changes that we do).
 
 Step 3: Starting and Stopping the Server
 ----------------------------------------
@@ -244,19 +260,6 @@ starts in *interactive mode*, as a foreground process. You will see
 debug/log messages directly in the terminal window instead of logging
 them to a file.
 
-Running the server in interactive mode is very useful for development
-and debugging but is not recommended for production environments. For
-the latter you'll want to run it as a *daemon* by skipping the ``-i``
-flag:
-
-::
-
-    python evennia.py start
-
-This will start the server as a background process. Server messages will
-be logged to a file you specify in your configuration file (default is a
-file in ``game/logs``).
-
 To stop Evennia, do:
 
 ::
@@ -285,45 +288,35 @@ the ajax web client.
 Welcome to Evennia! Why not try `building
 something <BuildingQuickstart.html>`_ next?
 
-Optional: Database migrations with South
-========================================
-
-Evennia supports database migrations using
-`South <http://south.aeracode.org/>`_, a Django database schema
-migration tool. Installing South is optional, but if it is installed,
-Evennia *will* use it automatically, meaning this section comes into
-play. You can install South from
-`http://south.aeracode.org/. <http://south.aeracode.org/.>`_ It is also
-available through the normal package distributions, easy\_install, pip,
-or pypm (see above notes).
-
-After your first run of ``migrate.py syncdb`` and whenever you see a
-commit or mailing list message telling you that "the Database Schema has
-changed", simply do the following from within the ``evennia/game``
-directory:
-
-::
-
-    python manage.py migrate
-
-You should see migrations being applied, and should be left with an
-updated DB schema afterwards.
-
 Optional: A separate installation environment with virtualenv
 =============================================================
 
 Apart from installing the packages and versions as above, you can also
-set up a very fast self-contained Evennia install using the
+set up a very easy self-contained Evennia install using the
-`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ program.
+`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ program. If you
+are unsure how to get it, just grab the ``virtualenv.py`` file from that
+page and run it directly in the terminal with ``python virtualenv.py``.
+
 Virtualenv sets aside a folder on your harddrive as a stand-alone Python
-environment. It should work both on Linux and Windows. First, install
+environment. It should work both on Linux/Unix and Windows. First,
-Python as normal, then get virtualenv and install it so you can run it
+install Python as normal, then get virtualenv and install it so you can
-from the command line. This is an example for setting up Evennia in an
+run it from the command line. This is an example for setting up Evennia
-isolated new folder *mudenv*:
+in an isolated new folder *mudenv*:
 
 ::
 
     python virtualenv mudenv --no-site-packages
+
+Or, if you grabbed ``virtualenv.py`` and is running it directly:
+
+::
+
+    python virtualenv.py mudenv --no-site-packages
+
+Followed by
+
+::
+
     cd mudenv
 
 Now we should be in our new directory *mudenv*. Next we activate the
@@ -331,27 +324,27 @@ virtual environment in here.
 
 ::
 
-    # for Linux:
+    # for Linux/Unix:
     source bin/activate
     # for Windows:
-    <path_to_this_place>\bin\activate.bat
+    <path_to_this_place>\Scripts\activate.bat
 
-Next we get all the requirements with *pip*, which is included with
+The virtual environment within our *mudenv* folder is now active. Next
+we get all the requirements with *pip*, which is included with
 virtualenv:
 
 ::
 
-    pip install django twisted pil mercurial
+    pip install django twisted pil mercurial south
 
-(The difference from the normal install described earlier is that these
+The difference from the normal install described earlier is that these
 installed packages are *only* localized to the virtual environment, they
 do not affect the normal versions of programs you run in the rest of
 your system. So you could for example experiment with bleeding-edge,
 unstable libraries or go back to older versions without having to worry
 about messing up other things. It's also very easy to uninstall the
-whole thing in one go - just delete your ``mudenv`` folder.)
+whole thing in one go - just delete your ``mudenv`` folder.
 
 You can now refer to **Step 1** above and continue on from there to
 install Evennia into *mudenv*. In the future, just go into the folder
-and activate it to make this separate virtual environment available to
+and activate it before starting or working with Evennia.
-Evennia.

docs/sphinx/source/wiki/Internationalization.rst

@@ -12,7 +12,10 @@ Note, what is translated in this way are hard-coded strings from the
 server, things like "Connection closed" or "Server restarted".
 Basically, the things users are not supposed to change on their own.
 This means that the default command set is *not* translated. The reason
-for this is that commands are *intended* to be modified by users.
+for this is that commands are *intended* to be modified by users. Adding
+*i18n* code to commands tend to add complexity to code that will be
+changed anyway. One of the goals of Evennia is to keep the
+user-changeable code as clean and easy-to-read as possible.
 
 Changing server language
 ------------------------

docs/sphinx/source/wiki/Licensing.rst

@@ -6,19 +6,19 @@ 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>`_.
 
-You should read the full license file to know what it says exactly, but
+You should read the full license text to know what it says exactly, but
 here are some answers to common questions.
 
 Q: When creating a game using Evennia, what does the licence permit me
 to do with it?
 -------------------------------------------------------------------------------------
 
-**A:** It's your own world to do with as you please! To summarize, a MUD
+**A:** It's your own game world to do with as you please! To summarize,
-world you create using Evennia (i.e. the files you create in ``game``)
+a MUD world you create using Evennia (i.e. the files you create in
-falls under **§6** of the license (it's a sort of "library"). So your
+``/game/``) falls under **§6** of the license (it's a sort of
-game world and all its contents belongs to you (as it should be). Keep
+"library"). So your game world and all its contents belongs to you (as
-it to yourself or re-distribute it under any license of your choice - or
+it should be). Keep it to yourself or re-distribute it under any license
-sell it and become filthy rich for all we care.
+of your choice - or sell it and become filthy rich for all we care.
 
 Q: I have modified Evennia itself, what does the license say about that?
 ------------------------------------------------------------------------
@@ -30,18 +30,20 @@ is referred to as "The Package, Standard version" in the license.
    you don't *have* to do anything to appease the license. Regardless,
    we'd of course appreciate it if you submitted bugs/fixes to us so
    Evennia becomes more complete!.
--  If you made other modifications or added new features to the server,
+-  If you made bigger modifications or added new features to the server,
    that's also ok, but falls under **§3** - you must make a clear note
-   of the changes as well as put the changes into the public domain or
+   of the changes you did and put those changes into public domain
-   make separate arrangements with us (since it's then no longer a
+   (since it's then no longer a "Standard version"). You could also
-   "Standard version"). Of course, if you plan to add new features to
+   contact the Evennia developers to make separate arrangements ... but
-   the server, the easiest way to do so is to simply become an Evennia
+   of course, if you plan to add new features to the server, the easiest
-   developer!
+   way to do so is to simply become an Evennia developer!
 
-Q: Can I re-distribute Evennia along with my custom game implementation?
+Q: Can I re-distribute the Evennia server package along with my custom
-------------------------------------------------------------------------
+game implementation?
+-------------------------------------------------------------------------------------------
 
 **A:** Sure. This is covered in **§4** - just package the "Standard
-version" (that is, the one you download from us) with your package. Make
+version" (that is, the one you download from us) with your game files.
-sure to include the original license and disclaimers and note where
+Also make sure to include the original license and disclaimers and note
-users may get it if they want to download it of their own.
+where users may get "plain" Evennia should they want to download it of
+their own.

docs/sphinx/source/wiki/Links.rst

@@ -32,6 +32,9 @@ Third-party Evennia links
 -  `Evennia on
    PyPi <http://pypi.python.org/pypi/Evennia%20MUD%20Server/Alpha>`_
 
+-  `Avaloria <http://code.google.com/p/avaloria/>`_ (MUD under
+   development, using Evennia)
+
 General mud/game development ideas and discussions
 --------------------------------------------------
 

docs/sphinx/source/wiki/Objects.rst

@@ -23,7 +23,7 @@ Here's how to define a new Object typeclass in code:
         """
         This creates a simple rose object        
         """    
-        at_object_creation(self):
+        def at_object_creation(self):
             "this is called only once, when object is first created"
             # add a persistent attribute 'desc' to object.
             self.db.desc = "This is a pretty rose with thorns."
@@ -44,20 +44,23 @@ To create a new object in code, use the method
     from src.utils import create
     new_rose = create.create_object("game.gamesrc.objects.flowers.Rose", key="MyRose")
 
-(You have to give the full path to the class in this case.
+(You have to give the full path to the class in this case -
 ``create.create_object`` is a powerful function that should be used for
-all coded creating. Check out the module for more info on which
+all coded creating, for example if you create your own command that
-arguments you can give the function.)
+creates some objects as it runs. Check out the ``src.utils.create``
+module for more info on which arguments you can give the function.)
 
-This particular class doesn't really do much, all it does it make sure
+This particular Rose class doesn't really do much, all it does it make
-the attribute ``desc``(which is what the ``look`` command looks for) is
+sure the attribute ``desc``(which is what the ``look`` command looks
-pre-set. You could just as well do the same with the ``@describe``
+for) is pre-set, which is pretty pointless since you will usually want
-command. The ``Object`` typeclass offers many more hooks that is
+to change this at build time (using the ``@describe`` command). The
-available to use though. Look at the ``Object`` class in
+``Object`` typeclass offers many more hooks that is available to use
-``game/gamesrc/objects/baseobjects.py`` to orient yourself. If you
+though - see next section.
-define a new Object class (inheriting from the base one), and wants that
+
-to be the default instead, set ``BASE_OBJECT_TYPECLASS`` in
+If you define a new Object class (inheriting from the base one), and
-``settings.py`` to point to your new class.
+wants the default create command (``@create``) to default to that
+instead, set ``BASE_OBJECT_TYPECLASS`` in ``settings.py`` to point to
+your new class.
 
 Properties and functions on Objects
 -----------------------------------
@@ -67,36 +70,41 @@ Beyond those properties assigned to all
 following custom properties:
 
 -  ``aliases`` - a list of alternative names for the object. Aliases are
-   stored database objects, but the ``aliases`` property receives and
+   stored in the database and can be searched for very fast. The
-   returns lists - so assign to it like normal, e.g.
+   ``aliases`` property receives and returns lists - so assign to it
-   ``obj.aliases=['flower', 'red blossom']``
+   like normal, e.g. ``obj.aliases=['flower', 'red blossom']``
--  ``location`` - a reference to the object currently storing this
+-  ``location`` - a reference to the object currently containing this
    object.
 -  ``home`` is a backup location. The main motivation is to have a safe
    place to move the object to if its ``location`` is destroyed. All
-   objects should usually have a home location for this reason.
+   objects should usually have a home location for safety.
 -  ``destination`` - this holds a reference to another object this
    object links to in some way. Its main use is for
    `Exits <Objects#Exits.html>`_, it's otherwise usually unset.
 -  ``nicks`` - as opposed to aliases, a `Nick <Nicks.html>`_ holds a
    convenient nickname replacement for a real name, word or sequence,
-   only valid for this object. Nicks are stored in the database and are
+   only valid for this object. This mainly makes sense if the Object is
-   a bit more complex than aliases since they have a *type* that defines
+   used as a game character - it can then store briefer shorts, example
-   where Evennia tries to do the substituion. Use nicks.get(alias, type)
+   so as to quickly reference game commands or other characters. Nicks
-   to get a nick, or nicks.add(alias, realname) to add a new one.
+   are stored in the database and are a bit more complex than aliases
+   since they have a *type* that defines where Evennia tries to do the
+   substituion. In code, use nicks.get(alias, type) to get a nick, or
+   nicks.add(alias, realname) to add a new one.
 -  ``player`` - this holds a reference to a connected
    `Player <Players.html>`_ controlling this object (if any). Note that
    this is set also if the controlling player is *not* currently online
-   - to test if a server is online, use ``has_player`` instead.
+   - to test if a player is online, use the ``has_player`` property
+   instead.
 -  ``sessions`` - if ``player`` field is set *and the player is online*,
    this is a list of all active sessions (server connections) to contact
-   them through.
+   them through (it may be more than one if multiple connections are
+   allowed in settings).
 -  ``permissions`` - a list of `permission strings <Locks.html>`_ for
-   defining access rights.
+   defining access rights for this Object.
--  ``has_player`` - a shorthand for checking if an online player is
+-  ``has_player`` - a shorthand for checking if an *online* player is
    currently connected to this object.
--  ``contents`` - this is a list referencing all objects 'inside' this
+-  ``contents`` - this returns a list referencing all objects 'inside'
-   object, that is which has this object set as their ``location``.
+   this object (i,e. which has this object set as their ``location``).
 -  ``exits`` - this returns all objects inside this object that are
    *Exits*, that is, has the ``destination`` property set.
 
@@ -113,8 +121,11 @@ headers in ``src/objects/models.py`` for arguments and more details.
 -  ``msg`` - this function is used to send messages from the server to a
    player connected to this object.
 -  ``msg_contents`` - calls ``msg`` on all objects inside this object.
--  ``search`` - this is a convenient way to search for a specific
+-  ``search`` - this is a convenient shorthand to search for a specific
-   object, at a given location or globally.
+   object, at a given location or globally. It's mainly useful when
+   defining commands (in which case the object executing the command is
+   named ``caller`` and one can do ``caller.search()`` to find objects
+   in the room to operate on).
 -  ``execute_cmd`` - Lets the object execute the given string as if it
    was given on the command line.
 -  ``move_to`` - perform a full move of this object to a new location.
@@ -127,11 +138,12 @@ headers in ``src/objects/models.py`` for arguments and more details.
 -  ``delete`` - deletes this object, first calling ``clear_exits()`` and
    ``clear_contents()``.
 
-Objects also define a host of *hook methods* beyond
+The Object Typeclass defines many more *hook methods* beyond
-``at_object_creation``. When implementing your custom objects, you will
+``at_object_creation``. Evennia calls these hooks at various points.
-inherit from the base parent and overload these hooks with your own
+When implementing your custom objects, you will inherit from the base
-custom code. See ``game.gamesrc.baseobjects`` for an updated list of all
+parent and overload these hooks with your own custom code. See
-the available hooks.
+``game.gamesrc.baseobjects`` for an updated list of all the available
+hooks.
 
 Subclasses of *Object*
 ----------------------
@@ -140,8 +152,9 @@ There are three special subclasses of *Object* in default Evennia -
 *Characters*, *Rooms* and *Exits*. The reason they are separated is
 because these particular object types are fundamental, something you
 will always need and in some cases requires some extra attention in
-order to be recognized by the game engine. In practice they are all
+order to be recognized by the game engine (there is nothing stopping you
-pretty similar to the base Object. You will import them all from
+from redefining them though). In practice they are all pretty similar to
+the base Object. You will import them all from
 ``game.gamesrc.objects.baseobjects``.
 
 Characters
@@ -154,9 +167,9 @@ attribute. A ``Character`` object must have a `Default
 Commandset <Commands#Command_Sets.html>`_ set on itself at creation, or
 the player will not be able to issue any commands! If you just inherit
 your own class from ``baseobjects.Character`` and make sure the parent
-methods are run you should not have to worry about this. You can change
+methods are not stopped from running you should not have to worry about
-the default typeclass assigned to new Players in your settings with
+this. You can change the default typeclass assigned to new Players in
-``BASE_CHARACTER_TYPECLASS``.
+your settings with ``BASE_CHARACTER_TYPECLASS``.
 
 Rooms
 ~~~~~

docs/sphinx/source/wiki/PortalAndServer.rst

@@ -5,11 +5,16 @@ Evennia consists of two processes, known as *Portal* and *Server*. They
 can be controlled from inside the game or from the command line as
 described `here <StartStopReload.html>`_.
 
+If you are new to the concept, the main purpose of separating the two is
+to have players connect to the Portal but keep the MUD running on the
+Server. This way one can restart/reload the game (the Server part)
+without Players getting disconnected.
+
 https://2498159658166209538-a-1802744773732722657-s-sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia*server*portal.png
 
 The Server and Portal are glued together via an AMP (Asynchronous
 Messaging Protocol) connection. This allows the two programs to
-communicate.
+communicate seamlessly.
 
 Portal and Server Sessions
 --------------------------

docs/sphinx/source/wiki/Scripts.rst

@@ -43,11 +43,12 @@ database model). Scripts have no in-game representation and you cannot
 define them with any default commands. They have to be created in python
 code modules and imported from there into the game.
 
-The vast majority of scripts are always run 'on'
+Scripts may run directly 'on' `Objects <Objects.html>`_, affecting that
-`Objects <Objects.html>`_ affecting that object and maybe its
+object and maybe its surroundings or contents. An alternative way to
-surroundings or contents. Scripts unrelated to objects are called
+affect many objects (rather than one script per object) is to create one
-*Global* scripts and could handle things like game-time, weather and
+Script and have it call all objects that "subscribe" to it at regular
-other tickers.
+intervals (a *ticker*). Scripts not defined directly 'on' objects are
+called *Global* scripts.
 
 Custom script modules are usually stored in ``game/gamesrc/scripts``. As
 a convenience you can inherit all scripts from
@@ -64,7 +65,7 @@ can try it out with an example script:
 This should cause some random messages. The ``/stop`` switch will kill
 the script again.
 
-In code, you add scripts to `Objects <Objects.html>`_ and the script can
+In code, if you add scripts to `Objects <Objects.html>`_ the script can
 then manipulate the object as desired. The script is added to the
 object's *script handler*, called simply ``scripts``. The handler takes
 care of all initialization and startup of the script for you.
@@ -73,11 +74,26 @@ care of all initialization and startup of the script for you.
 
     # adding a script to an existing object 'myobj'
      myobj.scripts.add("game.gamesrc.scripts.myscripts.CoolScript")
+     # alternative way
+     from src.utils.create import create_script
+     create_script("game.gamesrc.scripts.myscripts.CoolScript", obj=myobj)
 
-The ``myobj.scripts.add()`` method also takes an argument *key* that
+The creation method(s) takes an optional argument *key* that allows you
-allows you to name your script uniquely before adding it. This is not
+to name your script uniquely before adding it. This can be useful if you
-necessary, but is useful if you add many scripts of the same class and
+add many scripts of the same type and later plan to use
-later plan to use ``myobj.scripts.delete`` to remove individual scripts.
+``myobj.scripts.delete`` to remove individual scripts.
+
+You can create global scripts with ``src.utils.create.create_script()``.
+Just don't supply an object to store it on.
+
+::
+
+    # adding a global script
+     from src.utils.create import create_script
+     create_script("game.gamesrc.scripts.globals.MyGlobalEconomy", key="economy", obj=None)
+
+Assuming the Script ``game.gamesrc.scripts.globals.MyGlobalEconomy``
+exists, this will create and start it as a global script.
 
 Properties and functions defined on Scripts
 -------------------------------------------
@@ -85,12 +101,13 @@ Properties and functions defined on Scripts
 It's important to know the variables controlling the script before one
 can create one. Beyond those properties assigned to all typeclassed
 objects (see `Typeclasses <Typeclasses.html>`_), such as ``key``,
-``db``, ``ndb`` etc, all Scripts also has the following properties:
+``db``, ``ndb`` etc, all Scripts also have the following properties:
 
 -  ``desc`` - an optional description of the script's function. Seen in
-   listings.
+   script listings.
 -  ``interval`` - how often the script should run. If ``interval == 0``
-   (default), it runs forever (it will not accept a negative value).
+   (default), it runs forever, without any repeating (it will not accept
+   a negative value).
 -  ``start_delay`` - (bool), if we should wait ``interval`` seconds
    before firing for the first time or not.
 -  ``repeats`` - How many times we should repeat, assuming
@@ -102,8 +119,9 @@ There is one special property:
 
 -  ``obj`` - the `Object <Objects.html>`_ this script is attached to (if
    any). You should not need to set this manually. If you add the script
-   to the Object with ``myobj.scripts.add(myscriptpath)``, the ``obj``
+   to the Object with ``myobj.scripts.add(myscriptpath)`` or give
-   property will be set to ``myobj`` for you.
+   ``myobj`` as an argument to the ``utils.create.create_script``
+   function, the ``obj`` property will be set to ``myobj`` for you.
 
 It's also imperative to know the hook functions. Normally, overriding
 these are all the customization you'll need to do in Scripts. You can
@@ -129,6 +147,10 @@ find longer descriptions of these in ``gamesrc/scripts/basescript.py``.
    before calling.
 -  ``at_stop()`` - this is called when the script stops for whatever
    reason. It's a good place to do custom cleanup.
+-  ``at_server_reload()`` - this is called whenever the server is
+   warm-rebooted (e.g. with the ``@reload`` command). It's a good place
+   to save non-persistent data you might want to survive a reload.
+-  ``at_server_shutdown()`` - this is called on a full systems shutdown.
 
 Running methods (usually called automatically by the engine, but
 possible to also invoke manually)
@@ -140,16 +162,17 @@ possible to also invoke manually)
    script from a handler will stop it auomatically. ``at_stop()`` will
    be called.
 -  ``pause()`` - this pauses a running script, rendering it inactive,
-   but not deleting it. Timers are saved and can be resumed. This is
+   but not deleting it. All properties are saved and timers can be
-   called automatically when the server reloads. No hooks are called -
+   resumed. This is called automatically when the server reloads. No
+   hooks are called - as far as the script knows, it never stopped -
    this is a suspension of the script, not a change of state.
 -  ``unpause()`` - resumes a previously paused script. Timers etc are
    restored to what they were before pause. The server unpauses all
    paused scripts after a server reload. No hooks are called - as far as
    the script is concerned, it never stopped running.
 -  ``time_until_next_repeat()`` - for timed scripts, this returns the
-   time in seconds until it next fires. Returns None if not a timed
+   time in seconds until it next fires. Returns ``None`` if
-   script.
+   ``interval==0``.
 
 Example script
 --------------
@@ -188,27 +211,19 @@ above. Here we put it on a room called ``myroom``:
 
 ::
 
-    # Assuming Script is found in game/gamesrc/scripts/weather.py
     myroom.scripts.add(weather.Weather)
 
+In code you can also use the create function directly if you know how to
+locate the room you want:
+
+::
+
+    from src.utils.create import create_script
+    create_script('game.gamesrc.scripts.weather.Weather', obj=myroom)
+
 Or, from in-game, use the ``@script`` command:
 
 ::
 
     @script here = weather.Weather
 
-Global scripts
---------------
-
-You can create scripts that are not attached to a given object -
-*Global* scripts. You can create such a script with
-``src.utils.create.create_script()`` by refrainnig from supplying an
-object to store it on.
-
-::
-
-    from src.utils.create import create_script
-      create_script(globals.MyGlobalEconomy, key="economy", obj=None)
-
-Assuming ``game.gamesrc.scripts.global.MyGlobalEconomy`` can be found,
-this will create and start it as a global script.

docs/sphinx/source/wiki/Typeclasses.rst

@@ -16,19 +16,21 @@ Python object management for free.
 
 There are three main game 'entities' in Evennia that are what we call
 *typeclassed*. They are `Players <Players.html>`_,
-`Objects <Objects.html>`_ and `Scripts <Scripts.html>`_. As said, this
+`Objects <Objects.html>`_ and `Scripts <Scripts.html>`_. This means that
-basically means that they are (almost) normal Python classes that hide
+they are *almost* normal Python classes - they behave and can be
-underlying database models ...
+inherited from etc just like normal Python classes except that for
+storing data they hide underlying database models ...
 
 ... and that's basically all you *really* need to know about how
 typeclasses work behind the scenes.
 
-To work with them you should however know that all the listed game
+To work with them you should however know that Objects, Scripts and
-entities inherit a common interface from the typeclass system,
+Players all inherit a lot of helper methods from the typeclass system,
-properties you can *always* expect a typeclassed entity to have *beyond*
+properties you can *always* expect a typeclassed entity to have. In
-the more specialized properties unique to each sub-type. Typeclasses
+addition to these, each of the three sub types also offer a host of help
-also do some special things with their in-built class methods that you
+methods and properties you can use. The database handling is hidden, but
-shouldn't edit.
+it means that typeclasses do some special things with their in-built
+class methods that you shouldn't edit.
 
 Properties available to all typeclassed entities (Players, Objects,
 Scripts)