Palace Client manuals Palace Server ManualsWizards and Owners  ManualPalace Scripting manualHow to make Avatars ManualsPalace BuildersChat Guides

Iptscrae Language Guide



An Introduction to Iptscrae

This section introduces Iptscrae:


What is Iptscrae?

Iptscrae is a Forth-like interpreted language used exclusively by the Palace software. It possesses a full compliment of commonly-needed operators and functions, as well as over 100 Palace-specific commands, keywords and functions.

Here is a sample Iptscrae script:

ON OUTCHAT {
OCHAT GLOBAL
CHATSTR OCHAT =
{
"coffee" "$1" GREPSUB WHOPOS ADDLOOSEPROP
} CHATSTR "^buy (.*) coffee$" GREPSTR IF
}


Reverse Polish notation

Unlike other scripting languages you may have seen, Iptscrae might appear rigidly formal and possesses almost no punctuation. Iptscrae's syntax also uses RPN ("Reverse Polish Notation"), a style of command structuring that may seem a little "backward" until you get used to it

RPN uses what is called a postfix word ordering. In a sense, this is "backwards" from the usual infix word ordering that most of us are used to. For example, we are using infix word ordering when we say "two plus three." In postfix word ordering, it would be "two three plus." This is what the Palace software expects to see.

While saying "two three plus" might seem quite strange to you, to a computer it makes a good deal of sense. After all, the computer can't do anything with the operator until it possesses both operands; it can't perform an operation until it has all the data needed. In Iptscrae, as in many other programming languages, all data is stored on a stack until you pop it off and use it for something (see below for more information on how the stack operates). We have two pieces of data here -- the number 2 and the number 3 -- so in strictly logical terms, when we say "2 3 +", what we're really telling the machine is:

Put 2 on the stack.

Put 3 on the stack.

Add the two top things on the stack.

Place the result on the stack.
In plain English, you can think of this as placing the verb (action) at the end of the sentence or after the direct object. For example, instead of saying "I walk to the store," you'd say "I store walk."

Here are a few more examples of the differences between infix and postfix word ordering
Infix: Postfix:
2 + 3
2 3 +
(2 + 3) * 4
2 3 + 4 *
X = 4 - 3
4 3 - X =
printf("Howdy")
"Howdy" Say


Scripting the stack

All Iptscrae functions put the results of some operation onto something called the stack. If you're not familiar with the use of a stack, it can be a tricky concept to get hold of. Here's one way to think about it:

Imagine a spring-loaded stack of dishes like they have in cafeterias. The spring is set so that only one dish is available at a time. When you pop one off the stack, the rest get pushed up so that a new one becomes available; conversely, if you put a dish on the stack, the ones beneath it get pushed down so that your new one is the only one available.

There you have your stack metaphor, and that's pretty much how it works; except that putting something on the stack is called "pushing" and taking something off the stack is called "popping." In fact, if you ever want to remove the top-most value on the stack, you can always issue a POP command, which discards the top-most value and makes the next one available. You can also swap the two top-most items by issuing a SWAP command. Pushing occurs automatically. To see this in action, type the following statements into your Palace client input window:

/ "one" "two" "three" SAY

/ "one" "two" "three" SWAP SAY

/ "one" "two" "three" POP SAY

/ "one" "two" "three" POP POP SAY

So now you can see that when we tell Iptscrae " 2 3 + ", the following steps occur:

  1. Push 2 onto the stack

  2. Push 3 onto the stack

  3. Pop the top two items off the stack, add them, and push the result onto the stack

When it's done, the result (5 ) is sitting on the top of the stack, where we can easily get at it with another command.


How to run Iptscrae

Depending on what you're trying to do, there are several ways to enter Iptscrae commands. "One-shot" commands can be typed directly into the Palace client input box, or more permanent changes can be made to the script by owners and operators in authoring mode. For those interested in total control, any word processing program that can save as ASCII (text only) can also edit Iptscrae script files. The following sections explain how to do all of these things.

Entering Iptscrae in the input box ("Slash Commands")

A good way to get started with Iptscrae (or to test the functionality of individual commands) is to launch The Palace client, enter any room that allows user scripts, and type your commands straight into your client input window. To let the Palace software know that the coming text is a command (as opposed to mere speech), you must begin the line with a forward slash ( / ).

For example, if I type:

10 10 SETPOS

everyone in the room will see me say "10 10 SETPOS". Not what I wanted. But if I type:

/ 10 10 SETPOS

the SETPOS command is executed instead, and my avatar moves to position 10 , 10 on the screen.

