As previously stated, all options and definitions happen in the ".menus" notecard (which was named ".config" in earlier versions of the WearPose System). Please pay attention to the lowercase name: ".MENUS" will NOT work ! The leading dot in notecard names is there so that they appear near the top of the inventory. Do NOT manually edit the ".positions" notecard as it is encoded. Always use the WPS-Preparation script to generate it.

The .menus notecard uses keywords (freely inspired by those used by avSitter) followed by their value. The descriptions of these keywords follow.

First, a word of general warning: while keywords are case-insensitive (both POSE or pose will be understood), names and values ARE case-sensitive. For example "MENU menu1" and "MENU Menu1" will create two distinct menus. Note the lowercase or uppercase M to understand the difference. The same goes for spaces, don't let spurious spaces (at the beginning or end of a name) ruin your notecard!

Readability is a legitimate concern; you are encouraged to add comments to improve the readability of your configuration notecard. To add a comment line, just let this line begin with // (two slashes). It will then be completely ignored by the scripts.

When you update the ".menus" notecard while in the preparation phase (or more precisely as soon as an inventory change is detected), the WPS-Preparation script will reset automatically. However, when in the production phase the WPS-MainScript will need to be manually reset in order to reload the (modified) configuration notecard. You can do so by dropping the WPS-ResetMain script into your attachment's contents to do so (it will automatically remove itself after sending the reset message).

Button creation

The following directives all create a button of a certain type. All buttons thus created are then attached to the current menu, as set by a previous MENU directive, or to the main menu if no previous MENU was encountered.

POSE name|file

This declares "name" as a button to play the animation file "file". Note that the "name" button must be unique in the configuration (the WPS-Preparation will complain if it is not). If you want the same pose to be available at other places (in other menus for example) then you must use the RECALL keyword, described below.

Note however that the animation "file" may be used in another POSE declaration, as long as it is used with a different "name". This allows for example for the same animation to be played with different positional information.

The button created with POSE will be attached to the current menu as defined by the MENU keyword (see below) or the "Main menu" if no previous menu was declared before.

TOMENU name

This keyword creates a button attached to the current menu that will lead to another menu identified by "name". Clicking this button will open this new menu and enable access to its own buttons.

The same TOMENU may appear several times in the configuration.

As part of the verification process, the WPS-Preparation script will make sure that every TOMENU button matches an existing MENU.

BUTTON name|number|string|key

This declaration will define a "custom" button used to interface with other scripts in the object, to allow for different actions not caused by the WPS system.

Technically, clicking this kind of button will cause a link_message to be sent across the whole object (LINK_SET) with the "number", "string" and "key" parameters. What happens then wholly depends on the scripts that receive and interpret this message.

RECALL name

This clause will enable a previously defined button (be it a POSE, TOMENU or BUTTON definition) to appear once again in the current menu. There "name" must be the exact name of a previous POSE, TOMENU or BUTTON declaration.

Predefined buttons

3 predefined buttons exist as of version 3.0 that need not (and must not) be redefined. They can be used in the context of a RECALL, NAV or NAVMAIN directive and serve as default values mainly for the NAV and NAVMAIN directives.

• "Main menu": this button of type TOMENU is used as the default value for the NAV directive, to create a back link to the main menu in every other menu.
  Note that if the Main menu is renamed (see below the description of the MENU directive) then this button is renamed accordingly.

• "About...": this special button causes the opening of an informative window about the Wearpose System itself, containing a web link to this site. This button is the default value for the NAVMAIN directive.

• "Close menu": as the name implies, this button closes the menu. Doing so by this button (instead of "ignore") prevents the time out to happen (and thus no time out message). This Close menu button is not used unless you explicitly include it with a RECALL, NAV or NAVMAIN directive.
  The "Close menu" button itself can be renamed thanks to the CLOSEMENU directive, described below.

Structure

The structure of the menu system is an arrangement of MENU and TOMENU (see above) directives that will create a path for the end users to reach different parts of the menu system. Just try to be logical!

MENU name
MENU name|specific prompt

The MENU directive creates a new menu with the name "name" (which must be unique among all buttons in the configuration). All subsequent lines creating a button (using POSE, TOMENU, BUTTON, RECALL) will attach it to this new menu.

Note however that this new menu will be unreachable unless a path has been configured by TOMENU buttons from the Main menu. You can use this feature to "hide" buttons in menus so that they don't normally appear but can be referenced by a RECALL, NAV or NAVMAIN clause.

The second syntax, new as of version 3.0, enables you to set a specific prompt for this menu, that is the text that goes above the buttons in the menu window. If you use the first syntax (without a vertical bar), then the prompt will be the default one, as set by the TEXT directive.

