COB Help

The COB Help series was created to help novice object programmers learn the macro language. It can be a bit tough to learn from the reference files, after all.

The best way to learn any language is by example. In this case, that's especially true. Examining other COBs is a good way to do this, but if you want to create an object from scratch, step by step, this is the place to start.


Intro: The basics of the language.

Intro: The basics of the language

Well, before you get started, there are a few things you should know.

First of all, there are two types of code used by objects: Scripts and installation scripts. Most objects have one installation script and several regular scripts. This is not necessarily true for all objects, however. An object can have no installation script, and merely install scripts to run later; or, it can have no scripts besides the installation script.

A common type of object with only an installation script is one that inserts a copy of an existing object (like cheese or a ball) into Albia. The scripts that run the object are already installed, so there is no need to add new ones. The installation script creates an object and places it within the world, then quits.

Installation scripts always begin with inst, without exception. This tells the game to execute the script in a single timer tick. inst can be used in other scripts to do the same thing, but it is required here.

Other scripts begin either with the scrp command, which installs them into the scriptorium, or the scrx command, which removes a script. For example, scrp 2 6 1 1 installs script #1 for an object of family 2, genus 6, species 1. (That object, by the way, is a piece of cheese. Script #1 is one of the activation functions.) These commands, too, can be used within a script, although the practice is uncommon.

The number of a script is the event that triggers it. To see a full list of events, read scriptnumbers.txt on the Reference page.

Basic Syntax

There are a few basic syntax rules:
  1. All commands are four-letter words called tokens. They must be in lowercase (even if you see me write them in uppercase; I do that just so they'll stand out). All support files, including sprites and sounds, have four-letter filenames (not counting the extensions).
  2. Commands are separated by commas (,) or spaces. Either is allowed, although it is better form to use commas in most cases.
  3. Strings and some filenames are enclosed in brackets [ ], but they are rarely used. The language has little support for string operations. Some commands like SAY$ and BBD: WORD use strings.
  4. Each script has 10 variables: var0 through var9. They last only for the life of the script. If you want to do any calculations, use a variable. It may be possible to do calculations directly with some flags of an object, but I don't recommend it.
  5. Each object has 3 variables: obv0 through obv2. They last for the life of the object. Eggs use obv0 to hold a genetic moniker, and word objects (like the computer or my super speech toy) use obv0 to determine which word in their internal list will be played. It's a good idea not to use these variables unless you need the object to remember something that it can't remember any other way. (For example, many objects use their current pose to determine what state they're in.)
  6. Anything that isn't a four-letter token is typically a number or a string enclosed in brackets. Many numbers (such as chemicals or object flags like ATTR) range from 0 to 255 (1 byte). Variables range from -2,147,483,648 to 2,147,483,647 (4 bytes). (Incidentally, those commas are there just for show; don't actually type them in.)
That's the syntax in a nutshell, which is helpful to know when you start programming.

New Objects

If you make a new type of object, there's one cardinal rule to follow: Give it a unique class.

An object's class is its family, genus, and species. This determines what creatures will call it, and a bit of how it behaves. Most objects are simple objects, in family 2. Compound objects (including vehicles, lifts, the computer, etc.) are family 3. Creatures are in family 4.

The genus is also important. Family 2, genus 6 is the category for all food objects. Genus 7 is drink objects. 13 is toys, 14 is big toys; 4 is plants, 15 is weeds. You can observe some of the class categories by looking up a typical object in the list of implementation codes (also available on the Reference page).

Example: If you don't know what class 2 12 x is (family 2, genus 12), open the list of implementation codes and search for any objects with family 2, genus 12. You should find either the shower or the clock; those are both in the class of soothing objects, which Norns may call "shower" or "clock" or something similar. If you want to create a soothing object, think of a species number that (most likely) no other objects are using.

The reason class must be unique is that Creatures will try to run scripts for your object. If you install a new script with the same class as an existing object, the old object's scripts will be dumped in favor of the new one. If you use scrp 2 6 1 1, for example, you'll change the behavior of all cheese objects in the world. New cheese won't behave properly, since they don't install any scripts.

You might be tempted to use duplicate classes for your own objects, if you think no one will be using more than one kind at a time, but that's a really, really bad idea.

To set an object's class, you must use the setv clas command right after you create an object. is determined by adding up the following values:

Alexander Laemmle's COE and my own CobCom have functions which will tell you the value to use for CLAS if you supply the family, genus, and species.

For simple objects (family 2), you must also supply a set of attributes using the ATTR flag. A list of values for this flag is available in the macro language documentation. Also, you should set the object's response to clicks or creature activations using the BHVR command.

On to the Tutorials

If all this seems a bit too much to absorb, just move on to the first lesson. There you can see some of this in action, and get a feel for how the macro language works.

In the examples, I use CobCom to code the scripts. In CobCom, you can enter line breaks and the program will remember to use commas to separate the commands when you're done.

Enough blather. Read the first lesson, already.