Working With Your Palace Cyborg File

This tip sheet is meant to help you edit and maintain your Palace Cyborg. It does not discuss details for using the Palace programming language, Iptscrae. Nor does it provide details on the basics of manipulating and editing files on your computer.

 

What's a Cyborg?
Make a Backup
Replacing a Cyborg
Editing a Cyborg
Cyborg Anatomy
Cyborg Scripts
Comments and Globals
Cyborg Format Style

 

What's a Cyborg?

A Palace Cyborg is your private collection of scripts that perform various actions to automate your Palace avatar. The scripts are stored in the file named Cyborg.ipt in your Palace Client folder.
If you are using Windows and have the option to "Hide file extensions for known file types" turned on in your Folder View Options, well you should turn that off right now. If you hadn't noticed the ".ipt" on your Cyborg file, you will now, along with the real file names for many other file types.
These scripts are like miniature programs that respond to certain actions or words and phrases that you say or hear. The programs can perform tasks such as painting pictures, generate speech, wear or remove props, and any number of things that people dream up. As important as all those things are, Cyborg scripts are also useful to help automate many of the things that palace Wizards and Operators find themselves doing quite often.

For more detailed information about Iptscrae and the Cyborg file please read the Palace WEB site pages for these topics:

Automating Yourself with Iptscrae
Iptscrae Language Guide

- Back to Top -

 

Make a Backup Copy:

Before you edit or replace your Cyborg.ipt file you should always make a backup copy first. You may already have your own preferred methods for making copies of files to save. If not, the quickest way to to this is to first find the cyborg.ipt file in your Palace folder and select it by clicking on its icon just once. It should now be highlighted. Then ...

For Windows:

Type Control-C followed by Control-V. (for Copy and Paste)
For Macintosh:
Type Command-D. (for Duplicate)
The copy file will be named "Copy of Cyborg.ipt" on Windows or "Cyborg.ipt Copy" on Macintosh. That will serve as your backup in case something goes wrong when you edit the original file or new cyborg.ipt you install doesn't work.

If you need to revert to the backup file you can throw away the current cyborg.ipt file and rename the copy to "cyborg.ipt".

By the way, this is also a quick and simple way to keep your props safe. Every once in a while make a backup copy of your prop file, Palace.prp. If your working prop file should get corrupted (not an uncommon occurrence) you'll have a backup to restore from and you'll only have lost the most recent props you collected.

If your cyborg.ipt file gets completely messed up or you just want to start over, you can get a new, default copy here for Macintosh and Windows.

- Back to Top -

 

Replacing Your Cyborg with a New Cyborg File:

A very common way to get new scripts is to simply replace your cyborg.ipt file with one that a friend sends you or with a fresh copy downloaded from the Palace WEB site.

We are assuming that you know how to move or copy files on your computer using the "Windows Explorer" for Windows or the "Finder" for Macintosh. As you must know, there is more than one way to accomplish this task. There are a few important things to keep in mind when replacing your cyborg.ipt file.

  1. Make a backup copy of your current file first, as mentioned in the previous section of this page.

  2. Check the file name of the new cyborg file. For it to be used by the Palace client program, it must be named cyborg.ipt or Cyborg.ipt.

  3. You may replace the file while the Palace client is running but if you do, you have to use the Reload Script command found in the client's File menu to have the new scripts become active.
- Back to Top -

 

Editing Your Cyborg File:

Editing your cyborg.ipt file allows you to customize you scripts, add new scripts to the ones you already have and delete some that you no longer use.

The most important thing to do when editing your cyborg.ipt file is to (you guessed it) make a backup copy first.

Equally important is that you use an editing program that can save the file as a plain text file. Most people's cyborg.ipt files are small enough to be handled by Notepad on Windows or Simple Text on Macintosh. While these editors lack some of the fancy features found in more complicated text editing programs, they are certainly adequate for editing cyborg.ipt files.

If you must use another text editor, make sure that when you save the file, it is saved in a plain text (or text only) format. Many text processing programs, if not told otherwise, will save files in their own special format which includes data that the Palace program will not be able read and may render your cyborg.ipt file useless.

It helps to know your way around the cyborg.ipt file. We'll discuss some fundamental concepts and show a few examples to to help you get started.

