Updated ReST docs, fixed some things in Swedish translation.
This commit is contained in:
Griatch
parent
11e61255da
commit
c4f2c493d9
19 changed files with 937 additions and 745 deletions
|
|
@ -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
|
||||
--------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
mydict = obj.db.mydict
|
||||
# update temporary variable
|
||||
mydict[1][2] = "test"
|
||||
# save back to database
|
||||
obj.db.mydict = mydict
|
||||
# test
|
||||
temp = obj.db.mydict
|
||||
temp[1][2] = "test"
|
||||
obj.db.mydict = temp
|
||||
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
|
||||
-----
|
||||
|
|
|
|||
|
|
@ -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
|
||||
needed, the administrative overhead is tiny (as is resource
|
||||
consumption). The database will appear as a simple file
|
||||
(``game/evennia.db3``). It is not tested how well Evennia performs with
|
||||
SQLite under a heavier load, but it should probably be fine for most
|
||||
normal mud-related usage.
|
||||
installs it will probably be more than adequate for a long time. No
|
||||
server process is needed, the administrative overhead is tiny (as is
|
||||
resource consumption). The database will appear as a simple file
|
||||
(``game/evennia.db3``). SQLite is excellent for development and easy
|
||||
testing. The database is however hampered in speed by not allowing
|
||||
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
|
||||
possibility of clashes with file-locking of the database file under
|
||||
server, sqlite is probably also not be the best choice. This is due to
|
||||
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
|
||||
though, so check out Django's `Notes about supported
|
||||
and software versions involved. Older versions of MySQL had some
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 for certain implementations such as line editors that interpret
|
||||
non-commands as text input.
|
||||
|
||||
useful to do something here for certain implementations such as line
|
||||
editors that interpret non-commands as text input (an empty line in
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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>`_
|
||||
|
|
|
|||
|
|
@ -1,8 +1,17 @@
|
|||
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
|
||||
directories - ``src/``, ``game/``, ``contrib/`` , ``locale`` and
|
||||
``doc/``. The first two are the most important ones. ``game/`` is the
|
||||
place where you will create your own game, whereas ``src/`` is the home
|
||||
of the Evennia server itself. Your code should usually just import
|
||||
|
|
@ -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
|
||||
operations for storing listeners to channels.
|
||||
`communication <Communications.html>`_, notably *channels*, *messages*
|
||||
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
|
||||
and methods acting on the Player object.
|
||||
connected to the game. This directory defines the database handling and
|
||||
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
|
||||
protocols <SessionProtocols.html>`_ that allow users to connect to it.
|
||||
It also knows how to store dynamic server info in the database.
|
||||
itself (started from ``game/evennia.py``), the portal and all `sessions
|
||||
and protocols <SessionProtocols.html>`_ that allow users to connect to
|
||||
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
|
||||
certain object needs in the same module as that object, rather than
|
||||
slavishly split them out into their respective directories and import.
|
||||
Don't be shy to define your own directory structure as needed. A basic
|
||||
rule of thumb should nevertheless be to avoid code-duplication. So if a
|
||||
certain script or command could be useful for other objects, break it
|
||||
out into its own module and import from it.
|
||||
example, it could sometimes be easier to put all the commands and
|
||||
scripts a certain object needs in the same module as that object, rather
|
||||
than slavishly split them out into their respective directories and
|
||||
import. Don't be shy to define your own directory structure as needed. A
|
||||
basic rule of thumb should nevertheless be to avoid code-duplication. So
|
||||
if a certain script or command could be useful for other objects, break
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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, ...)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Mercurial)*.
|
||||
#. *Get the pre-requisites (Python, Django, Twisted and 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.
|
||||
- The default database system SQLite3 only comes as part of Python2.5
|
||||
and later.
|
||||
- Version 2.5+. Obs- Python3.x is not supported.
|
||||
- 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
|
||||
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>`_.
|
||||
This installs everything you need in one go.
|
||||
|
||||
Windows users not using ActivePython or virtual environments will have
|
||||
to manually download and install the packages in turn - most have normal
|
||||
Windows installers, but in some cases you'll need to know how to use the
|
||||
Windows command prompt to execute some python install scripts.
|
||||
to manually download and install the packages in turn (including their
|
||||
own dependencies in the list above). Most have normal Windows
|
||||
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
|
||||
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ program.
|
||||
set up a very easy self-contained Evennia install using the
|
||||
`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
|
||||
Python as normal, then get virtualenv and install it so you can run it
|
||||
from the command line. This is an example for setting up Evennia in an
|
||||
isolated new folder *mudenv*:
|
||||
environment. It should work both on Linux/Unix and Windows. First,
|
||||
install Python as normal, then get virtualenv and install it so you can
|
||||
run it from the command line. This is an example for setting up Evennia
|
||||
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
|
||||
Evennia.
|
||||
and activate it before starting or working with Evennia.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
------------------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
world you create using Evennia (i.e. the files you create in ``game``)
|
||||
falls under **§6** of the license (it's a sort of "library"). So your
|
||||
game world and all its contents belongs to you (as it should be). Keep
|
||||
it to yourself or re-distribute it under any license of your choice - or
|
||||
sell it and become filthy rich for all we care.
|
||||
**A:** It's your own game world to do with as you please! To summarize,
|
||||
a MUD world you create using Evennia (i.e. the files you create in
|
||||
``/game/``) falls under **§6** of the license (it's a sort of
|
||||
"library"). So your game world and all its contents belongs to you (as
|
||||
it should be). Keep it to yourself or re-distribute it under any license
|
||||
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
|
||||
make separate arrangements with us (since it's then no longer a
|
||||
"Standard version"). Of course, if you plan to add new features to
|
||||
the server, the easiest way to do so is to simply become an Evennia
|
||||
developer!
|
||||
of the changes you did and put those changes into public domain
|
||||
(since it's then no longer a "Standard version"). You could also
|
||||
contact the Evennia developers to make separate arrangements ... but
|
||||
of course, if you plan to add new features to the server, the easiest
|
||||
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
|
||||
sure to include the original license and disclaimers and note where
|
||||
users may get it if they want to download it of their own.
|
||||
version" (that is, the one you download from us) with your game files.
|
||||
Also make sure to include the original license and disclaimers and note
|
||||
where users may get "plain" Evennia should they want to download it of
|
||||
their own.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
arguments you can give the function.)
|
||||
all coded creating, for example if you create your own command that
|
||||
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
|
||||
the attribute ``desc``(which is what the ``look`` command looks for) is
|
||||
pre-set. You could just as well do the same with the ``@describe``
|
||||
command. The ``Object`` typeclass offers many more hooks that is
|
||||
available to use though. Look at the ``Object`` class in
|
||||
``game/gamesrc/objects/baseobjects.py`` to orient yourself. If you
|
||||
define a new Object class (inheriting from the base one), and wants that
|
||||
to be the default instead, set ``BASE_OBJECT_TYPECLASS`` in
|
||||
``settings.py`` to point to your new class.
|
||||
This particular Rose class doesn't really do much, all it does it make
|
||||
sure the attribute ``desc``(which is what the ``look`` command looks
|
||||
for) is pre-set, which is pretty pointless since you will usually want
|
||||
to change this at build time (using the ``@describe`` command). The
|
||||
``Object`` typeclass offers many more hooks that is available to use
|
||||
though - see next section.
|
||||
|
||||
If you define a new Object class (inheriting from the base one), and
|
||||
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
|
||||
returns lists - so assign to it like normal, e.g.
|
||||
``obj.aliases=['flower', 'red blossom']``
|
||||
- ``location`` - a reference to the object currently storing this
|
||||
stored in the database and can be searched for very fast. The
|
||||
``aliases`` property receives and returns lists - so assign to it
|
||||
like normal, e.g. ``obj.aliases=['flower', 'red blossom']``
|
||||
- ``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
|
||||
a bit more complex than aliases since they have a *type* that defines
|
||||
where Evennia tries to do the substituion. Use nicks.get(alias, type)
|
||||
to get a nick, or nicks.add(alias, realname) to add a new one.
|
||||
only valid for this object. This mainly makes sense if the Object is
|
||||
used as a game character - it can then store briefer shorts, example
|
||||
so as to quickly reference game commands or other characters. Nicks
|
||||
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.
|
||||
- ``has_player`` - a shorthand for checking if an online player is
|
||||
defining access rights for this Object.
|
||||
- ``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
|
||||
object, that is which has this object set as their ``location``.
|
||||
- ``contents`` - this returns a list referencing all objects 'inside'
|
||||
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
|
||||
object, at a given location or globally.
|
||||
- ``search`` - this is a convenient shorthand to search for a specific
|
||||
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
|
||||
``at_object_creation``. When implementing your custom objects, you will
|
||||
inherit from the base parent and overload these hooks with your own
|
||||
custom code. See ``game.gamesrc.baseobjects`` for an updated list of all
|
||||
the available hooks.
|
||||
The Object Typeclass defines many more *hook methods* beyond
|
||||
``at_object_creation``. Evennia calls these hooks at various points.
|
||||
When implementing your custom objects, you will inherit from the base
|
||||
parent and overload these hooks with your own custom code. See
|
||||
``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
|
||||
pretty similar to the base Object. You will import them all from
|
||||
order to be recognized by the game engine (there is nothing stopping you
|
||||
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
|
||||
the default typeclass assigned to new Players in your settings with
|
||||
``BASE_CHARACTER_TYPECLASS``.
|
||||
methods are not stopped from running you should not have to worry about
|
||||
this. You can change the default typeclass assigned to new Players in
|
||||
your settings with ``BASE_CHARACTER_TYPECLASS``.
|
||||
|
||||
Rooms
|
||||
~~~~~
|
||||
|
|
|
|||
|
|
@ -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
|
||||
--------------------------
|
||||
|
|
|
|||
|
|
@ -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'
|
||||
`Objects <Objects.html>`_ affecting that object and maybe its
|
||||
surroundings or contents. Scripts unrelated to objects are called
|
||||
*Global* scripts and could handle things like game-time, weather and
|
||||
other tickers.
|
||||
Scripts may run directly 'on' `Objects <Objects.html>`_, affecting that
|
||||
object and maybe its surroundings or contents. An alternative way to
|
||||
affect many objects (rather than one script per object) is to create one
|
||||
Script and have it call all objects that "subscribe" to it at regular
|
||||
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.
|
||||
|
|
@ -72,12 +73,27 @@ 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")
|
||||
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
|
||||
allows you to name your script uniquely before adding it. This is not
|
||||
necessary, but is useful if you add many scripts of the same class and
|
||||
later plan to use ``myobj.scripts.delete`` to remove individual scripts.
|
||||
The creation method(s) takes an optional argument *key* that allows you
|
||||
to name your script uniquely before adding it. This can be useful if you
|
||||
add many scripts of the same type and later plan to use
|
||||
``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``
|
||||
property will be set to ``myobj`` for you.
|
||||
to the Object with ``myobj.scripts.add(myscriptpath)`` or give
|
||||
``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
|
||||
called automatically when the server reloads. No hooks are called -
|
||||
but not deleting it. All properties are saved and timers can be
|
||||
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
|
||||
script.
|
||||
time in seconds until it next fires. Returns ``None`` if
|
||||
``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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
basically means that they are (almost) normal Python classes that hide
|
||||
underlying database models ...
|
||||
`Objects <Objects.html>`_ and `Scripts <Scripts.html>`_. This means that
|
||||
they are *almost* normal Python classes - they behave and can be
|
||||
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
|
||||
entities inherit a common interface from the typeclass system,
|
||||
properties you can *always* expect a typeclassed entity to have *beyond*
|
||||
the more specialized properties unique to each sub-type. Typeclasses
|
||||
also do some special things with their in-built class methods that you
|
||||
shouldn't edit.
|
||||
To work with them you should however know that Objects, Scripts and
|
||||
Players all inherit a lot of helper methods from the typeclass system,
|
||||
properties you can *always* expect a typeclassed entity to have. In
|
||||
addition to these, each of the three sub types also offer a host of help
|
||||
methods and properties you can use. The database handling is hidden, but
|
||||
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)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue