MLPV2 Reference Manual

From Second Life Wiki
Jump to: navigation, search


.MENUITEMS* NOTECARDS

Menu notecards create menus.

When MLP2 starts up, it reads all *.MENUITEMS* notecards ("*" can be anything), in the same order as they're shown in object contents. You can have as many MENUITEMS notecards as you wish, or just one. MLP2 essentially reads all MENUITEMS notecards as though they've been concatenated into one big file.

The first two things (other than comments) MLPV2 reads from the first *.MENUITEMS* notecard MUST be two POSE statements, first for "default" and second for "stand" -- even if you don't use the STAND button anywhere. Note that these must not be repeated in subsequent *.MENUITEMS* notecards. See Modules for help and more information on this when using modules.)

After the first two POSE statements, it expects directives and then MENU commands to build menus.

An example, to be clear:

POSE stand | stand | stand  | stand | stand | stand | stand 
POSE default | sit_ground | sit_ground | sit_ground

MENUORDER // NORELOAD

MENU MAIN MENU | ALL (etc)

Don't insert anything else at the top of the main MENUITEMS notecard, or you may experience strange errors such as "No Unused TOMENU"

The first MENU created is the main menu, which a user gets on touching the MLP2 object. The remaining menus are reached via buttons configured using TOMENU.

There are several built-in commands that you use to build your menu, as well as several options.

Most commands cause buttons to be added to menus. In this case, the command format is usually like this:

COMMAND ButtonLabel

Replace ButtonLabel with whatever you want to appear as the button label. In many cases, this is optional, and the button label will match the command name. (Whenever something in a command format is in italics, it means that you replace that text with what you want.)


COMMENTS

Comments in MENUITEMS notecards must be preceded by "//".

Any subsequent text on that line is ignored by the scripts.

Example 1:

//all this text is ignored

Example 2:

STOP // STOP is read by the scripts; but this part of the line is ignored.


DEFAULT / STAND