Like any complex system, the best way to get a feel for Iptscrae is to just jump in and start playing with it. The following examples will give you a good start. As you can see from the inclusion of the forward slash, these lines were intended to be typed into the Input Box in the Palace client. To paste them into scripts, remove the preceding slash.

/ "Hello" SAY

This says "Hello".

/ "My name is " USERNAME & SAY

This shows how to add two pieces of text together. USERNAME is a keyword that resolves to your name. The ampersand ( & ) is the concatenator; this operator takes the top two things off the stack and sticks them together into one big string variable, which it pushes back onto the stack. The SAY command takes this variable and sticks it in a cartoon balloon.

/ 2 2 + ITOA SAY

This one adds 2 and 2 together, converts the result to ASCII text (using the ITOA function), and displays the results in a cartoon balloon.

/ 2 3 * 4 + ITOA SAY

This one multiplies 2 and 3 together, then adds 4, then converts the answer from integer to ASCII and says the result.

/ "Hello" 10 40 SAYAT

This one says hello at the specified X (horizontal) Y (vertical) position on the screen. X cannot exceed 511. Y cannot exceed 383. This is because the screen dimensions of the Viewing Area are 512 by 384.

/ 100 RANDOM ITOA SAY

This one causes you to say a random number. Try it a few times; each time it will be different.

/ "Hello" 512 RANDOM 384 RANDOM SAYAT

This one says hello at a random position on the screen; try it a few times. 512 RANDOM determines a random number from 0 to 511. 384 RANDOM determines a random number from 0 to 383.

/ 10 10 SETPOS

This one moves your avatar to position 10, 10 on the screen. Try substituting different numbers.

/ 512 RANDOM 384 RANDOM SETPOS

This one moves you to a random position. Try it a few times.

By playing around with these simple examples you can get a feel for the flow of the language. Once you understand what these examples are doing, you can move on to creating your own, more complex, scripts.

Iptscrae in Authoring Mode

