Folks who want to hack their PennMUSH server's hardcode can look forward to considerably more extensive documentation in the source itself. The devteam has begun to use doxygen, a documentation system, to comment the source code (starting with 1.7.7).
Doxygen parses the comments in the source code and generates useful reference materials for the web. You can see the documentation in progress for 1.7.7 at http://www.pennmush.org/docs/1.7.7/html
Generally, powers are used to give an object limited permissions for something specific without having to resort to giving an object the wizard flag.
You can add and otherwise manage powers as God from in a game using the commands documented in HELP @POWER2, but aside from softcode checks using
haspower(), you'll have to modify hardcode to test for them.
Let's say you want to a new indexed text file to support a command called 'rumor'. rumor is to work just like help, news, or events, but is to be based on a file game/txt/rumor.txt which will be automatically generated from files in the game/txt/rumor directory with names like january.rumor, february.rumor, etc.
This turns out to be pretty easy. You'll need to modify two files:
- game/txt/Makefile (for Unix-like systems)
Here's the plan:
- Edit game/mush.cnf, and add this line:
help_command rumor txt/rumor.txt
- Users of Unix-like systems (including Windows systems like msys that provide bash, perl, and make):
N.B. This discussion applies to the PennMUSH flag system as of PennMUSH 1.7.7p5. If you're using an earlier version of PennMUSH, you need to find an older edition of Javelin's Guide for PennMUSH Gods
The easiest way to add flags in PennMUSH is to log in as #1 and use @flag. If you don't need your flags to have any special hardcoded effects, this is definitely the way to go.
So from here on out, I'll assume that you are coding your own hardcoded system (e.g. a space system) that you expect to distribute, and your system needs to automatically add a SPACE flag to the database and be able to test it in hardcode in order to implement special effects.
The PennMUSH devteam have adopted some coding conventions, which are listed below. If you use these conventions, your hacks are more likely to work on multiple systems, and will be easier for me to integrate into new patchlevels.
You can save yourself a lot of hassle if you're careful in how you hack the PennMUSH code. When you decide to add new code, or change old code, add an #define into options.h which will turn your code change on or off. For example, if you're adding a new feature to change the WHO format, put something like this into options.h:
/* If defined, the WHO commands will use a new format */
You can go a long way with diff and patch, but if you're making serious changes, you need more powerful tools. If you hack at the PennMUSH source code long enough, you will eventually make a mistake, and want to go back to an earlier version of your work. Or you'll make a really good but extensive change, and want to keep up with patchlevels or produce your own patchfiles to distribute it to others.
You can make your life a lot easier with some form of "source code control" or "revision management" software. ere are some common revision management approaches:
- Backups. Make a directory alongside your pennmush directory called "oldpenn", and put a copy of your source code into it. When you make changes, you can recover your old files from oldpenn, use it to produce patches, and eventually copy your new files into oldpenn when you're sure they work. Many people keep a "clean" source directory containing the original dist code of their version, in case they need it. Of course, if you need to go back more than one revision, you're in trouble unless you clutter your disk with many many oldpenn directories. A variant of this strategy involves storing older versions as compressed tar files.
Changes and bugfixes to the MUSH code are often distributed as paches in context diff format. Diffs are files which describe how the source code should be changed. The program "patch" (by Larry Wall, distributed by the GNU project) automatically reads these files and makes the changes to your source code. If you don't have the patch program, ask your system administrator to get it! (A version for Win32 systems is available at http://unxutils.sourceforge.net)
The "diff" program (a standard unix utility) can produce apatchfile, given the original and revised source code
files. For example, if you revise player.c, and save the older version as player.c.orig, you could make a patchfile like this:
diff -c player.c.orig player.c > patchfile
The "-c" switch indicates that you want a context diff, which is more detailed than an ordinary diff and better for patches. If you're going to publicly distribute the patch, be sure it's a context diff! (Another diff format, unified diff, is also appropriate. You can use "-u" to get a unified diff. Some people find them easier to read, and some -- like me -- don't.)
Sure, you want to add your own hacks to PennMUSH, but you also want to keep up with the patchlevels that the developers release so you get the benefit of bugfixes and new features, right? In this section, we'll look at how that's done, and you'll learn about generating your own patches, applying patches, and more sophisticated mechanisms of source code control.
I'll refer to the distributed PennMUSH source code and patches as the 'distributed branch' or 'dist'. We'll be looking at the situation where you have modified the dist to create your 'local branch' or 'local'. If you start out with the dist at patchlevel n (we'll call that dist[n]), and you add some hacks to it, you've created local[n] -- dist[n] + your local changes. Suddenly, the developers release dist[n+1] and a patch dist[n]->dist[n+1]. Now what?