Developer Primer

From LSWiki

Revision as of 00:06, 28 May 2007 (edit) Kabal (Talk | contribs) (→FTP Client and Code Editor) ← Previous diff		Revision as of 11:38, 28 June 2007 (edit) Chaos (Talk | contribs) (→A Few Necessities) Next diff →
Line 7:		Line 7:
	*First and foremost, the developer channel is "dev".		*First and foremost, the developer channel is "dev".
-	*If you get zapped by a dev--a likely fate for new developers--or whatever, just "heal me" to heal yourself.	+	*If you get zapped by a dev -- a likely fate for new developers -- or whatever, just "heal me" to heal yourself.
	*To move yourself somewhere quiet, "goto" a person, preferably a dev in a non-player room. E.g. "goto chaos".		*To move yourself somewhere quiet, "goto" a person, preferably a dev in a non-player room. E.g. "goto chaos".
Line 13:		Line 13:
	*There are several commands that let you review changes to the MUD that are important and that you get in the habit of using immediately. These are "show changes", "promotions", and "privs". You should probably <pre>set alias since to show changes since;promotions since;privs since</pre> and be in the habit of using that alias at least once per login. (The first time you do this you will probably be spammed, as it will give you the entire changelog; don't feel obligated to read through it all.) You can also use these commands with other arguments, such as "show change 1" to see the most recent change ("help change" for the full range of possibilities).		*There are several commands that let you review changes to the MUD that are important and that you get in the habit of using immediately. These are "show changes", "promotions", and "privs". You should probably <pre>set alias since to show changes since;promotions since;privs since</pre> and be in the habit of using that alias at least once per login. (The first time you do this you will probably be spammed, as it will give you the entire changelog; don't feel obligated to read through it all.) You can also use these commands with other arguments, such as "show change 1" to see the most recent change ("help change" for the full range of possibilities).
-	With that being said, its time to familiar yourself with the structural backbone of Lost Souls.	+	With that being said, its time to familiarize yourself with the structural backbone of Lost Souls.
	==The File Structure and the Command Line==		==The File Structure and the Command Line==

---

Revision as of 11:38, 28 June 2007

This page is documentation for new developers. If you edit this page please try to keep it to a minimum. Insofar as is possible it should not be overwhelming. These are the bare essentials needed to do two main things: (1) get comfortable as a developer--there are a lot of new commands and possibilities that should be learned right at the start, and (2) to get up and running development-wise, i.e. to start looking at examples of code and manipulating ones own objects. Advice on thematic/conceptual considerations, specific coding dos-and-don'ts, rules and expected behavior--all that should go elsewhere.

Some of this material may be old hat for those who have past experience with command line interfaces, FTP, or coding. If you haven't, going through this material may take some time. Please be patient. If you remain active-minded, all of this will become far less mysterious the more you dev, I promise.

Contents 1 A Few Necessities 2 The File Structure and the Command Line 3 Other Commands 4 FTP Client and Code Editor 5 Coding 6 Further Reading 7 Attitude

A Few Necessities

• First and foremost, the developer channel is "dev".

• If you get zapped by a dev -- a likely fate for new developers -- or whatever, just "heal me" to heal yourself.

• To move yourself somewhere quiet, "goto" a person, preferably a dev in a non-player room. E.g. "goto chaos".

