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

Iptscrae Language Guide



Iptscrae Language Reference

This section is a reference to the Iptscrae language:

Iptscrae possesses over 100 specialized commands and keywords, as well as its own versions of many commonly-used operators and functions; each of these represents a wide range of interactive possibilities awaiting your imagination.


Data types

The Palace is integer-based (meaning that it works in terms of whole numbers), but barring floating-point variables, the software can handle all basic data types: symbols (variables), numbers (integers), strings (string literals), atomlists (subroutines) and arrays, as well as a number of special-case symbols and reserved keywords.

Symbols (variable names)

Symbols must start with a letter, and may contain any combination of letters, numbers and the underscore. They may not contain any spaces, and have a maximum length of 31 characters. Examples:

x
plan9
my_really_big_variable

Numbers ( integers)

Numbers in Iptscrae are stored as 32 bit sized integers. No floating-point is allowed. Numbers must be specified in decimal notation using the digits 0 through 9, with an optional leading ( - ) for negative numbers. Examples:

2
-32
4283748

Strings (string literals)

String literals must be encased in double quotes, for Example "string". If you need to include a quote symbol within a string, precede it with a backslash: "these \"doublequotes\" are okay". You can create long strings by concatenating multiple strings together using the & operator (see Operators). Examples:

"Hello"

"A Flock " "of Words" &

"Suddenly, Fred shouted \"Look out!\" and hit the dirt."

Arrays

An array is an ordered list of other Iptscrae data types. Arrays may be declared with the ARRAY command or by encasing the elements of the array in square brackets ([and]). You use the GET function to extract an item from an array, use the PUT command to insert an item into an array, and the FOREACH command to perform an operation on each item in an array. Arrays can be composed of different data types, including other arrays. Examples:

[ 100 200 300 ]
[ "Hello" "World" ]
[ 100 "Hello" [ 0 1 2 ] ]

5 7 9 ARRAY

Atomlists

Atomlists are small Iptscrae scripts, or "subroutines." They can contain all other data types, including other atomlists. Some commands (such as EXEC, IF, WHILE, ALARMEXEC and FOREACH) operate on atomlists (rather than in them, as most other commands do). Atomlists must be encased in curly brackets ({and}). Examples:

{ 1 tempVar = }
{ "Howdy" SAY }
{
23 firstVar =
secondVar firstVar - deltaVar =
}

Special-Case Symbols

CHATSTR

CHATSTR is a reserved word and a special-case variable in Iptscrae. Whenever a script is executing in response to an INCHAT or OUTCHAT event, CHATSTR represents the chat text itself. This variable may be modified on the fly. In the case of an INCHAT event, this will change the text that ends up getting displayed on the screen. In the case of an OUTCHAT event, it will change the text that is sent to other users.

It is generally preferable to use OUTCHAT rather than INCHAT event handlers.

The following example shows how to make an effect that occurs whenever you speak (type) a key word or phrase, by applying an IF statement to CHATSTR. The whole thing resides in the OUTCHAT handler.

Example

ON OUTCHAT {
{
"applause" SOUND
} CHATSTR "!Thank you!" == IF
}

\ (The "Backslash" Character)

The backslash has a special meaning in Iptscrae; when it appears within a character string, it indicates that the character immediately following it should be included within the string literally (i.e., as a printable character). It is most often used to indicate that a double quote should be printed as part of a string, rather than signifying the end of it (as it typically would). The backslash can be used with other control characters, as well as in GREPSTR regular expressions.

Example 1 (a quote within a SAY command)

"The word he said was \"rosebud.\"" SAY

Example 2 (a local whisper in a "sign balloon")

"@200,20\^Note to myself..." WHOME PRIVATEMSG


Event handlers

Events are the basic stimuli of the server, representing all the things your Palace can "watch for" and respond to. They include significant user actions such as entering and leaving rooms, clicking on doors and spots, talking and other basic activities, plus a special type of event called an alarm.

For each event type, there exists an event handler. Event handlers reside within the SCRIPT... ENDSCRIPT portions of a script file. The name of each event handler consists of the word ON followed by the name of the event it handles (i.e., ON ENTER, ON LEAVE, ON SELECT, and others). When an event occurs, the server script file is consulted to see whether there is a handler for that event in the current room. The client also checks the user's Cyborg.ipt file. If any appropriate event handlers are found, the scripts within them are executed immediately.

Note that not all handlers may be used in all objects; some may be applied only to doors or spots, others to cyborgs, and some to all three.

ON ALARM

(Doors, Spots, Cyborgs)

An ALARM event occurs in response to the SETALARM command in a script. It can be used to schedule a periodic event, such as an animation, or to provide a delayed response. To trigger the following example handler, use the SETALARM command (see SETALARM).

Example

ON ALARM {
"I am alarmed!" SAY
}

ON ENTER

(Doors, Spots, Cyborgs)

An ENTER event occurs when a user enters the room. Scripts in this handler can be used (among other things) to start animations (via SETALARM), initialize user-defined functions, start room behavior, generate automatic "hello" messages from the entering user, etc.

Example

ON ENTER {
"I have entered!" SAY
}

ON INCHAT

(Doors, Spots, Cyborgs)

An INCHAT event is triggered in response to an incoming chat message; a better name for this handler might be ON HEAR. It is generally preferable to use the OUTCHAT handler instead of this one, because INCHAT events will be triggered by all user speech, user scripts, and any other "talking spots" in the room (very possibly flooding the server), whereas OUTCHAT events will only be triggered by users' deliberate speech. Scripts in the INCHAT handler can be used to modify the text of the incoming chat message via use of the CHATSTR variable.

Example

ON INCHAT {
"yes" SOUND
}

NOTE: Want to get killed for flooding your server? Make a spot in your Palace that does a SAY in the INCHAT handler. Better yet, make two of them in the same room. Then say something.

ON LEAVE

(Doors, Spots, Cyborgs)

A LEAVE event occurs when a user leaves the room. Scripts in this handler will be executed in their entirety before the user actually departs.

Example

ON LEAVE {
"I am leaving!" SAY
}

ON LOCK

(Lockable Doors)

A LOCK event occurs when a door becomes locked. The event is sent to the door itself. Scripts in this handler can be used to add additional behaviors to the door in question.

Example

ON LOCK {
"The door is locked!" SAY
}

ON MACROn for n=0 to n=9

(Cyborgs)

If the room allows cyborgs, this event runs when a script uses ONMACROn (where n is between 0 and 9) or the user uses an avatar selection 0-9

ON OUTCHAT

(Doors, Spots, Cyborgs)

An OUTCHAT event is triggered in response to an outgoing chat message (when a user types something and presses the Return key). Scripts in the OUTCHAT handler can be used to modify the text of outgoing chat messages via use of the CHATSTR variable. A good example of an OUTCHAT script is the text message handler in The Moor.

Example

ON OUTCHAT {
{
"Polo!" CHATSTR =
} "Marco" CHATSTR == IF
}

ON SELECT

(Doors, Spots)

A SELECT event occurs whenever a user clicks on a hotspot. Note that unless the hotspot possesses a DONTMOVEHERE command, the user's avatar will immediately move to the location clicked.

Example

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

ON SIGNON

(Cyborgs)

A SIGNON event is sent to each user as they sign on.

Example

ON SIGNON {
"I have signed on!" SAY
}

ON UNLOCK

(Lockable Doors)

An UNLOCK event occurs when a door becomes unlocked. The event is sent to the door itself. Scripts in this handler can be used to add additional behaviors to the door in question.

Example

ON UNLOCK {
"The door is unlocked!" SAY
}


Commands and functions

Now that you know where scripts can be placed and what events they can react to, you'll probably want to know what kinds of things you can make them do. You can add action to your scripts by using the commands and functions described in this section.

