mirror/evennia
3
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2025-10-30 03:44:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated readme's and other documentation.

Browse Source
This commit is contained in:
Griatch 2015-02-10 16:12:21 +01:00
parent 9d63b03635
commit f2a41161cb
6 changed files with 260 additions and 233 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
CHANGELOG.txt → CHANGELOG.md
View File

@ -1,7 +1,15 @@
Changelog
---------
# Evennia Changelog
Sept 2014:
## Feb 2015:
Development currently in devel/ branch. Moved typeclasses to use
django's proxy functionality. Changed the Evennia folder layout to a
library format with a stand-alone launcher, in preparation for making
an 'evennia' pypy package and using versioning. The version we will
merge with will likely be 0.5. There is also work with an expanded
testing structure and the use of threading for saves. We also now
use Travis for automatic build checking.
## Sept 2014:
Updated to Django 1.7+ which means South dependency was dropped and
minimum Python version upped to 2.7. MULTISESSION_MODE=3 was added
and the web customization system was overhauled using the latest
@ -9,28 +17,28 @@ functionality of django. Otherwise, mostly bug-fixes and
implementation of various smaller feature requests as we got used
to github. Many new users have appeared.
Jan 2014:
## Jan 2014:
Moved Evennia project from Google Code to github.com/evennia/evennia.
Nov 2013:
## Nov 2013:
Moved the internal webserver into the Server and added support for
out-of-band protocols (MSDP initially). This large development push
also meant fixes and cleanups of the way attributes were handled.
Tags were added, along with proper handlers for permissions, nicks
and aliases.
May 2013:
## May 2013:
Made players able to control more than one Character at the same
time, through the MULTISESSION_MODE=2 addition. This lead to a lot
of internal changes for the server.
Oct 2012:
## Oct 2012:
Changed Evennia from the Modified Artistic 1.0 license to the more
standard and permissive BSD license. Lots of updates and bug fixes as
more people start to use it in new ways. Lots of new caching and
speed-ups.
March 2012:
## March 2012:
Evennia's API has changed and simplified slightly in that the
base-modules where removed from game/gamesrc. Instead admins are
encouraged to explicitly create new modules under game/gamesrc/ when
@ -42,7 +50,7 @@ extensions, notably the MSDP and GMCP out-of-band extensions. On the
community side, evennia's dev blog was started and linked on planet
Mud-dev aggregator.
Nov 2011:
## Nov 2011:
After creating several different proof-of-concept game systems (in
contrib and privately) as well testing lots of things to make sure the
implementation is basically sound, we are declaring Evennia out of
@ -51,7 +59,7 @@ development is still heavy but the issue list is at an all-time low
and the server is slowly stabilizing as people try different things
with it. So Beta it is!
Aug 2011:
## Aug 2011:
Split Evennia into two processes: Portal and Server. After a lot of
work trying to get in-memory code-reloading to work, it's clear this
is not Python's forte - it's impossible to catch all exceptions,
@ -60,21 +68,21 @@ hackish, flakey and unstable code. With the Portal-Server split, the
Server can simply be rebooted while players connected to the Portal
remain connected. The two communicates over twisted's AMP protocol.
May 2011:
## May 2011:
The new version of Evennia, originally hitting trunk in Aug2010, is
maturing. All commands from the pre-Aug version, including IRC/IMC2
support works again. An ajax web-client was added earlier in the year,
including moving Evennia to be its own webserver (no more need for
Apache or django-testserver). Contrib-folder added.
Aug 2010:
## Aug 2010:
Evennia-griatch-branch is ready for merging with trunk. This marks a
rather big change in the inner workings of the server, such as the
introduction of TypeClasses and Scripts (as compared to the old
ScriptParents and Events) but should hopefully bring everything
together into one consistent package as code development continues.
May 2010:
## May 2010:
Evennia is currently being heavily revised and cleaned from
the years of gradual piecemeal development. It is thus in a very
'Alpha' stage at the moment. This means that old code snippets
@ -82,85 +90,28 @@ will not be backwards compatabile. Changes touch almost all
parts of Evennia's innards, from the way Objects are handled
to Events, Commands and Permissions.
April 2010:
## April 2010:
Griatch takes over Maintainership of the Evennia project from
the original creator Greg Taylor.
(Earlier revisions, with previous maintainer, go back to 2005)
Contact, Support and Development
-----------------------
This is still alpha software, but we try to give support best we can
if you have questions. Make a post to the mailing list or chat us up
on IRC. We also have a bug tracker if you want to report
bugs. Finally, if you are willing to help with the code work, we much
appreciate all help! Visit either of the following resources:
# Contact, Support and Development
Make a post to the mailing list or chat us up on IRC. We also have a
bug tracker if you want to report bugs. Finally, if you are willing to
help with the code work, we much appreciate all help! Visit either of
the following resources:
* Evennia Webpage
http://evennia.com
* Evennia manual (wiki)
https://github.com/evennia/evennia/wiki
* Evennia Code Page (See INSTALL text for installation)
https://github.com/evennia/evennia
* Bug tracker
https://github.com/evennia/evennia/issues
* IRC channel
visit channel #evennia on irc.freenode.com
or online client: http://tinyurl.com/evchat
Directory structure
-------------------
evennia
|
| ev.py
|_______game (start the server, settings)
| |___gamesrc
| |___(game-related dirs)
|_______src
| |___(engine-related dirs)
| |
|_______contrib
|
|_______docs
|
|_______locales
ev.py is the API file. It contains easy shortcuts to most
of Evennia's functionality. Import ev into a python interpreter
(like ipython) and explore what's available.
The game/ folder is where you develop your game. The root
of this directory contains the settings file and the executables
to start the server. Under game/gamesrc you will create the
modules that defines your game.
src/ contains the Evennia library. As a normal user you should
not edit anything in this folder - you will run into conflicts
conflicts as we update things from our end. If you see code
you like (such as that of a default command), copy&paste it
into a new module in game/gamesrc/. If you find that src/ doesn't
support a functionality you need, issue a Feature
request or a bug report appropriately. If you do add functionality
or fix bugs in src/ yourself, please consider contributing it to
Evennia's main repo to help us improve!
contrib/ contains optional code snippets. These are potentially useful
but are deemed to be too game-specific to be part of the server itself.
Modules in contrib are not used unless you yourself decide to import
and use them.
docs/ contain offline versions of the documentation, you can use
python-sphinx to convert the raw data to nice-looking output for
printing etc. The online wiki is however the most updated version
of the documentation.
locales/ holds translations of the server strings to other languages
than English.
Enjoy!
or the webclient: http://tinyurl.com/evchat

