MLPV2 Reference Manual

From Second Life Wiki
Revision as of 10:54, 4 August 2008 by Chaz Longstaff (Talk | contribs)

Jump to: navigation, search

MLPV2 Reference Manual


.MENUITEMS* NOTECARDS

Menu notecards create menus.

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.

(Note: The exception to this is module .menuitems notecards: see Modules for help and more information on this when using modules.)

After that, it expects directives and MENU commands to build menus.

The first MENU created is the main menu, which a user gets on touching the MLP 2.x 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.

Many menu commands can have "synonyms" to present themselves to users as buttons with more use-friendly language.

The syntax for this is:

COMMAND Friendly Text

Note the space in between the command and the friendly text. You can have spaces in the friendly text.


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 your MENUITEMS notecard. (You may insert commented lines before this; commented lines don't count.)

You may if you wish name other animations to use; these are standard ones built into the SL Client that you don't actually need an animation for. [1]

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

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


DIRECTIVES

Directives affect the overall behavior of MLP2. It doesn't really matter where in the .MENUITEMS* files they are, but by convention, they appear after the default and stand poses. ( To be clear: directives don't cause a menu button to appear.)

There are 4 directive options. All are case-sensitive and so therefore you must use them in uppercase 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


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.


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

(Note: MORE is the actual command; More--> is the synonym.


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.


NORELOAD

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



MENU COMMANDS

These will cause buttons to appear on menus.

Keyword Explanation
ADJUST


Sometimes shown on menu items with a synonym, like this:

ADJUST 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.

See tip on adjusting beams.


BACK


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

If you wish, you may present it with a synonym, like this:

BACK << Back

If you use the directive AUTOBACK, you will only need to manually put this on the last page of a submenu.


BALLUSERS


Cycles through the access levels concerning who can sit on the poseballs.

The levels are OWNER, GROUP and ALL

BALLUSERS BallUsers | ALL

The | ALL parameter in this example sets it to default to the balls being accessible to ALL on first being booted.

If it is set to GROUP, members having the same activated group tag as the MLP object is set to 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


This command toggles ON and OFF how much the MLP product will give information messages to the users.

CHAT Chattiness | ON

The | ON parameter sets it to default to being ON upon first being booted.


CHECK


Sometimes shown on menu items with a synonym, like this:

CHECK ConfigCheck

This will find buttons with no positions and vice versa.

Caution! This will reload all .POSITIONS.* files, so first backup any positions that are saved to script memory only!


DUMP


Sometimes shown on menu items with a synonym, like this:

DUMP MEMDUMP  

Lists in chat audible only to the prim owner 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 if at all possible be released to customers as MODIFY.

If the MLP product has several .positions.xxx notecards, then copy / paste all the info into the main .POSITIONS notecard -- that will be the one named just simply .POSITIONS . Then, delete all the other .positions.xxx notecards in the prim. They are no longer needed; all their information has now been amalgamated into the main .POSITIONS notecard.

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


DUMPPROPS


Causes all the prop positions you have saved to be printed to the screen. They are visible to the MLP product owner only. These are then to be copied and pasted to the .PROPS notecard for permanent storage.

You cause this command to appear like this in a menu:

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

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


HIDE


Causes any MLP pose balls rezzed to become invisible. Not many MLP product makers bother with offering this command. The opposite is the SHOW command.


INVISIBLE


Sometimes shown on menu items with a synonym, like this:

INVISIBLE Show/Hide

Toggles 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.


LINKMSG


This creates 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 name | menu,primnum,lm-num-arg,lm-str-arg
Parameter Explanation
name 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 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().


MENU


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

MENU name1 | who

or

MENU name1 | who | ballcolours

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

Under the MENU line, you then supply lines (up to 12 of them -- an SL limitation) which create buttons on the main menu for your menu. These lines start with a system command. They may be just a command, such as ADJUST, or a command such as POSE which needs further "arguments" supplied.

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.

Occasionally, you may find your menu showing as what appears to be a duplicate button on the main menu page. Check that you didn't type it in two different letter cases. For instance, in the main menu you may have typed TOMENU MYMENU, yet you may have actually called the menu "mymenu." MLPv2 is case sensitive, and will interpret this as two different menus on offer. (Note: this will only occur if you have a TOMENU - slot on the main menu. If you don't, there will be no duplication *but* because the button created on the main menu doesn't match an actual menu, nothing will happen when you click the button on the main menu.


MENUUSERS


Cycles through the access levels concerning who can use the menu.

The levels are OWNER, GROUP and ALL

MENUUSERS MenuUsers | ALL

The | ALL parameter in this example sets it to default to being accessible to ALL on first being booted.

If it is set to GROUP, members having the same activated group tag as the MLP object is set to can access the menu (note: you can restrict access to sub-menus on a per menu basis. See MENU 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


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.


POSE


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

POSE pname | anim1 | anim2 |anim3 |anim4 |ballcolour1|ballcolour2|ballcolour3|ballcolour4

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

Note: in technical terms, the | separator is called a PIPE symbol. It does not matter whether you prefer to go:

anim1|anim2|anim3|anim4

or to leave a space on either side of the PIPE symbol to increase readability like this:

anim1 | anim2 | anim3 | anim4

It's your choice.


REDO


Sometimes shown on menu items with a synonym, like this:

REDO REMENU

or

REDO RedoMenu

By default, when a user makes a choice on an MLP menu, the menu re-presents itself for further use. This feature is turned on by default in MLP.

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

In general practice, fewer and fewer MLP product makers offer this button to users, because turning off the menu coming back can create a user perception that something is broken.


RELOAD


Sometimes shown on menu items with a synonym, like this:

RELOAD Pos Reset    

Resets just the ~memory script, which in turn also resets the ~props script.

The ~memory script is the script that reads information in from the .POSITIONS card.


RESET


Sometimes shown on menu items with a synonym, like this:

RESET Menu Reset

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

The two scripts not restarted are: ~memory and ~run.


RESTART


Does what both RESET and RELOAD do, combined.

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


SAVE


Sometimes shown on menu items with a synonym, like this:

SAVE SAVEPOS  

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

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. It's only permanent when you do a DUMP and copy and paste the results to 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


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

To cause this command to appear on a menu, you do this:

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

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: the props 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


Causes any MLP pose balls rezzed to become visible, if they are not already. Not many MLP product makers bother with offering this command. The opposite is the HIDE command.


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.


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.

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.


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.

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 allow some TOMENU - slots on your main menu for the modules to be plugged into (as it were.)


Z


The Z command allows end users to easily adjust for themselves the height of the poseballs (note: only the height.)

You specify a range of whole numbers (aka "integers"), which can be positive or negative, proceeded by a Z.

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.

Clicking a Z-5 button, if offered, would decrease the height.

Note that 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, and clear the field.


Example:

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

Traditionally, MLP product makers have put these Z commands under the OPTIONS menu.

We now recommend, though, that they all be put together under a separate submenu called "HEIGHT."

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

Keyword Explanation
Animations (Facial)


You can cause an animation to also produce a facial expression on the person using the animation. To do this, you add to the animation name in the menuitems card a suffix (as per the table immediately following) specifying which facial animation you would like.

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 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.)


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



.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 notecard provides a safety against losing your work.

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. [2]

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>

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.


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 after other animations, the rotation will come out off in a zillion different ways. The problem is animations that have their hip position the same in their T frame and first animation frame. SL ignores that. 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.



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.

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! 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), there will be no floating text, and the right-click menu 'sit' choice text becomes the system default of just "sit".



