The Dawn of Time - Mud Codebase

Getting Started with Dawn

Version 1.3 - 09 April 2004


Table of Contents

Getting Started with Dawn

Table of Contents

Introduction

OS/Hosting Considerations

Choosing an Operating System
Where to host a mud?

Obtaining the Dawn of Time Codebase

-What does the Dawn Codebase consist of?

--The Dawn of Time Source Code

--The Dawn of Time Support Files

--The Dawn of Time Precompiled Windows Binary

-So which files do I need?

Unix Shell Account

-What is a shell account

-Connecting to a shell account

-Unix Shell Account Commands

--Unix Equivalents of DOS Commands

--Unix Commands With No Direct DOS Equivalent

What Compiler Can I use?

-A compiler (and debugger)

-The Unix Compiler g++

-The Unix Debugger gdb

-Microsoft Visual C++

-Cygwin - a free windows compiler

-The official development of Dawn

Getting Started With Dawn on Unix

-Where to put the mud?

-Unix Step by Step Guide

--Unix Supplemental Notes

Getting Started With Dawn on Windows

-Where to put the mud?

-Windows MSVC++ Step by Step Guide

--Windows Supplemental Notes

-Windows Cygwin Quick Start Guide

Document Version History 


Introduction

The Dawn of Time is a free mud Codebase.  In other words, it is the platform used to host a multi-user online game typically accessed over a telnet connection.

This document describes how to setup a mud using the Dawn of Time codebase available from the Dawn website http://www.dawnoftime.org/.  There are a number of aspects to starting a mud starting which are covered, you may want to skip sections of depending on what is relevant to your situation. 

If you are wanting to play a Dawn based mud or are interested in briefly checking out the codebase from a players perspective it is recommended you connect to one of the Dawn based muds listed on the Dawn website.


OS/Hosting Considerations

Choosing an Operating System

The Dawn codebase is able to run on a number of operating systems. Dawn primarily supports two common categories of operating systems - Unix based and Windows (Win32 API) based.

Typical examples of Unix operating systems include Linux, FreeBSD, OpenBSD, Solaris, etc.  There are a number of distributions (installations) of Linux each with different merits.  Redhat, Debian and SUSE are some common Linux distributions - see http://www.linuxiso.org/ for a list of downloadable popular Linux distributions.

The level of support in the Windows world varies slightly depending on what version of Windows is used.  Dawn runs best on versions which evolved from the original Windows NT Kernel (e.g. Win2k3, WinXP, Win2k, WinNT).  Dawn will run on versions that evolved from the first Windows 95 release (e.g. WinMe, Win98, Win95) but limited testing is performed for Dawn running on these platforms.  Windows 95 based operating systems are fine for developing or running a local building port, but are not recommended for running a live mud of any size on.

Where to host a mud?

Depending on the size of your mud in terms of players and your budget affects how to approach this.  A small mud for just a few friends could run by friends connecting to your Windows machine on your broadband  connection which you leave permanently on.  If you are serious about hosting a mud though which you are trying to attract a lot of players - Uptime is the most important factor.  Therefore a machine dedicated to hosting the mud is essential and we also recommend running on a Unix platform because the Hotreboot feature works seamlessly.  The dedicated machine can either be on a broadband connection or on that of a mud hosting company.  It is strongly recommended that the mud is configured to automatically restart (typically using a crontab) if rebooted/after a crash or the server has to go down for maintenance.

It is always possible to change the hosting arrangements for your mud if a particular solution isn't working, also because of the unreliability of commercial mud hosting services, it is recommended that you don't sign up/prepay for lengthy contracts.


Obtaining the Dawn of Time Codebase

What does the Dawn Codebase consist of?

The Dawn of Time codebase is made up of a number of files which are available for download from http://www.dawnoftime.org/download/

The files available for download are named as follows:

Filename Description

dawn*-src.tgz

The Dawn of Time source code.

dawn*-support.tgz

Supporting files

dawn*-win32bin.zip

A precompiled version of Dawn binary which will run on Microsoft Windows.

Note: in this document * represents the version number - e.g 1.69r

The Dawn of Time Source Code

The source code is written in the C++ programming language.  Knowledge of this programming language is not specifically required to host a mud using Dawn, but is essential if you want to do anything beyond trivial modifications to any 'hard coded' aspects of the game. 

