Palace Planet the Palace Chat community Portal: Iptscrae Language Reference

Iptscrae Language Reference
================================================================================
admin on 02/05/2009 12:50:00
 
DATA TYPES
The Palace is integer-based (meaning that it works in terms of whole numbers),
but barring floating-point variables, the software can handle all basic data
types: symbols (variables), numbers (integers), strings (string literals),
atomlists (subroutines) and arrays, as well as a number of special-case symbols
and reserved keywords.
SYMBOLS (VARIABLE NAMES)
Symbols must start with a letter, and may contain any combination of letters,
numbers and the underscore. They may not contain any spaces, and have a maximum
length of 31 characters. Examples:
x
plan9
my_really_big_variable
NUMBERS ( INTEGERS)
Numbers in Iptscrae are stored as 32 bit sized integers. No floating-point is
allowed. Numbers must be specified in decimal notation using the digits 0
through 9, with an optional leading ( - ) for negative numbers. Examples:
2
-32
4283748
STRINGS (STRING LITERALS)
String literals must be encased in double quotes, for Example "string". If you
need to include a quote symbol within a string, precede it with a backslash:
"these "doublequotes" are okay". You can create long strings by concatenating
multiple strings together using the & operator (see Operators). Examples:
"Hello"
"A Flock " "of Words" &
"Suddenly, Fred shouted "Look out!" and hit the dirt."
ARRAYS
An array is an ordered list of other Iptscrae data types. Arrays may be
declared with the ARRAY command or by encasing the elements of the array in
square brackets ([and]). You use the GET function to extract an item from an
array, use the PUT command to insert an item into an array, and the FOREACH
command to perform an operation on each item in an array. Arrays can be composed
of different data types, including other arrays. Examples:
[ 100 200 300 ]
[ "Hello" "World" ]
[ 100 "Hello" [ 0 1 2 ] ]
5 7 9 ARRAY
ATOMLISTS
Atomlists are small Iptscrae scripts, or "subroutines." They can contain all
other data types, including other atomlists. Some commands (such as EXEC, IF,
WHILE, ALARMEXEC and FOREACH) operate on atomlists (rather than in them, as most
other commands do). Atomlists must be encased in curly brackets ({and}).
Examples:
{ 1 tempVar = }
{ "Howdy" SAY }
{
23 firstVar =
secondVar firstVar - deltaVar =
}
SPECIAL-CASE SYMBOLS
CHATSTR   CHATSTR is a reserved word and a special-case variable in Iptscrae.
Whenever a script is executing in response to an INCHAT or OUTCHAT event,
CHATSTR represents the chat text itself. This variable may be modified on the
fly. In the case of an INCHAT event, this will change the text that ends up
getting displayed on the screen. In the case of an OUTCHAT event, it will change
the text that is sent to other users.
It is generally preferable to use OUTCHAT rather than INCHAT event handlers.
The following example shows how to make an effect that occurs whenever you
speak (type) a key word or phrase, by applying an IF statement to CHATSTR. The
whole thing resides in the OUTCHAT handler.
Example ON OUTCHAT {
{
"applause" SOUND
} CHATSTR "!Thank you!" == IF
}
(The "Backslash" Character)   The backslash has a special meaning in Iptscrae;
when it appears within a character string, it indicates that the character
immediately following it should be included within the string literally (i.e.,
as a printable character). It is most often used to indicate that a double quote
should be printed as part of a string, rather than signifying the end of it (as
it typically would). The backslash can be used with other control characters, as
well as in GREPSTR regular expressions.
Example 1 (a quote within a SAY command) "The word he said was "rosebud."" SAY
Example 2 (a local whisper in a "sign balloon") "@200,20^Note to myself..."
WHOME PRIVATEMSG
-------------------------
EVENT HANDLERS
Events are the basic stimuli of the server, representing all the things your
Palace can "watch for" and respond to. They include significant user actions
such as entering and leaving rooms, clicking on doors and spots, talking and
other basic activities, plus a special type of event called an alarm.
For each event type, there exists an event handler. Event handlers reside
within the SCRIPT... ENDSCRIPT portions of a script file. The name of each event
handler consists of the word ON followed by the name of the event it handles
(i.e., ON ENTER, ON LEAVE, ON SELECT, and others). When an event occurs, the
server script file is consulted to see whether there is a handler for that event
in the current room. The client also checks the user's Cyborg.ipt file. If any
appropriate event handlers are found, the scripts within them are executed
immediately.
Note that not all handlers may be used in all objects; some may be applied only
to doors or spots, others to cyborgs, and some to all three.
ON ALARM   (Doors, Spots, Cyborgs)
An ALARM event occurs in response to the SETALARM command in a script. It can
be used to schedule a periodic event, such as an animation, or to provide a
delayed response. To trigger the following example handler, use the SETALARM
command (see  SETALARM).
Example ON ALARM {
"I am alarmed!" SAY
}
ON ENTER   (Doors, Spots, Cyborgs)
An ENTER event occurs when a user enters the room. Scripts in this handler can
be used (among other things) to start animations (via SETALARM), initialize
user-defined functions, start room behavior, generate automatic "hello" messages
from the entering user, etc.
Example ON ENTER {
"I have entered!" SAY
}
ON INCHAT   (Doors, Spots, Cyborgs)
An INCHAT event is triggered in response to an incoming chat message; a better
name for this handler might be ON HEAR. It is generally preferable to use the
OUTCHAT handler instead of this one, because INCHAT events will be triggered by
all user speech, user scripts, and any other "talking spots" in the room (very
possibly flooding the server), whereas OUTCHAT events will only be triggered by
users' deliberate speech. Scripts in the INCHAT handler can be used to modify
the text of the incoming chat message via use of the CHATSTR variable.
Example ON INCHAT {
"yes" SOUND
}  NOTE: Want to get killed for flooding your server? Make a spot in your
Palace that does a SAY in the INCHAT handler. Better yet, make two of them in
the same room. Then say something.
ON LEAVE   (Doors, Spots, Cyborgs)
A LEAVE event occurs when a user leaves the room. Scripts in this handler will
be executed in their entirety before the user actually departs.
Example ON LEAVE {
"I am leaving!" SAY
}
ON LOCK   (Lockable Doors)
A LOCK event occurs when a door becomes locked. The event is sent to the door
itself. Scripts in this handler can be used to add additional behaviors to the
door in question.
Example
ON LOCK {
"The door is locked!" SAY
}
ON MACROn for n=0 to n=9   (Cyborgs)
If the room allows cyborgs, this event runs when a script uses ONMACROn (where
n is between 0 and 9) or the user uses an avatar selection 0-9
ON OUTCHAT   (Doors, Spots, Cyborgs)
An OUTCHAT event is triggered in response to an outgoing chat message (when a
user types something and presses the Return key). Scripts in the OUTCHAT handler
can be used to modify the text of outgoing chat messages via use of the CHATSTR
variable. A good example of an OUTCHAT script is the text message handler in The
Moor.
Example ON OUTCHAT {
{
"Polo!" CHATSTR =
} "Marco" CHATSTR == IF
}
ON SELECT   (Doors, Spots)
A SELECT event occurs whenever a user clicks on a hotspot. Note that unless the
hotspot possesses a DONTMOVEHERE command, the user's avatar will immediately
move to the location clicked.
Example ON SELECT {
"I selected the spot!" SAY
}
ON SIGNON   (Cyborgs)
A SIGNON event is sent to each user as they sign on.
Example ON SIGNON {
"I have signed on!" SAY
}
ON UNLOCK   (Lockable Doors)
An UNLOCK event occurs when a door becomes unlocked. The event is sent to the
door itself. Scripts in this handler can be used to add additional behaviors to
the door in question.
Example ON UNLOCK {
"The door is unlocked!" SAY
}
-------------------------
COMMANDS AND FUNCTIONS
Now that you know where scripts can be placed and what events they can react
to, you'll probably want to know what kinds of things you can make them do. You
can add action to your scripts by using the commands and functions described in
this section.
Commands perform actions that directly affect the state of objects in the
current room (users, doors, spots and props). Functions are similar to commands,
but their concerns are data-oriented; a Function always leaves a value (some
kind of data) on the top of the stack, so it can be accessed and manipulated by
other commands and Functions. This is what we mean when we say that a Function
"returns" a value: it places this value on the top of the stack. Most functions
perform both "pops" and "pushes" in doing their job: for instance, the "plus"
(+) operator pops the top two values off the stack, adds them, and pushes the
sum onto the stack. When the operation ends there is one value -- not three --
on the stack.
For ease of use, the commands and functions have been divided into several
categories, based upon the objects they affect and actions they perform:
*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.
CYBORG COMMANDS AND FUNCTIONS
CHAT  "message" CHAT
This command displays the message in a cartoon balloon, as though the user
typed it directly into the Input Box. It is identical to the SAY command.
Example "This is a sentence." CHAT
CLEARPROPS  CLEARPROPS
This command removes all the props the user is wearing. A synonym is NAKED.
Example CLEARPROPS
DOFFPROP  DOFFPROP
This command removes the last prop put on by the user.
Related commands   DONPROP, DROPPROP and REMOVEPROP.
Example DOFFPROP
DONPROP  propID DONPROP
"propName" DONPROP
This command (in either of its forms) adds a prop to the user's costume. The
prop can be specified by ID# (preferable) or by Name.
Related commands   DOFFPROP, DROPPROP and REMOVEPROP.
Examples 1280 DONPROP
"BRBSIGN" DONPROP
DROPPROP  x y DROPPROP
This command takes the last prop user put on and drops it into the floor
(making it a loose prop). x and y specify where it will be dropped.
Related commands   DOFFPROP, DROPPROP and REMOVEPROP.
Example 512 RANDOM tempX =
384 RANDOM tempY =
tempX tempY DROPPROP
GLOBALMSG  "message" GLOBALMSG
This command is available only to users with Operator privileges. It generates
a message that everybody on the server sees. Use it sparingly.
Example "This is a Global Message." GLOBALMSG
GOTOROOM  roomID GOTOROOM
This command is used by spots to navigate users to another room. You can find
out the roomID by looking at the Room Info window, or by using a ROOMID command.
Example  86 GOTOROOM
GOTOURL  "urlString" GOTOURL
This command can be used to send users to other Palaces and Internet URLs. If
you use a URL beginning with "palace://" the user will be connected to the
Palace site specified (if possible); otherwise the user's system will attempt to
go there via whatever application is normally associated with URLs of that type
(web browsers, news readers, FTP utilities, etc.) Same as NETGOTO.
NOTE: If the URL begins with "palace://", it must be the only thing in the
script in order to work with the Macintosh Client or The Palace Viewer.
Examples "palace://welcome.thepalace.com" GOTOURL
"http://www.thepalace.com" GOTOURL
GOTOURLFRAME  "url" "frame" GOTOURLFRAME
This command can be used to send users to the url passed in the browser frame
named "frame".
NOTE: Frame specification is effective in TPV only. The Macintosh and Windows
clients use the default frame.
Example  "http://www.thepalace.com" "myframe" GOTOURLFRAME
HASPROP   "propName" HASPROP
propID HASPROP
This function pushes a 1 onto the stack if the user possesses the specified
prop; otherwise it pushes a 0.
Example {
"I am wearing the Ray Bans" SAY
} {
"I am NOT wearing the Ray Bans" SAY
} "Ray Bans" HASPROP IFELSE
INSPOT  spotID INSPOT
This function pushes a 1 onto the stack if the user's current location is
within the spot indicated by spotID; otherwise it returns a 0. The following
example assumes that the current room includes a spot with an ID of 1.
Example {
"I'm in The Spot!" SAY
} {
"I'm not in The Spot!" SAY
} 1 INSPOT IFELSE
ISGOD  ISGOD
This function pushes a 1 onto the stack if the user running the script has
owner-level access, otherwise it pushes a 0.
Example {
"I am an Owner!" SAY
} {
"I am not an Owner!" SAY
} ISGOD IFELSE
ISGUEST  ISGUEST
This function pushes a 1 onto the stack if the user has guest access, otherwise
it returns 0.
Example {
"I am a Guest!" SAY
} {
"I am not a Guest!" SAY
} ISGUEST IFELSE
ISWIZARD  ISWIZARD
This function pushes a 1 onto the stack if the user has owner or operator-level
access, otherwise it returns 0.
Example
"I am a operator!" SAY
} {
"I am not a operator!" SAY
} ISWIZARD IFELSE
KILLUSER  userID KILLUSER
This command "kills" (disconnects) the user with the specified userID#. If
members aren't allowed to kill (which is typical of most Palace servers), this
command won't work. In any case guests cannot use it. Note that to get userID it
is necessary to use one of the following commands: ROOMUSER, WHOCHAT, WHOME or
WHOTARGET. The following example shows you how to commit suicide in Iptscrae:
Example WHOME KILLUSER
LOCALMSG  "message" LOCALMSG
This command generates a message that only the user executing the script sees.
You can precede the message with @x,y to control its position.
Example "This is a LOCALMSG.  I am the only one who sees it." LOCALMSG
MACRO  number MACRO
This command causes the user to don the specified macro (a "macro" corresponds
to an "avatar" -- a group of props that are all worn at the same time). If the
user possesses a saved macro for the number used in the script, their avatar
will instantly change to it. If an ON MACRO script exists in the user's
Cyborg.IPT, it will be executed instead of the prop change.
Example 16 RANDOM MACRO
MOVE  x y MOVE
This command moves the user x,y pixels relative to the current position.
Example 1 (move down and right) 5 5 MOVE
Example 2 (move randomly) 11 RANDOM 5 - tempX =
11 RANDOM 5 - tempY =
tempX tempY MOVE
NAKED  NAKED
This command removes all of a user's props. It is the same as CLEARPROPS.
Example NAKED
NBRROOMUSERS  NBRROOMUSERS
This function returns the number of users currently in the room.
Example NBRROOMUSERS ITOA tempVar =
"NBRROOMUSERS = " tempVar & "." & SAY
NBRUSERPROPS  NBRUSERPROPS
This function returns the number of props currently worn by the user.
Example NBRUSERPROPS ITOA tempVar =
"NBRUSERPROPS = " tempVar & "." & SAY
NETGOTO  "urlString" NETGOTO
This command can be used to access other Palace servers or other Internet URLs.
If you use a "palace://" URL, the user will be signed on to the Palace server
indicated (if possible); otherwise the system will attempt to take the user
there by some other means. Same as GOTOURL.
NOTE: If the URL begins with "palace://", it must be the only thing in the
script in order to work with the Macintosh Client or The Palace Viewer.
Example "palace://welcome.thepalace.com" NETGOTO
"http://www.thepalace.com" NETGOTO
POSX  POSX
This function returns the user's horizontal coordinate.
Example "My current POSX is " POSX ITOA & SAY
POSY  POSY
This function returns the user's vertical coordinate.
Example "My current POSY is " POSY ITOA & SAY
PRIVATEMSG  "message" userID PRIVATEMSG
This command generates a private message to another user. Note that to get
userID it is necessary to use one of the following commands: ROOMUSER, WHOCHAT,
WHOME or WHOTARGET.
Example "This is a PRIVATEMSG. I am whispering to myself." WHOME PRIVATEMSG
REMOVEPROP  propID REMOVEPROP
"propName" REMOVEPROP
This command removes a prop from the user's costume. The prop can be specified
by name or by propID. The following example removes the "Ray Bans" prop (if the
user is wearing it).
Related commands   DONPROP, DROPPROP and DOFFPROP.
Example {
"Ray Bans" REMOVEPROP
} {
"First I have to put on the Ray Bans!" SAY
} "Ray Bans" HASPROP IFELSE
ROOMMSG  "message" ROOMMSG
This command generates a message that everyone in the room sees. Use it
sparingly. You can precede the message with @x,y to control its position.
Example 1 "This is a ROOMMSG.  Everyone in this room can see it." ROOMMSG
Example 2 "@10,10 This is a ROOMMSG up in the corner.  Isn't that awesome?" 
ROOMMSG
ROOMUSER  number ROOMUSER
Every user on the server has a unique userID that stays the same as long as
they remain connected, but at any given moment they also possess a "room user"
number assigned to them by the room they're in. This function returns the userID
of room user number in the current room.
Example WHOME ROOMUSER ITOA tempVar =
"I am currently ROOMUSER number " tempVar & "." & SAY
SAY  "message" SAY
This command displays message as if the user typed it in directly. It is
identical to the CHAT command.
Example 1 (talking) "I am saying something!" SAY
Example 2 (thinking) ":I am thinking something!" SAY
Example 3 (shouting) "!I am shouting something!" SAY
Example 4 (sign) "^This is a sign!" SAY
Example 5 (positioning) "@10,10 Now I'm saying something way up here!" SAY
SETCOLOR  number SETCOLOR
This command sets the user's face color to one of 16 colors. If the "tinted
balloon" preference is checked, this command also contols the color of the word
balloon. The specified number must be an integer from 0 to 15. The possible
colors are numbered by dividing the spectrum into 16 equal steps, as follows:
#0 Red
#1 Orange
#2 Orange/Yellow
#3 Yellow
#4 Yellow/Green
#5 Light Green
#6 Green
#7 Green/Cyan
#8 Cyan
#9 Light Blue
#10 Medium Blue
#11 Dark Blue/Purple
#12 Purple
#13 Magenta
#14 Magenta/Pink
#15 Pink
Example  16 RANDOM SETCOLOR
SETFACE  number SETFACE
This commands sets the user's face to one of the 13 built-in faces (props are
not removed, however). The specified number must be an integer from 0 to 12.
#0 Eyes Closed (sleeping or blushing)
#1 Smile
#2 Look Down (nodding)
#3 Talking
#4 Wink Left
#5 Normal
#6 Wink Right
#7 Tilt Left (shaking head)
#8 Look Up (nodding)
#9 Tilt Right (shaking head)
#10 Sad
#11 Blotto
#12 Angry
Example 13 RANDOM SETFACE
SETPOS  x y SETPOS
This command immediately moves the user to position x y in the Viewing Area. x
must be an integer from 0 to 511. y must be an integer from 0 to 383.
Example 10 10 SETPOS
SETPROPS  [ propArray ] SETPROPS
This command acts like a macro, causing the user to immediately don all props
listed in [ propArray ]. Props may be listed either by Name or by ID#
Example [ "Ray Bans" "daisy" "Wine Bottle" ] SETPROPS
Like all arrays, [ propArray ] must be enclosed in square brackets ( [ ] ).
Also, prop names, being strings, must be enclosed in double quotes (").
SOUND  "fileName" SOUND
This command plays the sound file filename.  Sounds are WAV files, saved
without the .WAV extension, and reside on the client in
PalaceMediaYourPalaceNameSounds.
Example 1 (play specified sound) "Applause" SOUND
Example 2 (play random sound) 6 RANDOM tempVar =
[ "Yes" "No" "Fazein" "Applause" "Boom" "Crunch" ] tempVar GET SOUND
SUSRMSG  "message" SUSRMSG
This command generates a message that all owners and operators will see, no
matter where they are on the server. Use it sparingly.
Example "This is an SUSRMSG from " USERNAME & SUSRMSG
TOPPROP  TOPPROP
This function returns the propID of the last prop the user put on. If the user
is "naked" it returns 0 (zero). The following example shows you how to scatter
all your currently-worn props.
Example { 400 RANDOM 300 RANDOM DROPPROP } { TOPPROP } WHILE
USERNAME  USERNAME
This function returns the user's User Name as specified in the Preferences
dialog. You can't change a user name from a script.
Example "Hello, my name is " USERNAME & "!" & SAY
USERPROP  number USERPROP
This function returns the propID of one of the props currently worn by the
user. number is a number from 0 to 8 indicating which prop you want to identify
(note that this refers to the order they were donned in, not necessarily the
order they appear in). You can determine the number of props currently worn by
using the NBRUSERPROPS command, as illustrated in the following example.
Example  NBRUSERPROPS RANDOM whichProp =
whichProp USERPROP ITOA propIdent =
whichProp ITOA " USERPROP = " & propIdent & "." & SAY
WHOCHAT  WHOCHAT
This function returns the userID of the user who invoked an INCHAT event.
Example WHOCHAT ITOA tempVar =
"The WHOCHAT command returns " tempVar & "." & SAY
WHOME  WHOME
This function returns the user's own userID.
Example WHOME ITOA tempVar =
"The WHOME command returns " tempVar & "." & SAY
WHONAME  userID WHONAME
This function returns the User Name of the specified user. Note that to get
userID it is necessary to use one of the following commands: ROOMUSER, WHOCHAT,
WHOME or WHOTARGET. The following example causes you to say the name of room
user 0 (zero) in the current room (that's you, if you're the only person in the
room at the moment!)
Example 0 ROOMUSER WHONAME SAY
WHOPOS  "name" WHOPOS
userID WHOPOS
This function (in either of its forms) returns the current x,y position of the
user. Note that x is placed on the stack before y, which means that y is ready
to be retrieved from the stack first. To reverse their positions so they can be
used in their typical order (X, then Y), use the SWAP function.
Example WHOME WHOPOS SWAP ITOA tempY = ITOA tempX =
"WHOME WHOPOS returns '" tempX & "' '" & tempY & "'." & SAY
WHOTARGET  WHOTARGET
This function pushes the userID of the person you have selected for private
chat (i.e., Whisper Mode or ESP) or zero if you have not selected a target.
Example WHOTARGET USERNAME tempVar =
{
"WHOTARGET USERNAME returns '" tempVar & "'." & SAY
} {
"I must select someone in order to use the WHOTARGET Command." SAY
} tempVar  "" IFELSE
SPOT COMMANDS AND FUNCTIONS
DOORIDX  number DOORIDX
This function returns the ID of the door indicated by number. The following
example causes the user to leave through a random door:
Example NBRDOORS RANDOM DOORIDX SELECT
Related functions NBRDOORS, SELECT.
GETSPOTSTATE  spotID GETSPOTSTATE
This function returns the current state of the specified hotspot or door. The
following example uses NBRSPOTS and SPOTIDX as well as GETSPOTSTATE to determine
the state of a random door or spot in the current room.
Example NBRSPOTS RANDOM tempVar =
"The state of spot number " tempVar ITOA & " (" & tempVar SPOTIDX  SPOTNAME &
") is " & tempVar SPOTIDX GETSPOTSTATE ITOA & SAY
ISLOCKED  doorID ISLOCKED
This function returns a 1 if the indicated door is locked, otherwise it returns
a 0. The following example uses NBRDOORS and DOORIDX to determine the state of a
randomly-selected door in the current room.
Example NBRDOORS RANDOM doorNumber =
{
"Door number " doorNumber ITOA & " is locked." SAY
} {
"Door number " doorNumber ITOA & " is unlocked." SAY
} doorNumber DOORIDX ISLOCKED IFELSE
LOCK  doorID LOCK
This command is used by deadbolts (or doorknobs) to lock doors. Its counterpart
is the UNLOCK command. The following example assumes there is a lockable door
with an ID of 1 in the current room.
Example 1 LOCK
ME  ME
When a spot or door is executing the script, this function pushes its ID.
Example " "ME SPOTNAME" returns "" ME SPOTNAME & ""." & SAY
NBRDOORS  NBRDOORS
This function returns the number of doors in the room. This number may be less
than or equal to the number returned by NBRSPOTS (because all doors are spots,
but not all spots are doors).
Related commands  DOORIDX
Example " "NBRDOORS" returns "" NBRDOORS ITOA & ""." & SAY
NBRSPOTS  NBRSPOTS
This function returns the number of spots (including doors) in the room.
Example " "NBRSPOTS" returns "" NBRSPOTS ITOA & ""." & SAY
SELECT  spotID SELECT
This command "clicks" the spot specified by spotID. If the spot has an ON
SELECT handler, the script will be executed just as though the user had selected
it physically. The following example assumes there is a spot with an ID of 1 in
the current room. To see it work, put an ON SELECT handler in this spot that
does something noticeable.
Example 1 SELECT
SETALARM  futureTicks spotID SETALARM
This command is used to schedule an ALARM event in the future. It can be used
to create animations and other interesting activity. The user's subjective
duration of a "tick" depends on the speed of both the client and server as well
as the network load at the moment, but is about 1/60th of a second. The
following example assumes there is a spot with an ID of 1 in the current room.
To see it work, put an ON ALARM handler in this spot that does something
noticeable (see Handlers earlier in this document).
Example 300 1 SETALARM
SETLOC  x y spotID SETLOC
This command is used to move a spot or door, relative to its current position.
It is functionally equivalent to selecting the spot or door while in authoring
mode and dragging it to the new position. Note that this command is only
accessible to owners and operators; i.e. it will not be executed unless the user
is in owners or operator mode. For this reason, it is much more useful as an
authoring command than as a scripted command. The following example assumes that
you are in owners or operator mode, and that there is a spot with an ID of 1 in
the current room.
Example 10 10 1 SETLOC
SETPICLOC  x y spotID SETPICLOC
This command is used to change the x and y offsets of a picture associated with
spot spotID (these are the second and third numbers in the "triplets" appearing
between PICTS and ENDPICTS). Note that only a single picture is affected,
corresponding to the current state of the spot -- any pictures associated with
other states of the same spot will remain unchanged. Note also that this command
is only accessible to owners and operators; i.e., it will not be executed unless
the user is in owners or operator mode. For this reason, it is much more useful
as an authoring command than as a scripted command. In fact, the SETPICLOC
command provides the only way to change a picture's offset without editing the
server script, and this makes it very useful for "fine-tuning" the placement of
a particularly tricky graphic. The following example assumes that you are in
owners or operator mode, and that there is a spot with an ID of 1 (and at least
one picture) in the current room.
Example 10 10 1 SETPICLOC
To see this command in action, launch the Palace server using the "Mansion"
script and try this simple experiment:
*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
PAINT COMMANDS AND FUNCTIONS
Paint Commands always operate in the foreground layer of the Viewing Area; that
is to say, "in front of" all graphics in the midground layer.
LINE  x1 y1 x2 y2 LINE
This command draws a line from point x1,y1 to point x2,y2. The line is drawn in
the current PENSIZE and PENCOLOR. The following example draws a line from the
upper left corner of the Palace client viewing area to the user who triggered
it.
Example 0 0 POSX POSY LINE
LINETO  x y LINETO
This command draws a line from the current PENPOS to a point x,y away from the
current PENPOS. The line is drawn in the current PENSIZE and PENCOLOR. The
following example draws a diagonal line that goes 100 pixels to the right and 50
pixels upward, starting from the pen's current position.
Example 100 -50 LINETO
PAINTCLEAR  PAINTCLEAR
This command erases all painting/drawing from the screen, regardless of who put
it there. You can do the same thing by double-clicking on the Detonator in the
Painting Window.
Example PAINTCLEAR
PAINTUNDO  PAINTUNDO
This command erases the last painting/drawing command or action performed. You
can do the same thing by clicking once on the Detonator in the Painting Window.
Example PAINTUNDO
PENBACK  PENBACK
This command moves the pen to the "back" of the foreground layer: any painting
commands or actions subsequently performed will appear behind all avatars in the
room (but they'll still be in front of any graphics in the midground layer). Any
paint already on the screen is not affected. Note that you can do the same thing
by clicking on the Layerer in the Painting Window.
Example PENBACK
PENCOLOR  r g b PENCOLOR
This command sets the color of the pen: any painting commands or actions
subsequently performed will appear in the specified color. You can do the same
thing with the Palette in the Painting Window. The three arguments r, g and b
represent the relative amounts of red, green and blue in the color, on a scale
of 0 to 255 (where 0 0 0 yields black and 255 255 255 yields white). The
following example sets the pen color randomly.
Example 255 RANDOM tempR =
255 RANDOM tempG =
255 RANDOM tempB =
tempR tempG tempB PENCOLOR
PENFRONT  PENFRONT
This command moves the pen to the "front" of the foreground layer: any painting
commands or actions subsequently performed will appear in front of all avatars
in the room (in the closest possible position to the user's face). Paint already
on the screen is not affected. You can do the same thing by clicking on the
Layerer in the Painting Window.
Example PENFRONT
PENPOS  x y PENPOS
This command moves the pen to position x y on the screen, without drawing
anything. The following example moves the pen to the user's position.
Example POSX POSY PENPOS
PENSIZE  number PENSIZE
This command sets the pixel width of all lines drawn by the pen to number (an
integer from 1 to 9): any painting commands or actions subsequently performed
will create lines of this width. Paint already on the screen is not affected.
You can do the same thing with the Line Sizer in the Painting Window. The
following example paints a gradually-widening line across the Viewing Area.
Example 30 150 PENPOS
1 PENSIZE
50 0 LINETO
2 PENSIZE
50 0 LINETO
3 PENSIZE
50 0 LINETO
4 PENSIZE
50 0 LINETO
5 PENSIZE
50 0 LINETO
6 PENSIZE
50 0 LINETO
7 PENSIZE
50 0 LINETO
8 PENSIZE
50 0 LINETO
9 PENSIZE
50 0 LINETO
PENTO  x y PENTO
This command moves the pen to a position x y relative to the current PENPOS,
without drawing anything. The following example draws a line 100 pixels long,
moves the pen via PENTO, and continues drawing.
Example 0 150 100 150 LINE
50 50 PENTO
100 0 LINETO
SOUND COMMANDS AND FUNCTIONS
Prior to version 2.0 of the Palace client, audio files could not be sent across
the network. For WAV or MIDI files to be heard, they had to exist on the user's
hard disk, in the Sounds folder. A few users are still running around with this
limitation, and sounds should therefore be made available via a Web Page, public
FTP directory, or some other means.
Version 2.0 and greater allows clients to receive sounds as downloads from the
server. To be sent out, the audio files in question must be placed in the
Pictures folder on the server's computer.
MIDIPLAY  "fileName" MIDIPLAY
This command causes the MIDI file "fileName" to be played. The following
example assumes that there is a MIDI file called "testme.mid" in the
/Palace/Media/YourPalaceName/Sounds folder.
Example "testme.mid" MIDIPLAY
MIDISTOP  MIDISTOP
This command causes the currently-playing MIDI file to immediately stop. (PC
only)
Example MIDISTOP
SOUND  "fileName" SOUND
This command causes the file "fileName" to be played for all users in the room.
It is functionally identical to typing ")filename" SAY into the Input Box.
Example "teehee" SOUND
"Song.midi" SOUND
FLOW COMMANDS AND FUNCTIONS
ALARMEXEC  { atomlist } ticks ALARMEXEC
This command schedules an atomlist to be executed at a pre-specified time
(after so many "ticks" have elapsed). The user's subjective duration of a "tick"
depends on the speed of both the client and server as well as network load at
the moment, but is considered to be 1/60th of a second. The following example
waits ten seconds before finishing.
Example "Don't you hate..." SAY
{ "waiting?" SAY } 600 ALARMEXEC
BREAK  BREAK
This command breaks out of a WHILE or FOREACH loop. The following example sets
up a FOREACH loop causing a sentence to be spoken one word at a time, but halts
after the fourth word due to a BREAK command.
Example 0 tempVar =
{
tempStr =
tempVar ++
{
tempStr SAY
} {
BREAK
} 5 tempVar > IFELSE
} [ "I" "will" "never" "finish" "speaking" "this" "sentence" ] FOREACH
EXEC  atomlist EXEC
This command executes an atomlist. It can be used in combination with the DEF
command (see below) to execute a "user-defined function." Note that unless the
function was defined in the same handler, it must be made GLOBAL.
Example { "Hello world!" SAY } definedFunction =
definedFunction EXEC
EXIT  EXIT
This command stops the currently-running script. It is useful for breaking out
of looping errors that might otherwise flood the server or lock up the client.
The following example bounces you around the screen randomly. It would continue
to do so forever, except for the imbedded EXIT command.
The following script is likely get you killed for flooding if a death penalty
exists on the server where it is executed. It is recommended that you turn the
death penalty for flooding OFF before attempting to use this script.
Example 400 150 SETPOS
{
51 RANDOM 25 - tempX =
51 RANDOM 25 - tempY =
tempX tempY MOVE
{ EXIT } POSX 256 < IF
} { 1 } WHILE
FOREACH  { atomlist } [ array ] FOREACH
This command executes atomlist once for each item in array. Before executing
the atomlist, each item in the array is pushed onto the stack. The atomlist
should be something that pops these items off the stack and does something with
them, as the following example indicates.
Example { SAY } [ "Ready" "Steady" "Go!" ] FOREACH
IF  { atomlist } condition IF
This command can be used to create a conditional statement: if the condition
evaluates to TRUE (non-zero), atomlist will be executed. If the condition
evaluates to FALSE ("0") it will not. Any operator (or logical series of
operators) may be used to describe the condition being checked for (see the
Operators section). The following example rolls a pair of imaginary dice,
looking for a lucky total of 7.
Example 6 RANDOM 1 + tempVar =
6 RANDOM 1 + tempVar + tempVar =
"I rolled a " tempVar ITOA & SAY
{ "I'm a winner!" SAY } tempVar 7  == IF
IFELSE  { trueAtomList } { falseAtomList } condition IFELSE
This command can be used to create mutually-exclusive conditional statements:
if the condition evaluates to TRUE (non-zero), the trueatomlist will be
executed. Otherwise, the falseatomlist will be executed. Warning: a very common
Iptscrae bug is to use IF when you really mean IFELSE. The following example
randomly determines two numbers from 1 to 100 and compares them.
Example 100 RANDOM 1 + tempVar1 =
100 RANDOM 1 + tempVar2 =
{
tempVar1 ITOA "is less than or equal to " & tempVar2 ITOA & SAY
} {
tempVar1 ITOA "is greater than " & tempVar2 ITOA & SAY
} tempVar1 tempVar2