Interfacing with AVSitter (or similar)

Background information and Compatibility

AVSitter is a famous system with manages animations and poses for avatars sitting on an object. If used together with MvtPlayer, it can easily create nice effects like a buoy that smoothly moves as it floats when an avatar is using it, or a rocking chair, or a touring train... AVSitter's configuration is entirely managed by one (or several) notecard named AVPos (please refer to their website for information about this).

It is important to notice that you have to instruct AVSitter that keyframed motion (smooth movement) will be used by putting the following directive

KFM 1

at the top of all your AVPos notecards.

Indeed, for some reason (probably related to adjustment), AVSitter needs to "move" the current object (even if it's not moving at all, AVSitter uses a direct positioning function) and this interferes with the keyframed motion (smooth movement) performed by MvtPlayer. The "KFM 1" directive mentioned above is used to circumvent this problem (you can read about this here on their support site and also here).

Then, whenever AVSitter needs to position the object, it will first "pause" any playing keyframed motion first, and resume it afterwards. Unfortunately, this may in turn interact with the "pause" mode of MvtPlayer since AVSitter will "unpause" it as a side effect, and there is nothing we can do in the current implementation of the KeyFramed Motion system in SL.

Finally, special care was taken as of v2.2 so that MvtPlayer "tolerates" external pause commands and does not misinterpret the resulting events. More informaiton about this on this page.

Direct interface

The easiest way to achieve control of MvtPlayer from AVSitter is to use a BUTTON directive in AVSitter's configuration (the AVPos notecard). Detailed information about this directive is of course available on the AVSitter website ; we are just covering a few examples here.

The main advantage of this method is that it requires no additional script. The drawback is that you have no fine control over, for example, who is allowed to use a particular button, menu reopening, sequence of actions etc.. Note that the information below can very well be used in another system than AVSitter, as long as it is able to send configurable link_message's. Feel free to contact me if you need precise directions for another system.

The general syntax of the BUTTON directive in AVSitter is :

BUTTON <menu_name>|<custom_integer>|<custom_string>|<custom_key>

This creates a button in the current AVSitter menu that, when clicked, sends a message to whatever script is able to understand it. We use this message to have the MVTPlayer perform an action (typically starting and stopping a sequence). More details about such messages are given in the Scripting reference section of this website.

• The menu_name (first part) really is the text that will label your button. Use whatever you like but beware that SL menu buttons have limited length, of course.

• The custom_integer (second part) is a number identifying the command you are sending to MvtPlayer. Typically this will be 200010 (play the sequence), 200011 (stop the sequence), 200019 (pause the sequence), 200020 (resume the sequence after a pause) or maybe 200014 (a command that will satisfy a "plugin wait" step in the sequence).

• custom_string (third part) is a text that contains the parameters for this message (if any). Among the previously mentioned commands, only the "plugin wake" (200014) will expect a parameter that is the message used for this "plugin wait" step when recording the sequence (as described on the Recording steps page.

• The custom_key (last part) has to be MVTPLAYER (all lower case with no extra space). If it does not, the MvtPlayer will just ignore the message.

Sounds scary? Fear not this is easy once you get the few following examples.

BUTTON Start moving|200010||MVTPLAYER

BUTTON Stop moving|200011||MVTPLAYER

These two lines in the AVPos notecard will create buttons (in the current AVSitter menu) that will respectively start and stop the sequence. Note that there are two vertical bars before the MVTPLAYER part because for these two commands the custom_string part of the message is empty. You can however specify playback options for the 200010 message by separating them with &, as in the following examples:

BUTTON Faster!Bigger!|200010|SPEED=2&SCALE=2|MVTPLAYER

BUTTON Quieter|200010|VOL=0.1|MVTPLAYER

As you can guess from these last two lines, playback options can be separated by & in this context.

Of course for these to work you have to have a previously loaded sequence in the MvtPlayer. The easiest solution there is to use the Auto-Loading feature, described on this page: just name your notecard ".movementconfig" and you're set!

Likewise, you can easily create buttons that will pause and resume the sequence:

BUTTON Pause motion|200019||MVTPLAYER

BUTTON Resume|200020||MVTPLAYER

Finally, imagine that, inside the sequence you recorded, you had a "plugin wait" step with the "ready" text as expected signal. Then when your sequence reaches this step it will pause, waiting. You can then use the button created by the following directive to satisfy this step and have the sequence resume:

BUTTON Go on!|200014|ready|MVTPLAYER

MVTP_to_avSITTER_StartOnSit

This script was named Interface_avSitter in previous releases of MvtPlayer but was rename to be more accurate.

The role of this full perm script, when installed along AVSitter and MvtPlayer, will be to start the (currently loaded) sequence as soon as an avatar sits on a pose defined by AVSitter. The sequence will stop as soon as all the avatars stand.

Inside the MVTP_to_avSitter_StartOnSit script, there exist "security delay" on the following line :

float security_delay=1.0; // security delay (number of seconds to wait before starting the sequence)

This means that when the first avatar sits, the interface script will wait for 1 second (you may try smaller values if you wish) before starting the sequence. In my experience, this helps by giving time to AVSitter to perform its initial positional adjustment. With the "KFM 1" directive mentioned earlier in this page, this setting has become less critical.

MVTP_to_avSitter_MvtControl

Purpose

The MVTP_to_avSitter_MvtControl is a script that will manage a full menu system that integrates into avSitter's menu. You can precisely define which buttons will trigger which actions regarding MvtPlayer, while controlling who has the right to do so and a number of other features.

To use it, just install it in your object along with the MvtPlayer script and your movement configuration notecards. Here follows a brief explanation of the settings, all grouped at the start of the script.

Booting parameters

First we have a simple parameter named booting_notecard: if non-empty it must be the name of a notecard the MvtPlayer will load (mind the spelling, spaces etc.). If you plan to use the default notecard ".movementconfig" (as explained here) you can leave this equal to the empty string "".

string booting_notecard="";

Link_message parameters

integer linkmsg_integer=42; // the "number" part of the message

string linkmsg_string="mvtmenu"; // the "string" part of the message

These two lines define what the script expects to pop up its menu. It is composed of a number and a string inside a link_message that can be created inside the AVPos menu by a BUTTON directive: for example (with the settings above)

BUTTON Motion|42|mvtmenu

Access control

When receiving the message from avSitter, the first thing the script will verify is the user's right to access the menu. This is governed by the following setting:

integer allowed=0; // access rights: 0=everyone, 1=group, 2=object owner, 3=white list

As implied by the comment, there are 4 possible values, from 0 to 3:

• 0 means everyone will be allowed to access the menu;

• 1 means that only people wearing the same group tag as the prim containing the script will be allowed;

• 2 means only the object owner will be allowed;

• 3 means that only people from the white list will be allowed to use the menu.

The white list itself is defined in the following list:

list whitelist=[ // only used when allowed=3
"Oggy Fink",
"oggy2"
];

You can of course add more names, that can be either legacy names, user names or avatar UUIDs.

If someone is not allowed, they get the following message.

string accessdenied_msg="Sorry, you are not allowed to use this menu."; // set to "" to disable this message

You can completely suppress this message by setting it to "" (empty string).

Menu parameters

This is a very important section of the settings since they will define exactly what the menu will look like. You can define any number of buttons in the menu, "Next" and "Previous" buttons will appear as required to form pages of up to 9 buttons.

First we have a few "technical" settings you probably won't have to touch:

integer menu_channel=-419823; // there is no reason to change this
float menu_timeout=30.0; // menu timeout, in seconds
integer menu_pagesize=9; // number of buttons per menu page. Use only numbers between 1 and 9.

One noteworthy note about menu_timeout: you can set it to 0.0 if you do not want a timeout on the menu, but generally having a timeout is considered good practice to prevent lag with open listeners.

The following parameters is the menu prompt , where the special text [page] will be replaced by the actual menu page number.

string menu_prompt="Motion menu\n\nPage #[page]";

Then we have the usual button names, used for pagination and closing the menu:

string button_next="Next >>";
string button_previous="<< Previous";
string button_close="> Close <";
string button_placeholder=" - "; // used in place of "previous" or "next" if required

Then comes the most important list that will define the buttons you want in the menu:

list buttons=[ // list of pairs "button name","action1\naction2\n(etc)"
"PLAY","3",
"STOP","4",
"PAUSE","5",
"RESUME","6",
"Load & play","2:movement\n3\n13:3,4,5\n10:0:sequence has ended" // this example uses 4 actions (2, 3, 13 and 10) with appropriate arguments
];

Of course this list here is configured to contain a sensible example, but you decide how many buttons and which buttons you want exactly. For this it is important to understand that this list is organized in pairs. The first element of a pair is the button name. There are two constraints about buttons: they must be unique among all the buttons, and they must not be too long (typically, only up to 12 letters will be visible anyway).

The second element in a pair is a special code that will indicate what the action performed when the button is clicked, and this code may be accompanied by some parameters. More than one action for a button is possible too, in that case you can separate several actions by a newline character \n. You can see this in the last line of the example list above, which will perform four actions (2, 3, 13 and 10) with their own parameters.

The supported codes are given in the comments inside the script. Let me describe them again here:

• 0 - do nothing. It is not really useful, but possible to make a button that will do nothing.

• 1:name - load a notecard (but do not wait for it to load). "name" is of course the exact name of the notecard to load.

• 2:name - load notecard and wait until it's loaded (or until an error occurs). This is basically the same as action #1 except that the script will not perform any further action until MvtPlayer has finished loading the notecard or an error has occurred. This is useful if you want to perform another action right after the notecard has loaded.

• 3:option1:option2... - this code will start the currently loaded sequence. Options here may be the playback options SCALE, SPEED and VOL, as described on this page. You can specify none of them, or up to the three of them, separated by :, as in the following example: 3:SCALE=-1:SPEED=2, which will start the sequence in reverse direction (because of SCALE=-1) and double speed (because of SPEED=2).

• 4 - stop currently playing sequence. No arguments are supported here.

• 5 - pause currently playing sequence.

• 6 - resume currently paused sequence

• 7:text - send a message to satisfy a "plugin wait" step in the sequence. Here the argument text should be the text the currently active "plugin wait" step is expecting so that MvtPlayer resumes the sequence.

• 8:dest:number:string:key - send a link_message to another script who will react to it. This is a generic way to send a link_message, with the following parameters : dest is either a link (prim) number in the set (or one of the negative special values described on this page of the wiki) ; number is a mandatory parameter (number) for the message, string is the textual part of the message and so is key. Both string and key are optional. What will happen when sending the message is entirely up to the other scripts.
  For example, you can have the Theme-O-Matic apply a theme preloaded inside preloader #1 by entering in the list:
  "apply theme","8:-1:77017|1|T-O-M"
  (please refer to the Theme-O-Matic website to get information about this theme system).

• 9:message - say the message in the local chat

• 10:channel:message - send the message to the user of the menu (and their attachments) on the specified channel (use 0 for local chat). This is of course mainly intended to send a message over a private channel to the user's scripted attachments, do do whatever action they are prepared to perform.

• 11:channel:message - send the message over the private channel (sim-wide). This is basically the same as action #10 with one major difference, that the message can be heard by any object listening to the channel. Another more minor difference is that the channel number may not be 0 with this action (you cannot send a message over the whole sim on the public channel).

• 12:seconds - wait the specified number of seconds

• 13:statuses - this more complex action types lets the script wait for a specific status to be raised by MvtPlayer. The argument is a comma-separated list of status values, among: 0 (sequence starting), 1 (sequence paused), 2 (sequence resuming), 3 (sequence stopped), 4 (sequence interrupted because object was just rezzed), 5 (sequence looping). For example, the string "13:3,4,5" tells the script to wait for the sequence to be either stopped, interrupted or looping

If you need more action types to be implemented you can do so, if you have the scripting knowledge, inside the function playnextaction() near the beginning of the script. Or you can of course contact me about it.

Miscellaneous parameters

Finally a few last parameters are grouped in this last section.

First the verbosity level defines which messages are sent by the script. Possible values are 0 (no messages at all), 1 (only errors), 2 (errors and warnings), 3 (errors, warnings and informative messages). A value of 4 was used while developing to send debug messages. Using it again however requires un-commenting appropriate lines in the script.

integer verbose=3;

The next set of parameters deal with what happens when the "Close" button is hit. The script is designed to send a link message when this happens, on condition that the close_sendmsg is set to TRUE. This is primarily intended to reopen AVSitter's own menu, with the 90005-message. The "key" part of the message is not part of the parameters because it is automatically filled with the user's UUID (as expected by AVsitter).

integer close_sendmsg=FALSE; // indicates if the close message gets sent at all, either TRUE or FALSE

integer close_destination=LINK_THIS; // destination prim number for the link message. Shoud probably be

integer close_integer=90005; // the "number" part of the message

string close_string=""; // the string part of the message