docs: Adding missing rest pages to mercurial.

docs/sphinx/source/wiki/AddingCommandTutorial.rst

@@ -0,0 +1,114 @@
+Adding a new command - a step by step guide
+===========================================
+
+This is a quick first-time tutorial expanding on the
+`Commands <Commands.html>`_ documentation.
+
+Let's assume you have just downloaded Evennia and want to try to add a
+new command. This is the fastest way to do it.
+
+Tell Evennia where to look for custom commands/cmdsets
+------------------------------------------------------
+
+We will tell Evennia that you want to override the default cmdset with
+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.
+   You can rename them as you please, but in this example we assume you
+   don't.
+#. Edit ``game/settings.py``, adding the following line:
+
+    ``CMDSET_DEFAULT="game.gamesrc.commands.cmdset.DefaultCmdSet"``
+
+Evennia will now look for default commands in the ``DefaultCmdSet``
+class of your newly copied module. You only need to do this once.
+
+Creating a custom command
+-------------------------
+
+#. Edit your newly copied ``game/gamesrc/commands/command.py``. This
+   template already imports everything you need.
+#. Create a new class in ``command.py`` that inherits from
+   ``MuxCommand``. Let's call it ``CmdEcho`` in this example.
+#. Set the class variable ``key`` to a good command name, like ``echo``.
+#. Set the ``locks`` property on the command to a suitable
+   [Locks#Defining\_locks lockstring]. If you are unsure, use
+   ``"cmd:all()"``.
+#. Give your class a useful *\_doc\_* string, this acts as the help
+   entry for the command.
+#. Define a class method ``func()`` that does stuff. Below is an example
+   how it all could look.
+
+::
+
+    # file game/gamesrc/commands/command.py
+    #[...]
+    class CmdEcho(MuxCommand):
+        """
+        Simple command example
+
+        Usage: 
+          echo <text>
+
+        This command simply echoes text back to the caller.
+        """
+
+        key = "echo"
+        locks = "cmd:all()"
+
+        def func(self):
+            "This actually does things" 
+            if not self.args:
+                self.caller.msg("You didn't enter anything!")           
+            else:
+                self.caller.msg("You gave the string: '%s'" % self.args)        
+
+Adding the Command to a Cmdset
+------------------------------
+
+The command is not available to use until it is part of a Command Set.
+In this example we will go the easiest route and add it to the default
+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``.
+#. Add a line ``self.add(echo.CmdEcho())`` to ``DefaultCmdSet``, in the
+   ``at_cmdset_creation`` method (the template tells you where). This is
+   approximately how it should look at this point:
+
+::
+
+    # file gamesrc/commands/examples/cmdset.py
+    #[...]
+    from game.gamesrc.commands import echo
+    #[...]
+    class DefaultCmdSet(default_cmds.DefaultCmdSet):
+        
+        key = DefaultMUX
+
+        def at_cmdset_creation(self):
+
+            # this first adds all default commands
+            super(DefaultSet, self).at_cmdset_creation()
+
+            # all commands added after this point will extend or 
+            # overwrite the default commands.       
+            self.add(echo.CmdEcho())
+
+#. Reboot/restart Evennia (``@reload`` from inside the game). You should
+   now be able to use your new ``echo`` command from inside the game.
+   Use ``help echo`` to see the documentation for the command.
+
+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
+you want to overload existing default commands (such as ``look`` or
+``get``), just add your new command with the same key as the old one -
+it will overload the default one. Just remember that you must
+``@reload`` the server before you see any changes.