# Getting Started with Dawn

Version 1.3 - 09 April 2004

Getting Started with Dawn

Introduction

OS/Hosting Considerations

Obtaining the Dawn of Time Codebase

Unix Shell Account

What Compiler Can I use?

Getting Started With Dawn on Unix

Getting Started With Dawn on Windows

## 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?

 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 directoryList files - details formatList 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 cp copy file to location move mv move file1 to file2 del rm remove file cd cd cd pwd cd Change into a directory Show your current directory (present working directory) change into your home directory md mkdir Make a directory called rd rmdir Remove a directory called 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 Read the manual page on .  e.g. man ls apropos Search all the manual pages for the (not available on all Unix platforms) grep Search for expression wget Download the file at and save to disk +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 To terminate process with a process id of (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 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 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 Uncompress the source code file you just downloaded. In the case of the 1.69r release you would type tar xzvf dawn1.69r-src.tgznote: If the tar command didn't work, you could try gunzip -c dawn1.69r-src.tgz | tar xvf - tar xzvf 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 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 ... ... 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 ... ... 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 binaryIt 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: :: is ready to rock on port 4000.You can use +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++.

#### Windows Supplemental Notes:

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

### Windows Cygwin Quick Start Guide

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.

• 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