Difference between revisions of "Chapter 1"

Revision as of 12:37, 28 May 2009

'(incomplete)'

Numbers

The first thing you'll notice while looking through SPHERE scripts is the wide variety of ways to write numbers. Since numbers are insanely important to a SPHERE scripter, this is the first lesson in the series. By the end of the lesson, I hope that you have a general understanding of hexadecimal, decimal and binary numbering systems, and SPHERE's ways of identifying each. You will also know how to generate random numbers either from a series or from a list of choices.

The first thing you need to understand is that the way we count is not the only way to count. Our numbering system contains ten digits (0, 1, 2, 3, 4, 5, 6, 7, 8, and 9). Therefore, at the tenth number, we have to add an extra column to the number, and reset the first column to zero (1, 2, 3, 4, 5, 6, 7, 8, 9, 10). That's why our numbering system works the way it does.

In the decimal system, without realizing it, we write our numbers to mean powers of ten. For example, if you take the number 17282 (which I just made up), and divide it down we get this:

To reach the number 17282 from here, we simply take ten to the power of the number in the top row, multiply it by the number in the bottom row, and then add all those numbers together. We get 10000 + 7000 + 200 + 80 + 2. Obviously, this is simplistic, and we do it without even realizing we're doing it. You're probably thinking "Riiight, what does Taran think he's getting at?" Well, we aren't so special that our counting system is the only way to count.

Now, there is another numbering system that is used almost solely by computers. It only contains two numbers (1 and 0) and is therefore called the binary (meaning two) system. Binary numbers look like this: 101011101101, and you often see them in ads for computers and other electronic equipment (oftentimes they are shown streaming out of a CD player on television commercials). Digits in the binary system are called bits (short for BInary digiT)Binary numbers are almost impossible to translate to decimal directly, and so some math must be done.

Binary works in the same way, by adding powers of a number. In the case of binary, since there are two numbers in the whole system, that number is naturally two. Here are some examples of powers of two. These numbers might look familiar to some people.

Ridiculous eh?  :)

We need a better system! The reason we get such strange results is because 10 is not a power of two. We need to find a system where the number base IS a power of two. The most commonly used system used is base-16, or hexadecimal. I'm sure if you've perused the SPHERE boards, you've seen the word hex floating around. No, this isn't a curse or evil spell, it's a short way of saying "hexadecimal".

See how it works? There are an extra six numbers added onto the end of the system, represented by the first six letters of the alphabet.

Now, in SPHERE scripting, you are almost NEVER going to be dealing with binary numbers that are NOT powers of two, and if you do, you can simply use any scientific calculator to figure it out. But it's a lot easier in hexadecimal.

(This is the last table, I promise!!)

As you can see, there's a bit of a pattern in the hexadecimal column. You might be thinking, there seems to be some sort of pattern of the numbers 1, 2, 4 and 8. And you would be right. Another detail you may notice is the zeros in front of the hexadecimal numbers (like 0100, rather than just 100). In SPHERE, that 0 tells the script "Hey, this number is HEX!" 0100 and 100 are very different numbers.

Let's say, for a SPHERE script, you need to set the 13th bit of a number (FLAGS, for example), you could write something like this:

SRC.FLAGS |= 8192

But would you really remember that 8192 is 2 to the 13th power? I didn't think so. What would be easier is to go down through your list in your head, until you reach the 13th number. (Remember, START AT ZERO when you're counting!)

And there you have it. The first 14 powers of two in hexademical.

SRC.FLAGS |= 02000

The above code is identical to the previous example. 8192 (decimal) is EQUAL to 02000 (hexadecimal)

8192 = 02000