- Back to Top -

 

Anatomy of the Cyborg File:

The cyborg.ipt file is made up a different sections that correspond to the different types of event handlers. Within in each section are the scripts that are triggered for each type of event. The event handlers commonly used in cyborg.ipt files are briefly described below.

Each section begins with the event handler type and an opening left curly-brace and ends with a closing right curly-brace, as shown in the descriptions.

ON SIGNON  {
 }

This section contains scripts that are triggered when you first sign on (or connect) to a palace.

ON OUTCHAT  {
 }

This section contains scripts that are triggered when you say something.

ON INCHAT  {
 }

This section contains scripts that are triggered when you hear something said. Note that these will be triggered both when you hear what someone else says and when you hear what you say.

ON ALARM  {
 }

This section contains scripts that are triggered by a timer mechanism. These are usually used to perform delayed or repetitive actions.

 

The Iptscrae scripts are placed between the opening and closing curly braces of the appropriate event section. For example, a script that is to run when you sign on to a palace must appear in the ON SIGNON section:
             ON SIGNON  {
	         "@64,64 !It's " USERNAME & SAY
	         1 MACRO
              }
         
Scripts that are to be activated when you say something must appear in the OUTCHAT section:
             ON OUTCHAT  {
                 ; clean the room by saying "clean"
	         {
                    CLEARLOOSEPROPS
                    PAINTCLEAR
                    "" CHATSTR =
	         } CHATSTR "clean" == IF
              }
         
Notice in the second example that scripts, themselves may include curly braces. Curly braces will always be present in pairs. That is, for every left brace there will be a matching right brace.

Important:   All of your scripts must reside within an event handler. Any scripts not within the curly brace pair of an event handler will never be triggered.

Also Important:   There may be only one section for each type of event handler. If you have two sections for the same event, only the scripts in the second one will be used.

- Back to Top -

 

Basic Format of Scripts:

When you add a script to your cyborg, first determine what event handler section it belongs in. Most script you get will include this information. It is best to add scripts either at the beginning or end of the event handler section to avoid accidentally inserting the new script in the middle of the code for an existing script. However, you may want to organize your scripts by type. These basic concepts may help you in determining the beginning and end of the individual scripts in your cyborg.

The scripts within each event handler section of the cyborg.ipt file are made up of one or more lines of iptscrae, the programming language used to write scripts for the Palace. This language uses what is called Reverse Polish Notation which means that scripts appear in a sort of backwards manner. for example, to add 1 to A and save the result in B, instead of writing B = A + 1, you would write A 1 + B =

Most of the scripts you will come across are written to go in the OUTCHAT section - scripts that do something based on what you say. These will also work if put in the INCHAT section because you usually hear what you say. However, those scripts will also be triggered by what others say. You usually do not want that to happen.

Many scripts are made up of a grouping of Iptscrae commands, called an Atom List, which are surrounded by a pair of left and right curly braces. Almost always, OUTCHAT (and INCHAT scripts for that matter) are designed to work only if you say a particular word or phrase. So part of the script includes a test what was said which will appear after the commands that perform the script's actions.

A simple example is the "clean" script, shown again below.

             ; clean the room by saying "clean"
	     {
                CLEARLOOSEPROPS
                PAINTCLEAR
                "" CHATSTR =
	      } CHATSTR "clean" == IF
         
The Atom List for this script is the list of commands to clear any loose props, erase any paint in the room and replace what was said with an empty string of characters. The Atom List is followed by a test to see if what was said CHATSTR, is the word, clean. If this is true then the commands in the Atom List will be executed. Otherwise they will not.

This is basic form of most OUTCHAT scripts; an Atom List of commands followed by a test of CHATSTR to see if it matches the keyword for the script.

The test of CHATSTR will either be done using the == IF method, the GREPSTR IF method, or the SUBSTR IF method.

Some scripts may have two or more parts - one for the OUTCHAT section and one for INCHAT or ALARM. Usually scripts you receive will come with instructions telling you which parts go in which sections.

- Back to Top -

 

Script Comments and Global Variables:

