Difference between revisions of "MLPV2 Tutorial"

Latest revision as of 14:28, 25 September 2015

MLPV2

For users:

For users and builders:

For builders:

This tutorial is intended for : people adding poses to furniture.

Folks who just want to know how to use their furniture should see MLPV2 Users Tutorial.

Setting up MLPV2

These instructions look long, but it's easier than it looks. Here's the overview:

get the scripts and notecards and drop them into a prim (CREATE YOUR OWN PRIM -- so folks know who made it!)
put your anims in the same prim
Create and edit one or more .MENUITEMS.* notecards (use whatever you want for "*"). Configure menus and add poses to the menus. Mostly the same as old MLP, with enhancements and no need to edit the main menu.)
Reset and try the menu
adust each pose (same way as old MLP)
dump memory and save positions in notecard (nearly same way as old MLP; sellers may want to use modular .POSITIONS.* files)

These instructions are oriented for someone setting up a new object. However, those who bought one and are adjusting it or adding poses can simply skip the obvious steps that the maker would already have done.

Get the scripts

The latest scripts are available at jPose Island, in the FREEBIES section. It is Adult land, so you will need to either have payment info on file or be adult certified.

MLPV2.3 is available on Marketplace, under Lear Cale as merchant.

Take a good look at the .readme file.

Install scripts

Rez the MLPV2 and copy its contents into inventory and then into your furniture.

Delete the notecards ending in "examples", along with the ~pillow object and any example animations you don't plan to use.

Life is easiest if you use your object's root prim for MLPV2; instructions below for when it's not. For your first try, stick with root prim and keep life simple. (An easy way to add it to an existing bed is to just float it slightly above your mattress and then apply a totally clear texture, available in any freebie depot.) Below, we'll call this prim the "MLP prim".

[Tip: You'll thank yourself later in life if you try to keep the orientation of the MLP prim the same across your products, for example, with rotation 0,0,0. This makes it easier to transfer poses between products. However, with sculpties this isn't always feasible.]

Click the MLP prim so that it starts up for the first time. If you get a menu, fine; you've already done this. If nothing happens, click again -- an SL bug causes the first click to get lost.

Install animations

Drag all the anims you'll use into the prim. (You can pull these out of poseballs you like. If the animations are no-copy, this will render the poseballs useless.)

Note: not all animations will work with MLP. See discussion here: MLPV2_Reference_Manual#TIP.21_Animations_Caveat

Create and edit your .MENUITEMS.* file

Create a new notecard, named ".MENUITEMS.mystuff", where "mystuff" can be anything you want. MLPV2 can take any number of these, and bed sellers can make different pose sets for different customers.

Click for graphic view