You may be saying, "How do I know he's just not making all of this up?" Well, our wonderful friends at Microsoft have provided us with a nice tool that converters from decimal to hexadecimal to binary to octal (ANOTHER numbering system that is useless in SPHERE, so we will not deal with it). It's called the Calculator. You may find it by clicking your start button, going to Programs, then Accessories. Calculator should be sitting there looking pretty. Once in the calculator program, go to the View menu, and click Scientific. You'll see the display drastically change. To convert a number between numbering systems, simply click on the original system (Dec), type a number (8192), then click on the button for the other system (Hex). Automagically, Windows will convert your decimal number to hexadecimal. Stick a zero on the front, and SPHERE will be perfectly happy with it.

This is probably the hardest thing in all of SPHERE scripting to understand. Luckily, because of the next section, you won't have to deal with scary numbers most of the time. If I still have you at the end of this lesson, I know you're going to do great!

Onward to some SPHERE scripting!

DEFNAMES

Here's a list of scary numbers you might encounter while programming in SPHERE.

Obviously, no one is going to want to remember those numbers. Back in the old days, before SPHERE and TUS (pre-.50 SPHERE) and even into the mists of Grayworld (pre-.41 TUS), we all had to remember those numbers. I know all of those numbers I just said (except the serial number which I just made up), plus a couple dozen more, by heart. Luckily for those of you who don't like to sit around remembering numbers all day, SPHERE has developed a system whereby things can be identified by names instead of numbers.

Actually, the things are still identified by numbers. It's the numbers which are identified by the name.

In the game, type .add 0eed and press enter. A target will come up and you'll create a single gold piece.

Now type .add i_gold and press enter. You will create the same single gold piece.

Now which is easier to remember, 0eed or i_gold. I would say that i_gold wins by a long shot. But how does this magic happen? Let's take a look at the script definition for a piece of gold. Don't worry about understanding it. I'll explain item scripts in full in the next section! You can find this script in the file sphere_item_resources.scp.

[ITEMDEF 0eed]
//gold coin
DEFNAME=i_gold
TYPE=T_GOLD
VALUE=1
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coin
DUPELIST=0eee,0eef

I have highlighted in red the line that really matters for the purposes of this lesson. Take note of the 0eed in the top line of the script, and then ignore the rest of it. That 0eed is the real item number of this item. We'll cover item numbers more in the next section.