Place these are the very top of the first *.MENUITEMS* notecard, which is usually the one named ".MENUITEMS". (You may insert commented lines before this; commented lines don't count.)

Example:

POSE stand | stand | stand  | stand  //pose before starting and when stopping
POSE default | sit_ground | sit_ground | sit_ground //default pose when no animation entered

You may use other animations; the ones in the example are standard ones built into the SL, and don't need to appear in object inventory. [1]

See the default pose tip for help on setting coordinates for the default pose.


DIRECTIVES

Directives affect the overall behavior of MLP2. It usually doesn't matter where in the .MENUITEMS* files they are, but by convention, they appear after the default and stand poses. Directives do not cause a menu button to appear.

All are case-sensitive and so therefore you must use them in upper case as shown here.

If you want a directive to be acted upon, type its name into your menu card. If you don't, either just leave it out, or comment it out.

Keyword Explanation
AUTOBACK

(MLPV2.1) Automatically inserts BACK before any MORE--> automatically added by the AUTOMORE feature (see below). This does not add a BACK to every menu page, only those with "MORE-->" inserted by the AUTOMORE feature.

AUTOMORE

Automatically inserts "More-->" button for menus with more than 12 buttons *except* for the main menu. If you need a "More-->" on the Main Menu, you must add one manually.

You would add a manual one like this:

MORE More-->

"MORE" is the command; "More-->" is the button label.

MEMORY

(MLPV2.5) This directive changes the maximum memory limit for the ~menu script.

MEMORY MemoryLimit

Sets the limit to MemoryLimit in Byte on the ~menu script if encoutered in .MENUITEMS notecards.

MLPV2.5c and up reduce their memory limits after reading the configuration, to reduce parcel memory usage. This happens by default without any change to notecards. MEMORY commands for all notecards set the amount of free memory to reserve after reading configuration. Lower numbers use less region (sim) script memory but also increase risk of stack-heap errors. Set MEMORY to 65536 to get max permissible memory. If MEMORY commands are omitted, defaults are used.

When MLPV2 prints memory for a script as "(~scriptname: 10000 bytes free, 40000 byte limit)" 10000 bytes are available for the script's use. If it gets stack-heap errors, configure a higher MEMORY limit for that script's notecard. 40000 bytes is the limit: if this number is below 65535, you can configure more MEMORY for that script. If it's at 65535, you're maxxed out; you might have to reduce (remove poses, shorten pose names, etc -- see wiki for tips)

The "Adjust" menu button now prints free memory. During "Adjust" mode, ~memory script's limit is set to max, to allow storing new pose positions. Its limit goes back down when you leave Adjust mode.

Some scripts have hard-coded limits that can't be changed by notecard. If you get stack-heap errors for these, you can try modifying the script, increasing the number passed to llSetMemoryLimit().


|MEMORY|MemoryLimit|

Sets memory limit of ~props script in .PROPS notecards.

MEMORY | MemoryLimit

Sets memory limit of ~swap script in .SWAP notecards.


MENUORDER


This directive causes all menu buttons to appear in menus in the same order as they appear in the .MENUITEMS* files. If absent, menus are in the group-by-3-backwards order typical of SL menus, like original MLP. If present *anywhere* in any of the .MENUITEMS notecards, it affects all menus regardless of what .MENUITEM notecard they are in.


NORELOAD

This directive causes MLP2 not to do a menu reset when rezzed. MLPV2.1 does not autoreload on rez, and this directive has no effect with MLPV2.1. (Automatic reset on rez was added to fix a problem where multiple copies of the same MLP object responded to each others' menus. A better fix was found in MLPV2.1.)


MENU COMMANDS

These will cause buttons to appear on menus.

Keyword Explanation
ADJUST


Adds a button to make the balls turn into long, translucent beams for easy editing to manoeuvre them into their proper positions for each pose.

ADJUST ButtonLabel

ButtonLabel is optional. Typically, it's "AdjustPos".

See tip on adjusting beams.


BACK


Creates a button labelled "BACK" that, when pressed, displays the menu one level up in the menu hierarchy.

BACK ButtonLabel

ButtonLabel is optional.

If you use the AUTOMORE and AUTOBACK, you will only need to manually enter this on the last page of a submenu (including the only page of a menu with 12 or fewer buttons).


BALLUSERS


Creates a button to cycle through the access levels governing who can sit on the poseballs.

The levels are OWNER, GROUP and ALL

BALLUSERS ButtonLabel | Level

ButtonLabel is the optional button label. Level is ALL, GROUP, or OWNER.

If it is set to GROUP, avatars with the same active group tag as the MLP object can use the balls. The group for the MLPv2 product can set by right-clicking the product and selecting Edit, More >> General tab - Group: Set.


CHAT


Adds a button to toggle on/off whether the MLP object will chat the name of each pose as it is selected.

CHAT ButtonLabel | OnOff

ButtonLabel is the optional button label. OnOff is the default, either ON or OFF.

CHECK

Adds a button that find poses with no positions and vice versa.

CHECK ButtonLabel

ButtonLabel is the optional button label. Typically, it's "CheckPos".


Note! This will reload all .POSITIONS.* files, so first backup any positions that have been saved using SAVEPOS but not manually entered into a *.POSITIONS* notecard!


DUMP

Adds a button to dump the saved pose positions, suitable for saving into *.POSITIONS.* notecards.

DUMP ButtonLabel

ButtonLabel is the optional button label. Typically, it's "Dump Pos".

The positions are chatted to owner only. Positions for all poses are dumped. The user may then copy/paste this into *.POSITIONS* notecards so that the positions will be retained across a position reset, or a full restart or shutdown.

NOTE! *.POSITIONS* notecards should be released to customers with full permissions, to allow them to save positions that they've adjusted to fit their avatars.

If the MLP product has several *.POSITIONS* notecards, the end user may copy/paste all the info into the main .POSITIONS notecard, and delete all the other *.POSITIONS* notecards in the prim. They are no longer needed; all their information has now been amalgamated into .POSITIONS. However, builders may want to keep modules separate; they can do so by manually sorting the entries into their respective *.POSITIONS* files.

See Modules for help and more information on this when using modules.


(DUMPPROPS)

(MLPV2.1) To add a button that will save prop configurations, use the following line:

LINKMSG Dump Props | 0,-4,1,DUMPPROPS    // dump all prop configs

This adds a button named "Dump Props" (or whatever you prefer) that causes all the prop positions to be printed to the screen. They are visible to the MLP product owner only. The user may then copy/paste this text to *.PROPS* notecards for permanent storage.

If the MLP product has several *.PROPS* notecards, the end user may copy/paste all the info into the main .PROPS notecard, and delete all the other *.PROPS* notecards in the prim. They are no longer needed; all their information has now been amalgamated into .PROPS. However, builders may want to keep modules separate; they can do so by manually sorting the entries into their respective *.PROPS* files.

See Modules for help and more information on this when using modules.


HIDE

Adds a button that causes any MLP pose balls rezzed to become invisible. Not many MLP product makers bother with offering this button. The opposite is the SHOW command.

HIDE ButtonLabel

ButtonLabel is optional.


INVISIBLE


Adds a button to toggle visibility for the prim that the MLP scripts are in. Note: this does not apply to the balls or any other prims, even linked ones.

INVISIBLE ButtonLabel

ButtonLabel is optional.


LINKMSG


Adds a button that will send a specified link message to other scripts in the object when the button is pressed. This is useful for adding scripted features to MLP2 without having to modify MLP2 scripts.

LINKMSG ButtonLabel | menu,primnum,lm-num-arg,lm-str-arg
Parameter Explanation
ButtonLabel What you want the button to be called on the menu.
menu Set to 1 if the script receiving the button will pop up a menu. It causes MLP2 not to repost its menu, to avoid menus stacking up. Set to 0 otherwise -- (note: this doesn't inhibit MLP2's redo menu feature.)
primnum

Set to -1 to send the link message to all prims

Set to -4 for just the prim the script is actually in

lm-num-arg 'num' arg for llMessageLinked()
lm-str-arg 'str' arg for llMessageLinked()

The menu user's UUID key is passed automatically as the 'key' argument for llMessageLinked().


MENU

Creates a menu that can be reached from other menus. The first MENU configured becomes the main menu, which the user gets on 'touch'.

A menu's buttons are configured following the MENU statement.

MENU ButtonLabel | who

or

MENU ButtonLabel | who | ballcolors

This creates a menu named name1, and a button named the same on the main menu.

Those who can access it are specified by who, one of the following:

Keyword Explanation
ALL Anyone can use it
GROUP Only those who are wearing a group tag that matches the object's group can use it
OWNER Only the object owner can use it

ballcolors is a list of zero to four ball color names, separated by vertical bars ("|"). The color name MUST be in UPPER-CASE. The following ball color names are supported:

Version Colors
MLPV2 BLUE PINK
MLPV2.1 PINK, BLUE, PINK2, BLUE2, GREEN, MAGENTA, RED, ORANGE, WHITE, BLACK, YELLOW, CYAN, RED2, TEAL, GREEN2

See under Menu Parameters section for greater details.

For example:

MENU MyMenu | ALL | PINK | BLUE

Creates a menu named Mymenu. Poses in this menu will have 2 balls, a pink and a blue one.

Subsequent menu configuration lines add buttons to this menu, until the next MENU command. There is a limit of 12 buttons to a menu, unless AUTOMORE is used.

Note that, unless you use the MENUORDER directive, these menu items will be offered to users in the usual SL ass-backwards-by-three manner.

How do we get a button to get to this menu? There are two ways.

The first way is the same as with original MLP: use the TOMENU command to create a button to get to this menu:

TOMENU MenuName

The button label must match the menu name. Menu names are case-sensitive.

The second way requires "TOMENU -" configuration lines in the main menu. For any MENU statement where no preceeding TOMENU matches the menu name, a menu button is automatically added to the main menu. (For this to work, the main menu must be filled with "TOMENU -" statements, which create blank spaces for this purpose. When MONO comes out and memory is less of an issue, we will try to make this simpler!)

MENUUSERS

Adds a button that cycles through the access levels governing who can use the menu.

MENUUSERS ButtonLabel | Level

ButtonLabel is optional.

Level specifies the default, and must be one of the following: OWNER, GROUP, or ALL

If it is set to GROUP, avatars with active group tag amtching the MLP object's group can use the main menu. (You can restrict access to sub-menus on a per menu basis. See MENU above for more info.) The group for the MLPv2 product can set by right-clicking the product and selecting Edit, More >> General tab - Group: Set.

OFF

Adds a button to turn the MLP system off.

OFF ButtonLabel

ButtonLabel is optional. Typically, it's "Shutdown!"

When turned off, MLP deletes any balls, turns off all the scripts except for one that will turn it back on again when the owner touches it.

This reduces any contribution the MLP might be making to lag.

Any saved poses or prop configurations that have not been saved to *.POSITIONS* and *.PROPS* files are irrevocably lost.

POSE

Adds a button for a pose.

POSE PoseName | AnimList

PoseName is the button label, and also the pose name (found in the *.POSITIONS* and *.PROPS* notecards). AnimList is a list of animation names, separated by vertical bars ("|").

The number of animations must match the number of ball colors listed in the corresponding MENU configuration. That is, if the MENU has 3 poseballs, you must provide 3 animation names.

The animations are applied to the balls specified, in order. That is, if the ball colors are "PINK BLUE PINK", three animations should be listed. The first applies to the first pink ball, the second to the blue ball, and the third animation applies to the third ball, which is pink. (See also "Ball Colors" option below for more information.)

The ball positions are specified in a .POSITIONS* file, discussed below. If there is no .POSITIONS entry for a pose, the default pose is used. It's a good idea to always set up the default pose first for a new MLP product, to avoid balls rezzing underground or in other inconvenient locations.

Each animation name must have a corresponding animation in the object's contents, unless it is a built-in animation. Yyou cannot refer to animations by UUID.

REDO


Adds a button to enable/disable popping the menu back up after making a selection.

REDO ButtonName

ButtonName is optional.

By default, when a user makes a choice on an MLP menu, the menu re-presents itself for further use.

If you offer this command button to users, and they click it, it will toggle this feature off and on.

Few MLP product makers offer this button to users, because turning off the menu coming back can create the perception that something is broken.

RELOAD

Adds a button to reload *.POSITIONS* and *.PROPS* notecards.

RELOAD ButtonName

ButtonName is optional. Typically, it's "Reset Pos".

This button is useful after changing *.POSITIONS* or *.PROPS* notecards, to verify that you did what you intended. It's considerably faster than a complete reset since the menu isn't reread.

General rule: if you changed a .MENUITEMS card, do Menu reset. If you changed a .POSITIONS or .PROPS card, do Pos Reset.


RESET

Adds a button to reload *.MENUITEMS* notecards.

RESET ButtonName

ButtonName is optional. Typically, it's "Reset Menu".

In addition to re-reading the notecards, it resets most of the MLPV2 scripts.

RESTART

Adds a button to do what both RESET and RELOAD do, combined.

RESTART ButtonLabel

ButtonLabel is optional. Typically, it's "Reload".

RESTART is therefore the most thorough command to use for a complete reboot.


SAVE

Adds a button to save ball positions for the current pose.

SAVE ButtonName

ButtonName is typically "Save Pos".

Immediately after adjusting a pose, always, ALWAYS click this button! You will no doubt, like all of us, lose a few adjustments that you make when you first start out with MLP before this gets scarred into your habits.

Caution! This is not permanent. Anything that causes the *.POSITIONS* cards to be re-read will wipe these settings out from script memory. A pose is permanent only if it's saved in a *.POSITIONS* card.

See Modules for help and more information on this when using modules.

Note: the poseballs cannot be more than 10 metres from the MLP item for this to work.

(SAVEPROP)

To add a button to save the prop location for the current pose, use the following command:

LINKMSG Save Prop | 0,-4,1,SAVEPROP      // save position/rotation for a prop

where "Save Prop" is the button name (and can be whatever you choose).

You use this button after you have adjusted a prop. This stores information about the position, etc, to script memory.

This information will also be printed to the screen (only the owner can see it.) This information should be copied to the .PROPS notecard for permanent storage. You can either do this right on the spot, or arrange and save a whole bunch of prop positions, and then use the DUMPPROPS command to print out all the prop info at once for copying and pasting to the .PROPS notecard.

Note: a prop cannot be more than 10 metres from the MLP item for this to work.

See Modules for help and more information on this when using modules.


SHOW

Adds a button that causes any MLP pose balls rezzed to become visible.

SHOW ButtonName

Not many MLP product makers bother with offering this command. The opposite is the HIDE command.

STOP

Adds a button to delete any balls and unseat any participants.

STOP ButtonName

ButtonName is optional.

Note though that, unlike OFF (covered above) it does not significantly reduce any contribution the MLP system might be making to lag.


SWAP

Adds a button to swap positions between the first and second balls for any pose.

SWAP ButtonName

ButtonName is optional.

It has no effect on any third or fourth balls in a pose. However, this behavior may change in future versions.

Note: In some animation menuing systems such as XPOSE (as of summer 2008), hitting the SWAP button only swaps the current pose; the swap is lost at the next pose. In MLP, the SWAP is maintained until a user chooses to SWAP back.

IMHO, the XPOSE behavior is better, and I might change this in a future version. [Lear Cale]


TOMENU

Adds a button to get to another menu.

TOMENU MenuName

MenuName is used as the button label, and must exactly match the name of the menu (case-sensitive).

If a menu (say, "Foo") exists, and there is no "TOMENU Foo" statement on a preceeding menu, and if there are unused "TOMENU -" statements for the main menu, a button for "Foo" is added to the main menu, using up a "TOMENU -" line.

Don't worry about supplying lots of TOMENU - slots on your main menu. If MLPv2 doesn't need them, it will just ignore them!

Note that if you are offering modules, you must provide some "TOMENU -" slots on your main menu for the module menu buttons to appear.


Z*

The Z command adds a button that allows end users to easily adjust for themselves the height of the poseballs.

Z sign number

For this command (and only for this command!), no spaces are allowed between the items (Z, sign, and number). For example:

Z+1
Z+5
Z+25
Z-1
Z-5
Z-25

The numbers are treated by MLP as being a measurement in centimetres. Each time a user clicks a button, say Z+5, the height will be increased by 5 centimetres. If they have previously clicked the Z+5 button, then the height will be increased by an additional 5 centimetres.

A Z-5 button, if offered, would decrease the height by 5 cm.

Z adjustments chosen by users apply to all the poses, not just the one currently being used.

Note: the ongoing tally of these adjustments are stored in the Object Description of the prim that holds the MLP scripts, so any descriptions you put there will be replaced.

To clear them, you need to either use the Z buttons to set the offset back to 0, or, edit the object, select the MLP prim if it's not the root prim, and clear the description.

Traditionally, MLP product makers have put these Z commands under the OPTIONS menu. These were recently moved to a HEIGHT submenu, to make room for the Props commands.

See the Tip! Options Menu for more info on how exactly to do this.

See the Tip! Options Menu table at the end of this page for helpful advice on arranging many of these menu commands into a tidy sub-menu.

MENU PARAMETERS

Info that you can add to MENU statement lines.

Ball Colors

If a MENU has no pose ball colors listed, it should have no POSE buttons.

When, however, a particular MENU will contain POSE statements in it, then the MENU statement must be followed by a set of ball colors to be used for all poses in this particular menu.

One to four balls can be specified, supporting poses for up to four participants. The balls are rezzed as necessary when a pose in the menu is selected.

Supported colors as of summer 2008 are:

PINK PINK2 BLUE BLUE2 WHITE
GREEN GREEN2 RED RED2 BLACK
MAGENTA ORANGE YELLOW CYAN TEAL

PINK2, BLUE2, RED2, and GREEN2 are darker their respective colors with no number after them.

Note: The colors must be given in uppercase as shown above.

Examples:

MENU boy-girl | ALL | BLUE | PINK
MENU Boy Only | ALL | BLUE | HIDE
MENU Girl Only | ALL | PINK
MENU Anyone | ALL | GREEN
MENU 3Some  | ALL | PINK | BLUE | PINK
MENU 4Some  | ALL | PINK | BLUE | PINK | BLUE



POSE PARAMETERS

Info that you can add to POSE statement lines.


Animations (Facial)

In the POSE line, add the suffixes listed below to the animation names to cause facial expressions. (You don't change the animation name in inventory, just add the suffix to the anim name in the POSE line.)

NOTE: There is currently (April 2011) no menu button to allow MLP users to turn facial expressions off and on.

suffix expression
* mouth open
 ::1 mouth open
 ::2 surprise
 ::3 tongue out
 ::4 smile
 ::5 toothsmile
 ::6 wink
 ::7 cry
 ::8 kiss
 ::9 laugh
 ::10 disdain
 ::11 repulsed
 ::12 anger
 ::13 bored
 ::14 sad
 ::15 embarrassed
 ::16 frown
 ::17 shrug
 ::18 afraid
 ::19 worry
 ::20 sleep
 ::21 random (for MLPv2.4v or higher, produces random surprise / pleasure expressions)

Note: 20 is a combination of disdain and smile, the closest that could be found for sleep.


There must be NO SPACE between the animation name, and the suffix. Example:

POSE Sleep 01 | Sleep 01 femalesleep::20 | Sleep 01 malesleep::20 

To make the expression happen periodically rather than constantly, add another extension and the length of the repetition cycle (in seconds).

For example, to use MyAnim with open mouth every 5.5 seconds:

POSE Mypose | MyAnim::1::5.5

If during menu boot you get an error that says "animation xyx not found", but you know that animation xyx really is in there, check to see that you didn't put a space before the expression suffix after all.

Note that this suffix appears only in the POSE line of a MENU; the actual name of the animation in the object's contents folder should *not* be changed to have this suffix. (Many animations are sold no mod; so you wouldn't be able to, anyway.)

.POSITIONS* NOTECARDS

The .positions notecards, as their name implies, provide a place for storing information about positions of the poses in the menu.

As long as any position adjustments you have made have only been saved via the SavePos buttons, assume them to be temporary. They are only saved in script memory, and script memory is volatile. If you hand the MLP v 2.0 object to someone else, or if your sim crashes really terribly or if the script blows up with a stack-heap error, etc ... you may lose all the work you'd thought you'd saved.

The *.POSITIONS* notecards provide a safety against losing your work.

You create *.POSITIONS* notecards by your manually copying and pasting in information from the "Save Pos" or "Dump Pos" buttons (SAVE and DUMP commands described above). SL does not allow scripts to write data to notecards, so you must do this yourself.

NOTE: If the .POSITIONS notecard is no modify, or is placed in a no modify prim, people will not be able to open the notecard at all. This is a SL system limitation.


The lines in the .positions notecard look something like this:

{LieHold1} <-0.253,0.157,0.285> <0.0,0.0,0.0> <-0.146,0.000,0.177> <0.0,0.0,90.0>

where "LieHold1" is the name of a pose (from the POSE statement in a *.MENUITEMS* file).

The 4 vectors in the above example represent in order: first ball position, first ball rotation, second ball position, second ball rotation

If there are 3 and / or 4 balls also involved in a given pose, then the pattern repeats on for them as well.

If you rename a pose in the menu that you have already stored a position in the notecard for, be sure to edit the .positions card, locate that pose in it, and give it the new name as well to match.

Be sure to purge out position lines for which menu items no longer exist. This is one instance in which tidiness really does pay off: all that old, unneeded position information is read into the scripts' memory, which can make you think that your MLP product is "full" (that fatal stack-heap message) and can't hold any of the other poses you had planned to add.

See Modules for help and more information on .positions cards when using modules.

Note: Comparing positions to menu items is easier and the work of seconds as opposed to minutes if you keep the positions information cleaned up. See the tip on tidying .POSITIONS notecards, if you wish to do this extra (not-required) work.

Remember that purchasers of your MLP2 product should be able to adjust poses to fine-tune them to their own heights, sizes, etc. All *.POSITIONS* notecards should be supplied to end-users with MODIFY rights so that they too can permanently save all their hard work. [2]

(MLPV2.5) to set a memory limit on the ~memory script, use a line like this:

{MEMORY} <MemoryLimit>


SEQUENCE NOTECARDS

SEQUENCE | seqence-name | NOCHAT
use NOCHAT to inhibit chatting of poses

MENU | menu-name
set number & colors of balls

POSE | pose-name | chat-chan | chat-message
start a pose (chan & message are optional; message is whispered).

AVWAIT | 0 1 2 3 | chat-message-if-waiting
pause the entire sequence set until the balls listed are sat on (0 1 2 3 in this example)

examples:
to wait for two people: AVWAIT | 0 1 | Waiting for both people to get on the balls
to wait for three people: AVWAIT | 0 1 2| Waiting for three people to get on the balls
to wait for four people: AVWAIT | 0 1 2 3| Waiting for four people to get on the balls

Only have one (1) AVWAIT line per sequence set, or you may get stack-heap blow-ups.

WAIT | wait-seconds
pause before executing next command

GOTO | label-name
go to a label, to loop a portion of a sequence

LABEL | label-name
set a target for GOTO

REPEAT
repeat the whole sequence

SAY | chat-chan | chat-message
say the given text on the given chat chan

WHISPER | chat-chan | chat-message
whisper the given text on the given chat chan

SOUND | sound-name | 0 to 1.0
plays sound from prim contents at volume 0 to maximum

MEMORY | MemoryLimit

(MLPV2.5) Sets memory limit of the ~sequencer script.


NOTE: The chat messages can include the first names of participants using /0 for avatar on first ball, /1 for av on 2nd ball, etc.


Sequence scripting debugging

(very advanced)

Put any one of these are the very top of your sequences notecard, outside of any defined sequence, in order to turn on debugging for the sequences script:

debug | 1
sequence start/stop

debug | 2
echo each command as executed

debug | 4
avatar hop on/off

debug | -1
all debugging


Sequences and Props

Yes, props will still work for items used in sequences.

TIPS

TIP! ADJUST Beams


TIP! Animations Caveat

Though all animations will work with MLPv2, not every single one you come across will work reliably.

Some animations, if they happen to have been made by the creator in a certain way, will work as expected after certain other animations, but not after others. You'll get different results depending on which pose you ran last.

The problem is animations that have their hip position the same in their T frame and first animation frame. They just won't work with MLP.

Example: if you have 3 anims, 2 with hip positions set and one without, the hip position for the one without will be the hip position left over from whichever of the last two anims you used. It's the way SL animations work. If there's no change in any joint between the "T" frame (first frame in bvh file) and the first animation frame (second frame in bvh file), SL ignores that joint for the whole animation. And when all other animations are turned off, this means that these joints are left free to do whatever SL does with them. It leaves them as they were from the previous anim, or overrides them with SL builtin motions like typing, head movement, arm pointing while editing, etc.

The values in the hip joint aren't important; what's important is that that they *be* different between T frame and 1st animation frame. For MLP, you want every joint in the animation to have been moved (except head, if you want it to be able to move with the mouse.)

This problem can be avoided when making animations if you move the hip even just 1 degree, and normally the stomach 1 degree in the opposite direction.

So sadly, in the course of things, odds are, you're just going to buy some animations that just ain't going to work with MLP. And there is no way of knowing in advance.

When creating animations for MLP, Lear Cale highly recommends using priority 3. This disallows the typing while chatting animation, but allows head movement (if the head joint is not moved in the beginning of the animation). It also allows someone to create a priority 4 animation and run it to override MLP animation behavior (until the next pose is selected).


TIP! Animations Permission

The ball user, upon first sitting on a ball, will be asked permission to animate them. S/he must say yes to yes, or they will end up just "hovering" on the poseball.

The "permission pls" menu often gets hidden behind the MLP main menu (if you are the one who called up the menu.) You need to click the ">>>" to cycle through the menus on your screen to find the permissions prompt. This is SL behaviour and there's no way to fix it, other than turning "redo" menu off in MLP.

NOTE: in their great wisdom, SL modified the 1.20 viewer to show something other than ">>>" for this button. Damn them.

If you are wondering why permission must be asked, when normally sitting on something is taken as implying permission to be animated, it's because it's not actually the balls that are doing the animating -- it's a script in the MLP. Because one script is not allowed (for security reasons) to pass permission to another script, the scripts in the MLP itself can't take advantage of any permissions the poseballs have acquired.


TIP! Animation Synchronization

Animations appear to start separately per ball once an avatar sits on it. Thus, they're not in sync.

In fact, the animations are started at the same time. However, it takes time for the animations to get sent between SL and the client, so as a result they don't look synchronized.

There is no simple feature in MLPV2 to automatically synchronize poses as such. You can manually synchronize by shifting to another pose and then shifting back again. (Starting with

There is no built-in feature to automatically synchronize, as there is with couples danceballs. Prior to MLPV2.4z4, you can manually synchronize by changing to another pose and then back. Starting with MLPV2.4, you can manually resynchronize by selecting the same pose again.

There is an advanced feature of MLPV2 that you could use to get automatic periodic synchronization: Sequences.

A sequence is simply a list of poses that MLPV2 will play at the touch of a button, with the option to repeat the sequence or a portion of the sequence. See the example sequence in the distribution. You could set up a simple sequence that plays one pose, waits some time that's at least as long as the animations, and repeats, like this, which goes in .SEQUENCES notecard:

SEQUENCE | snuggle-seq | NOCHAT
MENU | couples
POSE | snuggle
AVWAIT | 0 1
POSE | snuggle
WAIT | 30
REPEAT




TIP! Animations and balls

Animations remain in the main MLP object; they are never placed in the poseballs. The animations are played from within the main MLP product; the poseball is just the delivery vehicle. Consequently, poseballs can be deleted or lost without the main product being affected. And, the poseballs themselves are just copies of the one inside the MLP product.

A ball will commit suicide if left behind somewhere (the MLP object needs to be within 20 metres.)


TIP! Ball text

By default, both the poseball floating text and the right-click menu 'sit' choice text is the word "LOVE". You can set these to whatever you want by editing the description of ~ball in object contents. If you type in that field the word "none" (without the quotes), or just type in a space or two, there will be no floating text, and the right-click menu 'sit' choice text becomes the system default of just "Sit Here" (for English viewers).


TIP! Phantom Balls

To make your balls rez as phantom, put an asterisk in the ~ball description line.


TIP! More than 6 balls

There are no plans to expand beyond 6 balls active at once. If this is totally necessary for you, you'd be better off just going with a product that actually supports the number of avatars you want, such as XPOSE. You'll save yourself and your customers time and confusion by going with a product that was designed to handle larger numbers from the ground up.



TIP! Balls are buried in furniture

Sometimes when you position the balls correctly for an animation, the balls end up buried in furniture.

This is a property of the animation: the hip position in the animation is too high. While it is in theory possible to fix this in MLP scripts, it would be hard to do, especially without using up lots of memory for poses.

Most people know that when this happens they can select another pose first, jump on, and then change to the pose they want. Consequently, the simplest workaround is to make sure the first pose in each menu has all balls visible.

Alternatively, you could ask the creator of the animation to adjust it, but the chances of them doing this just for your piece of furniture are not high.

If someone stands up while on balls that are buried in furniture, they will get ejected from the furniture unceremoniously. This won't happen if they use the STOP button on the menu instead.

Vesta Martynov suggests another workaround -- changing the offset that the ball is rezzed at. (Note that this will apply to all poses, not just the problem ones.) Her work-around is, before you start on a MLP product, to take the ball out and rez it on the ground. Edit the script in the ball, and search for this SitTarget line:

llSitTarget(<0.0,0.0,0.1>,ZERO_ROTATION);

The .01 there is the vertical offset. She changes it to something like this:

llSitTarget(<0.0,0.0,-0.25>,ZERO_ROTATION);

Save your changes, take the ball back into your inventory, and use it to replace the one that was inside the MLP.

After you do this, all the balls and animations will be lifted, so you can go in and lower the animations, but you will no longer have balls sinking into your furniture.

(Vesta Martynov, conversation in MLP group, 2009-06-11 19:46)


TIP! Ball scripts

When updating your version of MLPv2 scripts, make sure you update the script in ~ball as well.


TIP! Changing the number of active Balls

When going from a pose in a menu with 4 ball colors to a pose in a menu with 2 balls, the 2 balls are deleted. Assuming you're not using phantom balls, if the balls rez again (say you go back to a pose in a menu with 4 balls), the balls should bump anyone standing in their way out of the way. People wanting to use the newly re-rezzed balls and be animated by them will have to hop back on them. When changing the number of balls active, bear in mind that the number of animations in a POSE line must match the number of ball colors in the MENU line above. You can't mix poses with 2 anims and poses with 4 anims in the same menu section. This is not supported.



TIP! Default Pose

You need to set position coordinates for the default pose. To do this, on the MLPV2 main menu click the "adj-default" button, then ADJUST the default pose position, save, and copy the coordinates to the .positions notecard as per normal. When you have finished, delete the .menuitems.zz-default notecard from the prim.

If on the main blue menu you do not see a button called "adj-default", do the following steps:

1) Create a notecard with the file name of:

.Menuitems.zz-default

Paste the following in as content:

 
// The "default" pose below is for adjusting "default" position.
// Since there are currently no other items in this menu, you can comment out the whole menu<br />
// or simply delete this file when  you've done that.

MENU adj-default | ALL | BLUE | PINK | BLUE | PINK
POSE default | sit_ground | sit_ground | sit_ground | sit_ground
SWAP
ADJUST
SAVE Save Pos
DUMP Mem Dump
BACK

Tip! If the product you are making is only for 1 or 2 people, then you don't need to include all 4 balls that are listed in the menu above. For a solo product, you can just do instead:

 MENU adj-default | ALL | BLUE
 POSE default | sit_ground
 ADJUST
 SAVE Save Pos
 DUMP Mem Dump
 BACK

Drop this notecard into the prim where you are working with MLPV2.

2) Make sure the main menu notecard has a spare TOMENU slot to fit the adj-default choice into:

TOMENU -

3) restart the MLPV2 product.

