MLPV2 Reference Manual

NOTE* -- work in progress, and much of the text below is erroneous.

Back to MLPV2.
To MLPV2_Tutorial.

MLPV2 Reference Manual

.MENUITEMS* files

When MLP2 starts up, it reads all .MENUITEMS* ("*" can be anything) notecards, 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 a MENUITEMS notecard MUST be two POSE statements, first for "default" and second for "stand" -- even if you don't use the STAND button anywhere.

After that, it expects directives and menu configurations.

Comments

Comment in MENUITEMS notecards begin with "//". Any subsequent text on that line is ignored by the scripts.

Examples: //all this text is ignored STOP // STOP is read by the scripts; but this part of the line is ignored.

Directives

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

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 the .MENUITEMS files, it affects all menus.

AUTOBACK

Automatically inserts BACK before the MORE--> button *except* on single pages, and *except* on the last page of multi-page submenus. If you want BACK on such pages, you must do it manually.

NORELOAD

This directive causes MLP2 not to do a menu reset when rezzed.

Menu configurations

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

BALL COLOURS

If a MENU has no pose ball colours 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 colours 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 colours 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 colours with no number after them.

Note: The colours 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

TOMENU

TOMENU name1

This creates a button labeled name1, leading to menu name1, which is usually configured in a subsequent MENU statement.

If a menu (say, name2) exists, and there is no TOMENU statement on another menu, and if there are "TOMENU -" statements for the main menu, a button for name2 is added to the main menu.

POSE

POSE pname | animname ...

This creates a button for a pose labeled pname, using the animations listed after the vertical bar.

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 Colours" topic above.)

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 (note: to be clear, you cannot refer to animations by UUID.)

FACIAL ANIMATIONS

In addition, the animation name specified here can contain a suffix indicating an expression:


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

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 F::20 | Sleep 01 M::20

To make the expression happen periodically rather than constantly, add another extension and the length of the reptition 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 configuration; the animation name in the object's contents should *not* be changed to have this suffix.

LINKMSG

LINKMSG name | menu,primnum,lm-num-arg,lm-str-arg

This creates a button labeled name that will send the 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.


Parameter	Explanation
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 remenu feature.)
primnum	primitive number (e.g. LINK_ROOT, LINK_SET, LINK_ALL_OTHERS, LINK_ALL_CHILDREN,LINK_THIS. See llMessageLinked() documentation in LSL Wiki on the web)
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().

SWAP

This creates a menu button labelled "SWAP". When pressed, this swaps positions between the first and second balls for any pose. It has no effect on any third or fourth balls in a pose.

BACK

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

STOP

This creates a button labeled "STOP" that, when pressed, deletes any rezzed balls and unseats any participants.

Note though that, unlike OFF (covered below) it does not turn off the "listen" that the menu script is doing for menu commands. The menu will keep on listening, even when not in use.

OFF

Often referred to in menu cards as "Shutdown, using an alias for the button name like this:

OFF ShutDown!

This first sends out a llDie() command to any balls out there, then unseats any participants, then resets the ~run script.

Upon restarting, the ~run script is set to set all other scripts to not running (until the prim is clicked again, at which point it turns them back on again.)

This has the effect of shutting off the listen that is in the ~menu script. It also turns off the four other listens in each of these scripts: ~poser, poser1, poser2, and poser3.

With all the listens turned off, as well as all the other scripts, this helps to reduce the "footprint" of an MLP product in a sim.

RESET

Restarts the following scripts by resetting them:
~menu
~menucfg
~pos
~pose
~poser
~poser 1
~poser 2
~poser 3
~props

RELOAD

Resets just the ~memory script.

RESTART

Does what both RESET and RELOAD do, combined.

POSRESET

MENURESET

ADJPOS

The ADJUST command makes the balls turn into long, translucent beams for easy editing to manoeuvre them into their proper positions for each pose.

TIP! Finding the beams hard to see? First, make sure that you have set world to noon. If you still find them difficult to edit, haul one out of your prim.

Edit the script in it, and look for this part of the script in the listen event:

       } else if (str == "ADJUST") {

           llSetAlpha(0.2,ALL_SIDES);

           llSetText("Adjust",<1.0,1.0,1.0>,1.0);

           llSetScale(<0.1,0.1,5.0>);

It's the llSetAlpha setting it to only .2 that makes it hard to see. Try it at .4, or point 6.

Save, take the ball into inventory, then delete the old one in the prim and replace it with your adjusted one.

SAVEPOS

Creates a button on the menu to this effect. When clicked, it saves the settings for the pose currently being played to script memory.

Tip! 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.

MEMDUMP

Lists in open chat all positions currently stored in script memory. The user is meant to then copy/paste this information into the .POSITIONS notecard for backup. NOTE! It is for this reason that the .POSITIONS notecard should be released to customers as MODIFY.

Automore

.POSITIONS* notecards

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

As long as any 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 notecard(s) is/are populated by your manually copying and pasting in information from the MemDump operation (described above.) The reason you have to do this manual part is that Linden Labs for a variety of technical reasons cannot yet let us write via scripts directly to notecards (and some think, given how notecards are handled in the SL system, that they may never be able to let us.)

Remember that purchasers of your MLP 2.0 product are meant to be able to adjust poses to fine-tune them to their own heights, sizes, etc. The .position(s) notecard(s) should be supplied to end-users with MODIFY rights so that they too can permanently save all their hard work. [1]

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

{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>

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 msg) and can't hold any of the other poses you had planned to add. Comparing positions to menu items is easier and the work of seconds as opposed to minutes if you keep the positions information cleaned up [2] and sorted [3].

___________________________
.Position card footnotes
___________________________

[1] 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, 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, and then invite the user to drop his/her fresh .positons notecard in a second time, which would be very confusing.

[2] Actully, the lines in the .positions notecard look more 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 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>

[3] 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.)

The default pose

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

1) Create a notecard with the file name of:

.MENUITEMS.zz-default

Paste the following in as content (minus the solid lines, of course):

__________________________

// 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
// or simply delete this file when you've done that.

Drop this 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 it.

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

Menu reset on rez

Options Menu Tip

With the rapidly-increasing number of functions available within MLP, the OPTIONS submenu where many of the functionality buttons were "traditionally" stored is becoming very crowded.

Consider taking all the height adjusting things out of under OPTIONS and put them in a sub-menu like this:

MENU HEIGHT| GROUP
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

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