The Dawn source code is converted into the program which runs the mud (commonly called a binary or executable) by a process called compilation.  This compilation process is performed by a compiler and is covered later in this document.

It is not necessary to download the Dawn source code if you want to run Dawn on Windows without performing any structural/hard coded modifications as a precompiled version is available (see below).  If at a later date you decide you need to change something that is hard coded or move to a Unix platform you can always download the source code then.  Many aspects of how the Dawn codebase operates are configurable using the gameedit command (more on this later), making it one of the most flexible codebases available to date.

The Dawn of Time Support Files

The support file download is a compressed tarball (note the .tgz extension - think of it as the Unix equivalent of a zip file).  This can be uncompressed on a Linux platform with the command
"tar -xzvf dawn*-support.tgz"
(or using WinZip on a Windows platform).

You will find it uncompresses with the following directories:

Directory Description

dawn*\area

The default set of area files which come with Dawn.  This area set contains over 4900 rooms, 1150 mobiles (monsters/NPCs) and 2200 objects.

dawn*\help

This directory and the directories within it, contains the in game help files.  Each help file stores one or more help entries - combined to form a total of over 1000 help entries which are able are able to be read within the game with the help command or via a web browser connected to the Dawn integrated web server.

dawn*\system

The system directory contains all the 'system files' required to run the mud.  Examples of these include the lists of classes, races, skill groups, socials, continents and auto balance files.  While these files can be edited manually, it is recommended to edit them within in game editors (e.g. classedit, raceedit...) to ensure the file is not corrupted.

Because the mud wont start up without some of the above support files, it is essential that you download this file. 

You don't have to use all the area files in the Dawn area set, you are able to manually remove area file names from the area\arealist.txt file.  The actual name of an area file can be see within the game using the olc alist command.  Dawn requires the dawn.are file at a bare minimum, and an equivalent of the main ooc room in ooc.are is strongly recommended as this is necessary for the goooc command.

The Dawn of Time Precompiled Windows Binary

If you are wanting to run a copy of Dawn on a Windows machine, it is possible to download a precompiled version of the Dawn binary.  Contained within the dawn*-win32bin.zip file is the dawn.exe file (what you would obtain from compiling the source code on a Windows platform).

Apart from those hosting a small mud on a Windows machine using the precompiled binary, this binary is also useful for area builders.  Using this file they are able to run a local copy of the building environment and create areas on their local computer while online and offline.

So which files do I need?

If you are going to run your Dawn mud on a Unix platform, you need:
dawn*-src.tgz
dawn*-support.tgz
 

To run on Windows, where you will be developing using
dawn*-src.tgz
dawn*-support.tgz
 

To run on Windows, where you wont be modifying the source code (using precompiled binary) you need:
dawn*-support.tgz
dawn*-win32bin.zip


Unix Shell Account

What is a shell account

Dawn when run on a Unix server, runs within the context of a Unix shell account.  It is comparable to a command prompt in the Windows world (only it is designed to be run remotely).  A shell account enables you to remotely control the hosting server, instructing it to compile and run the mud etc.  You are obviously able to do a lot more than mud related tasks using a shell account, but this document doesn't go into this beyond basic commands which will help you get orientated.

Connecting to a shell account

Traditionally Unix shell accounts were accessed using the Telnet command.  Upon connecting using Telnet, you authenticate by typing in your shell account username and password.  The password is transmitted over the Internet in clear text (unencrypted) and it is therefore possible for someone to 'sniff' you account username and password when you logon without you being aware. 

Therefore, it is strongly recommended you connect  to your shell account using SSH (Secure SHell) software.

Free Unix SSH software is available from http://www.openssh.com/

Free Windows SSH software is available from http://www.chiark.greenend.org.uk/~sgtatham/putty/

Please note, if transferring files to and from your shell account using FTP, when you provide your username and password over the FTP protocol this is also in clear text.  It is also strongly recommended that you use SCP (Secure Copy) as a secure alternative for file transfers. 

An excellent free windows SCP client with a drag and drop interface is available from http://winscp.vse.cz/eng/

Unix Shell Account Commands

In the Unix world common dos commands tasks have different names, the following table shows some common Unix commands (with the nearest dos version to help those familiar with dos):