Commands perform actions that directly affect the state of objects in the current room (users, doors, spots and props). Functions are similar to commands, but their concerns are data-oriented; a Function always leaves a value (some kind of data) on the top of the stack, so it can be accessed and manipulated by other commands and Functions. This is what we mean when we say that a Function "returns" a value: it places this value on the top of the stack. Most functions perform both "pops" and "pushes" in doing their job: for instance, the "plus" (+) operator pops the top two values off the stack, adds them, and pushes the sum onto the stack. When the operation ends there is one value -- not three -- on the stack.

For ease of use, the commands and functions have been divided into several categories, based upon the objects they affect and actions they perform:

The following listings describe all Iptscrae commands and functions.

Cyborg commands and functions

CHAT

"message" CHAT

This command displays the message in a cartoon balloon, as though the user typed it directly into the Input Box. It is identical to the SAY command.

Example

"This is a sentence." CHAT

CLEARPROPS

CLEARPROPS

This command removes all the props the user is wearing. A synonym is NAKED.

Example

CLEARPROPS

DOFFPROP

DOFFPROP

This command removes the last prop put on by the user.

Related commands

DONPROP, DROPPROP and REMOVEPROP.

Example

DOFFPROP

DONPROP

propID DONPROP
"propName" DONPROP

This command (in either of its forms) adds a prop to the user's costume. The prop can be specified by ID# (preferable) or by Name.

Related commands

DOFFPROP, DROPPROP and REMOVEPROP.

Examples

1280 DONPROP

"BRBSIGN" DONPROP

DROPPROP

x y DROPPROP

This command takes the last prop user put on and drops it into the floor (making it a loose prop). x and y specify where it will be dropped.

Related commands

DOFFPROP, DROPPROP and REMOVEPROP.

Example

512 RANDOM tempX =
384 RANDOM tempY =
tempX tempY DROPPROP

GLOBALMSG

"message" GLOBALMSG

This command is available only to users with Operator privileges. It generates a message that everybody on the server sees. Use it sparingly.

Example

"This is a Global Message." GLOBALMSG

GOTOROOM

roomID GOTOROOM

This command is used by spots to navigate users to another room. You can find out the roomID by looking at the Room Info window, or by using a ROOMID command.

Example

86 GOTOROOM

GOTOURL

"urlString" GOTOURL

This command can be used to send users to other Palaces and Internet URLs. If you use a URL beginning with "palace://" the user will be connected to the Palace site specified (if possible); otherwise the user's system will attempt to go there via whatever application is normally associated with URLs of that type (web browsers, news readers, FTP utilities, etc.) Same as NETGOTO.

NOTE: If the URL begins with "palace://", it must be the only thing in the script in order to work with the Macintosh Client or The Palace Viewer.

Examples

"palace://welcome.thepalace.com" GOTOURL
"http://www.thepalace.com" GOTOURL

GOTOURLFRAME

"url" "frame" GOTOURLFRAME

This command can be used to send users to the url passed in the browser frame named "frame".

NOTE: Frame specification is effective in TPV only. The Macintosh and Windows clients use the default frame.

Example

"http://www.thepalace.com" "myframe" GOTOURLFRAME

HASPROP

"propName" HASPROP
propID HASPROP

This function pushes a 1 onto the stack if the user possesses the specified prop; otherwise it pushes a 0.

Example

{
"I am wearing the Ray Bans" SAY
} {
"I am NOT wearing the Ray Bans" SAY
} "Ray Bans" HASPROP IFELSE

INSPOT

spotID INSPOT

This function pushes a 1 onto the stack if the user's current location is within the spot indicated by spotID; otherwise it returns a 0. The following example assumes that the current room includes a spot with an ID of 1.

Example

{
"I'm in The Spot!" SAY
} {
"I'm not in The Spot!" SAY
} 1 INSPOT IFELSE

ISGOD

ISGOD

This function pushes a 1 onto the stack if the user running the script has owner-level access, otherwise it pushes a 0.

Example

{
"I am an Owner!" SAY
} {
"I am not an Owner!" SAY
} ISGOD IFELSE

ISGUEST

ISGUEST

This function pushes a 1 onto the stack if the user has guest access, otherwise it returns 0.

Example

{
"I am a Guest!" SAY
} {
"I am not a Guest!" SAY
} ISGUEST IFELSE

ISWIZARD

ISWIZARD

This function pushes a 1 onto the stack if the user has owner or operator-level access, otherwise it returns 0.

Example


"I am a operator!" SAY
} {
"I am not a operator!" SAY
} ISWIZARD IFELSE

KILLUSER

userID KILLUSER

This command "kills" (disconnects) the user with the specified userID#. If members aren't allowed to kill (which is typical of most Palace servers), this command won't work. In any case guests cannot use it. Note that to get userID it is necessary to use one of the following commands: ROOMUSER, WHOCHAT, WHOME or WHOTARGET. The following example shows you how to commit suicide in Iptscrae:

Example

WHOME KILLUSER

LOCALMSG

"message" LOCALMSG

This command generates a message that only the user executing the script sees. You can precede the message with @x,y to control its position.

Example

"This is a LOCALMSG. I am the only one who sees it." LOCALMSG

MACRO

number MACRO

This command causes the user to don the specified macro (a "macro" corresponds to an "avatar" -- a group of props that are all worn at the same time). If the user possesses a saved macro for the number used in the script, their avatar will instantly change to it. If an ON MACRO script exists in the user's Cyborg.IPT, it will be executed instead of the prop change.

Example

16 RANDOM MACRO

MOVE

x y MOVE

This command moves the user x,y pixels relative to the current position.

Example 1 (move down and right)

5 5 MOVE

Example 2 (move randomly)

11 RANDOM 5 - tempX =
11 RANDOM 5 - tempY =
tempX tempY MOVE

NAKED

NAKED

This command removes all of a user's props. It is the same as CLEARPROPS.

Example

NAKED

NBRROOMUSERS

NBRROOMUSERS

This function returns the number of users currently in the room.

Example

NBRROOMUSERS ITOA tempVar =
"NBRROOMUSERS = " tempVar & "." & SAY

NBRUSERPROPS

NBRUSERPROPS

This function returns the number of props currently worn by the user.

Example

NBRUSERPROPS ITOA tempVar =
"NBRUSERPROPS = " tempVar & "." & SAY

NETGOTO

"urlString" NETGOTO

This command can be used to access other Palace servers or other Internet URLs. If you use a "palace://" URL, the user will be signed on to the Palace server indicated (if possible); otherwise the system will attempt to take the user there by some other means. Same as GOTOURL.

NOTE: If the URL begins with "palace://", it must be the only thing in the script in order to work with the Macintosh Client or The Palace Viewer.

Example

"palace://welcome.thepalace.com" NETGOTO
"http://www.thepalace.com" NETGOTO

POSX

POSX

This function returns the user's horizontal coordinate.

Example

"My current POSX is " POSX ITOA & SAY

POSY

POSY

This function returns the user's vertical coordinate.

Example

"My current POSY is " POSY ITOA & SAY

PRIVATEMSG

"message" userID PRIVATEMSG

This command generates a private message to another user. Note that to get userID it is necessary to use one of the following commands: ROOMUSER, WHOCHAT, WHOME or WHOTARGET.

Example

"This is a PRIVATEMSG. I am whispering to myself." WHOME PRIVATEMSG

REMOVEPROP

propID REMOVEPROP
"propName" REMOVEPROP

This command removes a prop from the user's costume. The prop can be specified by name or by propID. The following example removes the "Ray Bans" prop (if the user is wearing it).

Related commands

DONPROP, DROPPROP and DOFFPROP.

Example

{
"Ray Bans" REMOVEPROP
} {
"First I have to put on the Ray Bans!" SAY
} "Ray Bans" HASPROP IFELSE

ROOMMSG

"message" ROOMMSG

This command generates a message that everyone in the room sees. Use it sparingly. You can precede the message with @x,y to control its position.

