MUF Programmer Guidelines

When writing/modifying MUF programs for NarniaMUCK, there are four possible scenarios:

  1. The program already exists on Narnia, isn't an official GlowMUCK program, and hasn't been imported into the NarniaMUF CVS Repository1
  2. The program already exists on Narnia and is already in the NarniaMUF CVS Repository1
  3. The program to be written hasn't existed before--a brand new program.
  4. The program already exists on Narnia and is an "official GlowMUCK" program. Best way to check this is to list the program and then see if it is the same program as one of the ones in the GlowMUCK MUF Repository.

Scenario #1: Already exists and not in the NarniaMUF Repository

This is possibly the most likely scenario right now. We've established using a version control system only recently and rather than spend hours importing all programs into it, we're importing them "as we need to edit/modify them."

Essentially, before making any modifications to a program, we need import the program into the CVS Repository, add the things that make it easy to upload new versions of the program to the server, commit those changes, and only then can we proceed with our needed modifications. Definitely a case where we're "slowed down at the beginning" in exchange for saving us from lost time and grief later. Here's a basic step-by-step:

  1. Make sure that the in-game MUF program editor has line numbers turned off. (@prog <any program>, 1 l(ist), if line numbers is turned on do 'n' to turn them off, then use 'a(bort)' to exit out without modifying the program).
  2. Go to a fairly quiet room on the MUCK.
  3. Turn your client's logging on. Your client's logger should NOT log ANSI color codes into the logfile. If it has such a feature, be sure it is turned off.
  4. List the program (@list <program>). This gets the program text into your log file.
  5. Edit your log file. Trim/scrub out pages, whispers, etc. that might have occurred before or after you listed the program. At the end of the program listing, the muck will have said "363 lines displayed.", remove that as well.
  6. Once you've cleaned up anything that wasn't actually the program, move the logfile to your local copy of the NarniaMUF CVS Repository, in the NarniaMUF directory.
  7. Name the file appropriately. This is a 'use your own best judgement' situation, but here's are some guidelines: As a concession to editors that identify file types by extension, the filename should have the extension '.muf'. If you on Windows or other GUI operating systems, make sure the OS isn't hiding the current extension from you, if it is, you'll end up putting blah.muf.txt as the filename, instead of blah.muf. The main part of the filename should either be the same as the name of the database item on the MUCK or if you prefer, you can follow the traditional convention of 'programtype-name' (examples: cmd-who, heartbeat-mobiles, lib-strings, etc.). If you can do so without breaking anything, rename the database item to match--without the .muf extension.
  8. Perform a CVS add on the file with your CVS client2
  9. Perform a CVS commit to complete the import of the file into the repository2, as with any commit, you should include a login message. Something like 'initial import into repository' is sufficient.
  10. I know...it feels like you should be done...but you're not. Now we add things to the file to make it easy to upload to the server. Go to the top of the file in your text editor and something that looks like this to the top of the file:
    @teleport $heartbeat/mobiles=me
@program heartbeat-mobiles
1 99999 delete
1 insert
( heartbeat-mobiles: $Date$ $Revision$            )
( Author: Wixenstyx                                                            )
( Modified-By: Feaelin                                                         )
( Purpose: Replacement for the Animazing program, a program to move thing dbi's)
(          around as if they were NPCs/creatures.                              )
( Dependencies: lib-strings, lib-wix,                                          )
( ---------------------------------------------------------------------------- )
( Place any documentation you think program needs here.                        )
( ---------------------------------------------------------------------------- )
(
  $Log$
)
( ---------------------------------------------------------------------------- )

    The first line (@tel...) makes sure the program is 'nearby'--this avoids the accidental creation of a new copy when uploading the latest version.
    The second line (@prog) will start the MUF program editor. The third deletes the current program so we can upload the new one in its place. 4th line puts the MUF editor in insert mode so the program text can be inserted. The rest, the comments is a collection of information that should be in the file. Note that $Date$, $Revision$, $Log$ will be automatically replaced by CVS with appropriate text.

  11. Now jump down to the end of the file. After the last line of the program (which should be a semi-colon!). Append something like the following:
    .
c
q
@register heartbeat-mobiles=heartbeat/mobiles
@set $heartbeat/mobiles=_version:$Revision$
@teleport $heartbeat/mobiles=*NarniaHeart

    Probably obvious what this does, but just in case: a period by itself to tell the MUF program editor to get out of insert mode, c to compile the program, and q to exit the MUF program editor. @register to make sure its registered to the correct registered name (in general, this should be $cmd/somename or $lib/somelib, or $heartbeat/someheartbeatprg. Again, CVS replaces $Revision$ with the version number, so this will effectively update the version number on the muck. And finally, an @teleport to teleport the program to wherever programs are being stored. I've been storing heartbeat programs on NarniaHeart, seemed convenient. I'd recommend storing the rest on NarniaEngine.

  12. Review your changes to the file. It can be pretty ugly if there's a typo or weird-mispaste. So take this moment to double-check your work. Smile
  13. Manually @teleport the program to you on the muck. The first time through, you can't rely on the program being properly registered, so you need to do this via dbref.
  14. Test the new script (e.g. upload). Using whatever facility your MU* client has for "dumping text to the muck from a file", you dump the entire contents of the file to the muck. If your client doesn't have this feature, get a different client. I DO NOT recommend "highlight all, copy, and paste". There are many things that can go wrong with that approach.
  15. Make sure the entire program uploaded, it teleported when it should have, that you don't have two copies of the program, and that the program still executes in the same manner as it did before.
  16. If everything is correct, commit your changes to the CVS Repository.2. Be sure to include a log message! Something like 'prepared file for uploading with CVS tags' will probably do.
  17. Perform the upload again. This updates the version number and it gives you one last test of the script.
  18. At last...make the changes you planned on making.
  19. Test the changes (upload to the muck, make sure the program still did what it could before, and that your fix fixed the problem).
  20. If your changes worked, commit your changes to the CVS Repository. Be sure to include a brief note of what you did/why. Start off with "Issue #2345." So we know what task/request/issue this was associated with.
  21. Yay. Done.
  • 1. a. b. If you don't know what this is, I recommend reading the CVS Starter Guide
  • 2. a. b. c. if you're unsure on how to do this, consult the CVS Starter Guide