Unix Equivalents of DOS Commands:

Dos Command Unix Command Unix Description

dir

 

ls

ls -l

ls -al
 

ls -lart
 

List the files in a directory

List files - details format

List All Files - including those starting with a .
(the Unix version of a hidden file)

List All Files - in reverse order sorted by time
(newest files at the bottom of the list)

copy <file> <loc>

cp <file> <loc>

copy file <file> to location <loc>

move <f1> <f2>

mv <f1> <f2>

move file1 <f1> to file2 <f2>

del <file>

rm <file>

remove file <file>

cd <dirname>
cd
<no dos version>

cd <dirname>
pwd
cd

Change into a directory <dirname>
Show your current directory (present working directory)
change into your home directory

md <new dirname>

mkdir <new dirname>

Make a directory called <new dirname>

rd <dirname>

rmdir <dirname>

Remove a directory called <dirname>

dawn

dawn 1234

 

 

./dawn

./dawn 1234

./dawn 1234 &
 

nohup ./dawn 1234 &

Run the dawn binary (defaults to port 4000)

Run the dawn binary bound to port 1234

Run dawn as above in background
(logging going to your terminal)

Run dawn as above, logging going to the nohup.out  file.

Unix Commands With No Direct DOS Equivalent:

Unix Command Description

man <command>

Read the manual page on <command>.  e.g. man ls

apropos <keyword>

Search all the manual pages for the <keyword>
(not available on all Unix platforms)

grep <filename> <expr>

Search <file> for expression <expr>

wget <url>

Download the file at <url> and save to disk

<ctrl>+z

Suspend a process

bg

To put a process into the background

fg