4) ADJUST the default pose position, save, and copy the coordinates to the .positions notecard as per normal.

5) When you have finished, delete the .menuitems.zz-default notecard from the prim.



TIP! Notecard Editing

If the MLP prim contains many animations, access to a notecards contents can be PAINFULLY slow.

First, make sure the prim is ready to let you open the notecard. Right-click on the notecard that you see in the contents folder. If you get a big menu of choices, rather than just the standard 4 of Open, Properties, Rename, Delete, then the prim isn't ready to let you open the notecard. You simply have to wait. Sometimes, you may need to wait up to 2 to 4 minutes. Yes, ridiculous -- but that's SL.

Make all your changes before saving. Once you save, the notecard you have open may no longer be the notecard that is inside the prim (sic.) Once you have saved, even if you did so by accident out of habit, leave the notecard opened for a few seconds, then close it, and wait until the prim is ready to let you open it again if you need to do further edits.

Note: as of summer 2008, the wait time for notecards to open from inside prim folder contents seems to be getting increasingly worse, and the system seems to be getting increasingly intolerant of allowing repeated saves on the same opened notecard. Thus, the advice to close and re-open after a save.



TIP! Modules -- multiple .menuitems and .positions notecards

There can be several *.MENUITEMS* and *.POSITIONS* notecards in an MLP product (where "*" is any text that's allowed in a notecard name). This is to allow the addition of modules to the product. This allows you the option, for example, of letting customers purchase an MLP product for couples, and then coming back later to purchase an odd-on for 3Somes. Customers then pad home, edit the contents folder of their MLP product, plop in the add-on stuff, and restart their MLP.

Note: a module's menu appears as a button on the MLP product's main menu. For this to actually happen, you *must* provide a blank slot for it by supplying a TOMENU - parameter on the main menu. Normally, there should be a bunch of these in the main menu.

The add-on will consist of a .menuitems card, a .positions card, and the associated animations (with permissions set correctly.)

For you as a vendor to make a module, you create a .MENUITEMS.xxx notecard, and a corresponding .POSITIONS.xxx notecard (where xxx can be anbything and is normally thought of as the name of the module.) If this module uses props, you also create a .PROPS.xxx notecard.

A *.MENUITEMS* card for a module should have no default or stand pose, etc. It normally has only the actual menus being added and the associated poses.

Example:

MENU myAddOns
 TOMENU myAddOn1
 TOMENU myAddOn2

 MENU MyAddOn1 | ALL | PINK | BLUE
 POSE Whoohoo! | Bump1 | Bump2
 POSE Zowee | Grind1 | Grind2

 MENU MyAddOn2 | ALL | PINK | BLUE | PINK
 POSE Fubar | Dance1 | Dance2 | Dance3


To test, you would then drop all associated notecards (.menuitems.xxx, .positions.xxx and .props.xxx if using) into the MLP product, along with the necessary animations and props, of course, and restart the MLP product. (Of course, if you were selling it as a separate add-on, you would after remove the above components from the main product, and package them separately.) Remember if you make any pose position adjustments during testing that the position information should be copied and pasted to the relevant .positions.xxx notecard -- not the main .positions notecard, because you are preparing a sold-separately module. Ditto for any prop adjustments, which go into the .props.xxx notecard.

Purchasers of an add-on need to always keep that .menuitems.xxx notecard in their product. However, the .positions.xxx and the .props.xxx notecards have, in a way, a limited lifespan. When you do a DUMP command, you copy / paste all that info into the notecard named simply .positions -- that is the main .positions notecard. Or, into .props notecard, in the case of a DUMPPROPS command. All the info that the subsidiary .positions.xxx and .props.xxx notecards hold is now amalgamated into the main notecard, and the subsidiary ones are no longer needed. They can be deleted. But to be clear, do not delete their corresponding .menuitems.xxx notecards.

Multiple .positions notecards are read by the script in the same order they appear in object inventory.

Note: it is best to be using the MENUORDER directive when offering modules.


TIP! Sub-Menus

Can you add a module menu ie: .MENUITEMS.myposes and have it show as a top menu item with sub menus? Something that would give a My Poses button that when clicked would open a sub menu dialog with buttons for my poses 1, my poses 2 etc.

Abolutely, and that's the best way to do it.

Start your .MENUITEMS.mystuff with the parent menu. Fill it with "TOMENU" statements like this:

MENU WhizBangInc | ALL
TOMENU WBI-cuddles
TOMENU WBI-fun
TOMENU WBI-freaky
TOMENU WBI-illegalin42states


TIP! Options Menu

By tradition, most of the common functionality command buttons are stored under a MENU called "OPTIONS".

Such commands include ADJUST, SAVE, DUMP, Show/Hide (aka INVISIBLE), MenuUsers, BallUsers, Chat, Dump Props, Save Prop, etc.

As well, the z commands for height adjustment were traditionally offered there as well.

With the rapidly-increasing number of functions available within MLPv2, however, the OPTIONS submenu is becoming very crowded.

Consequently, consider taking all the z height adjustment options out from under OPTIONS and put them in a sub-menu like this:

MENU HEIGHT | ALL
 Z+1 //adjust Z = height offset in cm - use any integer to set the step size
 Z+5
 Z+25
 Z-1
 Z-5
 Z-25
 BACK

Then, in the OPTIONS menu, just make this button linking to the HEIGHT submenu:

TOMENU HEIGHT



TIP! Positions Notecard tidying

The lines in the .positions notecard look like this when copied and pasted in directly from chat:

[7:46] Animated Living Sofa Combo Couple & Solo 2.1e: {Lie&Hold} <-0.413,0.130,0.245> <1.0,-9.0,-0.9> <-0.539,0.207,0.155> <-0.1,-8.9,-1.1>

The extraneous chatter before the {LieHold1} parameter in the curly brackets (aka braces) is ignored by the scripts, so there is no need to delete it.

Still, if you as an MLP professional wish cleaner, easier to read content (which is a boon for easier maintenance and troubleshooting), then copy the contents of the .positions card in question into a simple text programme (such as Notepad on a Windows PC), and using the example above, you would search for:

[7:46]  Animated Living Sofa Combo Couple & Solo 2.1e:  [including the final space at the end of it]

and just replace it with nothing, and then paste the cleaned up text back into the .positions card.

The cleaned up text then looks like this.

{LieHold1} <-0.253,0.157,0.285> <0.0,0.0,0.0> <-0.146,0.000,0.177> <0.0,0.0,90.0>


You may wish to also to SORT the positions in alpha order to make it easier to find them.

So that instead of:

{Massage} <-0.230,-0.133,-0.287> <0.0,0.0,-86.0> <-0.287,0.259,0.161> <0.0,0.0,-82.0>
{Sprawl 1} <0.960,0.000,-0.190> <0.0,0.0,0.0> <0.700,0.000,0.700> <0.0,0.0,-180.0>
{Lie 01} <-0.115,-0.069,0.694> <0.0,0.0,-90.0> <-32.417,-199.035,-518.585> <0.0,0.0,0.0>
{Couch 1} <-0.179,0.001,0.143> <0.0,-19.0,0.0> <0.700,0.000,0.700> <0.0,0.0,-180.0>

You have

{Couch 1} <-0.179,0.001,0.143> <0.0,-19.0,0.0> <0.700,0.000,0.700> <0.0,0.0,-180.0>
{Lie 01} <-0.115,-0.069,0.694> <0.0,0.0,-90.0> <-32.417,-199.035,-518.585> <0.0,0.0,0.0>
{Massage} <-0.230,-0.133,-0.287> <0.0,0.0,-86.0> <-0.287,0.259,0.161> <0.0,0.0,-82.0>
{Sprawl 1} <0.960,0.000,-0.190> <0.0,0.0,0.0> <0.700,0.000,0.700> <0.0,0.0,-180.0>

You can do this sorting in seconds by copying & pasting the (cleaned-up position chatter) into something such as Microsoft Word, or a spreadsheet, and telling it to sort, and then copying & pasting the sorted positions back into the .positions notecard. (This really works best though if you have stripped the initial chatter info from them.)


TIP! Notecard reading order

Q: I have a question about animation packs. I know the readme notecard says that the scripts read the notecards in alpha order. If I were to name the notecards as A, B, and C would the buttons on the menu then be in that order as well? I'm picky--I like my buttons in a certain order.

A: Yes.


TIP! Portable use of an MLPv2 product

Attach the MLPv2 object to your HUD. You can use its default shape and color for a clickable bar on one of the edges of your screen (to move HUD position: Right-click and Edit it and use the arrows). While in edit mode, you can also edit color/transparency/size/position.

Note that the balls will appear relative to the initial MLPv2 position. Adjust the height offset with a (Z) command.



TIP! Props

Props are objects the MLP product will rez for poses. When you choose another pose or hit STOP, any rezzed prop disappears. If you delete the MLP object, any prop will disappear within 3 minutes.

Props support starts with MLPV2.1.

To add a prop, edit a .PROPS notecard or add a new one (named .props.xxx where xxx is the name of the module, for a modular config). Copy the following example line and paste it into your .PROPS notecard.

| mypose | myobject | <1,1,1>/<0, 0, 0>

Then:

  • Replace "mypose" with the pose name;
  • Replace "myobject" with the name of the prop object. The object name cannot contain vertical bars;
  • Add the "~prop" script (from inside the "~pillow" object that comes with the standard distribution) to your prop object, and drop your prop object into the MLP prim's inventory. The prop and everything in it will need to be copiable for next owner;
  • Make sure your menu has the SAVEPROP and DUMPPROPS command on it.

Restart the MLP, and then select the pose. The prop should appear. It might be underneath the MLP object, so look around -- it may be best to do this using a single prim MLP floating in the air, the first time so that it doesn't rez in the ground!

Move the prop to where you want it, and use MLP menu command "SAVEPROP". To make the change permanent, select the chat information that is printed out on your screen (including the first vertical bar, and optionally any text before it) and replace the corresponding line in your .props.xxx file. Or, do all your props and use DUMPPROPS. (This procedure is similar to that for saving positions in .positions.xxx notecards.)

To get MLP to reread .props.xxx files, restart the product (which resets positions as well as props).

Keep in mind that props and positions are saved as two separate steps. If you adjust a pose and its prop, you need to save both pose position and prop.

Tip: We are all so used to hitting the button to save positions. If you find that a prop position isn't saving, check your chat history to make sure you didn't hit the save position button instead of save prop just out of habit!


Hand-held Props
For props to be used as hand-held items, use the ~give script add-on found here MLPV2_Give_Item_Add-on and have people wear the items.

Number of Props
For any pose, you can have at most one prop. If you need more than one prop to rez, you'll have to link the items so that they can be treated by MLP as one object. Alternatively, if you have a scripter friend to help you, you might try having the rezzed object rez another object from its contents. Your scripter friend would need to make the rezzed child object listen for the same die command as the main object that was rezzed.

Or, you *might* perhaps try the rezzed object as a coalesced object, making sure that each item has in it a script (created custom for you by a scripter friend) so they can die when required to -- experiment with that somewhere in the open at first in case it goes all over the place.


TIP! STOP in every menu

STOP and BACK buttons should be on every menu.

Why STOP on every menu? It solves so many problems. For example, if you use STOP, you don't get ejected like a James Bond villain if the poseball happens to be buried in the furniture. After moving or rotating a bed, STOP resets the position (Lear put in code to do this automatically, but there's no event that tells you when rotation stops.) And no doubt, SL and MLPV2 have bugs, and I've seen funky and unrepeatable oddness that STOP fixes in a jiffy. Plus it makes the poseballs go away.


