Updated ReST documentation

docs/sphinx/source/wiki/BuilderDocs.rst

@@ -12,14 +12,16 @@ Building basics
 -  `Adding colour <Colours.html>`_
 -  `Customizing the connection screen <ConnectionScreen.html>`_
 
-World creation
+Advanced building and World building
---------------
+------------------------------------
 
 `Overview of batch processors <BatchProcessors.html>`_
 
 -  `Batch-command processor <BatchCommandProcessor.html>`_
 -  `Batch-code processor <BatchCodeProcessor.html>`_
 
+`Adding zones <Zones.html>`_
+
 The Tutorial world
 ------------------
 

docs/sphinx/source/wiki/Commands.rst

@@ -29,7 +29,7 @@ into many different command sets. By storing the command set on a
 character object you will make all the commands therein available to use
 by that character. You can also store command sets on normal objects if
 you want users to be able to use the object in various ways. Consider a
-"Tree" object with a cmdset defining the commands *climb* and *shop
+"Tree" object with a cmdset defining the commands *climb* and *chop
 down*. Or a "Clock" with a cmdset containing the single command *check
 time*.
 
@@ -45,6 +45,21 @@ class that knows all the mux-like syntax like ``/switches``, splitting
 by "=" etc. Below we'll avoid mux-specifics and use the base ``Command``
 class directly.
 
+::
+
+    # basic Command definition
+    from game.gamesrc.commands.basecommand import Command
+    class MyCmd(Command):
+       """
+       This is the help-text for the command
+       """
+       key = "mycommand" 
+       locks = "cmd:all()" # this lock means cmd is available to all
+       def parse(self):
+           # parsing the command line here
+       def func(self):
+           # executing the command here
+
 You define a new command by assigning a few class-global properties on
 your inherited class and overloading one or two hook functions. The full
 gritty mechanic behind how commands work are found towards the end of
@@ -258,7 +273,8 @@ snippet:
 
     @py self.cmdset.add('game.gamesrc.commands.mycmdset.MyCmdSet')
 
-This will stay with you until you shut down the server or run
+This will stay with you until you ``@reset`` or ``@shutdown`` the
+server, or you run
 
 ::
 
@@ -602,6 +618,10 @@ non-commands as text input.
    subscribing to - Default is to relay the command's argument to that
    channel. Such commands are created by the Comm system on the fly
    depending on your subscriptions.
+-  New session connection ('cmdhandler.CMD\_LOGINSTART'). This command
+   name should be put in the ``settings.CMDSET_UNLOGGEDIN``. Whenever a
+   new connection is established, this command is always called on the
+   the server (default is to show the login screen).
 
 Below is an example of redefining what happens when the player don't
 give any input (e.g. just presses return). Of course the new system

docs/sphinx/source/wiki/Contributing.rst

@@ -29,11 +29,13 @@ changes to that. .
 #. If you are logged in, you should see a button named *Create a Clone*.
    Click that.
 #. You are asked to fill in a few fields. Name your clone repository
-   something snazzy. Give a brief summary, like "my repo for messing
+   something useful, like "Johns-evennia-fixes". Give a brief summary,
-   around with Evennia". Accept.
+   like "my repo for contributing to Evennia". Accept.
-#. Your new repo is created. This is actually your own mini-version of
+#. Your new repo is created. You should see it appear in the `clone-repo
-   the Evennia page! Go to your checkout page and use the command there
+   list <https://code.google.com/p/evennia/source/clones.html>`_. This
-   to get a local copy of your clone to your computer.
+   is actually your own mini-version of the Evennia page! Choose your
+   repo and you will find it has its own Checkout page. Use the command
+   there to get a local copy of your clone to your computer.
 #. Code away on your computer, fixing bugs or whatnot (you can be
    offline for this). Commit your code to your local clone as you work,
    as often as you like.
@@ -53,9 +55,9 @@ deemed good, pick and merge your work into Evennia proper.
 Contributing with Patches
 -------------------------
 
-It's recommended to use a clone repository as described above, but for
+To help with Evennia development it's recommended to do so using a clone
-small, well isolated things you are also welcome to submit your
+repository as described above. But for small, well isolated fixes you
-suggested Evennia fixes/addendums as
+are also welcome to submit your suggested Evennia fixes/addendums as
 `patches <https://secure.wikimedia.org/wikipedia/en/wiki/Patch_(computing).html>`_
 if you like. Depending on what fits best, post your patch to the `issue
 tracker <https://code.google.com/p/evennia/issues/list.html>`_ or to the

docs/sphinx/source/wiki/DefaultCommandHelp.rst

@@ -465,12 +465,12 @@ module <https://code.google.com/p/evennia/source/browse/src/commands/default/bui
 ::
 
     find objects    Usage:
-          @find[/switches] <name or dbref or *player> [= dbrefmin[ dbrefmax]]    Switches:
+          @find[/switches] <name or dbref or *player> [= dbrefmin[-dbrefmax]]    Switches:
           room - only look for rooms (location=None)
           exit - only look for exits (destination!=None)
           char - only look for characters (BASE_CHARACTER_TYPECLASS)    Searches the database for an object of a particular name or dbref.
         Use *playername to search for a player. The switches allows for
-        limiting matches to certain game entities. Dbrefmin and dbrefmax 
+        limiting object matches to certain game entities. Dbrefmin and dbrefmax 
         limits matches to within the given dbrefs, or above/below if only one is given.
 
 @help