Bring a process into the foreground (last processed bg'd)

jobs

To list all background tasks associated with your terminal

%1

To switch into background task number 1

ps ux

To show all processes belonging to your user account

ps -ef

To list processes

kill -9 <pid>

To terminate process with a process id of <pid>
(
This command can be used to terminate a hung mud)

w

See who is currently logged into the server

logout

Disconnect

note: If someone has some links to good Unix tutorials, you can send the links using the website contact page.


What Compiler Can I use?

A compiler (and debugger)

To compile the Dawn binary you need a compiler, different compiler products are available for different operating systems.  You may want to also use a debugger to aid in finding bugs.

The Unix Compiler g++

Most Unix servers have installed the excellent (and free) gnu compiler  g++.  If your server doesn't have this it is available from http://www.gnu.org/software/gcc/.  Installation of this compiler should typically performed by the system administrator, though it is possible to install your own local copy in your shell account.

The Unix Debugger gdb

There is a debugger which has been written to accompany g++.  GDB can be used to analyse core files to see what caused a mud to crash.  A core file is a dump of the memory used by a process at the point it crashes.  GDB can be downloaded from http://www.gnu.org/software/gdb/.

Microsoft Visual C++

Visual C++ is a commercial development product written by Microsoft - some times called an IDE (Integrated Development Environment).  It is called Integrated because it includes a compiler, a debugger, and a C++ editor.  The editor highlights the source code based on its syntactic meaning, and has a drop down box which can be used to instantly jump to any particular function by name. 

MSVC++ is able to do a lot more than what is required to develop Dawn, the most basic version available is sufficient, because of its integrated design it is strongly recommended for those wanting to develop on Windows.

MSVC++ is included as part of Microsoft Visual Studio (along with other Microsoft development products such as Visual Basic etc).

Cygwin - a free windows compiler

Quoting the cygwin website at http://www.cygwin.org/:

"Cygwin is a UNIX environment, developed by Red Hat, for Windows. It consists of two parts:
A DLL (cygwin1.dll) which acts as a UNIX emulation layer providing substantial UNIX API functionality.
A collection of tools, ported from UNIX, which provide UNIX/Linux look and feel."

Using cygwin, you are able to use a windows version of g++ and gdb to compile and run the dawn source code.  Cygwin is a free download, and further details on it are at the website address listed able.

The official development of Dawn

The Dawn codebase is developed using MSVC++ version 6.0  on Windows 2000 as of August 2002.  The source code is then transferred to a Linux server and compiled using g++ into the development mud. 


Getting Started With Dawn on Unix

The following instructions work on most Linux/BSD variants.  In Unix shell style, the ~ character (tilde character) is used to represent the top of your home directory... e.g. ~/dot/ represents the dot directory within the top level of your home directory.

Where to put the mud?

The directory naming convention used within this document, and the majority of Dawn muds is a follows:

Put the main mud port into ~/dot/

The olc/building port is in ~/olc/

A code/development port if used is in ~/code/

So the source code of the main mud port would be in ~/dot/src/

Dawn will happily run in other directories of other names, these are just the documented defaults.

Unix Step by Step Guide

The following instructions are based on if you are setting up dawn on a shell account which isn't currently running dawn in the ~/dot/ directory.

This guide assumes a few things about the environment you are running on.  These instructions will generally work for a modern Linux or BSD installation.

Unix command Comment

cd

Change in your home directory if you aren't there already

wget <url of latest src>

Download the latest source code. 

Checkout http://www.dawnoftime.org/download/ to find out what the latest version of the Dawn source code is called.  At the time this was written the latest version was called dawn1.69r-src.tgz... so if that was still the case you would use http://www.dawnoftime.org/download/dawn1.69r-src.tgz

If you don't have wget on the server, you can transfer the source code using some other method.  Wget can be downloaded from http://wget.sunsite.dk/ if you wanted to install it.

wget <url of latest support>

Download the support files. 

Checkout http://www.dawnoftime.org/download/ to find out what the latest version of the Dawn support files is called.  At the time this was written the latest version was called dawn1.69r-support.tgz... so if that was still the case you would use http://www.dawnoftime.org/download/dawn1.69r-support.tgz

tar xzvf <latest src>

Uncompress the source code file you just downloaded.

In the case of the 1.69r release you would type
tar xzvf dawn1.69r-src.tgz

note: If the tar command didn't work, you could try
gunzip -c dawn1.69r-src.tgz | tar xvf -

tar xzvf <latest support>

Uncompress the support file you just downloaded.

In the case of the 1.69r release you would type
tar xzvf dawn1.69r-support.tgz

ls dot

Confirm there is NOT an existing dot directory.

This command should return a message similar to:
ls: dot: No such file or directory
If you get a listing of files, then you already have a ~/dot/ directory.

If you have a ~/dot/ directory, you need to pick a different directory name to install and compile the dawn binary into (and change the instructions which follow appropriately).  If you can't figure out what this means and believe you have a ~/dot/ directory, then it is recommended that you get help from someone more experienced.

mv <dawn*> dot

Rename the directory which the source and support files uncompressed into to ~/dot/.

E.g. if the source and support files uncompressed into ~/dawn1.69r/ then you would type
mv dawn1.69r dot

 

cd ~/dot/src

Change into the ~/dot/src directory.

If you get an error message about an unknown directory, either the directory layout of the source code and support files has changed, or you have made a mistake.  It is recommended you get help from someone more experienced if you can't figure out why it isn't working.

make

Run the make command and check the instructions

Confirm that the instructions tell you to change into the configure directory and run configure. 

If the instructions do not say that, then the build process has changed since this document and you should proceed with caution.

cd configure

Change into the ~/dot/configure/ directory

./configure

Run the configure script.

The configure script is used to detect the exact environment of the Unix machine you are working on.  The Dawn code will compile differently based on the results of configure... for example, MCCP (Mud Client Compression Protocol) support will only be enabled if you have zlib on the server (the library required by MCCP).  Without this, if Dawn just assumed that MCCP support was available it would generate compile errors at the linking stage (the final stage in compilation where all the object files in the src/obj/ directory are merged into a single binary).

cd ..

Move up a directory

i.e. change from the ~/dot/src/configure/ directory to the ~/dot/src/ directory.  This step is required as make should be run within the src dir.

make

Compile the Mud binary!

This process will look something like the following:

shellaccount@servername:~/dot/src$ make
g++ -c -Wall -g -O act_comm.cpp -o obj/act_comm.o
g++ -c -Wall -g -O act_ente.cpp -o obj/act_ente.o
g++ -c -Wall -g -O act_info.cpp -o obj/act_info.o
... <insert about 240 file names here> ...
g++ -c -Wall -g -O whofmt.cpp -o obj/whofmt.o
g++ -c -Wall -g -O wizlist.cpp -o obj/wizlist.o
g++ -c -Wall -g -O com_time.cpp -o obj/com_time.o
rm -f ../dawn
g++ -g -O -lz -o ../dawn \
       obj/act_comm.o obj/act_ente.o obj/act_info.o
... <insert about 240 file names here> ... obj/whofmt.o obj/who.o obj/wizlist.o obj/com_time.o
shellaccount@servername:~/dot/src$

This compilation process creates a binary called ../dawn (~/dot/dawn in this case).  This binary is the Dawn source code in compiled form and able to be executed to run the mud.

You may get compilation warnings - on a clean install these generally can be ignored.  Dawn compiles cleanly on a large number of Unix versions so it is rare to get warnings.

If you get compilation errors, the compilation will fail.  If the compilation fails you could try using the gmake command to compile the code.  If this too fails, then either you have done something incorrect or the code is not directly supported on your choice of supported.  Either way fixing your problem is beyond the scope of this document.

cd ..

Move up out of the src directory into ~/dot/ (where the dawn binary resides)

./dawn

Run the dawn binary

It will most likely complain about some missing directories.  If it doesn't complain, then you can skip the next instruction.

If the dawn startup process fails, generally a descriptive error message will be displayed.  If dawn starts up successfully it will display a message in the last 10 or so lines stating something like:
:: <mud name>is ready to rock on port 4000.

You can use <ctrl>+c to terminate a mud running in the foreground like this.

./dawn --createdirs

Start dawn up in directory create mode.

This mode creates any missing directories.

./dawn

Start the mud up on the default port (4000).

If you receive a message during the bootup like:
Init socket: bind: Address already in use

Then port 4000 is in use by another process.  You can start Dawn up on any port higher than 1024. 
e.g. to start dawn up on port 1234 you could type: ./dawn 1234

If you have an error message which prevents you starting the mud other than those described above, your problem is beyond the scope of this document.

To start dawn in the background you can use the command:
nohup ./dawn 1234 &

While this isn't the most ideal method, it is a starting place... the better method is to use a startup script which is scheduled to run every 5 minutes... if the mud is down it will automatically restart it.

Connect to your mud.

You can connect to your mud using a mud client/telnet on the port you started the mud.  Instructions are displayed when you create your first character on how to set yourself up as an admin.

Unix Supplemental Notes:

  • When ever you want to start the mud, change into the ~\dot\ directory, then type your startup command which is most likely based on "nohup ./dawn 1234 &"

  • To recompile the code, change into the ~/dot/src directory and type make (or gmake, if make has problems on your OS).  If the code seems to compile okay, but randomly crashes for no apparent reason you can try typing "make clean", then make.  "make clean" deletes all the object files, and therefore does a complete rebuild of the source code instead of just compiling what it believes to be the changes since the last compile.


Getting Started With Dawn on Windows

Where to put the mud?

The following instructions are based on if you are setting up dawn to run within the c:\dawn\ directory. 

Windows MSVC++ Step by Step Guide

These instructions are bare bones, but should be enough to get you started.  The instructions are for both the .NET and 6.0 versions of MSVC++.

# Instruction

1

Download the dawn source and support files from the website from the same url as described in the Unix instructions above.

2

Uncompress the files using winzip, then rename so the src directory is called c:\dawn\src and the support files are in c:\dawn\area,  c:\dawn\help and c:\dawn\system.

Note: you may wish to change the drive letter from c: or the c:\dawn directory, used this is not a problem.
Note: It is important that you uncompress the files using a zip tool which retains the directory information... for example within you c:\dawn\src you should have a number of directories including 'extras', 'config' and 'obj'... if not, delete the src directory and use a different uncompression tool such as winzip to perform this step.

    Load up Visual C++ and do the following:

3

VC++ v6.0: From the File menu select the New option
VC++ .NET: From the File->New submenu select the "Project" option (Ctrl+Shift+N)

4

VC++ v6.0: Click the projects tab, and select Win32 Console Application
VC++ .NET: Select "Visual C++ Projects" in the "Project types" list, Select the "Win32 Project" template

5

Set the location to c:\

6

Type in "dawn" as the project name (without the quotes)

7

Click okay

VC++ v6.0:    A dialogue 'Win32 Console Application Step 1 of 1' appears:
VC++ .NET:   A dialogue 'Win32 Application Wizard' appears:

8

VC++ v6.0: Choose empty project
VC++ .NET: Select Application Settings, Select "Console application" and check "Empty Project"

9

Click finish

10

VC++ v6.0 only: Click okay in the 'New Project Information' dialogue.

11

VC++ v6.0: Click on the 'FileView' Tab within the 'Workspace' bar
VC++ .NET: From the View menu select "Solution Explorer" (Ctrl+Alt+L)

12

VC++ v6.0 only: Expand the 'dawn files' folder to show Source files, Header Files and Resource files

13

Remove the Source files, Header Files and Resource files folders as they generally get in the way (optional if you really want them keep them)

14

VC++ v6.0: Right click on 'dawn files'
VC++ .NET: Right click on "dawn" under "Solution 'dawn' (1 project)"

15

VC++ v6.0: Select 'Add Files to Project...' from the popup menu
VC++ .NET: Select 'Add Existing Item...' from the 'Add' popup submenu

    A file selection dialog will popup in the c:\dawn directory

16

Go into the src directory

17

Click on any file displayed there

18

Press <ctrl>+a to select all files in the src directory (note: we do not want to add files within src subdirectories)

19

Click okay (to add all the src files to the project)

20

Select save workspace/solution from the file menu

21

Press <ctrl>+F5 and click on yes to compile the code if required

    MSVC++ will compile the Dawn code then attempt to run the code
    we need to create the missing directories using the 'dawn --createdirs' command.

22

open a command prompt

23

c:   (change into c:)

24

cd \dawn (change into the dawn directory)

25

debug\dawn --createdirs  (run the dawn binary you just compiled in directory create mode)

26

exit   (close the command prompt)

27

Press <ctrl>+F5 in visual C++ to rerun the binary

28

Telnet to the mud by connecting to 127.0.0.1 port 4000

29

Create a character, and then follow the in game instructions for converting them to an immortal character

Windows Supplemental Notes:

  • You can close down dawn running in this way by using <ctrl>+c

Windows Cygwin Quick Start Guide

Cygwin can be downloaded for free using the installer available from http://www.cygwin.com/.  From this website, you can get started by clicking the 'install cygwin now' link - this will download/run a setup program.

While running the setup program, you can choose to install from the Internet, or download to disk for installing... either option should work fine.

The installer lets you pick what packages you would like, take the Cygwin installer default but in addition within the Devel section select the latest versions of the following:

  • binutils

  • gcc

  • gdb

  • make

The above will amount to roughly 30MB worth of downloading, uncompressed on the hard disk will be just over 70MB.

You may also optionally want to download the following:

  • unzip (in the archive category)

  • man (in the docment archive - gives you access to the help files via the man command)

  • cygwin-doc (Cygwin-specific manual pages)

  • newlib man (some additional manual pages for the man command)

  • lynx (in the web category)

  • wget (in the web category)

Install all these packages onto your machine (the default location is c:\cygwin - if you want to use another path that is fine, just adjust the following instructions accordingly). I normally use the dos default file format option if you are asked. Tell it to put an icon on your desktop near the end of the installation.

Once you have installed, click the cygwin desktop icon, you will find yourself in a unix looking environment, where c:\cygwin is your default root directory. e.g. typing 'cd /bin' would change you into the c:\cygwin\bin directory.  You can access other drive letters or the root directory of C: using the cd command... e.g. 'cd d:/', will put you in the root directory of d:.

Follow the Unix based getting started instructions, if you have already downloaded the dawn1.???.src.tgz file, put this in a location you can find - e.g. c:\cygwin\home within the shell.   Alternatively you can access other drive letters on your machine with the cd command... e.g. 'cd d:/', will put you in the root directory of your d:

This should be enough to get you started, If someone feels like writing a more detailed Cygwin specific section feel free to send it to me and I can include it here.

 


Document Version History

http://www.dawnoftime.org/getting_started.html

Date Version Description

09 April 2004

1.3

Updated to reference the 1.69r version of the codebase
Added instructions for MSVC++ .NET
Other minor tweaks throughout the document

05 December 2002

1.2

Added Table of Contents and various tweaks throughout document

09 September 2002

1.1

Addition of the Cygwin Quick Start Guide

08 August 2002

1.0

Initial Document

Note: in this document * represents the version number - e.g 1.69r