Comments are sections or lines in the file that are not executed as commands but are simply there as a explanation or comment to someone reading the file. Except when appearing inside a quoted string, any text following a semicolon is a comment. Some examples:
              ; this is a comment on a line by itself
              PAINTCLEAR ; this is a comment following an actual command
              "; this is an Iptscrae text string, not a comment"
         
Conscientious script writers will include comments to explain how to install and use the script and many include a comment identifying the author of the script. Some script writers also use comments to disable parts of the script they may have originally used for testing. The "clean" script example above includes a short comment describing what the script does. When you copy scripts into or from your cyborg.ipt file you should always include the comments.

Global variables are used to store information or settings that needs to be used the next time the script is executed or by another script. Global variables are specified in scripts using the word GLOBAL; this is called a declaration. They often appear along with the scripts that use them or the scripts will include a comment explaining what global variables are required.

Below is a somewhat simple example using global variables. It consists of a pair of scripts, one to store your current location and one to return to that location later. The marked location is stored in two global variables, one for the X position and one for the Y position.

             ON OUTCHAT  {

                   markx GLOBAL
                   marky GLOBAL

                   ; remember current location by saying "mark"
	           {
                      WHOCHAT WHOPOS marky = markx =
                      "" CHATSTR =
	           } CHATSTR "mark" == IF

                   ; return to marked location saying "return"
	           {
                      markx marky SETPOS
                      "" CHATSTR =
	           } CHATSTR "return" == IF
              }
         
Note that the declaration of global variables must be inside the event handler section in which they are used. In the case where globals are used by scripts in different event handlers, their declarations must appear inside both event handler sections.
- Back to Top -

 

Cyborg Format and Style:

Iptscrae, as with most program languages, has a syntax that does not rely on any particular style or file format. As long as the keywords, variable names, operators and curly braces are in the proper order, the computer will be able to deal with it.

However, it is much easier for a person to decipher what a program or script does if the code is written neatly and in a format that suggests the flow of the script. Readability and visual organization are important for making it easier to find where things are in the cyborg.ipt file. With this in mind, we suggest a few guidelines to keep in mind as you edit your cyborg.ipt file.

Indentation:

Consider placing the event handler keywords and their curly braces at the beginning of the line and indenting all the scripts by 3 or four spaces. Then indent the commands within Atom Lists another 3 or 4 spaces. The examples presented on this page follow this rule of thumb.

If you maintain decent indentation rules it will be much easier to find the beginning and end of each event handler section and the beginning and end of each script within the event handlers. Otherwise you will have to look much more carefully to find the matching curly braces that mark the beginning and end of scripts and even handler sections.

You will likely encounter scripts that have no formatting at all or with every line starting at the beginning of the line. Consider indenting these scripts when you add them into your cyborg so you maintain a consistent formatting style.

Comments:

Comments, as mentioned earlier, provide a way of describing what a script does or how it is used. They also provide a good formatting tool. If you include a comment at the beginning of every script you leave yourself a marker making it easier to find each script later on.

When you add a script to your cyborg.ipt file, be sure to include any comments that came with it. If it had none, add a comment of your own.

Another great use of comments is to mark the end of each event handler section to make it easy to find. For example:

             ON OUTCHAT  {
                   ; clean the room by saying "clean"
	           {
                       CLEARLOOSEPROPS
                       PAINTCLEAR
                       "" CHATSTR =
	           } CHATSTR "clean" == IF

                   ; place a named prop at mouse coordinates
                   ; type @here propname
                   {
                       "$1" GREPSUB propstr =
                       MOUSEPOS y = x =
                       propstr x y ADDLOOSEPROP
                       "" CHATSTR =
                   } CHATSTR "@here (.*)$" GREPSTR IF

               } ; endof OUTCHAT

              ON SIGNON  {

                   ; "@40,40 !It's " USERNAME & SAY
                   1 MACRO
                   {
                        9 SETCOLOR
                        5 SETFACE
                   } 40 ALARMEXEC

               } ; end of SIGNON
         
Notice yet another use of comments in the example. I got tired of having my SIGNON script anounce my name so I disabled it by puting a semicolon in front of that command to turn it into a comment. All I need to do is delete the semicolon if I decide to use it again.
- Back to Top -

 

 

 

Copyright © 2000-2006 Studio Dust
Comments or questions to:
Studio Dust Webmaster