TIP! "Couldn't find (script)" error

If you get a message like this upon first dragging and dropping the MLPv2 scripts into a prim, disregard it. It occurs because a prim contents are very slow to refresh in SL, and one script thinks another one is not there yet. Do nothing; it will sort itself out in a few seconds.



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! Editing the notecards

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. 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 the add-on stuff in, 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.

The number of modules you can offer is constrained by the number 12. That is the maximum number of buttons (an SL scripting limitation) that can be offered on the main menu. If the core product uses up 7 of those buttons, then you can offer a maximum of 5 add-on modules.

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 represents whatever name of the module.) If this module uses props, you also create a .props.xxx notecard.

A .menuitems card for a module gets no directives, no default or stand pose, etc. It gets only the actual menu being added and the associated poses.

Example:

MENU myAddOns | ALL | PINK | PINK | BLUE
 POSE Whoohoo!| Bump1 | Bump2 | Bump3


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 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 alphabetical order.

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



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! 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. For any pose, you can have at most one prop. 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.

To add a prop, edit a .PROPS notecard r 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 "~pillow") 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!



TIP! "Script run-time error / Stack-Heap Collision"

This is a clue that, sadly, there are too many items in your .menuitems.xxx or .positions.xxx notecards for the script memory to handle. Congratulations, you've just been initiated into the battle-scarred club like the rest of us.

First, make sure you have no unused positions stored in any .positions notecards. See tidying tip above. Restart and see if that helps.

The next step is more drastic. You must give up on some poses, and cull their POSE lines from the .menuitems card, and their position settings from the .positions card. You may leave the actual animations in the MLPv2 prim, but you might as well remove them as they won't be used anyway.



  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.