When in authoring mode (select Authoring Mode from your client's Operator Menu as described in The Palace Operators Guide), you can edit the script of any spot in the current room.

  1. Select the spot to be edited.

  2. Double-click within its boundaries (alternately, you can select Door Info from the Operator Menu while the spot is selected). The Door Info window will appear.

  3. Click Script (Macintosh) or Edit Script (Windows). You'll see the scripting window (shown in Windows version):



This window is little more than a large scrolling textbox. Any scripts already associated with the selected spot will appear here. By directly editing the text in this window and clicking OK (or selecting Save for Mac users), you cause the server to update the script file. The new script begins functioning almost immediately (this might take up to a minute on slower systems or under bad network conditions).

NOTE: The Script Edit window displays only the Iptscrae code, not the Room/Spot description code.

To see the scripting window in action, try the following simple example:

  1. Create a new room and put a door in it.

  2. Double-click on the door to bring up the Door Info window.

  3. From this window, make the door's Type Normal. This turns it into a spot.

  4. Click Script to pull up the scripting window.

  5. Now add a simple event handler (like this one, for instance)

    ON SELECT {
    "I selected the Spot!" SAY
    }

  6. Click Ok (or select Save for Macintosh) and turn authoring mode off.

  7. Now test the script by clicking on your new spot.

Iptscrae in ASCII: Editing script files

Using the scripting window in the Palace client doesn't provide you with access to everything. The only way to obtain 100% access to the contents of the script is to edit it directly, which can be done using any word processing program. The only stipulation is that the word processor must be capable of saving as ASCII ("text only"), and fortunately, it's hard to find one that isn't. Simply open the script file and edit it as you would any other document; but be sure to make a backup copy first!

Never edit the server script while the server is running. This may cause overwrite errors, which can corrupt the file and/or cause your server to hang. Always save your server and make a backup before modifying your peserver.pat file.

When you have finished editing the script file, save it (remember: text only) and launch the server. If your script file is well-structured, you'll see no error messages as the server sets up your Palace site. If you're a Windows or Macintosh user, the next thing you see will be the server interface itself. Congratulations; your new script has taken effect!


Anatomy of a script file

Although to beginners Iptscrae might appear to be an irregular mass of confusing commands and oddly-ordered references, in fact it's really quite a formal language, with a rigid and symmetrical structure all script files must adhere to. You got a glimpse of this structure while editing your own cyborg.ipt file (see The Palace Users Guide); you've probably also seen it in the scripting window while you were in authoring mode. The basic structure looks like this:

ON EVENT {
command
}
ON EVENT {
command
{
atomlist
}
}

Basic Event Handling Structure

This example shows two event handlers. The first possesses only a single command, while the second possesses a command and an atomlist (see the following paragraphs). Note that an event handler always possesses a pair of curly brackets that denote its portion of the script. Any or all of the possible event handlers may appear here. Within each handler, any number of individual commands or atomlists may appear. The only limit is the total size of all scripts for the current room, which should not exceed 15.8 kilobytes in size (and that's an awful lot of Iptscrae).

Before moving on to the next level of the script structure, a note on terminology is necessary. The Palace community uses the word script in a number of different ways. While it is true that scripts are fractal in nature (i.e., small "scripts" can be put together to create larger things which might just as easily be called "scripts"), for purposes of this manual we need to differentiate these things semantically. The following terminology makes things a bit more clear:

Another word for handler would be routine. Another word for atomlist would be subroutine.

When working with the Cyborg.ipt file, this is as much as you need to know; since there is only one Cyborg (you), all handlers in the script obviously refer to that entity. When working with the server script things get more complex, and two additional levels must be added to the structure we have just created. These two new levels appear above the level of "scripts" -- they are doors/spots and rooms.

Here's how it works Just as commands and atomlists are contained within handlers, handlers in the server script are found only within scripts (those clearly-marked SCRIPT ... ENDSCRIPT areas in the script file). Scripts are themselves contained within spots (one script per spot). Finally, spots (and their cousins, doors) are contained within rooms. The following three bullet points, then, would be placed above the previous three:

All elements higher than event handlers -- scripts, doors, spots and rooms -- are identified by special keywords indicating where they begin and end. These keywords are:

Element Begin End
Room
ROOM
ENDROOM
Spot
SPOT
ENDSPOT
Door
DOOR
ENDDOOR
Script
SCRIPT
ENDSCRIPT

Demarcation Keywords

Correct use of these keywords is crucial to the successful operation of the server script. The keywords are shown in BOLD CAPITALS in this example:

ROOM
; Room Data
DOOR
; Door Data
ENDDOOR
SPOT
; Spot Data
SCRIPT
ON EVENT {
Command
Command
}
ON EVENT {
Command
{
AtomList
}
{
AtomList
}
}
ENDSCRIPT
ENDSPOT
ENDROOM

Basic Room Structure

In addition to the basic layout of keywords, this simple example also illustrates the types of "plurality" a script file can accommodate. Multiple commands and atomlists can be placed within a single handler, and multiple handlers can be placed within the SCRIPT ... ENDSCRIPT region of a single spot (there can only be one SCRIPT ... ENDSCRIPT region per spot, however).

Let's examine a sample room from the original "Mansion" Palace to see how this structure is put to use in real life. The following code was taken from the room called Heaven's Gate...

ROOM
ID 777
NAME "Heaven's Gate"
PICT "Heaven.gif"
ARTIST "Elaine Alderette"
DOOR
ID 1
DEST 103
OUTLINE 0,309 512,313 512,384 0,384
ENDDOOR
SPOT
ID 2
OUTLINE 35,35 96,35 94,76 34,77
SCRIPT
ON ENTER {
"FazeIn" SOUND
CLEARPROPS
"Halo" DONPROP
8 SETCOLOR
}
ENDSCRIPT
ENDSPOT
SPOT
ID 3
OUTLINE 387,24 444,21 437,57 390,51
SCRIPT
ON SELECT {
"palace://mansion.thepalace.com:1313" NETGOTO
}
ENDSCRIPT
ENDSPOT
ENDROOM

Example Room ("Heaven's Gate")

In this example, the room is constructed in nested levels of detail: Scripts reside within handlers, handlers reside within the areas indicated by SCRIPT and ENDSCRIPT keywords, SCRIPT ... ENDSCRIPT regions reside within doors or spots, which reside within the Room itself. It is the rigidity of this structure that allows the server to quickly locate and execute the correct actions at the correct times; this is key to the power of the Palace.

NOTE: ON INDENTING: Although indenting your code is considered good programming practice and is definitely recommended for Iptscrae programmers, it is not strictly necessary, nor is it aided or enforced in any way by the software. In other words, it's up to you. But it's hard to imagine anything more confusing than unindented Iptscrae

Specifying room data

Every room in a server script begins with a block of data, only some of which is accessible via authoring mode. This "room data block" will contain some or all of the following commands:

ROOM
ID number
PRIVATE
NOPAINTING
NOCYBORGS
HIDDEN
NOGUESTS
NAME "Room Name"
PICT "picture.gif"
ARTIST "Artist Name"
PICTURE ID number NAME "another.gif" <TRANSCOLOR number> ENDPICTURE

The Room Data Block

The Room block has the following components.

ID number

This line indicates the roomID assigned to this room in the script. Although this number may be assigned by whatever arbitrary means you wish, there must be a number assigned, and it must be unique to the room. In other words, it's perfectly fine to number rooms sequentially, or to skip numbers between rooms, or to put rooms in illogical order, but every room must possess an ID which is different from any other room's ID.

PRIVATE

PRIVATE

This line, if it exists, hides the number of people in the room. Generally, when a user looks in the Rooms Window (via the Options Menu in the Palace client), each room is shown with the number of people currently in that room. Private rooms, on the other hand, possess a dash instead of a number. The only way to tell the number of users in a private room is to enter it. This line can be toggled in authoring mode via the Private option in the Room Info window.

NOPAINTING

NOPAINTING

This line, if it exists, prohibits the use of all paint commands in the room. It is a good idea to use this command in rooms with a large amount of scripted activity (looping alarms, for example), as painting can seriously affect the speed of events in the room. This line can be toggled in authoring mode via the No Painting option in the Room Info window.

NOCYBORGS

NOCYBORGS

This line, if it exists, prohibits user scripts (also known as "cyborg scripts") in the room. It is a good idea to use this command in rooms with a large amount of scripted activity (for example, alarms), as well as in rooms where fairly large numbers of people are expected to gather, as user scripts can seriously affect the speed of events in the room. This line can be toggled in authoring mode via the No User Scripts option in the Room Info window.

HIDDEN

HIDDEN

This line, if it exists, keeps the room from showing up in the Rooms Window. For all intents and purposes, the room doesn't exist for non-operators (owners and operators still see all rooms in the Palace). Note that non-operators can still enter the room via a door or by using the GOTOROOM command if they know the roomID. This line can be toggled in authoring mode via the Hidden option in the Room Info window.

NOGUESTS

NOGUESTS

This line, if it exists, prohibits Guests from entering the room (making the room into a "members only" room). This line can be toggled in authoring mode via the No Guests option in the Room Info window.

NAME

NAME "Room Name"

This line indicates the name of the room as it will appear in the Status Bar (just beneath the Viewing Area in the Client interface) and when accessed by the ROOMNAME command. The room name can be changed in authoring mode via the Room Info window.

PICT

PICT "picture.gif"

This line indicates the name of the .GIF image used as the background of the room. Whenever a user enters the room the Palace client checks to see if it possesses this graphic, and requests it from the server if necessary. The background graphic of a room can be changed in authoring mode via the Room Info window.

NOTE: All background graphics should be 512 by 384 pixels in size (since this is the size of the client's Viewing Area; larger images will not be seen in their entirety, and smaller images will not fill the screen). To avoid unwanted colorshifts, the Palace Palette should be used for all Palace art (this palette can be extracted from any of the images that come with the Palace software).

The Palace client for Macintosh version 2.3 can display .JPG files as well as .GIFs. To support older Macs and Windows users, however, GIF images must be still made available. When entering a room for which both file types exist, Macs version 2.3+ will request the JPG file only, while older Macs and Windows clients will request the GIF file only.

ARTIST

ARTIST "Artist Name"

This line indicates the name of the artist whose work appears in the room. The name can be changed in authoring mode via the Room Info window.

PICTURE ... ENDPICTURE

PICTURE ID number NAME "picture" ENDPICTURE

This line indicates the name of a graphic (.GIF) that will be used to animate a spot in the room. Whenever a user enters the room the client checks to see if it possesses all the graphics called for, and requests any graphics it needs from the server.

If additional graphics will be used in the room (i.e., anything besides the background image itself), each must possess its own PICTURE ... ENDPICTURE line. These pictures will appear, disappear and do their interactive stuff behind all avatars and props (the "foreground" layer) but in front of the room's "background" layer, in what is called the "midground" layer. Within this layer, midground pictures can be stacked and manipulated as desired.

Each picture in the midground must have a unique ID assigned to it. The ID of a picture can be any number at all -- the order doesn't matter -- but every graphic in the room must possess an ID that is different from the ID of any other graphic in the room.

TRANSCOLOR

TRANSCOLOR number

This command, which may optionally be included in the PICTURE ... ENDPICTURE line, is used to inform the Mac client which of the picture's 256 colors (if any) should be displayed as transparent, revealing whatever exists beneath. If this command is left out, the Mac client will use whatever transparency color the picture was originally created with. The Windows client will do this in any case.

A TRANSCOLOR command is automatically inserted into the PICTURE ... ENDPICTURE line whenever a new picture is assigned to a spot in authoring mode. The default number inserted is 0 (zero); i.e., by default, it is assumed that the graphic uses the color 0 as the transparent, or "alpha" channel. Mac-based operators may address this value directly via the Door Info window, and must set it correctly (or remove it via ASCII editing) so that other Mac users will see the transparent effects correctly. The following table explains how a sample picture will be displayed on each type of client under various circumstances; our sample picture uses color 114 as the transparent color.

USER OS TRANSCOLOR COMMAND (IN SERVER SCRIPT)

TRANSCOLOR 0
(default inserted via authoring mode or by editing script manually)
TRANSCOLOR 114
(set via Mac wizard in authoring mode or by editing script manually)
<no TRANSCOLOR command>
(TRANSCOLOR can only be removed or avoided by editing the script manually)
Windows Client Right
Right
Right
Mac Client Wrong
(color 114 will be visible,
color 0 will be invisible)

Right
Right

NOTE: Windows-based operators: The Windows client does not allow operators to affect the TRANSCOLOR value via authoring mode, and as the table above indicates, it ignores the TRANSCOLOR command completely (using the actual alpha channel of the image instead). To make sure your Windows modifications will display properly on the Mac client, you have two choices. Either:

A. Create your GIFs using the color 0 (white) as the transparent color. If you have white regions in your picture that you want to appear visible (i.e., not transparent), use the alternate white (color number 215) for them. This method will allow you to assign new pictures to new spots in authoring mode later, without having to worry about the TRANSCOLOR setting, or

B. Edit your server script manually, using a word processor capable of saving as ASCII (text only). You may choose to replace all of your "TRANSCOLOR 0" commands with the appropriate numbers, or you can simply remove them entirely.

Specifying spot data

Like rooms, every spot (including doors) begins with a block of special data, only some of which is accessible via the Scripting Window. This "Spot Data Block" will contain some or all of the following commands:

SPOT
ID number
NAME "Spot Name"
OUTLINE x1,y1 x2,y2 x3,y3 ...
PICTS pictureID,xOffset,yOffset ... ENDPICTS
SCRIPT
ENDSCRIPT

The Spot Data Block

ID

ID number

This line indicates the spotID assigned to this spot in the room. Although this number may be assigned by whatever arbitrary means you wish, it must be here, and it must be unique to the spot. Again, it's perfectly fine to number spots sequentially, or to skip numbers between spots, or to put spots in any illogical order you want, but every spot must possess an ID that is different from any other spot in the room.

NAME

NAME "Spot Name"

This line indicates the name of the spot as it will appear if a SPOTNAME command is used. The name of a spot can be changed in authoring mode via the Door Info window.

OUTLINE

OUTLINE x1,y1 x2,y2 x3,y3 < ... >

This line indicates the positions of all points (vertices) that determine the shape of the spot; each x,y specifies the position of a single point in the outline. Although the default doors created by selecting New Door from the Operator Menu always possess four points, by editing this line manually you can create doors and spots with any number of points greater than two (Mac users can set the number of points via the Spot Info window). As usual, all "x" values must be between 0 and 511, while all "y" values must be between 0 and 383.

PICTS ... ENDPICTS

PICTS pictureID,offsetX,offsetY < ... > ENDPICTS

This line indicates the IDs and relative positions of the midground graphics that will be used to animate the spot. The data between the keywords is arranged in "triplets," each made up of three numbers (e.g.: "100,10,20" or "5,-25,0"). Each triplet describes one of the spot's states: the first triplet describes state 0, the second triplet describes state 1, the third describes state 2, and so on.

Each triplet -- each state -- is defined by a pictureID, an xOffset, and a yOffset. The pictureID specifies which graphic will be displayed when the spot enters the State. These IDs are the same as those specified in the PICTURE ... ENDPICTURE line of the Room Data Block. The xOffset indicates how far the graphic will be shifted to the left (negative) or right (positive), relative to the spot's actual location. The yOffset indicates how far the graphic will be shifted to upward (negative) or downward (positive), relative to the spot's actual location.

The graphics associated with a spot's states can be changed in authoring mode by selecting Edit Pictures from the Door Info window. The order in which these graphics are displayed in the Pictures List is the same as the "state order," i.e.: the first picture listed -- "NONE" by default -- represents state 0, the second is state 1, the third is state 2, and so on.

To change the X and Y offsets of a picture while in authoring mode:

  1. Use SETSPOTSTATE to set the spot to the state you want to change.

  2. Use SETPICLOC to move the picture relative to the spot's position.

SCRIPT ... ENDSCRIPT

SCRIPT
<handlers>
ENDSCRIPT

These lines (if they exist) indicate the beginning and end of a spot's script (as opposed to "Spot Data"). Everything appearing between the keywords SCRIPT and ENDSCRIPT is part of the script, and may also be accessed via the Scripting Window in authoring mode.