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.
Top ^
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
Top ^
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 OUTCHATevents
will only be triggered by users' deliberate speech. Scripts in the INCHAThandler
can be used to modify the text of the incoming chat message via use of
the CHATSTRvariable.
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
}
Top ^
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 commandsand
functionsdescribed
in this section.
Commands perform actions that directly affect the state
of objects in the current room (users, doors, spots and props). Functionsare
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:
-
Cyborg Commands directly affect or refer to users,
avatars and props. See Cyborg
commands and functions.
-
Spot Commands directly affect or refer to hotspots
(both doors and spots). See Spot
commands and functions.
-
Paint Commands deal with the paint tools and painting on
the screen. See Paint
commands and functions.
-
Sound Commands deal with WAV or MIDI files and their use.
See Sound commands
and functions.
-
Flow Commands affect the logical flow (decision-making processes)
of the program. Flow
commands and functions.
-
General Commands affect data and variables; usually on the
stack, and perform other miscellaneous actions which don't fit easily into
the other categories. See General
commands and functions.
NOTE: Just because something is called a "cyborg
command" doesn't mean that it can only be placed in the Cyborg.IPT.
On the contrary, most commands will work just fine in either script file,
in any type of object. Rather, the categories refer to the types of objects
or actions that are manipulated by the command; what we might
call "the subject objects."
The following listings describe all Iptscrae commands and functions.
Top ^
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
xy
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.
Exaple
{
"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) |
| #2 Look Down (nodding) |
| #1 Smile |
| #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 userIDof
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
Top ^
Spot commands and functions
DOORIDX
number DOORIDX
This function returns the IDof
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
xyspotID
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:
-
Launch your client to access your server.
- From your client, enter the room called "The Study" and enter Operator
mode (from the Options menu).
- If the secret bookshelf-door isn't already open, say "open sesame" to flip
the spot's state and display the "open" graphic.
- Type the following command into the Input Box (100 is the ID of
the magical door):
/-50 -50 100 SETPICLOC
- 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.
- 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
Top ^
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
x1y1x2y2
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
xy
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
rgb
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
xy
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
xy
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
Top ^
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
MIDILOOP
number "fileName"
MIDILOOP
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. Also, by using TRUE instead of a number, you can loop a
midi infinitly!
Example
5 "testme.mid" MIDILOOP
TRUE "testme.mid" MIDILOOP
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
Top ^
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
Top ^
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
propIDx
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
| 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. |
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
theGREPSTRcommand.
Up to nine such symbols may be used in a singleGREPSTR-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
nPICK
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" xy
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
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
Top ^
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 symbolsand
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 inverseof valueonto
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 --
|