But the real line we want to see the DEFNAME=i_gold line. This is where the script tells the server, "I want item 0eed to be identified by the text i_gold from here on." If you tried to refer to i_gold before the server read this script (more on reordering scripts in Chapter 2, the server would spit out an error, but now it knows what that refers to, so you can use it in the game or in another script.

You should ALWAYS give items you create a DEFNAME that fits the item. Usually the defname will be defined in the [ITEMDEF] identifier itself (again, more on this later), but if you insist upon using numbers, be sure you give it an easy-to-remember name (not golden_gulash for a viking sword). It makes it easier to remember names than numbers.

A second way to define a DEFNAME is by using the [DEFNAME] tag in a script. Here is an example of that:

[DEFNAME colors]
color_blue 02
color_red 021
color_green 041

You'll find a script similar to this in spheredefs.scp, another file that should be loaded before any other file.

Here's the rundown on this script, line by line:

Line 1: This is where the type of script and the defname (yes colors is the defname of this script) is defined. This tells the server what type of script to expect between this and the next identifier (identifiers are the lines contained in square brackets). All identifiers have this format. The first parameter is the script type. These are numerous, and I will go over them as we get to them. The second parameter is either an ID number or a defname. In most cases, in the scripts you write, it will be a defname. The only exceptions to this I can think of would be if you used a program to insert a new item into the client files.

Lines 2-4: These set up your individual DEFNAME pieces. It says that color_blue is equal to 02, color_red is equal to 021, and color_green is equal to 041. You may have any number of spaces between the name and the value. The definitions contained in spheredefs.scp are among the most useful you will encounter, as they prevent you from writing the long scary numbers we went over in the previous section. These include things like names for flags, names for item attributes, names for the built-in MIDI or MP3 music, names for memory types, and many other things. Look through the file to see what it offers you.

That's about it for DEFNAMEs. You'll see more of these later as we cover other types of scripts.

Now go on to learn about items.

ITEMDEF

Or, how to make a mountain from a molehill, SPHERE style

Most people make item scripting much harder than it needs to be. For the purposes of this tutorial, since there is a more advanced one later, we will simply go over the basics of an ITEM script, line by line. We'll be using the gold script from the previous lesson, provided I can find it again....

Ah, here it is, conveniently color coded for your viewing pleasure!

[ITEMDEF 0eed]
//gold coin
DEFNAME=i_gold
TYPE=T_GOLD
VALUE=1
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coin
DUPELIST=0eee,0eef

This is the simplest of item scripts, since it has no additional behaviors beyond existing. I will go through this line by line, describing to you what each line does, and how it affects the end result.

Line 1: [ITEMDEF 0eed]

The first lines of an item script are frequently the most important. Basically, this line tells the server "Hey this is an item and I want it to be called 0eed!" The server then looks through one of the client files (specifically art.idx), and identifies whether or not this item is one of the built-in items. I think all items below 04500 are defined as built-in items, so never define a new item in that range. By typing this line, you tell the server that an item script is following. You also define 0eed as a valid item, which will definitely help later on when you try to give gold to players!

Line 2: // gold coin

This is the SPHERE version of comment. C programmers will recognize the format immediately. If you type // on any line of code, everything beyond that is ignored by the script reader. This can be on a line by itself, or at the end of a line to explain what the specific line does. In all cases, it won't affect your program, just make it easier to read.

Line 3: DEFNAME=i_gold

You should know by now what this does! If you don't, go back and read the previous lesson! It tells the server that i_gold and 0eed mean the same thing. In item scripts, all parameters are defined in that format:

variable=value

You will see later on, when we get into scripting, how that format will help you more than you would believe. Items have a good number of variables that you can define, including:

• DEFNAME
• ID
• TYPE
• VALUE
• RESOURCES

Other variables depend on the value of the TYPE. Which leads us right into...

Line 4: TYPE=t_gold

The first thing you might say is "What the heck is t_gold?" Well it's a DEFNAME. Actually it's a number. And that number is 72. If you want to check me on this, look in spheredefs.scp, it's there! Writing TYPE=72 would have the exact same effect.

There are, currently, 183 built-in item types. These are hardcoded item types that contain predefined actions for an item. If an item has no type, when you click it, you get the "You cannot think of a way to use that item" message. There is a complete list of types, and how to set them up, here . All you need to know for now is that setting the type of this item to t_gold has no effect other than to make the item act like a gold coin (i.e. you can buy stuff with it!) Setting another item to type t_gold would probably make the server think that you can buy stuff with that item too. I've never tried this. It might be an interesting way to have unique currencies...

Line 5: VALUE=1

This defines how much the item costs when purchased, in gold. Of course, this is one gold piece, which is worth, well, one gold piece. So the value of the item is one.

Lines 6-8: CATEGORY, SUBSECTION, DESCRIPTION

These are lines used only by SPHERE's GM tool, Axis, which actually saves you a lot of work by typing ".add i_gold" for you. More importantly, it types ".add 01737" and things like that for you, for items that were not important enough to get their own separate DEFNAME.

Line 9: DUPEITEM

It would be a ton of work for the SPHERE team to define all 8000 items that came with the game, especially when many of them are the same. (For an example of this, use the .xflip command on a door or sign. It cycles through all of the DUPEITEMs for that the item being flipped.) The numbers listed here are item numbers, which probably have not been defined yet. Here is the script for item 0eee:

[ITEMDEF 0eee]
//gold coins
DUPEITEM=0eed
CATEGORY=Provisions - Miscellaneous
SUBSECTION=Coins
DESCRIPTION=Gold Coins

As you can see, there is only one parameter for this whole item. It reiterates the DUPEITEM and sends the server looking to our 0eed (or i_gold) item for more information, such as TYPE and VALUE. DUPEITEM only exists to save typing. You probably won't use it.