PalaceChat Iptscrae Extensions

From PalaceChat
Jump to navigationJump to search

This page documents new Iptscrae commands that are supported by PalaceChat and OpenPalace.

New Events[edit]

There are a few new hotspot events supported in PalaceChat and OpenPalace. Be warned, however, that if you use these events in your script, users of the antiquated "The Palace" (Palace32) client will be presented with an Iptscrae Error for those event handlers in the log.

ON IDLE[edit]

IMPORTANT: This event is not yet implemented in OpenPalace.

This event will be fired when the user is idle for 10 minutes.

ON MOUSEDRAG[edit]

This event will fire continuously as the user clicks and drags on a hotspot.

ON MOUSEDOWN[edit]

This is the exact same as the ON SELECT event.

ON MOUSEMOVE[edit]

This event will be fired continuously as the user moves the mouse cursor over the hotspot's area.

ON MOUSEUP[edit]

This event will fire when a user clicks a hotspot after releasing there mouse button.

ON ROLLOVER[edit]

This event will be fired when the user's mouse cursor enters the hotspot's area.

Example:

ON ROLLOVER {
    1 ME SETSPOTSTATELOCAL ; Make button glow
}

ON ROLLOUT[edit]

This event will be fired when the user's mouse cursor leaves the hotspot's area.

Example:

ON ROLLOUT {
    0 ME SETSPOTSTATELOCAL ; Make button return to normal
}

ON ROOMREADY[edit]

IMPORTANT: This event is not yet implemented in OpenPalace or PalaceChat.

This event will be fired once all the images for the current room have been downloaded and processed. Any usage of the new ROOMWIDTH and ROOMHEIGHT commands should be in this event handler, as the actual room size is unknown until the background image has been processed.

Example:

ON ROOMREADY {
    "The room graphics have finished downloading." LOGMSG
    "This room is sized: " 
        ROOMWIDTH ITOA & "x" &
        ROOMHEIGHT ITOA & "." & LOGMSG
}

ON STATECHANGE[edit]

IMPORTANT: This event is not yet implemented in OpenPalace.

This event will fire when a doors state is changed.

Example:

ON STATECHANGE {
	ME GETSPOTSTATE newState =
	"New state is: " newState ITOA & LOGMSG
	"Previous state was: " LASTSTATE ITOA & LOGMSG
}

ON USERENTER[edit]

IMPORTANT: This event is not yet implemented in OpenPalace.

This event will fire when any user enters the room. Variable WHOENTER contains the ID of the user who has entered.

Example:

ON USERENTER {
	"Hello " WHOENTER WHONAME & SAY
}

ON USERMOVE[edit]

IMPORTANT: This event is not yet implemented in OpenPalace.

This event will fire when any user moves. Variable WHOMOVE contains the ID of the user who has moved.

Example:

ON USERMOVE {
	WHOMOVE WHOPOS y = x =
	x ITOA " " & y ITOA & LOGMSG
}

New Commands[edit]

General Utility[edit]

IPTVERSION[edit]

This command now returns 2 for both PalaceChat and OpenPalace.

Example:

{ "I'm using the latest version of iptscrae!" SAY } IPTVERSION 2 == IF

OPENPALACE[edit]

Pushes a 1 onto the stack if the user is using OpenPalace. On non-OpenPalace clients, it will be interpreted as an uninitialized variable, and will evaluate to 0 (zero.) You can use this function to detect OpenPalace and provide customized scripting for OpenPalace users.

Example:

{ "I'm using OpenPalace!" SAY }
{ "I'm not using OpenPalace!  :-(" SAY }
OPENPALACE IFELSE


PALACECHAT[edit]

Pushes a 1 onto the stack if the user is using PalaceChat. On non-PalaceChat clients, it will be interpreted as an uninitialized variable, and will evaluate to 0 (zero.) You can use this function to detect PalaceChat and provide customized scripting for PalaceChat users.

Example:

{ "I'm using PalaceChat!" SAY }
{ "I'm not using PalaceChat!  :-(" SAY }
PALACECHAT IFELSE


Room and Hotspot Commands[edit]

GETPICDIMENSIONS[edit]