Example 1

"This is a ROOMMSG. Everyone in this room can see it." ROOMMSG

Example 2

"@10,10 This is a ROOMMSG up in the corner. Isn't that awesome?" ROOMMSG

ROOMUSER

number ROOMUSER

Every user on the server has a unique userID that stays the same as long as they remain connected, but at any given moment they also possess a "room user" number assigned to them by the room they're in. This function returns the userID of room user number in the current room.

Example

WHOME ROOMUSER ITOA tempVar =
"I am currently ROOMUSER number " tempVar & "." & SAY

SAY

"message" SAY

This command displays message as if the user typed it in directly. It is identical to the CHAT command.

Example 1 (talking)

"I am saying something!" SAY

Example 2 (thinking)

":I am thinking something!" SAY

Example 3 (shouting)

"!I am shouting something!" SAY

Example 4 (sign)

"^This is a sign!" SAY

Example 5 (positioning)

"@10,10 Now I'm saying something way up here!" SAY

SETCOLOR

number SETCOLOR

This command sets the user's face color to one of 16 colors. If the "tinted balloon" preference is checked, this command also contols the color of the word balloon. The specified number must be an integer from 0 to 15. The possible colors are numbered by dividing the spectrum into 16 equal steps, as follows:

#0 Red
#1 Orange
#2 Orange/Yellow
#3 Yellow
#4 Yellow/Green
#5 Light Green
#6 Green
#7 Green/Cyan
#8 Cyan
#9 Light Blue
#10 Medium Blue
#11 Dark Blue/Purple
#12 Purple
#13 Magenta
#14 Magenta/Pink
#15 Pink

Example

16 RANDOM SETCOLOR

SETFACE

number SETFACE

This commands sets the user's face to one of the 13 built-in faces (props are not removed, however). The specified number must be an integer from 0 to 12.
#0 Eyes Closed (sleeping or blushing)
#1 Smile
#2 Look Down (nodding)
#3 Talking
#4 Wink Left
#5 Normal
#6 Wink Right
#7 Tilt Left (shaking head)
#8 Look Up (nodding)
#9 Tilt Right (shaking head)
#10 Sad
#11 Blotto
#12 Angry

Example

13 RANDOM SETFACE

SETPOS

x y SETPOS

This command immediately moves the user to position x y in the Viewing Area. x must be an integer from 0 to 511. y must be an integer from 0 to 383.

Example

10 10 SETPOS

SETPROPS

[ propArray ] SETPROPS

This command acts like a macro, causing the user to immediately don all props listed in [ propArray ]. Props may be listed either by Name or by ID#

Example

[ "Ray Bans" "daisy" "Wine Bottle" ] SETPROPS