@@ -1670,6 +1670,21 @@ Unloggedin
 `Link to Python
 module <https://code.google.com/p/evennia/source/browse/src/commands/default/unloggedin.py.html>`_
 
+**unloggedin*look*command
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  ``key`` = ``__unloggedin_look_command``
+-  ``aliases`` = ``look, l``
+-  `locks <Locks.html>`_ = ``cmd:all()``
+-  `helpcategory <HelpSystem.html>`_ = ``Unloggedin``
+-  `Auto-help <HelpSystem#Auto-help%3C/i%3Esystem.html>`_
+   (``__doc__ string``) =
+
+::
+
+    This is an unconnected version of the look command for simplicity.     This is called by the server and kicks everything in gear. 
+        All it does is display the connect screen.
+
 connect
 ~~~~~~~
 
@@ -1717,21 +1732,6 @@ help
     This is an unconnected version of the help command,
         for simplicity. It shows a pane or info.
 
-look
-~~~~
-
--  ``key`` = ``look``
--  ``aliases`` = ``l``
--  `locks <Locks.html>`_ = ``cmd:all()``
--  `helpcategory <HelpSystem.html>`_ = ``Unloggedin``
--  `Auto-help <HelpSystem#Auto-help%3C/i%3Esystem.html>`_
-   (``__doc__ string``) =
-
-::
-
-    This is an unconnected version of the look command for simplicity. 
-        All it does is re-show the connect screen.
-
 quit
 ~~~~
 

docs/sphinx/source/wiki/TutorialWorldIntroduction.rst

@@ -2,7 +2,7 @@ Tutorial World Introduction
 ===========================
 
 The *Tutorial World* is, quite simply, a small example of Evennia usage
-for you to learn from. It's also a functioning (if small) game - a small
+for you to learn from. It's also a functioning (if small) game - a
 single-player quest area with some 20 rooms that you can explore on your
 quest to find a mythical weapon.
 
@@ -45,15 +45,79 @@ 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
-will end up back in Limbo with a new exit called ``tutorial``. You can
+will end up back in Limbo with a new exit called ``tutorial``.
-also use the ``/interactive`` switch of ``@batchcommand`` to be able to
+
-slowly go through each step of building the world in detail.
+::
+
+    @batchcommand/interactive contrib.tutorial_world.build
+
+will allow you to step through the building process at your own pace to
+see what happens in detail.
 
 To play the tutorial "correctly", you should *not* do so as superuser.
 The reason for this is that many game systems ignore the presence of a
 superuser and will thus not work as normal. Create a new, non-superuser
-character instead (as superuser you can of course examine things "under
+character for playing instead. As superuser you can of course examine
-the hood" later if you want).
+things "under the hood" later if you want.
+
+Gameplay
+--------
+
+*To get into the mood of this miniature quest, imagine you are an
+adventurer out to find fame and fortune. You have heard rumours of an
+old castle ruin by the coast. In its depth a warrior princess was buried
+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
+and rain screaming in your face you stand where the moor meets the sea
+along a high, rocky coast ...*
+
+Look at everything.
+
+Some objects are interactive in more than one way. Use the normal
+``help`` command to get a feel for which commands are available at any
+given time. (use the command ``tutorial`` to get insight behind the
+scenes of the tutorial).
+
+In order to fight, you need to first find some type of weapon.
+
+-  *slash* is a normal attack
+-  *stab* launches an attack that makes more damage but has a lower
+   chance to hit.
+-  *defend* will lower the chance to taking damage on your enemy's next
+   attack.
+
+You *can* run from a fight that feels too deadly. Expect to be chased
+though.
+
+Being defeated is a part of the experience ...
+
+Uninstall
+---------
+
+Uninstalling the tutorial world basically means deleting all the rooms
+and objects it consists of. First, move out of the tutorial area.
+
+::
+
+    @find tut#01
+     @find tut#17
+
+This should locate the first and last rooms created by ``build.ev`` -
+*Intro* and *Outro*. If you installed normally, everything created
+between these two numbers should be part of the tutorial. Note their
+dbref numbers, for example 5 and 80. Next we just delete all objects in
+that range:
+
+::
+
+    @del 5-80
+
+You will see some errors since some objects are auto-deleted and so
+cannot be found when the delete mechanism gets to them. That's fine. You
+should have removed the tutorial completely once the command finishes.
 
 Notes
 -----

docs/sphinx/source/wiki/Typeclasses.rst

@@ -1,10 +1,23 @@
 Typeclassed objects
 ===================
 
-Several of the the main game 'entities' in Evennia, namely
+How do you represent different objects in a game? What makes a bear
-`Players <Players.html>`_, `Objects <Objects.html>`_ and
+different from a stone, or a character different from a house? How do
-`Scripts <Scripts.html>`_ - are what we call *typeclassed*. This
+you store such differences in the database? One way would be to create
-basically means that they are almost normal Python classes that hide
+new database tables for each type. So a bear would have a database field
+"claws" and the stone would have fields specifying its weight and colour
+... and you'd soon go crazy with making custom database manipulations
+for all infinite combinations.
+
+Evennia instead uses very generic and simple database models and
+"decorates" these with normal Python classes that specify their
+functionality. Using Python classes means you get all the flexibility of
+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
+basically means that they are (almost) normal Python classes that hide
 underlying database models ...
 
 ... and that's basically all you *really* need to know about how