• There are several commands that let you review changes to the MUD that are important and that you get in the habit of using immediately. These are "show changes", "promotions", and "privs". You should probably

  set alias since to show changes since;promotions since;privs since

  and be in the habit of using that alias at least once per login. (The first time you do this you will probably be spammed, as it will give you the entire changelog; don't feel obligated to read through it all.) You can also use these commands with other arguments, such as "show change 1" to see the most recent change ("help change" for the full range of possibilities).

With that being said, its time to familiarize yourself with the structural backbone of Lost Souls.

The File Structure and the Command Line

If you're familiar with command line interfaces (CLIs), this will be old hat. If not, it may take some getting used to. This document will at least assume you are familiar with directory trees, i.e. that you know at least what the various components of "C:\windows\system" designate. If you don't and you can't figure it out, then, I'm sorry to say, you just need to learn more about computers in general before you start coding for Lost Souls.

• Your home directory--where you can directly upload and download files from via FTP (see below)--is /w/devname. So for me, Twilight, my home directory would be /w/twilight.

• The cd command stands for "change directory", and is used to navigate from one folder to another. When used by itself, without any other arguments, it moves you to your home directory. "cd .." will move up one directory and is used to predicate relative movement within a file structure (e.g. "cd ../etc" will move you from "/w/twilight/Hanoma/dmn" to /w/twilight/Hanoma/etc"). "cd /" will move to the root directory and is used to predicate absolute movement (e.g. "cd /w/twilight/Hanoma/etc" will move you there no matter where you are).

• ls lists the contents of a directory. By default it lists them in a little table consisting of only file names in various colors (what the colors designate will become apparent to you over time). "ls" also takes arguments to display hidden files, or to display files in a verbose format that indicates their size and when they were last modified. "help ls" for more.

• pwd stands for "print working directory", and will print the directory that you are currently in. This is useful if you don't remember where you are and don't want to get a file listing, either because its too long (like /obj/magic/rings) or uninformative (like a project daemon directory, which mostly look the same).

• cp and mv respectively copy and move files. To rename a file you use mv within a directory ("mv workroom.c workroom.c.old" renames the former file to the latter).

• rm deletes files. The files will be moved to /tmp/.removed/ for a short time, or until they are ovewritten by you deleting a file with an identical name. Note in this regard that deleting a file is actually less hazardous than overwriting one with a bad "cp" or "mv" command. Try not to do that, it sucks.

• If you have the privileges to write in a directory, you can use mkdir to make a new directory.

• Last but certainly not least, more will display the contents of a file.

Try moving around some, seeing what files are there, and reading some files. Don't worry if you don't understand them. "cd /pub/fun" might be an entertaining place to start. Also, within your home directory, trying making and removing some directories, copying them, etc. If you have any files there, move them around some too. If you don't, try it after you've read the FTP section and put some there.

After you've mastered this you should be fairly well-equipped to traverse any *NIX CLI, so rejoice.

Other Commands

There are a huge number of commands available to you as a developer. First there are more settings than there were when you were a player, type "help set" and "help show" to see them. Particularly useful is "help set notify". I'd recommend turning most or all of your notifications on. Also useful is "help start crashing". I'd "start crashing channel all" for starters. (Many developers also "start being unlisted on all" as well.) You should "switch omniscience" until it's on, so you don't have to identify people and items. Also: "people" is much more informative than "who".

There is also the useful "show administrative commands" file. Each of those commands has a help file for it. Don't worry if you don't understand what many of them do; just skim through it occasionally, and as you develop more and more, you'll learn the various commands.

FTP Client and Code Editor

You need both of these things, and it is highly preferable that you have instances of each that can interact with the other.

An FTP client is a program you can use to transfer files to and from an FTP server. Lost Souls is such a server. You will be able to transfer files to and from your home directory. There are a number of free FTP clients. A code editor is just a plain text editor that has certain capabilities for dealing with structured code, the most important of which is colorizing various things. The ideal situation is to have a code editor which you can use to "directly" edit files on the server. (Directly is in quotes because the actual mechanics of this usually involve saving to a temporary file on your computer and then uploading, but it happens behind the scenes and you don't need to worry about it.) Otherwise you will have to save the file, then upload it, instead of just saving and uploading in one step. Given the amount of screwing up/minor modifications you will be doing, this extra step can become an egregious pain in the ass.

For Mac people, I recommend Cyberduck and either BBEdit or SubEthaEdit. Either of these should interface with Cyberduck (check the Cyberduck preferences and documentation for how). It might take some fiddling to get this to work. As the program is frequently updated, I'm not going to provide a step-by-step for this, but it isn't so complicated.

Someone give PC recommendations please? I'm way out of date. I know Chance likes Crimson. Presumably *nix people will know what to do without my telling them.

Slash uses EditPlus on his PC (it's a code editor with FTP).

Kabal uses jGRASP, which is free but may be a little heavyweight for some.

The information you will use to login is: host: lostsouls.org, port: 21, username: your developer name, all lowercase, password: your atman password.

Coding

This is not the place to give even a proper introduction to coding, but I'll tell you a few very basic things so you can start looking at examples and cloning your own items, even though you might lack any real knowledge of what is going on. This is how I and probably many people actually start coding.

Most things on the mud are "objects". Objects are little bundles of code in a file that have been processed and stored in memory.

Generally the first thing I have a coding neophyte developer do is copy a simple file to his home directory, modify it slightly, and then clone the object. For example, copy over /obj/weapons/longsword.c to your home directory, now modify the file in your code editor and FTP client, then clone it ("clone <filename>") to make a new object. You might change the weapon type from Weapon_Type_Longsword to Weapon_Type_Katana, and the material from Material_Steel to Material_Adamantium. Then voila, you have an adamantium katana. Much of your initial learning and coding will follow this pattern in more and less complex ways.

If you're wondering what a function (one of those things that looks like this: foo(), or foo(bar)) does or how to use it, see if there's a manual page for it with man <topic>. For example, "man add_proportion". Note that often you will not understand a lot of the stuff in the file, but you will probably be able to understand some stuff, and hopefully the stuff you need. A good example of this is "man message", which should, via example and instruction, tell you enough to write a message after a few tries, even if you have no idea what most of it is saying.

Most of all get used to reading the mud code. Often you can get some sense of what's going on just by the function names.

An important tool in learning how to code is the eval command. "eval <argument>" will process the argument as code. For example, "eval me->set_attribute(Attr_Siz, 300)" will make you rather large. "eval find_living("<person>")" will return the object for said person. "eval 1 + 3" will return 4. If you ever wonder what something does, try testing with eval. You can also "log Eval" to see recent evals by yourself and other developers.

Further in-MUD reading in this regard is: help reload, help reset, help clone, man style, and man projects. Some of this may seem mysterious right now, and will probably not in a week or so.

Formal non-LS-specific documentation on LPC coding can be found here. It's actually quite useful, though I recommend mucking around a bit before you delve in. Certain things in it will be inapplicable here, and are often easier, because of the work Chaos has done on our core library. However, it will teach you important basic concepts, like what a function is and what the parts of a function are, that will be quite applicable.

Don't feel shy about asking coding questions on the dev channel.

Further Reading

• After you get familiar with being a developer and what possibilities are open to you, you should read "man developer". Reading it beforehand will probably just be confusing, but it contains the rules and guidelines and behaviors expected of you as a developer.

• While you will learn coding primarily by example, there are some very bad examples of code out there, and it can be hard to tell what is what. To innoculate yourself from the worst aspects of this, read "man style" for our standard coding styles. Some of this may be hard to understand at first, so you'll probably want to check back after you've learned some more code.

• You should familiarize yourself with some of the log files in /txt/log. Also note that you can use the "log" command to return the tail end of any file in that directory. For example, "log lpmud.log" will return the newest portion of the error log. This is a particularly useful logfile, as is the "Eval" log.

• Another very important thing you'll need to learn how to use is the "grep" command. In its simplest cases, the ones you'll use most frequently, grep is fairly easy, so get started reading the help files on it and using it to find simple patterns in documents.

• Where the hell are things, anyway? Read up on the Lost Souls directory structure.

Attitude

Learning how to code is no different than learning how to cook, fish, drive, play an instrument, speak another language, paint, do calculus, interpret history, write well, think clearly, or be a good lover. It takes time, practice, and effort. Do not expect coding to be easy, to "come naturally," or to be able to do all the cool stuff right away or even relatively quickly. Learn how to feel good about learning things inch-by-inch, and don't take any fact you've learned as trivial. Everything you learn is a step towards becoming a better coder, and you will be learning things all the time. Keep in mind that you don't know a lot of things, but you do know some things. Make notes of things that you don't know how to do and try and make a point of, at least occasionally, trying to learn something hard on that list. Don't be afraid to experiment and try things, you (probably) won't break the mud, and if you do, no one will hate you forever.

The vast, vast majority of developers never learn or produce anything of consequence, and either quit or lurk uselessly. Usually it's because they have misconceptions about what it means to develop, to learn how to code and produce content. These result in improper attitudes. Such people have no fun. Do not fall into this trap. Learning how to code is a process, one that takes your voluntary effort and time, no matter how intelligent you are or what else you already know. There is nothing mysterious about it.

Happy developing!