This section is a reference to the Iptscrae language:
* Data types
* Event handlers
* Commands and functions
* Operators
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 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 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
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."
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 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 =
}
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
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
}
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.
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:
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.
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
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:
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 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
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
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
; <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:
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 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 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 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 --
del.icio.us |
Digg
Email to a friend
Print version
Plain text
Home
Set as homepage
Add to favorites
Mobile site
Rss
Plain text
Archive
Post your comment