TIP! Scripting -- call on MLP Menu from another script via linked msgs

If you just want the MLP menu to come up from another script in the object (same prim or different one), simply do what the ~touch_passer script does (the llMessageLinked() call). If your script is in the same prim as MLP scripts, change LINK_ALL_OTHERS to LINK_THIS.


TIP! Scripting -- call on MLP Menu from another script via chat

MLP listens for menu responses on this channel, minus one:

// Return a channel number that's based on the prim's key -- unique per object
integer channel() {
return (integer)("0x"+llGetSubString((string)llGetKey(),-4,-1));
}

Note that the key here is the key of the MLP object.

Oh, warning: it also checks to see if the chat came from the same user as whoever used the menu recently. If they don't match, it sends a menu (dialog) -- in this case, to your object, which won't do anything. So, I suspect that this will work only if you keep users from getting access to the MLPV2 menu directly.


API

When the MLP is ready for use, the menu script in its ON state sends out a linked message on channel -11003 saying "READY" (from MLP version 2.4p1 and onwards.)

llMessageLinked(LINK_SET, -11003, "READY", NullKey);


  1. ^ For a list of other built-in animations, see here: [1].
  2. ^ Some furniture makers prefer to sell their furniture no mod so that others can't just disassemble it and copy the dimensions of the pieces and thereby duplicate the furniture -- fair enough. However, if the .positions notecard is in a no-mod prim, notecards inside it will also be no mod. There doesn't seem to yet be a way around this. While llAllowInventoryDrop in a small add-on script might seem promising (and the change event could be set to delete the old .positions card), the problem remains that by then, a fresh positions card the user had dropped in would already be named .positions 1, an invalid file name. Because you can't rename objects inside a prim, you'd have to then have your script delete that .positions 1 card as well, and then invite the user to drop his/her fresh .positions notecard in a second time, which would be very confusing. Or, using the LINKMSG feature, create a button that tells a script to delete the .positions notecard, and then invites the user to drop a new one in. But you'd want that script to ask the user if s/he really knew what they were doing. Note as well that a no-mod prim prevents the option of allowing customers to purchase add-on modules for you -- unless provision is made for an llAllowInventoryDrop.

Illegal Pirated Animation Kit FYI

http://wiki.secondlife.com/w/index.php?title=62_Animation_MLP_Set

For "free" status of Sexgen animation kit released October 2011 by Stroker Serpentine, see here: https://wiki.secondlife.com/wiki/Stroker_Serpentine_Sexgen_Animation_Set