Like all arrays, [ propArray ] must be enclosed in square brackets ( [ ] ). Also, prop names, being strings, must be enclosed in double quotes (").

SOUND

"fileName" SOUND

This command plays the sound file filename. Sounds are WAV files, saved without the .WAV extension, and reside on the client in \Palace\Media\YourPalaceName\Sounds.

Example 1 (play specified sound)

"Applause" SOUND

Example 2 (play random sound)

6 RANDOM tempVar =
[ "Yes" "No" "Fazein" "Applause" "Boom" "Crunch" ] tempVar GET SOUND

SUSRMSG

"message" SUSRMSG

This command generates a message that all owners and operators will see, no matter where they are on the server. Use it sparingly.

Example

"This is an SUSRMSG from " USERNAME & SUSRMSG

TOPPROP

TOPPROP

This function returns the propID of the last prop the user put on. If the user is "naked" it returns 0 (zero). The following example shows you how to scatter all your currently-worn props.

Example

{ 400 RANDOM 300 RANDOM DROPPROP } { TOPPROP } WHILE

USERNAME

USERNAME

This function returns the user's User Name as specified in the Preferences dialog. You can't change a user name from a script.

Example

"Hello, my name is " USERNAME & "!" & SAY

USERPROP

number USERPROP

This function returns the propID of one of the props currently worn by the user. number is a number from 0 to 8 indicating which prop you want to identify (note that this refers to the order they were donned in, not necessarily the order they appear in). You can determine the number of props currently worn by using the NBRUSERPROPS command, as illustrated in the following example.

Example

NBRUSERPROPS RANDOM whichProp =
whichProp USERPROP ITOA propIdent =
whichProp ITOA " USERPROP = " & propIdent & "." & SAY

WHOCHAT

WHOCHAT

This function returns the userID of the user who invoked an INCHAT event.

Example

WHOCHAT ITOA tempVar =
"The WHOCHAT command returns " tempVar & "." & SAY

WHOME

WHOME

This function returns the user's own userID.

Example

WHOME ITOA tempVar =
"The WHOME command returns " tempVar & "." & SAY

WHONAME

userID WHONAME

This function returns the User Name of the specified user. Note that to get userID it is necessary to use one of the following commands: ROOMUSER, WHOCHAT, WHOME or WHOTARGET. The following example causes you to say the name of room user 0 (zero) in the current room (that's you, if you're the only person in the room at the moment!)

Example

0 ROOMUSER WHONAME SAY

WHOPOS

"name" WHOPOS
userID WHOPOS

This function (in either of its forms) returns the current x,y position of the user. Note that x is placed on the stack before y, which means that y is ready to be retrieved from the stack first. To reverse their positions so they can be used in their typical order (X, then Y), use the SWAP function.

Example

WHOME WHOPOS SWAP ITOA tempY = ITOA tempX =
"WHOME WHOPOS returns '" tempX & "' '" & tempY & "'." & SAY

WHOTARGET

WHOTARGET

This function pushes the userID of the person you have selected for private chat (i.e., Whisper Mode or ESP) or zero if you have not selected a target.

Example

WHOTARGET USERNAME tempVar =
{
"WHOTARGET USERNAME returns '" tempVar & "'." & SAY
} {
"I must select someone in order to use the WHOTARGET Command." SAY
} tempVar <> "" IFELSE

Spot commands and functions

DOORIDX

number DOORIDX

This function returns the ID of the door indicated by number. The following example causes the user to leave through a random door:

Example

NBRDOORS RANDOM DOORIDX SELECT

Related functions

NBRDOORS, SELECT.

GETSPOTSTATE

spotID GETSPOTSTATE

This function returns the current state of the specified hotspot or door. The following example uses NBRSPOTS and SPOTIDX as well as GETSPOTSTATE to determine the state of a random door or spot in the current room.

Example

NBRSPOTS RANDOM tempVar =
"The state of spot number " tempVar ITOA & " (" & tempVar SPOTIDX SPOTNAME & ") is " & tempVar SPOTIDX GETSPOTSTATE ITOA & SAY

ISLOCKED

doorID ISLOCKED

This function returns a 1 if the indicated door is locked, otherwise it returns a 0. The following example uses NBRDOORS and DOORIDX to determine the state of a randomly-selected door in the current room.

Example

NBRDOORS RANDOM doorNumber =
{
"Door number " doorNumber ITOA & " is locked." SAY
} {
"Door number " doorNumber ITOA & " is unlocked." SAY
} doorNumber DOORIDX ISLOCKED IFELSE

LOCK

doorID LOCK

This command is used by deadbolts (or doorknobs) to lock doors. Its counterpart is the UNLOCK command. The following example assumes there is a lockable door with an ID of 1 in the current room.

Example

1 LOCK

ME

ME

When a spot or door is executing the script, this function pushes its ID.

Example

" \"ME SPOTNAME\" returns \"" ME SPOTNAME & "\"." & SAY

NBRDOORS

NBRDOORS

This function returns the number of doors in the room. This number may be less than or equal to the number returned by NBRSPOTS (because all doors are spots, but not all spots are doors).

Related commands

DOORIDX

Example

" \"NBRDOORS\" returns \"" NBRDOORS ITOA & "\"." & SAY

NBRSPOTS

NBRSPOTS

This function returns the number of spots (including doors) in the room.

Example

" \"NBRSPOTS\" returns \"" NBRSPOTS ITOA & "\"." & SAY

SELECT

spotID SELECT

This command "clicks" the spot specified by spotID. If the spot has an ON SELECT handler, the script will be executed just as though the user had selected it physically. The following example assumes there is a spot with an ID of 1 in the current room. To see it work, put an ON SELECT handler in this spot that does something noticeable.

Example

1 SELECT

SETALARM

futureTicks spotID SETALARM

This command is used to schedule an ALARM event in the future. It can be used to create animations and other interesting activity. The user's subjective duration of a "tick" depends on the speed of both the client and server as well as the network load at the moment, but is about 1/60th of a second. The following example assumes there is a spot with an ID of 1 in the current room. To see it work, put an ON ALARM handler in this spot that does something noticeable (see Handlers earlier in this document).

Example

300 1 SETALARM

SETLOC

x y spotID SETLOC

This command is used to move a spot or door, relative to its current position. It is functionally equivalent to selecting the spot or door while in authoring mode and dragging it to the new position. Note that this command is only accessible to owners and operators; i.e. it will not be executed unless the user is in owners or operator mode. For this reason, it is much more useful as an authoring command than as a scripted command. The following example assumes that you are in owners or operator mode, and that there is a spot with an ID of 1 in the current room.

Example

10 10 1 SETLOC

SETPICLOC

x y spotID SETPICLOC

This command is used to change the x and y offsets of a picture associated with spot spotID (these are the second and third numbers in the "triplets" appearing between PICTS and ENDPICTS). Note that only a single picture is affected, corresponding to the current state of the spot -- any pictures associated with other states of the same spot will remain unchanged. Note also that this command is only accessible to owners and operators; i.e., it will not be executed unless the user is in owners or operator mode. For this reason, it is much more useful as an authoring command than as a scripted command. In fact, the SETPICLOC command provides the only way to change a picture's offset without editing the server script, and this makes it very useful for "fine-tuning" the placement of a particularly tricky graphic. The following example assumes that you are in owners or operator mode, and that there is a spot with an ID of 1 (and at least one picture) in the current room.

Example

10 10 1 SETPICLOC

To see this command in action, launch the Palace server using the "Mansion" script and try this simple experiment:

  1. Launch your client to access your server.

  2. From your client, enter the room called "The Study" and enter Operator mode (from the Options menu).

  3. If the secret bookshelf-door isn't already open, say "open sesame" to flip the spot's state and display the "open" graphic.

  4. Type the following command into the Input Box (100 is the ID of the magical door):

    /-50 -50 100 SETPICLOC

  5. You will see the graphic suddenly jump to a very "wrong" location. Try saying "close sesame" and "open sesame" a few times; you'll see that you have "permanently" changed the position of the graphic associated with the "open" state.

  6. To return the graphic to its original position, type:

    /54 -21 100 SETPICLOC

SETSPOTSTATE

state spotID SETSPOTSTATE

This command changes the state of a spot for all users currently in the room. For multi-state hotspots, this can be used to create animation effects. The following example assumes that the current room contains a spot with an ID of 3 which possesses three states (0, 1 and 2); the script will advance the spot to the next of these three states by using an IFELSE command. Try executing it several times in a row.

Example

{
0 3 SETSPOTSTATE
} {
3 GETSPOTSTATE 1 + 3 SETSPOTSTATE
} 2 3 GETSPOTSTATE == IFELSE

SETSPOTSTATELOCAL

state spotID SETSPOTSTATELOCAL

This command functions just like SETSPOTSTATE, except that only the person executing the script will actually see the new state occur. Because this command does its work locally (i.e., on the client computer only), it changes the spot's state much more quickly than the non-local version. For this reason, this is the preferred way to do animations and effects that don't need to sync up exactly for all users. The following example assumes that the current room contains a spot with an ID of 3 that possesses three states (0, 1 and 2). The difference between this example and the preceding one (SETSPOTSTATE) is that in this case, the user who executes the script will be the only one who sees the spot change.

Example

{
0 3 SETSPOTSTATELOCAL
} {
3 GETSPOTSTATE 1 + 3 SETSPOTSTATELOCAL
} 2 3 GETSPOTSTATE == IFELSE

SHOWLOOSEPROPS

SHOWLOOSEPROPS

This command creates a list in the Log Window, providing the propID and location of all loose props in the room. This is useful, for example, if you want to write a script that automatically places chess pieces on a chess board: In authoring mode, determining the exact X and Y positions to place all these props by hand would be a tedious task. Instead of doing this the hard way, you can simply place the props in the desired positions on the screen, type /SHOWLOOSEPROPS into the client input box, and copy the listing from the Log Window. This command may also be executed from within a script. The listing in the Log Window will follow the format shown below:

1009 188 120 ADDLOOSEPROP
1013 108 178 ADDLOOSEPROP
1018 162 185 ADDLOOSEPROP

Example

SHOWLOOSEPROPS

SPOTDEST

spotID SPOTDEST

This function returns the DEST (destination) of the spot or door specified by spotID. Note that Normal spots may possess DEST fields, although unlike Passages, they require a scripted GOTOROOM in the ONSELECT handler to send the user there when selected. The following example assumes that the current room contains a door with an ID of 1, for which a DEST has been set:

Example

1 SPOTDEST ITOA tempVar =
"Door number 1 leads to Room number " tempVar & SAY

NOTE: You might find it odd that a normal spot can contain a DEST it doesn't use, but consider this: if you place an integer value into a spot's DEST field (which may require editing the server script manually), you can then use SPOTDEST to refer to it, effectively providing a "room-level constant" (and you can do this for each normal spot in the room). Palace designers are always looking for places to store data without using globals or incurring too much memory overhead; this is one of 'em.

SPOTNAME

spotID SPOTNAME

This function returns the name of the spot (or door) specified by spotID. The following example assumes that there is a spot (or door) with an ID of 1 in the current room, and that it has a name. The following example determines the names of all spots in the current room, and prints its output to the Log Window.

Example

0 tempVar =
{
"Spot " tempVar ITOA & "'s name is \"" & tempVar SPOTIDX SPOTNAME & "\"." & LOGMSG
tempVar ++
} { NBRSPOTS tempVar > } WHILE

SPOTIDX

number SPOTIDX

This function returns the spotID of the spot specified by number. The following example determines the IDs of all spots in the current room, and prints its output to the Log Window.

Example

0 tempVar =
{
"Spot " tempVar ITOA & "'s ID is " & tempVar SPOTIDX ITOA & LOGMSG
tempVar ++
} { NBRSPOTS tempVar > } WHILE

UNLOCK

doorID UNLOCK

This command is used by Deadbolts (BOLT commands) to unlock doors. Its counterpart is the LOCK command. The following example assumes that there is a lockable door with an ID of 1 in the current room.

Example

1 UNLOCK

Paint commands and functions

Paint Commands always operate in the foreground layer of the Viewing Area; that is to say, "in front of" all graphics in the midground layer.

LINE

x1 y1 x2 y2 LINE

This command draws a line from point x1,y1 to point x2,y2. The line is drawn in the current PENSIZE and PENCOLOR. The following example draws a line from the upper left corner of the Palace client viewing area to the user who triggered it.

Example

0 0 POSX POSY LINE

LINETO

x y LINETO

This command draws a line from the current PENPOS to a point x,y away from the current PENPOS. The line is drawn in the current PENSIZE and PENCOLOR. The following example draws a diagonal line that goes 100 pixels to the right and 50 pixels upward, starting from the pen's current position.

Example

100 -50 LINETO

PAINTCLEAR

PAINTCLEAR

This command erases all painting/drawing from the screen, regardless of who put it there. You can do the same thing by double-clicking on the Detonator in the Painting Window.

Example

PAINTCLEAR

PAINTUNDO

PAINTUNDO

This command erases the last painting/drawing command or action performed. You can do the same thing by clicking once on the Detonator in the Painting Window.

Example

PAINTUNDO

PENBACK

PENBACK

This command moves the pen to the "back" of the foreground layer: any painting commands or actions subsequently performed will appear behind all avatars in the room (but they'll still be in front of any graphics in the midground layer). Any paint already on the screen is not affected. Note that you can do the same thing by clicking on the Layerer in the Painting Window.

Example

PENBACK

PENCOLOR

r g b PENCOLOR

This command sets the color of the pen: any painting commands or actions subsequently performed will appear in the specified color. You can do the same thing with the Palette in the Painting Window. The three arguments r, g and b represent the relative amounts of red, green and blue in the color, on a scale of 0 to 255 (where 0 0 0 yields black and 255 255 255 yields white). The following example sets the pen color randomly.

Example

255 RANDOM tempR =
255 RANDOM tempG =
255 RANDOM tempB =
tempR tempG tempB PENCOLOR

PENFRONT

PENFRONT

This command moves the pen to the "front" of the foreground layer: any painting commands or actions subsequently performed will appear in front of all avatars in the room (in the closest possible position to the user's face). Paint already on the screen is not affected. You can do the same thing by clicking on the Layerer in the Painting Window.

Example

PENFRONT

PENPOS

x y PENPOS

This command moves the pen to position x y on the screen, without drawing anything. The following example moves the pen to the user's position.

Example

POSX POSY PENPOS

PENSIZE

number PENSIZE

This command sets the pixel width of all lines drawn by the pen to number (an integer from 1 to 9): any painting commands or actions subsequently performed will create lines of this width. Paint already on the screen is not affected. You can do the same thing with the Line Sizer in the Painting Window. The following example paints a gradually-widening line across the Viewing Area.

Example

30 150 PENPOS
1 PENSIZE
50 0 LINETO
2 PENSIZE
50 0 LINETO
3 PENSIZE
50 0 LINETO
4 PENSIZE
50 0 LINETO
5 PENSIZE
50 0 LINETO
6 PENSIZE
50 0 LINETO
7 PENSIZE
50 0 LINETO
8 PENSIZE
50 0 LINETO
9 PENSIZE
50 0 LINETO

PENTO

x y PENTO

This command moves the pen to a position x y relative to the current PENPOS, without drawing anything. The following example draws a line 100 pixels long, moves the pen via PENTO, and continues drawing.

Example

0 150 100 150 LINE
50 50 PENTO
100 0 LINETO

Sound commands and functions

Prior to version 2.0 of the Palace client, audio files could not be sent across the network. For WAV or MIDI files to be heard, they had to exist on the user's hard disk, in the Sounds folder. A few users are still running around with this limitation, and sounds should therefore be made available via a Web Page, public FTP directory, or some other means.

Version 2.0 and greater allows clients to receive sounds as downloads from the server. To be sent out, the audio files in question must be placed in the Pictures folder on the server's computer.

MIDIPLAY

"fileName" MIDIPLAY

This command causes the MIDI file "fileName" to be played. The following example assumes that there is a MIDI file called "testme.mid" in the /Palace/Media/YourPalaceName/Sounds folder.

Example

"testme.mid" MIDIPLAY

MIDISTOP

MIDISTOP

This command causes the currently-playing MIDI file to immediately stop. (PC only)

Example

MIDISTOP

SOUND

"fileName" SOUND

This command causes the file "fileName" to be played for all users in the room. It is functionally identical to typing ")filename" SAY into the Input Box.

Example

"teehee" SOUND

"Song.midi" SOUND

Flow commands and functions

ALARMEXEC

{ atomlist } ticks ALARMEXEC

This command schedules an atomlist to be executed at a pre-specified time (after so many "ticks" have elapsed). The user's subjective duration of a "tick" depends on the speed of both the client and server as well as network load at the moment, but is considered to be 1/60th of a second. The following example waits ten seconds before finishing.

Example

"Don't you hate..." SAY
{ "waiting?" SAY } 600 ALARMEXEC

BREAK

BREAK

This command breaks out of a WHILE or FOREACH loop. The following example sets up a FOREACH loop causing a sentence to be spoken one word at a time, but halts after the fourth word due to a BREAK command.

Example

0 tempVar =
{
tempStr =
tempVar ++
{
tempStr SAY
} {
BREAK
} 5 tempVar > IFELSE
} [ "I" "will" "never" "finish" "speaking" "this" "sentence" ] FOREACH

EXEC

atomlist EXEC

This command executes an atomlist. It can be used in combination with the DEF command (see below) to execute a "user-defined function." Note that unless the function was defined in the same handler, it must be made GLOBAL.

Example

{ "Hello world!" SAY } definedFunction =
definedFunction EXEC

EXIT

EXIT

This command stops the currently-running script. It is useful for breaking out of looping errors that might otherwise flood the server or lock up the client. The following example bounces you around the screen randomly. It would continue to do so forever, except for the imbedded EXIT command.

The following script is likely get you killed for flooding if a death penalty exists on the server where it is executed. It is recommended that you turn the death penalty for flooding OFF before attempting to use this script.

Example

400 150 SETPOS
{
51 RANDOM 25 - tempX =
51 RANDOM 25 - tempY =
tempX tempY MOVE
{ EXIT } POSX 256 < IF
} { 1 } WHILE

FOREACH

{ atomlist } [ array ] FOREACH

This command executes atomlist once for each item in array. Before executing the atomlist, each item in the array is pushed onto the stack. The atomlist should be something that pops these items off the stack and does something with them, as the following example indicates.

Example

{ SAY } [ "Ready" "Steady" "Go!" ] FOREACH

IF

{ atomlist } condition IF

This command can be used to create a conditional statement: if the condition evaluates to TRUE (non-zero), atomlist will be executed. If the condition evaluates to FALSE ("0") it will not. Any operator (or logical series of operators) may be used to describe the condition being checked for (see the Operators section). The following example rolls a pair of imaginary dice, looking for a lucky total of 7.

Example

6 RANDOM 1 + tempVar =
6 RANDOM 1 + tempVar + tempVar =
"I rolled a " tempVar ITOA & SAY
{ "I'm a winner!" SAY } tempVar 7 == IF

IFELSE

{ trueAtomList } { falseAtomList } condition IFELSE

This command can be used to create mutually-exclusive conditional statements: if the condition evaluates to TRUE (non-zero), the trueatomlist will be executed. Otherwise, the falseatomlist will be executed. Warning: a very common Iptscrae bug is to use IF when you really mean IFELSE. The following example randomly determines two numbers from 1 to 100 and compares them.

Example

100 RANDOM 1 + tempVar1 =
100 RANDOM 1 + tempVar2 =
{
tempVar1 ITOA "is less than or equal to " & tempVar2 ITOA & SAY
} {
tempVar1 ITOA "is greater than " & tempVar2 ITOA & SAY
} tempVar1 tempVar2 <= IFELSE

RETURN

This command breaks out of an atomlist.

Example

{
"This line will be executed" SAY
RETURN
"This line will not" SAY
}

SETALARM

futureTicks spotID SETALARM

This command schedules the ALARM event for the spot spotID; this event will occur futureTicks in the future. A "tick" is 1/60th of a second. The following example assumes that there is a spot with an ID of 1 in the current room, and that this spot possesses an ON ALARM handler. When executed, the code will cause the spot's ON ALARM handler to be triggered ten seconds later.

Example

600 1 SETALARM

WHILE

{ atomlist } { condition } WHILE

This command creates a loop in which atomlist will continue iterating until condition evaluates to TRUE (non-zero). Any operator (or logical series of operators) may be used to describe the condition being checked for. The following example will continue counting until tempVar equals 5.

Example

{
tempVar 1 + tempVar =
tempVar ITOA SAY
} { tempVar 5 < } WHILE

General commands and functions

; <comment>

; comment

A semicolon (;) at the beginning of a line tells the program to ignore everything up to the next carriage return; it is used to insert comments into your scripts. Commenting your code is considered good programming practice in general, and comes in especially handy when you return to a script you haven't looked at in a long time. Note that comments placed outside of the script proper (i.e. outside of the SCRIPT... ENDSCRIPT block) will not be saved by the server.

Example

"This line will be executed" SAY
; "This line will not" SAY

ADDLOOSEPROP

propID x y ADDLOOSEPROP
"propName" x y ADDLOOSEPROP

This command adds a loose prop to the Viewing Area. The prop can be specified by propID or by propName. In the first case (propID), you must either know the propID already or use a command to retrieve it (TOPPROP or USERPROP will accomplish this). In the second case (propName), remember to place the name of the prop in quotes. Note that the prop specified must exist in either the client's propfile or the server's propfile; otherwise the command will have no effect.

Example 1 (by propName)

"halo" 100 200 ADDLOOSEPROP

Example 2 (by propID)

1016 100 200 ADDLOOSEPROP

Example 3 (duplicating a worn prop)

"halo" DONPROP
TOPPROP 100 200 ADDLOOSEPROP

ARRAY

number ARRAY

This command creates an array containing number elements. This array will contain zeros when first created. Data may be stored via the PUT command. The following example creates an empty array of ten elements and names it "myArray."

Example

10 ARRAY myArray =

ATOI

"string" ATOI

This function ("Ascii TO Integer") converts a character string to a number. Strings - even numerals spoken as text strings -- must be converted to integers before you can do math with them. The following example causes any integer spoken (all by itself) to be multiplied by ten before it appears in the user's cartoon balloon.

Related commands

ITOA

Example

{
CHATSTR ATOI yourNumber =
yourNumber 10 * myNumber =
myNumber ITOA CHATSTR =
} CHATSTR "^[0-9]$" SUBSTR == IF

BEEP

BEEP

This commands causes the system beep sound to be heard on the user's computer. The following example causes this sound to be heard whenever the user says "beep" (even if it's imbedded in another word, or capitalized).

Example

{
BEEP
} CHATSTR LOWERCASE "beep" SUBSTR == IF

CLEARLOOSEPROPS

CLEARLOOSEPROPS

This command clears all loose props from the room. The following example clears the room of loose props whenever the user says "be gone" (without the quotes).

Example

{
CLEARLOOSEPROPS
} CHATSTR "be gone" == IF

CLIENTTYPE

CLIENTTYPE

This command pushes "WINDOWS32", "MAC68K", "MACPPC", "TPV", or "unknown" onto the stack, depending on which client is running the script. The following example tells the user which client he/she is using whenever the user asks "which client".

Example

{
CLIENTTYPE SAY
} CHATSTR "which client" == IF

DATETIME

DATETIME

This function returns the number of seconds that have passed since January 1st, 1970 (Pacific Standard Time). Translating this number to a Julian date is left as an exercise for the reader (it's tough, but quite do-able).

Example

"The current DATETIME is " DATETIME ITOA & SAY

DEF

{ atomlist } symbol DEF

This command is used to create your own custom functions. Note that symbol must be declared GLOBAL if you want it to be recognized by any event handlers other than the one it's defined in; it will also have to be declared GLOBAL there (i.e., in the other handlers). As long as you adhere to this rule, your function can be executed in any room in your Palace.

Example 1 (defined and executed within the same handler)

{
"@50,50! " USERNAME & " has entered the room!" & SAY
} myFunction DEF
myFunction EXEC

Example 2 (defined ON ENTER, executed ON SELECT)

ON ENTER {
myFunction GLOBAL
{
"@50,50! " USERNAME & " is the greatest!" & SAY
} myFunction DEF
}

ON SELECT {
myFunction GLOBAL
myFunction EXEC
}

DELAY

number DELAY

This command causes a delay affecting all activity on the client -- events, alarms, queued commands and even prop animations -- for the duration specified by number. Delay times are measured in ticks (1/60 of a second) Note that SETALARM and ALARMEXEC are preferred since they don't lock up all processes on the client, although use of the DELAY command might be appropriate in a game, or as a penalty for breaking some house rule. The following example suggests one possible use:

Example

ON ALARM {
foulMouthFlag GLOBAL
{
USERNAME ", you have been flagged for swearing. You have been sentenced to 30 seconds of dead time. If you persist you will be kicked off the server." & LOCALMSG
1800 DELAY
} foulMouthFlag 1 == IF

DIMROOM

number DIMROOM

This command allows you to "dim the lights" in the room, decreasing the luminance of all visible graphics and props. The natural state of a room is 100% lit. By specifying an integer (number) lower than 100 and higher than 0, you can set the lighting to any desired percentage. Note that if number equals 100 or 0 (zero), the room will be made 100% lit again. The following example fades the lights down and then brings them back up again.

Example

{
lightingNow =
lightingNow DIMROOM
} [ 90 80 70 60 50 40 30 20 10 0 10 20 30 40 50 60 70 80 90 100 ] FOREACH

DUP

DUP

This command duplicates the top element on the stack. The following example shows an easy way to multiply an expression by itself; in this case, ( x + 1 ) * ( x + 1 ).

Example

x 1 + DUP *

GET

array index GET

This function gets item number index from array. Note that the elements of an array are numbered from 0 (zero) to (number of elements minus 1). The array may be specified directly (element by element) or by reference to its symbol (name).

Related commands

PUT

Example 1 (referring to array directly)

[ "alpha" "beta" "gamma" "delta" "epsilon" ] 5 RANDOM GET tempStr =
tempStr SAY

Example 2 (referring to array by its Symbol)

[ "alpha" "beta" "gamma" "delta" "epsilon" ] myArray =
myArray 5 RANDOM GET tempStr =
tempStr SAY

GLOBAL

symbol GLOBAL

This command declares symbol as a global variable, which allows it to be shared among event handlers. The GLOBAL command must used in EVERY event handler and ALARMEXEC in which the global symbol is used, even in the same room. It is good practice to declare your globals as soon as you enter the handler in which they will be used; this makes it easy to remember which ones you need and what you were doing.

Example

ON ENTER {
first_variable GLOBAL
other_variable GLOBAL
"Hello" first_variable =
"World" other_variable =
60 ME SETALARM
}
ON ALARM {
first_variable GLOBAL
other_variable GLOBAL
first_variable SAY
other_variable SAY
}

About nested globals. GLOBAL is an executable command. After it is executed, the variable will operate as a global value for the rest of the script.

For non-programmers, the following examples should make all of this a bit more clear; compare the level of indentation at which the myGlobal GLOBAL statement appears in each example.

Example 1 (this works):

{ myGlobal GLOBAL "I rolled a " myGlobal ITOA & SAY } 30 ALARMEXEC myGlobal GLOBAL
6 RANDOM 1 + myGlobal =

Example 2 (this doesn't):

{ "I rolled a " myGlobal ITOA & SAY myGlobal GLOBAL } 30 ALARMEXEC myGlobal GLOBAL
6 RANDOM 1 + myGlobal =

GREPSTR

string "pattern" GREPSTR

This function performs a case-sensitive search for the specified pattern within the specified string, and returns true (1) if the pattern is found. It may be placed in the INCHAT or OUTCHAT handler to operate directly on CHATSTR. Note that this command uses UNIX grep-style syntax; i.e., any character matches itself, unless it is one of the following special characters:
Character Matches
.
Any character
\
The character following it
[<set>]
One of the characters in the set, for example:
[aeiou] matches any vowel (except y)
[A-Za-z] matches any alphabetic character
[^0-9] matches anything but the characters 0-9
*
Any pattern followed by * matches zero or more instances of the pattern.
+
Same as * except it matches one or more instances of the pattern.
()
Used to tag sub-expressions that can be referred to in a GREPSUB command or subsequently, using the special symbols $1 through $9.
^
A pattern beginning with ^ must start at the beginning of the line.
$
A pattern ending with $ must match to the end of the line.

Special GREPSTR Characters

Example 1 (using IF to check for existence of string )

{
"I hate $1" GREPSUB ROOMMSG
} CHATSTR LOWERCASE "^i like (.*)$" GREPSTR == IF

Example 2 (using WHILE to check for all instances of string )

{
"$1darn$2" GREPSUB CHATSTR =
} { CHATSTR LOWERCASE "(.*)damn(.*)" GREPSTR } WHILE

NOTE: These examples use the special Symbols $1 and $2, allowing the GREPSUB command to use the text picked up by the wildcards (.*) in the GREPSTR command. Up to nine such symbols may be used in a single GREPSTR-GREPSUB structure ($1 through $9). For more information on regular expressions in general, see Mastering Regular Expressions by Jeffrey Friedl. Copyright 1997, O'Reilly and Associates

GREPSUB

"replacementPattern" GREPSUB

This function is executed in conjunction with a GREPSTR command: it locates specified spaces within a string, and fills them with any text that was "captured" by the GREPSTR. The replacement pattern uses the special Symbols $1 through $9 to refer to these captured character strings.

Example (the "Elmer Fudd" script from "The Moor"):

{
"$1w$2" GREPSUB CHATSTR =
} { CHATSTR "(.*)[lr]([aeiouy][^ .].*)" GREPSTR } WHILE

IPTVERSION

IPTVERSION

This command pushes the current Iptscrae version number (currently 1) into the stack. The following example would tell another user which version of Iptscrae you are currently using.

Example

"I'm currently using Iptscrae version" IPTVERSION ITOA & SAY

ITOA

ITOA

This function ("Integer TO Ascii") takes a numeric variable from the top of the stack, converts it to a character string, and places it back on the stack. Numerals must be converted to character strings before you can text-based commands (such as SAY) on them. For instance,

WHOME SAY

fails, since the WHOME function puts an integer (your userID) on the stack, while the SAY command is looking for a character string. The example below shows how you can use ITOA to remedy this.

Example

WHOME ITOA SAY

Related commands

LAUNCHAPP

appName LAUNCHAPP

This command tells the Palace software to look for the program called appName in the user's PlugIns folder, and launch it. It is used to launch Palace-compatible games and other software known as "Palace Plugins." The PalacePresents Viewer, which is distributed with the Palace User Software client, is a good example. Note that the full name of the program must be used (including file extensions, if any exist). The full path does not need to be specified, as this command applies to the Plugins folder only.

Example

ON ENTER {
"PalacePresents Viewer.dll" LAUNCHAPP
}

LENGTH

array LENGTH

This function returns the number of elements in array. The array may be specified directly (element by element) or by reference to its symbol (name).

Example 1 (referring to array directly)

[ "alpha" "beta" "gamma" "delta" "epsilon" ] LENGTH ITOA SAY

Example 2 (referring to array by its Symbol)

[ "alpha" "beta" "gamma" "delta" "epsilon" ] myArray =
myArray LENGTH ITOA SAY

LOGMSG

"message" LOGMSG

This command causes message to appear in the user's Log Window. Like CHAT, SAY and other message-related commands, it deals with character strings rather than integers. This command is primarily useful for debugging, since many users keep their Log Windows closed (guests and new users may be completely unaware that this window exists at all).

Example

"This is a message in your Log Window." LOGMSG

LOWERCASE

"string" LOWERCASE

This function converts a character string to lowercase.

Example

"I WANT TO SHOUT, BUT I CAN'T!" LOWERCASE SAY

MOUSEPOS

MOUSEPOS

This function returns the current X (horizontal) and Y (vertical) coordinates of the cursor. The X coordinate is put on the stack first, then the Y coordinate; they must be retrieved separately. This means you'll need two ITOA commands to get the mouse position, not just one. If you want get them in the traditional order (X, then Y), issue a SWAP command before getting them from the stack. The example below shows how to do this, sending the output to the Log Window.

Example

MOUSEPOS SWAP ITOA LOGMSG ITOA LOGMSG

OVER

OVER

This command is the same as 1 PICK. See the PICK command below for a full description.

PICK

PICK

The command n Pick reaches down n stack items and copies that item to the top of the stack. O PICK is the same as DUP, and 1 PICK is the same as OVER.

POP

POP

This command pops the top element off the stack and discards it.

Example

"none" "one" "two" "three" "four"
POP POP POP POP
SAY

PUT

data array index PUT

This command is used to put a data element into an array, in the position indicated by index. If the data is a string (as opposed to an integer), it must be encased in double quotes. Note that the elements of an array are numbered from 0 (zero) to (number of elements minus 1). The following example creates an array of letters, places the word "foo" in a random position within it, and prints the results in the Log Window.

Related commands

GET

Example

[ "a" "b" "c" "d" "e" ] myArray =
"foo" myArray 5 RANDOM PUT
{ LOGMSG } myArray FOREACH

RANDOM

number RANDOM

This function puts a random integer on the stack, from 0 to (number minus 1). The following example shows you how to roll a die (i.e., how to generate a random integer from 1 to 6):

Example

6 RANDOM 1 + tempVar =
"I rolled a " tempVar ITOA & "!" & SAY

ROOMID

ROOMID

This function returns the ID of the current room (as an integer).

Example

"The ID of this room is \"" ROOMID ITOA & ".\"" & SAY

ROOMNAME

ROOMNAME

This function returns the name of the current room.

Example

"The name of this ROOM is \"" ROOMNAME & ".\"" & SAY

SAYAT

"message" x y SAYAT

This command causes message to appear as though it was spoken from position x,y. This is also known as "spoofing."

Example

512 RANDOM tempX =
384 RANDOM tempY =
tempX ITOA " by " & tempY ITOA tempStr =
tempStr tempX tempY SAYAT

SERVERNAME

SERVERNAME

This is the name of the server as specified in the Server Preferences dialog. You can't change the servername from a script.

Example

"Hello and welcome to " SERVERNAME & "!" & LOCALMSG

STACKDEPTH

STACKDEPTH

This command pushes the number of items on the stack to the top of the stack.

STATUSMSG

"message" STATUSMSG

This command causes message to be displayed in the status bar (just above the Input Box) on the Macintosh and Windows clients. On The Palace Viewer, this command causes message to be displayed in the center of the Grapic window. It can be annoying; use it sparingly.

Example

"What a cool STATUSMSG!" STATUSMSG

STRINDEX

"str" "sp" -- off

This command pushes the offset of the string "sp" in "str" or pushes -1 if "sp" does not appear in "str".

STRLEN

"str" -- len

This command pushes the length of the string to the top of the stack.

STRTOATOM

"string" STRTOATOM

This command turns a character string into an executable atomlist.

Example

"WHOME WHONAME SAY" STRTOATOM EXEC

SUBSTR

string "stringpattern" SUBSTR

This function searches string for stringpattern (not case-sensitive) and returns 1 if it is found; otherwise it returns a 0.

Example

ON OUTCHAT {
CHATSTR LOWERCASE tempStr =
{
"The letters ae appeared in that sentence." CHATSTR =
} {
"The letters ae did not appear in that sentence." CHATSTR =
} tempStr "ae" SUBSTR IFELSE
}

SUBSTRING

"str" off len -- "f"

This command pushes the substring of "str" at offset off for length len. Negative values of len mean the rest of the string at offset off. Negative values of offset are an error. The example below says "I like roses".

Example

"I like violets" 0 7 SUBSTRING "roses" & SAY

SWAP

SWAP

This command swaps the top two elements on the stack.

Example

MOUSEPOS
"The current MOUSEPOS is " ITOA & " (Y) " & ITOA & "(X)." & SAY
MOUSEPOS
"But if I do a SWAP I get " SWAP ITOA & " (X) followed by " & ITOA & "(Y)." & SAY

TICKS

TICKS

This function returns the current time (on the client) in ticks. The user's subjective duration of a "tick" depends on the speed of both the client and server as well as the network load at the moment, but is considered to be about 1/60th of a second.

Example

"Current TICKS = " TICKS ITOA & "." & SAY

TOPTYPE

TOPTYPE

This command pushes a number indicating the type of the top item on the stack (the top item remains on the stack). The codes are

0 - Internal Error/unknown/stack empty

1 - number

2 - symbol (variable name)

3 - AtomList

4 - String

5 - ArrayMark (a [ character)

6 - Array

UPPERCASE

"string" UPPERCASE

This function converts string to uppercase. The following example causes everything to be spoken that way (in Cyborg.IPT it will operate on everything the user says; in a room script it will operate on everything said by anyone in the room).

Example

ON OUTCHAT {
CHATSTR UPPERCASE CHATSTR =
}

VARTYPE

VARTYPE

This command is like TOPTYPE, unless the top item on the stack is a symbol (variable). If the top item is a symbol, the type of the current value of the variable is pushed. For variable types, see TOPTYPE on page 80

WHOPOS

"userName" WHOPOS
userID WHOPOS

This function (in either of its forms) returns the x,y position of the user specified. The following example causes the user to speak his/her coordinates.

Example

WHOME WHOPOS
ITOA tempY = ITOA tempX =
"My current WHOPOS is " tempX & " by " & tempY & "." & SAY


Operators

Operators are functions that perform traditional mathematical and logical operations. If you want to add, subtract, multiply, divide, or perform higher math tricks, you'll need these. You'll also need to use operators for setting and comparing the values of symbols and other data; the most commonly-used operators are "equal" ( == ) and "let equal" ( = ). All operators make use of the stack, where they deposit the results of their calculations.

Standard Operators

Standard operators allow you to perform all basic mathematical operations in RPN format. This section describes the syntax and use of all standard operators.

Each of the following examples is preceded by the equivalent statement in infix format (in parentheses).

valueA valueB +

Adds the two values and pushes the result onto the stack. If the two values are strings, this operator concatenates the two strings and pushes the result onto the stack.

Example ( 2 + 3 )

2 3 +

valueA valueB -

Subtracts valueb from valuea and pushes the result onto the stack.

Example ( 3 - 2 )

3 2 -

valueA valueB *

Multiplies the two values and pushes the result onto the stack.

Example ( 2 * 3 )

2 3 *

valueA valueB /

Divides valueA by valueB and pushes the (integer) result onto the stack. The remainder is discarded (e.g., the example below yields a result of "1").

Example ( 3 / 2 , discard remainder)

3 2 /

valueA valueB %

Divides valuea by valueb and pushes the remainder (modulo) onto the stack. The result itself is discarded (e.g., the example below yields a result of "5").

Example ( 3 / 2 , keep remainder only)

3 2 %

value value ==

Pushes 1 onto the stack if the two values are equal, 0 otherwise. If the two values are strings, this operator does a case-insensitive string comparison. The example below returns 0 (false).

Example ( 2 = 3 )

2 3 ==

value value !=

value value <>

These two operators are synonymous. They push 1 onto the stack if the two specified values are not equal, otherwise they return 0. The examples below both return 1 (true). Values specified for this function may be either integers or strings. These operators are case-insensitive when comparing strings.

Example 1 ( 2 <> 3 )

2 3 <>

Example 2 ( "a" != "b" )

"a""b" !=

valueA valueB <

Pushes 1 onto the stack if valueA is less than valueB; otherwise it returns a 0. Values specified for this function may be either integers or strings. This operator is case-insensitive when comparing strings. The example below returns a 1 (true).

Example ( 2 < 3 )

2 3 <

valueA valueB >

Pushes 1 onto the stack if valueA is greater than valueB; otherwise it returns a 0. Values specified for this function may be either integers or strings. This operator is case-insensitive when comparing strings. The example below returns a 0 (false).

Example ( 2 > 3 )

2 3 >

valueA valueB <=

Pushes 1 onto the stack if valueA is less than or equal to valueB; otherwise it returns a 0. Values specified for this function may be either integers or strings. This operator is case-insensitive when comparing strings. The example below returns a 1 (true).

Example ( 2 <= 3 )

2 3 <=

valueA valueB >=

Pushes 1 onto the stack if valueA is greater than or equal to valueB; otherwise it returns a 0. Values specified for this function may be either integers or strings. This operator is case-insensitive when comparing strings. The example below returns a 0 (false).

Example ( 2 >= 3 )

2 3 >=

valueA valueB AND

Pushes 1 onto the stack if the two values are both true (non-zero), otherwise it returns a 0. The example below returns a 0 (false).

Example (0 AND 1)

0 1 AND

valueA valueB OR

Pushes 1 onto the stack if either of the two values is true (non-zero), otherwise it returns a 0. The example below returns a 1 (true).

Example ( 0 OR 1 )

0 1 OR

value NOT

value !

These two operators are synonymous. They push the logical inverse of value onto the stack (e.g., 1 if value is equal to zero, 0 otherwise). The NOT of 0 is 1. The NOT of 1 (or any non-zero integer) is 0.

Example ( NOT 1 )

1 NOT

value SINE

Pushes the trigonometric sine of value multiplied by 1000. Remeber that value is in degrees.

Example (sine 30)

30 SINE ITOA SAY

value COSINE

Pushes the trigonometric cosine ofvalue multiplied by 1000. Remember that value is in degrees.

Example (cosine 30)

30 COSINE ITOA SAY

value TANGENT

Pushes the trigonometric tangent of value multiplied by 1000. Remember that value is in degrees.

Example (tangent 45)

45 TANGENT ITOA SAY

value SQUAREROOT

Pushes the integer part for the square root of value. The folowing example displays the message "4".

Example (squareroot 20)

20 SQUAREROOT ITOA SAY

string1 string2 &

Concatenates string1 and string2, and pushes the result onto the stack. The example below creates a complete sentence out of two parts.

Example ( "Are we having fun yet?" )

"Are we " "having fun yet?" &

Assignment Operators

Assignment operators are shortcuts for commonly-used sets of functions. For example, to add 4 to X, you could say:

x 4 + x =

This works just fine ("take X and 4 and add them, and then let X equal that"), but using the += assignment operator is easier, because it allows you to combine the addition and the let equal operations into a single function that does exactly the same thing:

4 x +=

Assignment operators exist for all basic math operations (addition, subtraction, multiplication, integer and modulo division), and for the common operations of incrementing and decrementing (adding or subtracting 1). So instead of saying

x 1 + x =

you can say

x ++

The following entries explain the syntax and effects of all the assignment operators.

value symbol +=

Adds value to symbol and assigns the total to symbol.

Example (let x = x + 3)

3 x +=

In this operation, you may also specify a string as the value. In this case the operation appends the string "a" to the string variable x, then assigns the result to x.

Example (let x=x+"a")

"a" x +=

value symbol -=

Subtracts value from symbol and assigns the total to symbol.

Example (let x = x - 3)

3 x -=

value symbol *=

Multiplies value by symbol and assigns the total to symbol.

Example (let x = x * 3)

3 x *=

value symbol /=

Divides symbol by value and assigns the total (integer) to symbol.

Example (let x = x / 3, rounded down)

3 x /=

value symbol %=

Divides symbol by value and assigns the integer remainder (modulo) to symbol.

Example (let x = the remainder of x / 3)

3 x %=

symbol ++

Adds 1 to the value of symbol.

Example (let x = x + 1)

x ++

symbol --

Subtracts 1 from the value of symbol.

Example (let x = x - 1)

x --