Added Sphinx (reST-style) conversion of Evennia documentation to docs/. This is an auto-generated conversion directly from the Wiki, so it's not custom-written in any way (will also make it easy to update). You need Sphinx to compile the sources into fancy pages. Supporting sphinx is to make documentation easier to print and view offline. Currently no sphinx src-code viewing is activated by default, it gives too many spurious errors (the converters are in the repo though if you're interested in experimenting). So for offline autodocs, doxygen is still to recommend.

docs/sphinx/source/wiki/Players.rst

@@ -0,0 +1,121 @@
+<wiki:toc max\_depth
+
+"3" />
+======
+
+Players=
+
+All users (in the sense of actual people) connecting to Evennia are
+doing so through an object called *Player*. The Player object has no
+in-game representation; rather it is the out-of-character representation
+of the user. The Player object is what is chatting on
+`Channels <Communications.html>`_. It is also a good place to store
+`Permissions <Locks.html>`_ to be consistent between different in-game
+characters, configuration options, account info and other things related
+to the user. Players are `TypeClassed <Typeclasses.html>`_ entities and
+can store a `CmdSet <Commands.html>`_ of their own for OOC-type
+commands.
+
+If you are logged in into default Evennia, you can use the ``@ooc``
+command to leave your current `Character <Objects.html>`_ and go into
+OOC mode. You are quite limited in this mode, basically it works like a
+simple chat program. It acts as a staging area for switching between
+Characters (if your game supports that) or as a safety mode if your
+Character gets deleted. . Use ``@ic`` to switch back "into" your
+character. Also note that the Player object can have a different set of
+`Permissions <Locks#Permissions.html>`_ from the Character they control
+(in the first character you create permissions for Player and Character
+are the same, however).
+
+How to create your own Player types
+-----------------------------------
+
+You will usually not want more than one Player typeclass for all new
+players (but you could in principle create a system that changes a
+player's typeclass dynamically).
+
+An Evennia Player is, per definition, a Python class that includes
+``src.players.player.Player`` among its parents (if you are aware of how
+`Typeclasses <Typeclasses.html>`_ work, this is a typeclass linked to
+the ``PlayerDB`` database model). There is no equivalence to this in the
+``game/gamesrc`` folder, you need to inherit from the base object
+directly.
+
+Here's how to define a new Player typeclass in code:
+
+::
+
+    from src.players.player import Playerclass ConfigPlayer(Player):     """     This creates a Player with some configuration options     """             at_player_creation(self):         "this is called only once, when player is first created"        self.db.real_name = None      # this is set later         self.db.real_address = None   #        ''        self.db.config_1 = True       # default config         self.db.config_2 = False      #       "         self.db.config_3 = 1          #       "        # ... whatever our game needs to know
+
+There is no pre-made folder in ``game/gamesrc`` to store custom player
+typeclasses. Either make your own folder or store it in
+``gamesrc/objects`` (remember that if you make your own folder you need
+to add an empty ``__init__.py`` file so that you can import the file
+later). To change which object becomes the Player object for new
+players, set the variable ``BASE_PLAYER_TYPECLASS`` in your
+``settings.py`` file.
+
+Properties on Players
+---------------------
+
+Beyond those properties assigned to all typeclassed objects (see
+`Typeclasses <Typeclasses.html>`_), the Player also has the following
+custom properties:
+
+-  ``user`` - a unique link to a ``User`` Django object, representing
+   the logged-in user.
+-  ``character`` - a reference to an associated *Character*-type
+   `Object <Objects.html>`_.
+-  ``obj`` - an alias for ``character``.
+-  ``name`` - an alias for ``user.username``
+-  ``sessions`` - a list of all connected Sessions (physical
+   connections) this object listens to.
+-  ``is_superuser`` (bool: True/False) - if this player is a superuser.
+
+Special handlers:
+
+-  ``cmdset`` - This holds all the current `Commands <Commands.html>`_
+   of this Player. By default these are the commands found in the cmdset
+   defined by ``settings.CMDSET_OOC``.
+-  ``nicks`` - This stores and handles `Nicks <Nicks.html>`_, in the
+   same way as nicks it works on Objects. For Players, nicks are
+   primarily used to store custom aliases for
+   `Channels <Communications#Channels.html>`_.
+
+How it all hangs together
+-------------------------
+
+Looking at the above list, it's clear there are more to ``Player``s than
+what first meets the eye.
+
+What happens when a person connects to Evennia and logs in is that they
+log in as a ``User`` object. This is a Django object that knows all
+about keeping track of authentication - it stores the login name
+(``username``), password, e-mail etc.
+
+We can't change ``User`` very much unless we want to start digging down
+into Django source code (and we don't). Django however allows another
+model (technically called a *profile*) to reference the User for
+customization. This is our ``Player`` object. There is a one-to-one
+relationship between ``User`` and Player, so we have tried to completely
+hide the ``User`` interface throughout Evennia and left you to only have
+to deal with ``Player``.
+
+So for all purposes, ``Player`` represents the OOC existence of a person
+logged into Evennia. You e.g. connect to
+`Channels <Communications.html>`_ using your Player identity. The Player
+object may store configurations and follows you wherever you go. You
+will however never see the Player object in-game. This is handled by a
+*Character*, a type of `Object <Objects.html>`_ connected to the
+``character`` property in the list above.
+
+So why don't we just use ``Player`` to walk around with too? The main
+reason for this is flexibility. Your Player object won't change, but
+your character *might*. By separating the two you could easily implement
+a game where you can ``swap`` between different *Character* objects. All
+you'd need to do is change the ``character`` property to point to
+another suitable object (and change the values of the ``player``
+property on the affected objects).
+
+So the structure looks like ``User - Player - Character``, where the
+last two are typeclassed, customizable objects.