How To Convert Your Ideas Into Reality A CircleMUD Coding Manual Jeremy Elson and the rest of the CircleMUD Group <[email protected]> Section 4 written by Luis Pedro Passos Carvalho <[email protected]> November 17, 2002 Abstract This is a guide to writing C code for use with CircleMUD. Includes a description of com- monly used functions, tips on how to add new commands and spells, and other commonly asked coding questions. Good familiarity with both C and UNIX is assumed, although system-level UNIX C programming skill not required. The intended audience is for CircleMUD coders, and this document does not cover area-building. See the building document for details on that. More information about CircleMUD, including up-to-date versions of this documenta- tion in ASCII and Postscript, can be found at the CircleMUD Home Page <http://www. circlemud.org/> or FTP site <ftp://ftp.circlemud.org/pub/CircleMUD/ > Contents 1 Introduction 3 2 Overview and Coding Basics 5 2.1 An Internet Server Tutorial . 5 2.2 The Way Things Work – Overview . 8 2.2.1 Boot Phase . 8 2.2.2 Interactive Phase . 11 1 2.2.3 Shutting Down . 13 2.3 CircleMUD’s Global Variables . 14 2.3.1 World Variables . 14 2.3.2 Object Instance Lists . 15 2.3.3 Other . 15 2.4 Frequently Used Functions . 15 2.4.1 Basic String Handling . 15 2.4.2 Argument Processing . 16 2.4.3 Character Output (Hello, world!) . 17 2.4.4 File Input . 17 2.4.5 Utility Functions . 18 2.4.6 Character/Object Manipulation . 18 2.4.7 Object Locating . 20 2.4.8 Character Locating . 21 2.4.9 Violence . 22 3 Adding Features 22 3.1 Adding Commands . 22 3.2 Adding Socials . 25 3.3 Adding Spells . 26 3.3.1 Template Spells . 27 3.3.2 Manual Spells . 29 3.4 Adding Skills . 30 2 3.5 Adding Classes . 32 3.6 Adding Levels . 33 3.7 Adding Color . 34 4 Writing Special Procedures 36 4.1 Overview of Special Procedures . 36 4.2 Pulsed vs. Command-Driven Special Procedures . 36 4.2.1 Pulsed Special Procedures . 37 4.2.2 Command Driven Special Procedures . 37 4.2.3 Preparing for all occurrences . 38 4.3 Relating Special Procedures to Objects, Mobiles, and Rooms . 38 4.4 The Special Procedure Function Header . 38 4.5 The Special Procedure Return Value . 39 1 Introduction When DikuMUD was first released in 1990, the authors were rightly more concerned with getting their product released than with little cosmetic details. Between writing 25,000 lines of C code and building the entire DikuMUD world, complete with objects, rooms, and monsters, it’s under- standable that making the code portable or clean was not at the top of the list of their priorities. Most DikuMUD distributions were not portable and had a number of bad bugs and even syntax errors which prevented the code from compiling at all. If a potential MUD implementor wanted to run a Diku, an excellent knowledge of C was necessary, because the MUD simply wouldn’t run otherwise. Now the situation is much different. With the proliferation of user-friendly code bases such as Merc and Circle, any Average Joe can just type “make” and inflict yet another MUD on the world. Therefore, the number of truly unique MUDs as a fraction of the total is dropping drastically because coding experience is no longer a prerequisite to being able to put a MUD up on the ‘Net. Some people may tell you that you don’t need to know how to code in order to run a MUD – don’t believe them. Those people are wrong. 3 If you want your MUD to succeed and flourish, you’ll have to know how to code in C. Other- wise, your MUD will be exactly like every other MUD out there. You’re not the only person who knows how to type make! Although the quality and originality of your areas is also very important, it is the code that transforms the areas from lifeless text files into a living, breathing virtual world. If you don’t know how to code, you won’t be able to add new features, respond to requests of your players, add new world flags for your area builders, or even fix the simplest of bugs. Running a MUD without knowing how to code is certainly a recipe for disaster. If you’re a great game-player and have some terrific ideas about how a MUD should work, but don’t know how to code, you should either learn or find a good coder who can join your team. Don’t assume that you can get away with running a MUD without knowing C – you can’t. Not for very long, anyway. This document won’t teach you how to program in C; you’ll have to learn that on your own. Instead, it will try to familiarize you with the way Circle’s code is structured so that you can put your C skills to good use. Even for the best programmers, it takes a while to “get into” a program and feel comfortable enough with the way it works to start modifying it. Hopefully, by reading this manual, your breaking-in period for getting to know Circle will be minimized. Circle consists of close to 30,000 lines of moderately dense C code, so you shouldn’t expect familiarity to come overnight. The best way to learn is to DO. Get your hands dirty! Don’t be afraid to tinker with things. Start small by modifying existing functions. Then, work your way up to creating new functions by copying old ones. Eventually you’ll be able to write completely original functions, and even tear some of Circle’s native functions out as you realize completely new ways of implementing them! But you should learn to walk before you try to run. Most of all, try to remember that coding for a MUD should be fun. It can sometimes be easy to lose site of the ultimate goal of personal enjoyment that MUDs are supposed to provide, particularly when they start to get crushed under the weight of their own politics or the egos of their administrators. If you enjoy coding, but find yourself spending more time on politics than you are on code, don’t be afraid to restructure your MUD or even remove yourself as Imp to a lower wizard position which requires less politics. People often ask me why I do so much work on CircleMUD. They want to know why I spend so much time writing code only for the purpose of letting other people use it, since I don’t actually run a MUD myself. After reading the preceding paragraph, the answer to that question should be clear. I’ve spent considerable time coding for on-line MUDs in the past, but after a while it just wasn’t fun any more. I eventually found myself doing nothing but working politically and doing virtually no coding at all. Eventually, I even lost the will to write code completely. By quitting from my various Immortal positions on every MUD I was of which I was a member, and concentrating on my public Circle releases, I have the luxury of enjoying MUD coding in its purest form: all code, no politics. Well, almost none, anyway – my past still comes back to haunt me now and then. :) A final thought: nothing will turn potential players away from your MUD more than logging in and finding that it’s exactly like half the other CircleMUDs out there. Strive to show the world something new and unique. And may the source be with you. 4 2 Overview and Coding Basics Before getting down to the details of learning how to write code, we will first examine generally what a MUD is and what it does, to give you an overview of what type of program you’re working with. The first section, “An Internet Server Tutorial”, describes how Internet servers such as Cir- cleMUD work. It contains interesting background material if you’d like a deeper understanding of how the MUD actually interacts with the Internet and the computer on which it runs, but little practical coding advice. So, if you’re reading this document purely to learn how to write MUD code, you should skip to the second section. 2.1 An Internet Server Tutorial An Internet “server” is a program which provides some service to Internet users (called “clients”). There are many different types of servers on the Internet. FTP servers allow you to transfer files between a remote computer and your own. Telnet servers allow you to connect to remote machines. News servers allow you to read USENET news. Similarly, CircleMUD is a server which allows you to play a game. However, MUDs such as CircleMUD differ from most Internet servers in several very impor- tant ways. When ten different people connect to CircleMUD, they can all interact with one another. CircleMUD – a single program – must be aware of many users at the same time. On the other hand, most other Internet servers such as FTP servers are written to only be aware of one user at a time. If more than one user wants to use an FTP server simultaneously, the operating system runs two copies of the server: one to handle each user. Each individual copy of the FTP server is not aware of anything but the single user it has been assigned to serve.