Pushes the width and height of the picture associated with the specified state of the specified hotspot.

  • Parameters:
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door.
    • SpotID: The ID of the hotspot that the picture is in.

Example:

;this example gets the width and height of the current picture in
;the current door.
-1 ME GETPICDIMENSIONS height = width =

GETPICLOC[edit]

Pushes the x and y cordinates of the picture associated with the specified state of the specified hotspot. The values are relative to the hotspots x and y cordinates.

  • Parameters:
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door.
    • SpotID: The ID of the hotspot that the picture is in.

Example:

;this example gets the x and y of the current picture in the
;current door.
-1 ME GETPICLOC y = x =

GETSPOTLOC[edit]

Pushes the x and y cordinates of the specified hotspot.

  • Parameters:
    • SpotID: The ID of the hotspot that the picture is in.

Example:

;this example gets the x and y of the current hotspot.
ME GETSPOTLOC y = x =

HIDEAVATARS[edit]

Hides all avatars in the room. This could be useful for certain kinds of games. It only applies locally, for the user executing the script.

Example:

ON ENTER {
    HIDEAVATARS
}


ROOMWIDTH[edit]

Pushes the width of the room's background image onto the stack. If the background image has not yet been loaded, it will push 512, the default room width, onto the stack.

Example:

;move the user to a random x position in the room.
ROOMWIDTH RANDOM POSY SETPOS


ROOMHEIGHT[edit]

Pushes the height of the room's background image onto the stack. If the background image has not yet been loaded, it will push 384, the default room height, onto the stack.

Example:

;move the user to a random y position in the room.
POSX ROOMHEIGHT RANDOM SETPOS


SETLOCLOCAL[edit]

Changes the location of the specified hotspot.

This command functions the same as SETLOC, except without changing the hotspot's location in the room definition on the server.

  • Parameters:
    • X: The position for the picture on the x axis relative to the hotspot's location.
    • Y: The position for the picture on the y axis relative to the hotspot's location.
    • SpotID: The ID of the spot you wish to modify.

Example:

20 40 ME SETLOCLOCAL

SETPICLOCLOCAL[edit]

Changes the location of the picture associated with the specified state of the specified hotspot. The coordinates are relative to the location of the hotspot.


  • Parameters:
    • X: The position for the picture on the x axis relative to the hotspot's location.
    • Y: The position for the picture on the y axis relative to the hotspot's location.
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door. (this parameter is only available with IPTSCRAE version 2 and higher)
    • SpotID: The ID of the spot you wish to modify.

Example:

;good practice to check IPTVERSION for the state parameter.
20 40 {-1} IPTVERSION 1 > IF ME SETPICLOCLOCAL

SETPICBRIGHTNESS[edit]

IMPORTANT: This command is not yet implemented in OpenPalace. It will interpret the command and read the parameters off the stack, which means your scripts will not break, but the command doesn't actually do anything.

Changes the brightness of the picture associated with the specified state of the specified hotspot.


  • Parameters:
    • Brightness: The pictures brightness. Valid values range from -100 to 100. Default is 0
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door.
    • SpotID: The ID of the spot you wish to modify.

Example:

;sets the current state picture to be brighter than normal.
50 -1 ME SETPICBRIGHTNESS

SETPICOPACITY[edit]

Changes the opacity of the picture associated with the specified state of the specified hotspot.


  • Parameters:
    • Opacity: The pictures opacity. Valid values range from 0 to 100. Default is 100
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door.
    • SpotID: The ID of the spot you wish to modify.

Example:

;sets the current state picture to half opacity.
50 -1 ME SETPICOPACITY

SETPICSATURATION[edit]

IMPORTANT: This command is not yet implemented in OpenPalace. It will interpret the command and read the parameters off the stack, which means your scripts will not break, but the command doesn't actually do anything.

Changes the color saturation of the picture associated with the specified state of the specified hotspot.


  • Parameters:
    • Saturation: The pictures color saturation. Valid values range from -10000 to 10000. Default is 100
    • state: The spot state that the picture is associated with, negative value will default it to the current state of the door.
    • SpotID: The ID of the spot you wish to modify.

