Tree [83a90d] f/mcp_nocommands /

File Date Author Commit
benchmarks 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
datalogs 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
docs 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
lib 2010-07-21 Marco Fontani Marco Fontani [83a90d] Fixed compilation for old code
scripts 2009-05-03 Marco Fontani Marco Fontani [4b7dfd] Added second parameter to be able to analyze a ...
t 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
Build.PL 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
LICENSE 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
Makefile 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
README 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
help.are 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
log.conf 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo
mud 2010-07-21 Marco Fontani Marco Fontani [75b6c7] Import from older repo

Read Me

Anacronia v4 - Copyright (c) 2009,2010 Marco Fontani - MFONTANI at CPAN dot ORG
Released under the GPL v.3.0 license -- see LICENSE

Anacronia V4 is the fourth rewrite of a Multi User Dungeon (MUD), a multi-user
internet gaming system. It is written in the Perl programming language, and
uses "modern" technologies and modules, such as POE, Moose, and Memcache.

In any examples in this document the "$ " indicates the shell prompt; anything
after it indicates the command you should type. Any lines after it, unless it
also starts with a "$ ", indicates the output the command should give.


In order to start the MUD, you'll need the following Perl modules installed.
You will also need a working C compiler, as the program uses Inline::C.
You may want to use App::cpanminus to install these, as that allows you to
have them installed in your $HOME rather than system wide.

    Digest::MD5                 used to calculate Memcache keys for help pages
    IO::Socket                  handles the incoming connections, asynchronously
    Compress::Zlib              needed for MCCP support
    YAML                        for debug dumping and (in future) config files
    POE                         the event loop that makes the mud "tick"
    POE::XS::Loop::EPoll        a very fast event loop for POE
    POE::XS::Queue::Array       (semi-unused) fast array queues for POE
    Inline::C                   Allows very performant C routines to be called
    Log::Log4perl               For debugging and logging purposes
    Moose                       The modern OOP system for some classes
    Cache::Memcached::Fast      To cache ansified help pages, and soon more

You may do so by issuing commands similar to the following:

    $ cpan  Digest::MD5
    $ cpanm Digest::MD5

A Build.PL file is also included, and it may (or may not) help you installing
the right prerequisites, too.

Launching the MUD

Once the prerequisite modules are installed and working, you can launch the
MUD by typing, in the root of this repository:

    $ perl mud
    2010/07/21 21:41:58 lib/ Av4::run WARN TCP ready on port 8081

The "mud" program accepts several options; you can see these options by
typing the following:

    $ perl mud --help
        ./mud [options]
    #  ..  follows list of options

The MUD's Perl modules

The various mud-related modules that constitute Anacronia V4 are located in the
lib/ subdirectory of this repository.
Their purpose is as follows:

    lib/                  The server. It loads a sample area file, starts
                                accepting connections, and handles the connections
    lib/Av4/           The object that identifies the server. It contains
                                the input and output buffers for the clients, the
                                parsed help pages, etc.
    lib/Av4/           Contains constants used for handling telnet options
    lib/Av4/    Handles all the supported telnet options for a
                                connection: MCCP, TTYPE, NAWS
    lib/Av4/             Handles the ANSI colorization of MUD strings given
                                by either the MUD or inputed by the players.
    lib/Av4/             A user object: any connection made to the MUD gets
                                assigned one of these objects. This handles the
                                connection's state, as well as the telnet options
                                associated, MCP authorizations, the commands queue,
                                the commands the user can execute, and allows the
                                commands to be executed.
    lib/Av4/          An object which identifies a MUD command, with its
                                name, queue priority, the amount of ticks it delays
                                for, the code that should be executed, and manages
                                its execution.
    lib/Av4/         A list of all the commands (by category) supported
                                by the MUD. These are the ones that end up in a
                                User's object.
    lib/Av4/Commands/     All the commands that handle the MCP protocol: the
                                authentication key, the negotiation, and some MCP
                                extensions. The support for MCP is far from working
                                reliably, as it needs tested with more clients.
    lib/Av4/Commands/   All the basic commands which every user gets. In this
                                release any user is able to use the @shutdown command
                                to shutdown the MUD process.
    lib/Av4/            A get_logger() function that gets the right logger
                                (Log::Log4perl instance) for a function; the cached
                                ansify() function which uses Memcached.
    lib/Av4/        A utility module to parse SMAUG format help files
    lib/Av4/             A "help page" object, with the level, keywords and
                                the data that actually comprises the help page.

The command queue concept.

In many MUDs commands are parsed and executed in a first-come first-served fashion:
if the character is currently performing an action which delays (casting a spelli for
example), any other command (including non-delaying ones such as SCORE) need to wait
for the first command to be executed.
In other mode modern MUDs there may be multiple command queues which allow the player
to perform delaying actions which don't overlap with each other. For example, using
an attack prevents the player from attacking again before N seconds, but meanwhile
the player can still ready a defensive command or see their statistics.
Anacronia V4 implements a queue system in which all the unknown commands are weeded
out of the command queue, and commands are executed in order of priority. Adding
specific queue types (attack, defense, movement) is on the roadmap and should be
fairly easy to implement.

The process through which the queue system works is found on lib/Av4/

The datalogs

Since the MUD supports a number of telnet and MUD-specific protocols, I've gathered
log dumps of the input/output of a number of MUD clients which connected to the
MUD a number of times. These can be found in the datalogs/ directory. They are
included for reference, and will/should be used to construct tests or debug non
working features.

The benchmarks

Using Devel::NYTProf several slow subroutines were found and sped up. For example,
the ansify() subroutine used to take most of the CPU time for the MUD. Since then,
the subroutine has been rewritten in Inline::C. A benchmark file has been added to
benchmarks/ to allow users to repeat the benchmark and decide for themselves if
they want to use the Inline::C version or substitute the much slower pure Perl one.
The directory also contains some excerpts of older Devel::NYTProf runs on the MUD
executable, just in case these details need to be referenced or compared in the

The scripts

There are some scripts which have been used during the development at one time or
the other. The most used is scripts/ which allows a number of clients
to connect to the MUD and start sending a number of commands, fast. This is used
to benchmark various parts of the MUD and see which areas are slow or need some

The tests

The t/ directory contains a number of tests for some of the features of the MUD.
Not all features are tested. If you do want to write a small test file or contribute
a test case you're more than welcome to do so. Meanwhile, the two test files that
are provided exercise the ANSIfication of strings and the inner workings of the
priority queue, two widely used features of the MUD.
Both achieve quite high branch coverage in the subroutines they call. The aim is
for all areas of the MUD code to be exercised, and achieve and maintain a high level
of branch coverage.