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.pm:102 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
# .. 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/Av4.pm The server. It loads a sample area file, starts
accepting connections, and handles the connections
lib/Av4/Server.pm The object that identifies the server. It contains
the input and output buffers for the clients, the
parsed help pages, etc.
lib/Av4/Telnet.pm Contains constants used for handling telnet options
lib/Av4/TelnetOptions.pm Handles all the supported telnet options for a
connection: MCCP, TTYPE, NAWS
lib/Av4/Ansi.pm Handles the ANSI colorization of MUD strings given
by either the MUD or inputed by the players.
lib/Av4/User.pm 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/Command.pm 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
lib/Av4/Commands.pm A list of all the commands (by category) supported
by the MUD. These are the ones that end up in a
lib/Av4/Commands/MCP.pm 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/Basic.pm 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/Utils.pm A get_logger() function that gets the right logger
(Log::Log4perl instance) for a function; the cached
ansify() function which uses Memcached.
lib/Av4/HelpParse.pm A utility module to parse SMAUG format help files
lib/Av4/Help.pm 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/User.pm.
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
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
There are some scripts which have been used during the development at one time or
the other. The most used is scripts/fuzzier.pl 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 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.