Example:

;sets the current state picture to greyscale.
0 -1 ME SETPICSATURATION

SETSPOTNAMELOCAL[edit]

Locally changes the name of the specified hotspot. Only updates for the user who is running the script. You might use this to display the current score in a game. You can hide a spot name by setting it to the empty string ("")

Example:

SCORE GLOBAL
15 SPOTID =
"Your score is: " SCORE ITOA & SPOTID SETSPOTNAMELOCAL


SHOWAVATARS[edit]

Makes all avatars in the room visible again after a HIDEAVATARS command has hidden them.

Example:

ON SELECT {
    SHOWAVATARS
}


Prop Commands[edit]

LOADPROPS[edit]

Allows you to pre-load props in the background. This is probably most useful for game developers. This is especially important on OpenPalace, because with a web-based client, there is no way to keep props cached from one session to the next, so they must be loaded from the server every time.

Important: You may only load up to 500 props at a time with this command. Attempting to load more will cause an Iptscrae error.

Example:

[ 48329285 394829 -195839523 ] LOADPROPS

LOOSEPROP[edit]

Pushes the prop id of the loose prop by index.

Example:

;this example causes you to wear the last dropped loose prop.
0 LOOSEPROP propId =
propId DONPROP


LOOSEPROPIDX[edit]

Pushes the index of the loose prop by prop id onto the stack. If there are two or more loose props with the same id the index of the first one is pushed.

Example:

;this example asumes a prop with the id of 60035 is already a loose prop.
60035 LOOSEPROPIDX index =
index REMOVELOOSEPROP


LOOSEPROPPOS[edit]

Pushes the x and y cordinates of a loose prop by index onto the stack.

Example:

;this example logs the cordinates of the last dropped loose prop.
0 LOOSEPROPPOS y = x =
x ITOA " " & y ITOA & LOGMSG


MOVELOOSEPROP[edit]

Sets the location of a looseprop by index. The looseprop will not update its position until the server responds to the query.

  • Parameters:
    • X: The position for the loose prop on the x axis.
    • Y: The position for the loose prop on the y axis.
    • Index: The index of the looseprop within the room.

Example:

;move the last dropped looseprop to your mouse position.
MOUSEPOS 0 MOVELOOSEPROP


NBRLOOSEPROPS[edit]

Pushes the number of loose props onto the stack.

Example:

;this example logs the prop id's of all the loose props in the room.
{ i LOOSEPROP ITOA LOGMSG i++ }{ i NBRLOOSEPROPS <} WHILE


PROPDIMENSIONS[edit]

Pushes the width and height of a prop onto the stack.

Example:

;this example logs the width and height of a prop.
60035 PROPDIMENSIONS height = width =
width ITOA "x" & height ITOA & LOGMSG


PROPOFFSETS[edit]

Pushes the x and y offset of a prop relative to how it would appear on a user onto the stack.

Example:

;this example places a loose prop at your mouse position based on
;how it would appear on a user.
60035 PROPOFFSETS offy = offx =
MOUSEPOS y = x =
60035 x offx + y offy + ADDLOOSEPROP

REMOVELOOSEPROP[edit]

Removes of a looseprop by index. The looseprop will not be removed until the server responds to the query.

Example:

;remove the last dropped looseprop.
0 REMOVELOOSEPROP

Drawing Commands[edit]

