MLPV2 Reference Manual

== .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. 
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().	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 	
CHAT 	
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)	
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 	
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()
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. 
(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 ==
== 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);
== 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
Category:MLPV2