CarbonMU is a general-purpose, extendable MUD/MUSH server framework written in Ruby. It's designed to scale to thousands of players, handle a wide variety of game types, from classic hack-n-slash MUDs to innovative text-based social communities. CarbonMU is not ready for public use by non-developers, but we welcome user contributions to help move the project along.
The remainder of this documentation is currently intended more as design documentation than how-tos.
Where to talk about CarbonMU
- #carbonmu on Freenode IRC.
- In the near future there will be an official CarbonMU support site running... CarbonMU. In the meantime, you can find me on M*U*S*H (mush.pennmush.org 4201) as Rince.
The road to 1.0
See this wiki page for the latest updates on what's on the todo list. You are more than welcome to get involved! Feel free to open issues with questions, join discussions, or ask if you need help finding a task suitable for your interest and skill level.
CarbonMU is powered by DCell, a framework for distributed applications, which is built on top of Celluloid and ZeroMQ. CarbonMU uses MongoDB (via Mongoid) to store all of its data. The framework is designed to support a variety of connections by players, including basic TCP telnet, SSL telnet, and JSON over HTTP, API-style.
It's also intended to use a highly plugin-based model. A typical CarbonMU game will probably consist of the carbonmu core gem (what you see here), some number of community-supported third-party gems to provide things like a bboard system and other common utilities, and some game-specific custom code. It will not include a scripting engine or "softcode"-type functionality.
Internally, CarbonMU looks like this:
Server are separate actors. The
Server can be therefore be restarted to load new game code without dropping TCP connections.
There are four built-in descendants of
GameObject in core (modules may choose to add their own).
Room, which mixes in
Containerso it can have contents
Thing, something tangible that is in one and only one room (mixes in
Movable), and also can have contents (is a
Player, similar to
Thingexcept can be logged into, and will support more interactions (i.e. you can send in-game mail to a
Player, but not a
Exit, a connection between two
All of these are stored in MongoDB in the
Of course, MU*s need a lot more data than just things that can be interacted with. There'll be things like bboard messages, mail, and thousands of other things games will want to add for their custom needs. Plugins are welcome to declare their own classes that inherit
Mongoid::Document, and can even reference the
GameObject descendants. There's no need to create 'data objects' and store them there.
Defining a new command is done by subclassing Command, adding one or more
syntax calls using regular expressions with named captures for parameters, and providing an
execute model that receives a
@params hash with its named captures and a CommandContext instance in
@context. See lib/commands for examples. This will continue to be fleshed out.
We will use a pubsub model (not yet implemented) to allow for both core functionality and people's gems to provide behavior when game events occur, as well as register their own events too.
Building external plugins/modules/gems
This needs to be documented in detail once an example is done.
CarbonMU will have full i18n support on a per-player basis, allowing each player to see game messages in their own locales (of course, chat messages and so on will not be auto-translated).
CarbonMU is tested and supported on Ruby 2.0 or newer, JRuby (latest release), and Rubinius (latest release). Using JRuby or Rubinius will allow your game to be multi-threaded.
Creating a game with CarbonMU
Create a new game with
carbonmu create mygame. This will create a directory with
some files that give you a general skeleton for your game and install some
You can play your newly created game by typing
carbonmu start in that
Look at the issues, find something to fix and fix it. Alternatively expand upon these instructions, they're suboptimal.
You will need ZeroMQ 3.x (4.1.x does not currently work, due to underlying issues in CarbonMU's dependencies), and MongoDB.
Clone the repo, start Mongo and Redis, bundle and run
rake console to open an interactive
You can start a server with