Also note that a \n in the prompt text (backslash n) automatically gets replaced by a newline.

Declaring the Main menu with a MENU directive is optional. Doing so, however, enables you to rename it and maybe set a specific prompt. If you choose to do so, then the corresponding MENU declaration must happen before any other MENU and before any other button-creation directive (like TOMENU, POSE, BUTTON or RECALL). This feature is new as of version 3.0 (previously this would count as an error).

Settings

The following directives enable to define some settings for the WearPose System. Normally they will appear only once in the notecard, and it probably makes more sense to group them at the start (but this is only a convention).

TEXT text

This command will set the default text that appears on each dialog, below the menu name. The default is an empty string. Again, any \n is replaced by a newline.

Note that this default text can, as of version 3.0 of the WearPose System, be overridden on a per-menu basis thanks to an extra argument in the MENU directive itself, as described above.

MTYPE code

This command sets an option affecting the behavior of the menus. Possible values are 0, 1, 2, and 3 as described below:

• 0: this is the default value. It causes the menu to open as soon as the object is attached. The menu can be reactivated by touching the object.

• 1: the menu only opens when the object is touched (by its owner).

• 2: same as 1 but the menu immediately reopens after a pose is selected. The user will have use an explicit "Close menu" button (as described above) or to "ignore" the menu to make it disappear.

• 3: the menu does not normally appear at all. The only way to make it appear is by sending a link_message with number==100005 from another script, as described in the API section of this manual.

PREV label

A replacement for the "previous" pagination button. The default is "<< Prev".

NEXT label

A replacement for the "next" pagination button. The default is "Next >>".

ADJUST label

A replacement for the "adjust" button. The default is ">Adjust<".

CLOSEMENU label

A replacement for the "Close menu" predefined button. If you use this directive, make sure you use the exact same name for any RECALL, NAV or NAVMAIN directive referring to this button. For this reason the CLOSEMENU directive should happen before any such directive referring the Close menu predefined button.

Again it's best to group the settings-type directives near the beginning of the notecard.

NAVMAIN buttonid
NAV buttonid

The three bottom buttons in each menu are "special". The bottom left button is either the "previous" button or the "adjust" button. The rightmost button is either the "next" button or a placeholder. The button sitting between them is blandly called the "nav" button. You can define two nav buttons: one for the "Main menu" and another (possibly the same) for all other menus. The NAVMAIN option deals with the nav button on the main menu and the NAV option deals with nav buttons on all the other menus.

To do this, the button you want to appear must have been previously defined, as this option will work like the RECALL command. Therefore the nav button can be a POSE, a TOMENU or a BUTTON-type button, or one of the predefined buttons mentioned above.

If you want a nav button that does not appear anywhere else, you can just set up a hidden MENU that is not the destination of a TOMENU button. Here is an example:

// definitions for the Main menu

POSE pose1|animation1

POSE pose2|animation2

TOMENU OtherMenu

MENU Hidden

POSE NavPose|animation3

TOMENU Main|Main menu

NAVMAIN NavPose

NAV Main

MENU OtherMenu

POSE Complicated|complicated-animation

In this example, the "NavPose" and "Main" buttons are defined with POSE and TOMENU commands respectively and attached to the "Hidden" menu. Since there is no TOMENU clause in other menus that can cause this "Hidden" menu to appear, it will actually be hidden. But since the buttons attached to it are declared with NAVMAIN and NAV, those buttons will be used as nav buttons, as explained above. On the main menu, the nav button will cause the "animation3" to be played, while on the "OtherMenu" the nav button will bring you back to the Main menu.

The default value for the NAVMAIN option is the  "About..." predefined button to be created on the Main menu. This button opens an informative window about the WearPose System. A sound replacement would of course be the "Close menu" predefined buttons if you do not want any explicit mention of the WPS on your product.

The default value for the NAV option is the "Main menu" predefined button, which is a link back to the Main menu.

TIMEOUT seconds

This directive, new as of version 3.0, enables you to specify the number of seconds after which the menu expires (as an anti-lag measure). The default of 30 seconds is the same as in earlier versions but a lot of people have asked to increase this value. This is now possible.

You can also completely disable this timeout by specifying a value of 0 (meaning the menu never expires), but this is not recommended.

TIMEOUTMSG message

This directive sets the message said to owner when the menu expires. The default is "Menu timeout, click to reactivate.". In the message once again, all \n are converted to newlines.

You can completely disable this message by using no value at all: just say TIMEOUTMSG all alone on its line.