This is a work in progress. Please suggest modifications or additions.

Introduction

This document is intended as a beginner's guide to building on the Cryosphere. It will explain enough about the internals of MusicMUD to allow you to understand the rest of the documentation.

Target Audience

This document is intended to be read by players who have run to Commander and want to start building. If you fall into this category and you don't understand the contents of this document, then it is too complex. This is a bug - please report it.

Test site

The Cryosphere would typically run three copies of the mud simutaneously - "Live", "Test", "Dev". Live is the main mud and is designed to be 100% stable.

Test is a staging instance, which will be used for testing the exact release that is planned to become the new live.

Dev is where building takes place and is designed to be 90% stable. It may significantly advance. When it is time to upgrade, a release of the MUD will be cut from dev, and then deployed to Test. We will then test on Test. Fixes may take place. When it is deemed suitable Live will be updated to the version then on Test.

Note that on account of the server migration we are currently operating with a nonstandard arrangement. Live is on our old host, and our new host features "Staging", which is intended to become the new Live soon.

All building should usually happen on Dev. If you notice a minor bug on Live which you are able to fix, you should do so on Dev. If you feel the bug is important enough to be fixed now, instead of at the next swap, tell someone and it will be transferred over.

MusicMUD Structure

Everything is an object

There is no fundamental difference between a player, a mobile, a room or a door. All in-game items you can interact with are "the same".

Properties

The data about an object is stored in properties inside that object.

Strings

A string is some text. For example, the description on an object is held in the "desc.internal" property. You can see that by typing "stat object desc"

Our colour codes are described here. Note that some of them are semantic tags, as we allow user colour scheme customisation.

Ints

Int is short for integer - a number.

Flags

Flags aren't properties. You can't use "change" or "delete" on them. You need to use the flags command on them

Arrays (sort of)

We don't have native support for arrays as properties, but we have the common convention of setting, say, auto.count to 2 and then setting auto.0 to the first thing and auto.1 to the second thing. It is planned that this will be migrated to first class array properties.

Tree structure

All objects have a single owner (or "parent", if you prefer). This determines where in the mud the object appears. The owners are also objects and therefore have an owner. The only exception to this is the "@musicmud" object which is at the "root" of the tree. An object can have many "branches" (or "children") below it.

Zones

Typically, @musicmud contains zones, zones contain rooms and rooms contain objects. Objects can also be containers (imagine a box) and contain more objects. A zone is a single, autonomous, area of the mud. For example, level 2 of the station has its own zone, as does Livingstone city.

Being in a particular zone doesn't necesserily show where that object physically resides. (Objects contain a "zone" property, which may be different to the zone their parent is in). This allows two or more zones to overlap each other. Missions generally have their own zone, which only contains items specifically related to that mission. This allows the mission zone to reset while there are other people in the same area [FIXME: word that better].

Make

The "make" verb makes new objects. It asks you questions about what sort of object you want.

Boot

The "boot" verb removes objects. Be careful, once it's gone, it's gone. You must never, ever use boot on static objects on the Live site. This will result in grevious retribution from the admins. Our only undo is source control.

Displace/Goto

These commands move objects around in the mud. They have a number of sanity and security checks so you can usually use these with impunity and not worry too much.

Set/Unset

"Set" changes the contents of an object's properties. It knows what properties are strings and which are numbers and contains enough sanity checking to stop stuff getting too broken. "Unset" will completely remove a property from an object. You won't be able to set/unset everything, but this should be more than adequate for building purposes.

Setstate

This sets the state of an object to the given number. Openable objects are considered to be open in state 0, and closed in state 1. Lockable/latchable objects are locked when they are in state 2. States are also used in other situations for scripting purposes.

Unreset

When you move or change the state of an object, it will be automatically returned to its original state and position following a reset. Unresetting and object will 'fix' it in its current state and position, and regardless of what happens to it, it will always return to its current state and position when reset.

Chint/Chstr

There are some properties which "set" doesn't know about, or does know about but has security and sanity restrictions and therefore won't let you modify. Chint and Chstr are lower-level commands and contain very few sanity checks. You shouldn't need to use these commands (indeed, you may not even have access to them) - use set instead. If you find something which set can not do, submit a bug report.

Chown

Chown is a low-level command used for moving objects around the mud. It has fairly high level restrictions, but it doesn't do anything useful you cannot do yourself using displace or summon.

Delete

Delete is the low-level counterpart to unset, which will remove any attribute from and object. This can potentially cause serious damage, and so in general you should be using unset.

WebMake

[FIXME: document it when it's done :) ]