Drop this notecard into the object. [You might want to do most of the editing first; objects with lots of things in inventory react slowly to changes, and you might have a lot of animations. As of Nov/2009, there's also an issue with editing notecards in object inventory. Unless you've heard the "all clear" on this, or know the workaround, it's best to edit in your avatar inventory.]

Create a menu:

MENU MyMenu | ALL | PINK | BLUE

[Tip! The standard practice is to list the pink ball first, then the blue -- you may do the opposite if you wish, but for what it's worth, that's the convention. This convention was established in 2006 with the release of MLP 1.1, and is practised in XPOSE! as well.]

This creates a menu whose button in the top menu will be labeled MyMenu. ALL indicates that it will be accessible by everyone (alternatives here are GROUP, only allowing people in the same group as the object, or OWNER, only allowing the owner). After that, list each ball color for the poses in this menu. You can have up to six balls. If you have some solo poses, some couples poses, and some 3some poses, they have to be in different menus.

In this example, a pink and a blue poseball will be rezzed.

For each pose in this menu, add a line like this:

POSE pose1 | anim1 | anim2

where

pose1 will be the button name for this pose.

anim1 is the name of the animation for the first poseball (which happens to be pink in our example)

anim2 is the name of the animation for the second poseball (which happens to be blue in our example)

Zero, one, or two spaces are allowed around the vertical bars. Avoid extra spaces.

For facial expressions, you add a suffix to the animation names indicating the expression. Note that you don't change the actual name of the animation in the inventory, you just add the suffix in this configuration notecard. These are explained in MLPV2_Reference_Manual#Animations_.28Facial.29 . For a simple example, appending "*" will give an astonished open-mouth expression.

The following can also be included in your menu:

STOP
SWAP
BACK
TOMENU MyOtherMenu

STOP makes a button labeled STOP that de-rezzes the poseballs and unsits everyone.

SWAP makes a button labeled SWAP that exchanges the first two balls, by default. Starting with MLPV2.4, you can configure the swap arrangements for poses with multiple balls, [LINNK TBD].

BACK makes a button labeled BACK that goes back to the previous menu. Every menu should have one of these!

TOMENU makes a button labeled MyOtherMenu, which goes to the MyOtherMenu menu (which you must create).

With MLPV2 (assuming you're using the .MENUITEMS that comes with MLPV2 rather than an old MLP configuration), any MENU that is not found in a previous TOMENU entry is added to an empty slot in the top menu. I'll talk more about this below, under MLPV2 Submenus.

It's a good convention to end each menu with the following:

SWAP
STOP
BACK

For MLPV2 (again, assuming you're using the .MENUITEMS that comes with MLPV2 rather than an old MLP config), buttons are placed in the menu in the same order they appear in the config notecard. To set old MLP configs to using this new (sane) menu order, see here: [1]

Repeat the above for each menu you want. Poses with different numbers of participants have to be in different menus, since the MENU line gives the number and colors of the balls.

For a menu with 3 or more poses, the POSE line would list that number of animations, separated by vertical bars ("|").

Continuation menus

As we all know, you get at most 12 buttons in an SL menu. However, starting with MLPV2.1, you can have more than 12 buttons in a configured MENU. If there are more than 12, MLPV2.1 and later will automatically add a MORE--> button after the 11th item, leading to the remaining choices. (And also after the 22nd item, etc.)

If you wish MLPV2 to automatically a BACK button whenever it adds a MORE--> button, add the AUTOBACK directive to your .MENUITEMS config card. It doesn't matter where it is, but convention is to put it near the top. Put it alone on a line.

Note that a BACK button will not be added to the top, main menu (because there is no further back there to go back up to.) Nor will it add it to the last page of a series of sub-menu pages, or to a single-page sub-menu -- you must add the word BACK yourself manually to these if desired.

Menu Reset

Save your changes. (If you're editing a copy in inventory, install it in the MLPV2 prim).

Click the MLPV2 object. If this is the first time since you installed the scripts, it will start up and read the configurations. If you get a menu, select OPTIONS -> ShutDown -> Menu Reset. This button causes it to re-read all .MENUITEMS* files, including yours.

Watch for warning messages. The most common one is due to an animation being missing or misspelled in the configuration. Fix any mistakes and do another Menu Reset. (A reset is not required for missing animations; just drop in the anim. If you don't have some of them yet, don't worry, this won't do any harm.

Click to get the menu. You should see the button for your new menu; click it. You should see the menu you configured. Click the first pose. You should see the right number and color balls appear. They may be in odd places.

Tip! Note that "MenuReset" will not re-read positions from the positions card. PosReset and Restart will.

The default pose

The "default pose" is a set of poseball positions and orientations that is used for any new pose, since new poses don't have saved positions yet.

The default pose in the MLPV2 distribution assumes that the MLPV2 prim is essentially an unrotated box, flattened and stretched like a mattress cover. If your prim is rotated (as is likely if you're using a flattened cylinder lying on its side for the mattress, and MLPV2 is in the mattress), you will want to adjust the default pose so none of the balls are underground.

Go to main blue menu and select adj-default -> default.

Tip! If you don't have this choice, see here: [2]

If the default pose looks fine (6 balls arranged in a hexagon, avs sitting facing each other), skip this step.

If the default pose looks wrong, adjust it following the instructions below, as for any pose you would add. You may have to be clever to get at balls that might end up under the floor or buried in your object.

When saving the default pose as described below, be sure to save it to the .POSITIONS notecard, rather than to your .POSITIONS.mystuff notecard.

The stand pose

MLPV2 uses the stand pose whenever STOP is used (or on any reset button in the Shutdown menu), just before unseating the avatars. This helps avoid them popping high into the sky, which happens when poseballs are buried inside the object.

I suggest using the default pose for the stand pose. Simply duplicate the "{default} ..." line in .POSITIONS and change "default" to "stand".

Adjusting poses

MLPV2.3 and later

Select OPTIONS -> Adjust Pos at any time. Whenever anyone is sitting on a poseball, it will be long and translucent to be easy to find and select. We call these "beams". Participants can hop on and off balls at any time during adjustment.
Select the beams (right-click -> Edit) and adjust them as desired. When done with a pose, simply select the next pose. The current pose's position is automatically saved. Also, you can save the current pose's position at any time using OPTIONS -> Save Pos.
To undo changes to the current pose, just select it again. Alternatively, just quit adjusting.
To quit adjusting, make sure the current pose is saved (if desired), and use either STOP or OPTIONS -> Adjust Pos. (Stop will also delete the balls and pop off any participants.)

MLPV2.2 and earlier

Use the menu to select whichever pose you want to adjust. If it's a new pose, it will get the default pose. Have avatars sit on the poseballs. Use the menu OPTIONS -> Adjust Pos to make the poseballs visible and easy to select for editing. (They get long and translucent, so we call them "beams".)
Select the beams and orient them as desired. When done, use the OPTIONS -> SavePos button.
You may continue with the next pose, or re-adjust this one. When someone stands, their poseball will go back to the normal shape. Just click the AdjustPos button to make it a beam again.
The AdjustPos button's only affect is to change the size and appearance of the poseballs. Feel free to adjust positions by selecting the clear tiny sat-upon poseballs and moving them, if you prefer.

Saving pose positions to notecards

NOTE WELL: The SavePos button saves the position in MLPV2 memory. A reset will cause it to forget. End users will probably want to save the changes to notecards, and sellers will need to.

This is why the .POSITIONS notecard should be ideally released to customers as MODIFY. Note as well, though, that if a notecard is placed in a no modify object, people will not be able to open the notecard at all, regardless of the perms on the notecard. This is a SL system limitation.

NOTE: The ~swap script has to be in and running to save new positions! [for MLPV2.4 and later]

Saving pose positions, new object

Follow these instructions if this is a new object and you plan to sell it and possibly a line of related objects with MLPV2 poses. There is a simpler way for end users, below.

Create a .POSITIONS.mystuff notecard, where mystuff matches your .MENUITEMS.mystuff file name. (This isn't absolutely required, but makes life simple and I will assume that convention is followed in this tutorial.)

Use OPTIONS -> Dump Pos to dump all the positions. Using the chat history window, copy the text between the "-----" lines, which looks something like this:

 [xx:xx]  : {pose1} <... numbers ...>

Paste them into your notecard. It isn't necessary to delete the stuff to the left of {pose1}, but you can if you like things tidy.

Delete the {default} line. (Note: if you changed the default pose, save this line in .POSITIONS notecard.) Delete the {stand} line. (Note: if you changed the stand pose, save this line in .POSITIONS notecard.)

Save, and use OPTIONS -> ShutDown -> PosReset. This causes the .POSITIONS.* files to be re-read, including yours.

That's about it; now you're ready to test your poses. Have fun!

Tip! For those using old MLP .MENUITEMS files: If the PosReset button is not offered, look for the RESTART option. Note that RESET will not re-read positions from the positions card. Only PosReset and RESTART will.

Saving a single position that you've updated

When you use OPTIONS -> SavePos for, say, pose1, you'll see a line in chat looking like this:

MLPV2 (empty): {pose1} <... numbers ...>

There may be a timestamp. You can copy this line and replace it in the corresponding .POSITION.* file (e.g., the one already containing this pose's position).

Saving pose positions, simplified version for end users

If you're adjusting an object you bought that's already set up, and you've adjusted a lot of poses, this is the easiest way to save all your changes. Note, however, that if your product has pose pack modules and you might want to remove one to make room for other add-on poses, this might not be the best way.

Use OPTIONS -> Dump Pos to dump all the positions. Using the chat history window, copy the text between the "-----" lines, which looks something like this:

MLPV2 (empty): {pose1} <... numbers ...>

It may include a timestamp.

Paste them into the .POSITIONS notecard, replacing its previous contents. It is not necessary to delete the stuff before {pose1}, but you can if you like things tidy.

Delete all other .POSITIONS.* files in the MLPV2 prim's inventory.

If you later decide to delete a pose pack (a .MENUITEMS.* file) with poses you won't use, you can still do that. The positions for those poses will still be in the .POSITIONS notecard, and you can feel free to delete them manually.

Deleting adj-default menu button

Once you're happy with the default pose positions, simply delete .MENUITEMS.zz-default from the MLPV2 prim's inventory. You can always put it back by dragging that file from the MLPV2 distribution.

PROPS

Beginning with MLPV2.1, you can provide prop objects that MLP will rez for specific poses.

When you choose another pose or hit STOP, any rezzed prop disappears. If you delete the MLP object, any prop will disappear in a few minutes.

For any pose, you can have at most one prop object. If you need more than one prop to rez, you'll have to link them so that they can be treated by MLPV2 as one object.

1) The following lines are required in your MLP menu. Starting with MLPV2.1, they're already in the standard .MENUITEMS, in the OPTIONS menu. Add them if you're starting with an older version.

*LINKMSG DumpProps | 0,-4,1,DUMPPROPS    // dump all prop configs
*LINKMSG SaveProp | 0,-4,1,SAVEPROP      // save position/rotation for a prop

2) Find the prim prop object that you want MLP to rez, and rez it.

3) Add to this prop object the "~prop" script (you'll find this inside the supplied "~pillow" object). Take your prop object back into inventory and drop it into the MLP prim's inventory. Note: the prop object and everything in it will need to be copiable for next owner -- otherwise, it will only rez once for them!

4) Edit a .PROPS notecard or add a new one (named .PROPS.* where * is whatever you want, for a modular config.) Copy this example line and paste it into your .PROPS file.

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

(Don't omit the vertical bar ("|") at the left.)

*Replace "mypose" with the name of the pose that the object should rez for.

*Replace "myobject" with the name of the prop object. The object name cannot contain vertical bars.

Save your work.

5) Use the MLP menu's PosReset or Restart button. When the MLP has restarted, select the pose that the prop goes with. The prop should appear. It might be underneath the MLP object, or some distance away, so look around -- it may be best to do this using a single prim MLP floating in the air, the first time.

6) Edit the prop, and use the editing arrows to move the prop to where you want it. Then, use the MLP menu "SaveProp" button.

To make the change permanent, select the text in the chat line (including the first vertical bar, and optionally any text before it) and replace the corresponding line in your .PROPS* file. Or, do all your props, saving their positions, and then use the DumpProps button. This works the same way as saving positions in .POSITIONS* files.

7) To get MLP to reread .PROPS* files, use PosReset (which resets positions as well as props), or Restart.

Keep in mind that props and positions are saved separately, so if you adjust a pose and its prop, you need to save both pose position and prop. (When using AdjustPos feature with MLPV2.4 or later, both pose and prop positions are saved when you select a new pose.)

Worn or Hand-held Props: For props to be worn by the user, use the ~give script add-on found here MLPV2_Give_Item_Add-on and have people wear the items.

SEQUENCES

Starting with MLPV2.3, you can create sequences of poses that run automatically once started.

It's a little complicated. You need to:

set up menus (and often poses as well) for the sequences to use
set up a control menu for the user to access and control the sequences
program the sequences

1. Set up the menus (and poses)

In a .MENUITEMS.* notecard, create menus for the sequences to use. These menus:

(a) tell sequences how many balls to rez, and of what colour;
(b) are used to set up poses for the sequences

If your sequence will use poses that are already in your menus, you're done here, nothing special to do.

If your sequence will use poses that you don't want to appear in any menu, you need to set up a "hidden menu". To do this, just make a menu the usual way, except use "HIDDEN" rather than "ALL", "GROUP", or "OWNER", like this:

MENU ROMNIGHT | HIDDEN | PINK | BLUE

Add your poses to this menu. Avoid extra spaces, especially between MENU and the menu name.

If you have sequences with different numbers of participants, you'll need to use additional menus with the appropriate number and color poseballs.

2. Create a control menu for the sequence(s)

See the .MENUITEMS.example notecard in MLPV2 distribution as an example. This menu has two buttons to start sequences, and two buttons to stop and continue them, along with the usual navigation and swap buttons:

// example menu containing 2 sequences, and sequence controls
MENU Tours... | ALL
LINKMSG *Tour1* | 0,-4,-12001,SEQUENCE Tour1-seq
LINKMSG *Tour2* | 0,-4,-12001,SEQUENCE tour2-seq
LINKMSG PAUSE | 0,-4,-12001,PAUSE
LINKMSG RESUME | 0,-4,-12001,RESUME
LINKMSG NARRATION | 0,-4,-12001,NARRATION
SWAP
STOP
BACK

In the above, "*Tour1*" and "*Tour2*" are button labels -- that's what the user will see in the menu. The "| 0,-4,-12001,SEQUENCE" part is pure magic, don't mess with that unless you're a magician. "Tour1-seq" and "tour2-seq" are names of sequences in the .SEQUENCE* notecards. Be careful: the names need to match exactly.

PAUSE causes the sequence to stop advancing.

RESUME causes the sequence to resume where it left off. Alternatively, if you didn't PAUSE, RESUME advances to the next step. This is handy for quickly testing a sequence with long wait times.

NARRATION allows the user to toggle off and on any WHISPER or SAY messages you might have programmed.

STOP stops the sequence and unrezzes the balls. After a STOP, RESUME and PAUSE have no effect.

NOTE WELL Avoid having two different buttons in an MLP/MLPV2 menu with the same button name. Only the first of the two will work. Subsequent ones (duplicates) will only cause the first button's effect. (It's OK to have the same button appear in multiple places, if you want them all to do the same thing. BUT:

LINKMSG PLAYALL | 0,-4,-12001,SEQUENCE MASSAGESCENE-seq

and

LINKMSG PLAYALL | 0,-4,-12001,SEQUENCE BJSCENE-seq

in the same menu will cause havok, as the menu will get confused about the duplicate button label of PLAYALL

3. Programming a sequence

Create a notecard whose name starts with .SEQUENCES, followed by whatever you wish. In the MLPV2 distribution, this is .SEQUENCES.example. I'll go through an example sequence explaining what each line does.

Start the sequence with the sequence name specified in the control menu in .MENUITEMS file; in this case, "Tour1-seq". The name is arbitrary, it just has to match between the MENUITEMS notecard and the SEQUENCES notecard. For example:

SEQUENCE | Tour1-seq

Next, give it the name of a menu to use to model itself after for setting the number and color of balls. You can change the menu later in the sequence using more MENU lines.

MENU | Example

Note the vertical bar ("|"), unlike in a .MENUITEMS* card. Note as well that all you put is the name of the menu, and not the stuff that would follow it in a .MENUITEMS* card.

Now, program the steps in the sequence as poses followed by timed pauses, and possibly waiting for participants to hop on. (Note the pipe symbol | required, unlike in the .MENUITEMS card. Note as well that you only list the name of the pose -- not any associated animation.)

POSE | standing

The line above starts the "standing" pose.

Important: The sequencer script currently (2011) won't give you any error messages if the Pose you reference doesn't actually exist. You're on your own here, Bernice, to get it right!

AVWAIT | 0 | Waiting for someone to sit on blue ball

The line above causes the sequence to wait for someone to sit on ~ball0. (To see which ball a ball is, pick the pose using the menu and right-click->Edit the ball. The number at the end of the name is the number to put between the "|" characters above.) The text after the final "|" is optional; it's what the object chats if it needs to wait.

You can specify any number of balls here; for example, you can use:

AVWAIT | 0 1 2 3 | Waiting for all participants!

Important: Any looping sequence should have an AVWAIT in the loop. We don't want to disturb the neighborhood with an unused bed running endlessly through a sequence. In a future version, Lear might in fact make it an error to have a loop without an avwait.

WHISPER | 0 | /0 and /1 stand together

The line above causes the object to whisper the given line on channel 0 (the number between the "|" characters). "/0" through "/5" get substituted with the first name of the av on the corresponding ball. If nobody is on the ball, it uses "somebody".

WAIT | 10

The line above causes the sequence to wait for 10 seconds before proceeding.

POSE | pillow-sit | 0 | /0 and /1 sit with a comfy pillow

The line above selects a new pose and whispers the text on channel 0. Note that we omitted this optional chat in the POSE line above. As earlier, /0 and /1 are replaced with the participant's first names. Although you have two poses within the 10m rule, if the next pose in the sequence is 10m+ from the previous pose the balls won't go the distance.

WAIT | 10
POSE | sit2 | 0 | The pillow disappears
WAIT | 10

You should know by now what the lines above do.

Programming a loop

The next line causes the whole sequence to repeat.

REPEAT

Alternatively, you can use a LABEL line anywhere in the sequence, and end the sequence with a GOTO line, as in the other example provided with the MLPV2 distribution:

LABEL | mylabel
AVWAIT | 0 1|   //make sure we're not looping with no one using the balls, so check for people on both ball0 and ball1
...
...
GOTO | mylabel

TIP! Don't re-use a label name twice in the same sequence notecard or funky things may happen.

Or, you can just have the sequence end by not adding any more steps (or, by starting a new sequence). If the sequence doesn't end with GOTO or REPEAT, it simply pauses at the end, leaving the participants in the last pose.

TIP! It doesn't matter whether you leave spaces or not around the | symbol; the sequences script will sort it out.

Avoiding the posename chat

By default, MLPV2 chats the pose name whenever it starts, either by menu or sequence. If you don't want it chatting pose names during sequence, add "| NOCHAT" to the end of the SEQUENCE line, like this:

SEQUENCE | Tour1-seq | NOCHAT

Hiding the poses from the menu

You can hide any MENU in the notecards from the user by using "HIDDEN" instead of "ALL", "GROUP", or "OWNER", as below:

MENU | seq1-poses | HIDDEN | PINK | BLUE

Put your sequenced poses in such a menu and they'll be invisible to the user. Just remember to set up the pose positions before hiding the menu they're in! Of course, you can use "Adjust pos", PAUSE in the sequence, and adjust.

TIP: Sequence naming rules

A sequence has

a button name
a sequence name

The button name and sequence name appear in the .MENUITEMS.myStuff notecard:

LINKMSG Cuddle | 0,-4,-12001,SEQUENCE WarmUp

Cuddle is the button name, WarmUp is the sequence name.

The sequence name also appears in the .SEQUENCES.myStuff notecard:

SEQUENCE | WarmUp

This is the fist line of the sequence. WarmUp is the sequence name. It must exactly match the sequence name (WarmUp) in the LINKMSG line in the .MENUITEMS.myStuff notecard!

The button name does not need to match the sequence name. It's OK if it does.

Configurable SWAPs

By default, the SWAP button swaps the first two balls, which is appropriate for couples poses. Therefore, there is no need to configure swaps for solo and couples poses.

For poses with 3 or more parties, you may want to configure what the swap button does. In this case, the button will cycle through a set of ball orders for the pose.

It's confusing, but stick with me and we'll muddle through. Here's the big picture. Each line in the .SWAPS.myStuff notecard configures the swaps for one pose. (I would rather have done it per menu, but that just didn't work out, sorry!)

For a pose, we configure a set of ball permutations (arrangements, or orders). When the user hits SWAP, the balls will cycle through the given permutations. The first perumtation is always 0 1 2 3 4 5, meaning that ball0 is first, ball1 is second, ball2 is next, etc. (For a PINK | BLUE | RED menu, ball0 is pink, ball1 is blue, and ball2 is red.)

Since the "0 1 2 3 4 5" permutation is the default, it is NOT configured but is assumed. We only configure the 2nd, 3rd, and subsequent permutation (as many as we like).

Each line of the swap configuration notecard looks like this:

posename | permu2 : permu3

where there can be any number of permutations, separated by a colon (":").

As mentioned above, the orders are given by a list of poseball position numbers.

Let's look at an example, with a 3-ball menu that uses PINK | BLUE | RED balls. Let's say we want the pink and red balls to swap, but leave the blue ball alone.

So, the permutations would be first the implicit 0 1 2 permutation, and then the swapped one, which in this case would be 2 1 0. It would be configured like this:

fmf-cuddle | 2 1 0

where fmf-cuddle is the pose name.

Confused yet? Yeah, me too. Now let's try a 3some pose where we want to rotate all three. For example, they're sitting around a round table, and we just want each one to move one position to the side.

The first permutation is always 0 1 2.

For the next permutation, we want 2 0 1. Balls 0 and 1 move right one place, and ball 2 slips back around to the first position.

For the next permutation, we want 1 2 0. Balls 2 and 0 move right one place, and ball 1 slips back around to the first position.

We'd configure it like this. Remember we omit the first permutation, since it's the default permutation and is implicit:

3-sitting | 2 0 1 : 1 2 0

When we hit SWAP the first time, we get the 2 0 1 permutation. Hit it again, we get 1 2 0. Hit it again and we go back to 0 1 2, the implicit default permutation. And so on, until the avatars get dizzy.

When I configure swaps, I actually write down the default permutation and keep it there to help me think, and then delete it when I create the pose configuration line.

Now let's try a two couples 4some for a PINK BLUE RED GREEN menu (female, male, female, male), where first we want the females to swap, and then we want the males to swap. I'll start out with the default permutation shown because it helps my feeble mind. Then I'll put the subsequent permutations below, in sequence.

0 1 2 3 - default
2 1 0 3 - females swapped

for the next one, let's swap the men but leave the women swapped:

2 3 0 1 - females swapped, males swapped

Are we done? Well, if we stopped here, the next click on SWAP would move all 4 balls. Instead, let's swap the men again, and then moving back to the default will only swap the women.

0 3 2 1 - males swapped

So, putting them all together:

0 1 2 3 - default
2 1 0 3 - females swapped
2 3 0 1 - females swapped, males swapped
0 3 2 1 - males swapped

I hope you're getting the picture by now. If your head hurts, well, mine does too. Just try doing some 6some swaps for real fun!

Here's the resulting configuration line:

Swingers | 2 1 0 3 : 2 3 0 1 : 0 3 2 1

NOTE: I did not test these configs, and I make mistakes. I'll try to find time to test. In the meantime, please feel free to try it out and please let me know of any mistakes.

Here are some common useful swaps, including the examples above. Delete the comments before using, and of course, replace the name I've given here with the actual pose name.

3somes

mfm-mfm | 2 0 1 : 1 2 0                                // swap first & third of 3some
3-swap-other | 0 2 1                                   // swap 2nd pair of 3some
3-rotate-1 | 2 0 1 : 1 2 0                             // rotate three, one direction
3-rotate-2 | 1 2 0 : 2 0 1                             // rotate three, other direction
3-all | 0 1 2 : 0 2 1 : 2 0 1 : 2 1 0 : 1 2 0 : 1 0 2  // all permutations

4somes

Swingers | 2 1 0 3 : 2 3 0 1 : 0 3 2 1
fmmm-rotate-m | 0 2 3 1 : 0 3 1 2                      // hold 0, rotate others
mfmm-rotate-m | 2 1 3 0 : 3 1 0 2                      // hold 1, rotate others

5somes

fmfmf | 2 1 4 3 0 : 2 3 4 1 0 : 4 3 0 1 2 : 4 1 0 3 2  // alternately rotate women, swap men

Tips

Expandability

For expandability, we recommend that each .MENUITEMS* file contain one "unanchored" menu at the top, with any submenus in the notecard hanging off of that unanchored one. This allows 10 independent modules and only memory limitations on the total number of menus. We also suggest dividing menus & positions into separate notecards making it easy for customers to delete the ones they won't use.

(An "unanchored" menu is one that doesn't have any TOMENU button leading to it.)

MLPV2 loads the notecards in the same order they appear in object inventory. The buttons for the unanchored menus in these notecards are added to the main menu in the same order. So, name your extensions so your notecards sort in the order you want these buttons to appear.

Main menu

By convention, the top, "main menu" often includes buttons such as OPTIONS, SHUTDOWN, etc, as well as buttons providing access to the sub-menus. By convention, this menu is defined in the .MENUITEMS notecard (note, no suffix).

Don't attempt to put actual poses in the menus found here. They won't work reliably, since these menus don't list the number and color of poseballs.

Help button

You may wish to add at this top level a HELP button.

The configuration would be something like this:

LINKMSG HELP | 1,-4,987789,-Help for XYZProduct##Here's your help notecard

Put this line at the end of the "TOMENU -" lines below MAIN MENU.

Then drop in the ~give script add-on found here MLPV2_Give_Item_Add-on

It might be better to name the help notecard something other than just "Help", so that your users can identify it more easily when it ends up in their inventories.