42
CODING_STYLE.md Normal file
View File

@ -0,0 +1,42 @@
# Evennia Code Style
All code submitted or committed to the Evennia project should aim to
follow the guidelines outlined in [Python PEP
8](http://www.python.org/dev/peps/pep-0008). Keeping the code style
uniform makes it much easier for people to collaborate and read the
code.
A good way to check if your code follows PEP8 is to use the [PEP8
tool](https://pypi.python.org/pypi/pep8) on your sources.
## A quick list of code style points
* 4-space indendation, NO TABS!
* Unix line endings.
* CamelCase is only used for classes, nothing else.
* All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.
* Module-level global variables (only) are to be in CAPITAL letters.
* (Evennia-specific): Imports should normally be done in this order:
- Python modules (builtins and standard library)
- Twisted modules
- Django modules
- Evennia src/ modules
- Evennia game/ modules
- Evennia 'ev' API imports
## Documentation
Remember that Evennia's source code is intended to be read - and will
be read - by game admins trying to implement their game. Evennia
prides itself with being extensively documented. Modules, functions,
classes and class methods should all start with at least one line of
docstring summing up the function's purpose. Ideally also explain
eventual arguments and caveats. Add comments where appropriate.
## Ask Questions!
If any of the rules outlined in PEP 8 or in the sections above doesn't
make sense, please don't hesitate to ask on the Evennia mailing list
or in the chat.

63
CODING_STYLE.txt
View File

@ -1,63 +0,0 @@
Evennia Code Style
------------------
All code submitted or committed to the Evennia project needs to follow
the guidelines outlined in Python PEP 8, which may be found at:
http://www.python.org/dev/peps/pep-0008/
A quick list of code style points
---------------------------------
* 4-space indendation, NO TABS!
* Unix line endings.
* CamelCase is only used for classes, nothing else.
* All non-global variable names and all function names are to be
lowercase, words separated by underscores. Variable names should
always be more than two letters long.
* Module-level global variables (only) are to be in CAPITAL letters.
* (Evennia-specific): Imports should normally be done in this order:
- Python modules (builtins and standard library)
- Twisted modules
- Django modules
- Evennia src/ modules
- Evennia game/ modules
- Evennia 'ev' API imports
Documentation
-------------
Remember that Evennia's source code is intended to be read - and will
be read - by game admins trying to implement their game. Evennia
prides itself with being extensively documented. Modules, functions,
classes and class methods should all start with at least one line of
docstring summing up the function's purpose. Ideally also explain
eventual arguments and caveats. Add comments where appropriate.
Pylint
------
The program 'pylint' (http://www.logilab.org/857) is a useful tool for
checking your Python code for errors. It will also check how well your
code adheres to the PEP 8 guidelines (such as lack of docstrings) and
tells you what can be improved.
Since pylint cannot catch dynamically created variables used in
commands and elsewhere in Evennia, one needs to reduce some checks to
avoid false errors and warnings. For best results, run pylint like
this:
> pylint --disable=E1101,E0102,F0401,W0232,R0903 filename.py
To avoid entering the options every time, you can auto-create a
pylintrc file by using the option --generate-rcfile. You need to dump
this output into a file .pylintrc, for example like this (linux):
> pylint --disable=E1101,E0102,F0401,W0232,R0903 --generate-rcfile > ~/.pylintrc
From now on you can then just run
> pylint filename.py
Ask Questions!
--------------
If any of the rules outlined in PEP 8 or in the sections above doesn't
make sense, please don't hesitate to ask on the Evennia mailing list
at http://evennia.com. Keeping our code style uniform makes this
project much easier for a wider group of people to participate in.

136
INSTALL.md Normal file
View File

@ -0,0 +1,136 @@
# Evennia installation
The latest and more detailed installation instructions can be found
[here](https://github.com/evennia/evennia/wiki/Getting-Started).
## Installing Python
First install [Python](https://www.python.org/). Linux users should
have it in their repositories, Windows/Mac users can get it from the
Python homepage. You need the 2.7.x version (Python 3 is not yet
supported). Windows users, make sure to select the option to make
Python available in your path - this is so you can call it everywhere
as `python`. Python 2.7.9 and later also includes the
[pip](https://pypi.python.org/pypi/pip/) installer out of the box,
otherwise install this separately (in linux it's usually found as the
`python-pip` package).
### installing virtualenv
This step is optional, but *highly* recommended. For installing
up-to-date Python packages we recommend using
[virtualenv](https://pypi.python.org/pypi/virtualenv), this makes it
easy to keep your Python packages up-to-date without interfering with
the defaults for your system.
```
pip install virtualenv
```
Go to the place where you want to make your virtual python library
storage. This does not need to be near where you plan to install
Evennia. Then do
```
virtualenv vienv
```
A new folder `vienv` will be created (you could also name it something
else if you prefer). Activate the virtual environment like this:
```
# for Linux/Unix/Mac:
source vienv/bin/activate
# for Windows:
vienv\Scripts\activate.bat
```
You should see `(vienv)` next to your prompt to show you the
environment is active. You need to activate it whenever you open a new
terminal, but you *don't* have to be inside the `vienv` folder henceforth.
# Get the developer's version of Evennia
This is currently the only Evennia version available. First download
and install [Git](http://git-scm.com/) from the homepage or via the
package manager in Linux. Next, go to the place where you want the
`evennia` folder to be created and run
```
git clone https://github.com/evennia/evennia.git
```
If you have a github account and have [set up SSH
keys](https://help.github.com/articles/generating-ssh-keys/), you want
to use this instead:
```
git clone git@github.com:evennia/evennia.git
```
In the future you just enter the new `evennia` folder and do
```
git pull
```
to get the latest Evennia updates.
## Evennia package install
Stand at the root of your new `evennia` directory and run
```
pip install -e .
```
(note the period "." at the end, this tells pip to install from the
current directory). This will install Evennia and all its dependencies
(into your virtualenv if you are using that) and make the `evennia`
command available on the command line. You can find Evennia's
dependencies in `evennia/requirements.txt`.
## Creating your game project
To create your new game you need to initialize a new game project.
This should be done somewhere *outside* of your `evennia` folder.
```
evennia --init mygame
```
This will create a new game project named "mygame" in a folder of the
same name. If you want to change the settings for your project, you
will need to edit `mygame/server/conf/settings.py`.
## Starting Evennia
Enter your new game directory and run
```
evennia -i start
```
Follow the instructions to create your superuser account. A lot of
information will scroll past as the database is created and the server
initializes. After this Evennia will be running. Use
```
evennia -h
```
for help with starting, stopping and other operations.
Start up your MUD client of choice and point it to your server and
port *4000*. If you are just running locally the server name is
*localhost*.
Alternatively, you can find the web interface and webclient by
pointing your web browser to *http://localhost:8000*.
Finally, login with the superuser account and password you provided
earlier. Welcome to Evennia!

76
INSTALL.txt
View File

@ -1,76 +0,0 @@
-------------
Evennia Setup
-------------
You can find the updated and more detailed version of this page on
https://github.com/evennia/evennia/wiki/Getting-Started. You don't
need to make your server visible online during development, you only
need an internet connection for downloading and updating.
Installation
------------
* Make sure you have the prerequsites with minimum versions
listed on https://github.com/evennia/evennia/wiki/Getting-Started:
- python
- django
- twisted + Pillow
- GIT
- django-south
* Go to a directory on your harddrive where you want the 'evennia'
directory to be created, for example mud/.
cd mud/
* Get a copy of the Evennia source (you should have done this
already if you are reading this file):
git clone https://github.com/evennia/evennia.git
or
git clone git@github.com:evennia/evennia.git
In the future, do 'git pull' to update the server.
* Change to the evennia/game directory and run the setup scripts.
cd evennia/game
python manage.py
* Edit the new game/settings.py if needed, then run
python manage.py syncdb
Starting Evennia
----------------
* Start the server with
python evennia.py -i start
or run without arguments for a menu of launch options. Make
sure to create a superuser when asked. The email does not have
to be a real one for testing (evennia does not check it)
* Start up your MUD client of choice and point it to your server and port 4000.
If you are just running locally the server name is 'localhost'.
* Alternatively, you can find the web interface and webclient by
pointing your web browser to http://localhost:8000.
* For superuser access, login with the account and password you provided earlier.
Welcome to Evennia!
-------------------
* See www.evennia.com for more information and help with how to
proceed from here.
* For questions, see the discussion group or the chat. Report bugs or
request features via the Issue Tracker.

69
README.md
View File

@ -1,29 +1,66 @@
Evennia MUD/MU\* Creation System
================================
# Evennia MUD/MU\* Creation System
*Evennia* is a Python-based MUD/MU\* server/codebase using modern technologies. It is made available as open source under the very friendly [BSD license](https://github.com/evennia/evennia/wiki/Licensing). Evennia allows creators to design and flesh out text-based massively-multiplayer online games with great freedom.
![evennia logo](https://github.com/evennia/evennia/blob/devel/evennia/web/static/evennia_general/images/evennia_logo.png)
http://www.evennia.com is the main hub tracking all things Evennia. The documentation wiki is found [here](https://github.com/evennia/evennia/wiki).
*Evennia* is a modern library for creating online multiplayer text games
(MUD, MUSH, MUX, MOO etc) in pure Python. It allows game creatores to
design and flesh out their games with great freedom.
Features and Philosophy
-----------------------
http://www.evennia.com is the main hub tracking all things Evennia.
The extensive documentation is found
[here](https://github.com/evennia/evennia/wiki). Evennia is made
available under the [BSD license](https://github.com/evennia/evennia/wiki/Licensing).
Evennia aims to supply a bare-bones MU\* codebase that allows vast flexibility for game designers while taking care of all the gritty networking and database-handling behind the scenes. Evennia offers an easy API for handling persistent objects, time-dependent scripting and all the other low-level features needed to create a MU\*. The idea is to allow the mud-coder to concentrate solely on designing the parts and systems of the mud that makes it uniquely fit their ideas.
Coding in Evennia is primarily done by normal Python modules, making the codebase extremely flexible. The code is heavily documented and you use Python classes to represent your objects, scripts and players. The database layer is abstracted away.
## Features and Philosophy
Evennia offers extensive connectivity options. A single server instance may offer connections over Telnet, SSH, SSL and HTTP. The latter is possible since Evennia is also its own web server: A default website as well as a browser-based comet-style mud client comes as part of the package ([screenshot](https://github.com/evennia/evennia/wiki/Screenshot)). Due to our Django and Twisted foundations, web integration is a snap since the same code that powers the game may also be used to run its web presence (you may use a third-party webserver too if you prefer though). Evennia in-game channels can also be interlinked with external IRC and IMC2 channels so players can chat with people "outside" the game.
Evennia aims to supply a bare-bones MU\* codebase that allows vast
flexibility for game designers while taking care of all the gritty
networking and database-handling behind the scenes. Evennia offers an
easy API for handling persistent objects, time-dependent scripting and
all the other low-level features needed to create an online text-based
game. The idea is to allow the mud-coder to concentrate solely on
designing the parts and systems of the mud that makes it uniquely fit
their ideas.
Whereas Evennia is intended to be customized to almost any level you like, we do offer some defaults you can build from. The code base comes with basic classes for objects, exits, rooms and characters. There is also a default command set for handling administration, building, chat channels, poses and so on. This is enough to run a 'Talker' or some other social-style game out of the box. Stock Evennia is however deliberately void of any game-world-specific systems. So you won't find any AI codes, mobs, skill systems, races or combat stats in the default distribution (we might expand our contributions folder with optional plugins in the future though).
Coding in Evennia is primarily done by normal Python modules, making
the codebase extremely flexible. The code is heavily documented and
you use Python classes to represent your objects, scripts and players.
The database layer is abstracted away.
If this piqued your interest, there is also a [lengthier introduction](https://github.com/evennia/evennia/wiki/Evennia-Introduction) to Evennia to read.
![screenshot](https://github.com/evennia/evennia/wiki/Screenshot)
Current Status
--------------
Evennia offers extensive connectivity options. A single server
instance may offer connections over Telnet, SSH, SSL and HTTP. The
latter is possible since Evennia is also its own web server: A default
website as well as a browser-based comet-style mud client comes as
part of the package.
Due to our Django and Twisted foundations, web integration is
easy since the same code that powers the game may also be used to run
its web presence.
Whereas Evennia is intended to be customized to almost any level you
like, we do offer some defaults you can build from. The code base
comes with basic classes for objects, exits, rooms and characters.
There is also a default command set for handling administration,
building, chat channels, poses and so on. This is enough to run a
'Talker' or some other social-style game out of the box. Stock Evennia
is however deliberately void of any game-world-specific systems. So
you won't find any AI codes, mobs, skill systems, races or combat
stats in the default distribution (we might expand our contributions
folder with optional plugins in the future though).
If this piqued your interest, there is also a [lengthier
introduction](https://github.com/evennia/evennia/wiki/Evennia-Introduction)
to Evennia to read.
## Current Status
The codebase is currently in **Beta**. While development continues, Evennia is already stable enough to be suitable for prototyping and development of your own games.
More Information
----------------
## More Information
To learn how to get your hands on the code base, the [Getting started](https://github.com/evennia/evennia/wiki/Getting-Started) page is the way to go. Otherwise you could browse the [Documentation wiki](https://github.com/evennia/evennia/wiki) or why not come join the [Evennia Community](http://www.evennia.com). Welcome!
To learn how to get your hands on the code base, the [Getting started](https://github.com/evennia/evennia/wiki/Getting-Started) page
is the way to go. Otherwise you could browse the [Documentation wiki](https://github.com/evennia/evennia/wiki) or why not come join
the [Evennia Community](http://www.evennia.com). Welcome!