Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-29 12:07:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated rst-docs to match online wiki

Browse source
This commit is contained in:
Griatch 2011-09-14 21:17:50 +02:00
parent f523ce686a
commit 60e980be67
4 changed files with 111 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

53
docs/sphinx/source/wiki/GettingStarted.rst
View file

@ -49,7 +49,7 @@ Evennia:
- 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)
(http://www.activestate.com/activepython/downloads)
**Twisted** (http://twistedmatrix.com)
@ -106,19 +106,22 @@ all you need:
If some or all dependencies are not readily available (for example,
running some flavors of !RedHat/CentOS or an older Debian version) you
can still retrieve them easily by using Python's
can still retrieve them easily by installing and using Python's
`easyinstall <http://packages.python.org/distribute/easy%3Ci%3Einstall.html>`_
or the alternative
`pip <http://www.pip-installer.org/en/latest/index.html>`_:
``easy_install django twisted pil mercurial``
::
easy_install django twisted pil mercurial
::
pip install django twisted pil mercurial
**Windows** users may choose to install
`ActivePython <http://www.activestate.com/activepython>`_ instead of the
usual Python. If ActivePython is installed, you can use
`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:
@ -127,8 +130,10 @@ getting started on Windows:
pypm install Django Twisted PIL Mercurial
}} Another simple alternative (for all platforms) is to set up a
*virtual Python environment* and install to that. This is covered
Another simple alternative (for all platforms) is to set up a *virtual
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
@ -257,6 +262,10 @@ To stop Evennia, do:
python evennia.py stop
See `Running
Evennia <https://code.google.com/p/evennia/wiki/StartStopReload.html>`_
for more advanced options on controlling Evennia's processes.
Step 4: Connecting to the server
--------------------------------
@ -287,9 +296,10 @@ play. You can install South from
available through the normal package distributions, easy\_install, pip,
or pypm (see above notes).
Whenever you see a commit or mailing list message instructing you to run
migrations to update your DB schema, simply do the following from within
the ``evennia/game`` directory:
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:
::
@ -325,17 +335,22 @@ virtual environment in here.
# for Windows:
<path_to_this_place>\bin\activate.bat
In here you can play around and install python packages of any version
without affecting your normal system installation at all. Next we get
all the requirements with *pip*, which comes with virtualenv. This is
the cool bit.
Next we get all the requirements with *pip*, which is included with
virtualenv:
::
pip install django twisted pil
pip install django twisted pil mercurial
(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.)
You can now refer to **Step 1** above and continue on from there to
install Evennia into *mudenv* (you need to get ``subversion`` manually
still, it's not a python program). In the future, just go into the
folder and activate it to make this separate virtual environment
available to Evennia.
install Evennia into *mudenv*. In the future, just go into the folder
and activate it to make this separate virtual environment available to
Evennia.

68
docs/sphinx/source/wiki/HelpSystem.rst
View file

@ -8,7 +8,7 @@ players and staff alike to learn how to use the game's commands as well
as other information pertinent to the game. The help system has many
different aspects, from the normal editing of help entries from inside
the game, to auto-generated help entries during code development using
the *auto-help* system.
the *auto-help system*.
Viewing the help database
-------------------------
@ -31,18 +31,19 @@ Command Auto-help system
One important use of the help system is to teach the use of in-game
commands. Evennia offers a dynamically updated help system for all your
commands, new and old, known simply as the *auto-help* system. Only
commands that you can actually use are picked up by the auto-help
system. That means an admin will see a considerably larger mass of help
topics when using the ``help`` command than a normal player.
commands, new and old, known simply as the *auto-help system*. Only
commands that you and your character can actually currently use are
picked up by the auto-help system. That means an admin will see a
considerably larger amount of help topics than a normal player when
using the ``help`` command.
The auto-help system uses the ``__doc__`` strings of your command
definitions and formats this to a nice-looking help entry. This makes
for a very easy way to keep the help updated - just document your
commands well - updating the help system is just a ``@reload`` away.
There is no need to manually create help database entries for commands;
as long as you keep the docstrings updated your help will be dynamically
updated for you as well.
commands well abd updating the help file is just a ``@reload`` away.
There is no need to manually create and maintain help database entries
for commands; as long as you keep the docstrings updated your help will
be dynamically updated for you as well.
Example (from a module with command definitions):
@ -59,37 +60,38 @@ Example (from a module with command definitions):
help_category = "Building"
...
So the text at the very top of the command class definition is the
class' ``__doc__``-string and what will be shown to users looking for
help. Try to use a consistent formatting between your help strings (for
example, all default commands have ``__doc__``-strings formatted in the
way seen above). You should also supply the ``help_category`` class
property if you can; this helps to group help entries together for
easier finding (if you don't supply a help\_category, "General" will be
assumed).
The text at the very top of the command class definition is the class'
``__doc__``-string and will be shown to users looking for help. Try to
use a consistent format - all default commands are using the structure
shown above. You should also supply the ``help_category`` class property
if you can; this helps to group help entries together for easier finding
(if you don't supply a help\_category, "General" will be assumed).
Other help entries (entries stored in database)
-----------------------------------------------
The *Other help* section you see when using the ``help`` command shows
all help entries that has been manually added to the database by staff.
Instead of being generated from the code by Evennia, these are stored in
the database using a model called *!HelpEntry*. HelpEntry topics are
intended for world-game-info, tutorials and other types of useful
information not directly tied to a command and covered by auto-help.
Not all help entries concern commands. You will also probably need help
entries describing how your particular game is played - its rules, world
descriptions and other types of information not covered by the auto-help
system. Such entries are manually added to the database by staff and
will appear under a heading "Other help" whenever you have any. Instead
of being generated from the code by Evennia, these entries are stored in
the database as a ``HelpEntry``.
A help entry consists of four parts:
- The *topic*. This is the name of the help entry. This is what players
search for when they are looking for help. The topic can contain
spaces.
spaces and also partual matches will be found.
- The *help category*. Examples are *Administration*, *Building*,
*Comms* or *General*. This is an overall grouping of similar help
topics, used by the engine to give a better overview.
- The *text* - the help text itself, of any length. This can also
include *markup*, see below.
- locks - a `lock definition <Locks.html>`_. Help commands check for
access\_types ``examine`` and ``edit``.
- The *text* - the help text itself, of any length.
- locks - a `lock definition <Locks.html>`_. This can be used to limit
access to this help entry, maybe because it's staff-only or otherwise
meant to be restricted. Help commands check for ``access_type``s
``view`` and ``edit``. An example of a lock string would be
``view:perm(Builders)``.
You can create new help entries in code by using
``src.utils.create.create_help_entry()``:
@ -116,11 +118,13 @@ You can change this using a different form of the ``@sethelp`` command:
> @sethelp/add emote, Roleplaying = Emoting is important because ...
If the category *Roleplaying* did not exist it is created and will
appear in the help index. You can, finally, define a lock for the help
entry by following the category with a `lock definition <Locks.html>`_:
If the category *Roleplaying* did not already exist, it is created and
will appear in the help index.
You can, finally, define a lock for the help entry by following the
category with a `lock definition <Locks.html>`_:
::
> @sethelp/add emote, Roleplaying, view:all() = The emote command ...
> @sethelp/add emote, Roleplaying, view:all() = Emoting is important because ...

27
docs/sphinx/source/wiki/PortalAndServer.rst
View file

@ -7,9 +7,9 @@ described `here <StartStopReload.html>`_.
https://2498159658166209538-a-1802744773732722657-s-sites.googlegroups.com/site/evenniaserver/file-cabinet/evennia*server*portal.png
As seen above, the Server and Portal are glued together via an AMP
(Asynchronous Messaging Protocol) connection. This allows the two
programs to communicate.
The Server and Portal are glued together via an AMP (Asynchronous
Messaging Protocol) connection. This allows the two programs to
communicate.
Portal and Server Sessions
--------------------------
@ -24,15 +24,16 @@ Session* is created on the Portal side. This session object looks
different depending on which protocol is used to connect, but all still
have a minimum set of attributes that are generic to all sessions.
These common properties are piped through AMP to the Server, who is now
informed a new connection has been established. On the Server side, a
*Server Session* object is created to represent this. There is only one
type of Server Session. It looks the same regardless of how the Player
connects, it leaves such details up to the Portal.
These common properties are piped from the Portal, through AMP, to the
*Server*, which is now informed a new connection has been established.
On the Server side, a *Server Session* object is created to represent
this. There is only one type of Server Session. It looks the same
regardless of how the Player connects.
From now on, there is a one-to-one match between the Server Session on
one side and the Portal Session on the other. Data arriving to the
Portal Session is sent on to its mirror Server session and vice versa.
one side of the AMP connection and the Portal Session on the other. Data
arriving to the Portal Session is sent on to its mirror Server session
and vice versa.
During certain situations, the portal- and server-side sessions are
"synced" with each other:
@ -43,12 +44,12 @@ During certain situations, the portal- and server-side sessions are
- The Player quits from inside the game, killing the Server Session.
The Server then syncs with the Portal to make sure to close the
Portal connection cleanly.
- The Server is rebooted/reset/shutdown - The Server Sessions are then
- The Server is rebooted/reset/shutdown - The Server Sessions are
copied over ("saved") to the Portal side. When the Server comes back
up, this data is returned by the Portal so the two are again in sync.
This way a Player's login status and other connection-critical things
can survive a server reboot (assuming the Portal is also not stopped,
obviously).
can survive a server reboot (assuming the Portal is not stopped at
the same time, obviously).
Sessionhandlers
---------------

46
docs/sphinx/source/wiki/SessionProtocols.rst
View file

@ -1,8 +1,8 @@
Portal Sessions and Protocols
=============================
*Note: This is considered an advanced topic and not relevant to most
users.*
*Note: This is considered an advanced topic and is mostly of interest to
users planning to implement their own custom client protocol.*
A *Portal Session* is the basic data object representing an external
connection to the Evennia `Portal <PortalAndServer.html>`_ -- usually a
@ -40,17 +40,21 @@ A straight-forward protocol (like Telnet) is assumed to at least have
the following components (although the actual method names might vary):
- ``connectionMade`` - called when a new connection is made. This must
call ``self.init_session()`` with three arguments: an identifier for
the protocol type (e.g. the string 'telnet'), the IP address
connecting, and a reference to the sessionhandler.
call ``self.init_session()`` with three arguments: an *identifier*
for the protocol type (e.g. the string 'telnet' or 'ssh'), the *IP
address* of the client connecting, and a reference to the
*sessionhandler*. The sessionhandler is by convention made available
by storing it on the protocol's *Factory* in
``src/server/portal.py``, see that file for examples. Doing it this
way avoids many possible recursive import issues.
- ``connectionLost`` - called when connection is dropped for whatever
reason. This must call 'self.sessionhandler.disconnect(self)' so the
handler can make sure the disconnect is reported to the rest of the
system.
reason. This must call ``self.sessionhandler.disconnect(self)`` so
the handler can make sure the disconnect is reported to the rest of
the system.
- ``getData`` - data arriving from the player to Evennia. This should
apply whatever custom formatting this protocol needs, then relay the
data to ``self.sessionhandler.data_in(self, msg, data)``.
- sendLine - data from server to Player. This is called by hook
- ``sendLine`` - data from Server to Player. This is called by hook
``data_out()`` below.
See an example of this in
@ -58,8 +62,8 @@ See an example of this in
These might not be as clear-cut in all protocols, but the principle is
there. These four basic components - however they are accessed - links
to the *Session*, which is the actual common interface between the
different low-level protocols and Evennia.
to the *Portal Session*, which is the actual common interface between
the different low-level protocols and Evennia.
Portal Sessions
---------------
@ -85,13 +89,15 @@ be named exactly like this):
- ``disconnect()`` - called when manually disconnecting. Must call the
protocol-specific disconnect method (e.g. ``connectionLost`` above)
- ``data_out(string="", data=None)`` - data from Evennia to player.
``string`` is normally a raw text string with formatting. ``data``
can be a collection of any extra information the server want to give
to the protocol; it's completely up to the Protocol to handle this
(e.g. telnet completely ignores the ``data`` variable). From inside
Evennia, this if often called with the alias ``msg`` instead. This
method should call the protocol-specific send method, such as
``self.sendLine()``, directly.
This method should handle any protocol-specific processing before
relaying data on to a send-method like ``self.sendLine()`` mentioned
above. ``string`` is normally a raw text string with formatting.
``data`` can be a collection of any extra information the server want
to give to the protocol- it's completely up to the Protocol to handle
this. To take an example, telnet assumes ``data`` to be either
``None`` or a dictionary with flags for how the text should be
parsed. From inside Evennia, ``data_out`` is often called with the
alias ``msg`` instead.
Assorted notes
--------------
@ -100,4 +106,6 @@ To take two examples, Evennia supports the *telnet* protocol as well as
*webclient*, a custom ajax protocol. You'll find that whereas telnet is
a textbook example of a Twisted protocol as seen above, the ajax client
protocol looks quite different due to how it interacts with the
webserver through long-polling (comet) style requests.
webserver through long-polling (comet) style requests. All the necessary
parts mentioned above are still there, but implemented in very different
ways.