OVAL[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Draws a oval with the current pen and penfill settings.

  • Parameters:
    • X: The position for the oval on the x axis relative to the center of the oval.
    • Y: The position for the oval on the y axis relative to the center of the oval.
    • Width: The width of the oval
    • Height: The height of the oval.

Example:

;this example draws a large green oval across the room with
;50% opacity with a red border.
127 PENFILLOPACITY
0 255 0 PENFILLCOLOR
255 0 0 PENCOLOR
3 PENSIZE
ROOMWIDTH w = ROOMHEIGHT h =
w 2 / x =
h 2 / y =
x y w h OVAL

PENOPACITY[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Sets the Opacity for drawn lines. Valid values range from 0 to 255. Be sure to set PENOPACITY back to 255 at the end of any script that uses it.

  • Parameters:
    • Opacity: The line opacity for lines, polygons and ovals.

Example:

;this example draws a line across the room with half opacity in the
;color red.
127 PENOPACITY 255 0 0 PENCOLOR 9 PENSIZE
0 0 ROOMWIDTH ROOMHEIGHT LINE
255 PENOPACITY
;be sure to reset the opacity to full after

PENFILLCOLOR[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Sets the fill color for polygons and ovals. The parameters are identical to that of the function PENCOLOR. (red green blue)

Example:

;this example draws a large green oval across the room with 50% opacity
;with a red border.
127 PENFILLOPACITY
0 255 0 PENFILLCOLOR
255 0 0 PENCOLOR
3 PENSIZE
ROOMWIDTH w = ROOMHEIGHT h =
w 2 / x =
h 2 / y =
x y w h OVAL

PENFILLOPACITY[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Sets the fill Opacity for polygons and ovals. Valid values range from 0 to 255. Setting PENFILLOPACITY to zero will turn fills off completely. The default value is zero.

  • Parameters:
    • Opacity: The fill opacity for polygons and ovals.

Example:

;this example draws a large green oval across the room with 50% opacity
;with a red border.
127 PENFILLOPACITY
0 255 0 PENFILLCOLOR
255 0 0 PENCOLOR
3 PENSIZE
ROOMWIDTH w = ROOMHEIGHT h =
w 2 / x =
h 2 / y =
x y w h OVAL

POLYGON[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Draws a filled polygon if PENFILLOPACITY is not set to zero. Draws an array of lines if PENFILLOPACITY is zero.

  • Parameters:
    • Number Array: An array of x's and y's.

Example:

;draws a random color over the entire room with a semi translucent opacity.
0 PENOPACITY
PENFRONT
255 RANDOM 255 RANDOM 255 RANDOM PENCOLOR
180 PENFILLOPACITY
ROOMWIDTH x = ROOMHEIGHT y =
[0 0 0 y x y x 0] POLYGON


DRAWTEXT[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Draws text at the x and y provided in the current penfont, pencolor and penopacity.

  • Parameters:
    • X: The position for the text on the x axis.
    • Y: The position for the text on the y axis.
    • Text: The string of text to be drawn.

Example:

;draws red text in the top left corner of the room.
"Arial" PENFONT
PENFRONT
255 0 0 PENCOLOR
255 PENOPACITY
"This is a test" 0 0 DRAWTEXT


PENFONT[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Sets the font to be used in DRAWTEXT.

  • Parameters:
    • fontName: The exact name of the font to be used in quotes.

Example:

;draws red text in the top left corner of the room.
"Arial" PENFONT
PENFRONT
255 0 0 PENCOLOR
255 PENOPACITY
18 PENSIZE
"This is a test" 0 0 DRAWTEXT


PENBOLD[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Turns bold on or off for DRAWTEXT.

  • Parameters:
    • number: 0 turns bold off, 1 turns bold on.

Example:

;draws bold red text in the top left corner of the room.
1 PENBOLD
"Arial" PENFONT
PENFRONT
255 0 0 PENCOLOR
255 PENOPACITY
18 PENSIZE
"This is a test" 0 0 DRAWTEXT


PENUNDERLINE[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Turns underline on or off for DRAWTEXT.

  • Parameters:
    • number: 0 turns underline off, 1 turns underline on.

Example:

;draws bold red text in the top left corner of the room.
1 PENUNDERLINE
"Arial" PENFONT
PENFRONT
255 0 0 PENCOLOR
255 PENOPACITY
18 PENSIZE
"This is a test" 0 0 DRAWTEXT


PENITALIC[edit]

IMPORTANT: This command is not yet implemented in OpenPalace.

Turns penitalic on or off for DRAWTEXT.

  • Parameters:
    • number: 0 turns penitalic off, 1 turns penitalic on.

Example:

;draws bold red text in the top left corner of the room.
1 PENITALIC
"Arial" PENFONT
PENFRONT
255 0 0 PENCOLOR
255 PENOPACITY
18 PENSIZE
"This is a test" 0 0 DRAWTEXT