Initial commit.

This is the current alpha version, it was time to put it somewhere.

1 files changed, 532 insertions, 0 deletions

diff --git a/README.md b/README.md
index 992f454..8c9ab96 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,534 @@
 # MLP-lite
 A lighter version of the MLP scripts, built for OpenSim.
+
+MLP lite v3.0 for OpenSim is almost a complete rewrite by onefang
+rejected, of the venerable MLP scripts.  It uses OpenSim specific
+functions, so wont work in Second Life.  It might not work on some
+OpenSim grids or sims, due to the use of OpenSim specific "high threat
+level" functions.  Test it first before putting it in anything important.
+
+The main justification for this rewrite is that I have about a dozen
+OpenSim sims, some with dozens of copies of MLP running.  So this
+variation uses some OpenSim specific LSL functions, tries to use less 
+resources, be quicker, and automatically shuts down when no one is
+around.  Some functions where removed, hence the "lite" in the name, most
+of these seem to not be used, or useful, or just don't get used in my
+sims.  Note that I've not extensively tested any of this stuff yet.  It's
+not a huge improvement, but when you have dozens of the things, every
+little bit helps.  And then I added more features.  lol
+
+Note that some of the OpenSim functions used are what OpenSim classes as
+"high threat level".  More about that below.  This means that these
+scripts wont work without some tweaking of your grid / sims 
+configuration.  This has only been tested in my hacked up version of
+OpenSim 0.8.2, which removes a lot of the insane threat levels and script
+delays, so anything I say about speed improvements might not apply.  I
+did at least remove script delays in both LL and OS functions.  If
+nothing works for you, this is likely why, and you should go back to the
+old scripts.  Test it first before upgrading anything that's not full
+perm.
+
+Based on the original MLP - MULTI-LOVE-POSE V1.2 - Copyright (c) 2006, by
+Miffy Fluffy (BSD License).  This code has bounced around Second Life and
+OpenSim for over a decade, with various people working on it.  I can't
+compile a complete list, as I have no idea of the complete history of the
+versions I have received.  The names I do know coz they where in the
+source code (in no particular order) - Miffy Fluffy, Learjeff Innis, Jez
+Ember, Liz Silverstein, Zonax Delorean, Purrcat Miranda, and Kokoro
+Fasching.  Apologies to anyone who's code is in this variation and I
+haven't mentioned you.  It's likely that some or all of the code written
+by these people is no longer in this variation.  Thanks to you all.
+
+This variation is still BSD licensed.  The text of the BSD license wasn't
+included in any of the versions I have, but it's a simple and standard
+license, you should easily find copies all over the Internet, or a 
+simple search.  The versions I have seen don't specify which variation of
+the BSD license, so I wont either.  GitHub insists on a license file, so
+I went with 3 clause BSD.
+
+The next two sections of this document is mostly copied from the .readme
+file I got with the latest MLP versions I had laying around.
+
+================================================
+
+FEATURES:
+- Put all your poseball animations into one object (110 pairs or even more
+should be no problem).
+- Create submenus for each category of poses, for instance: "Solo,
+Boy-Girl, Girl-Girl, Dance, 3some, 4some"
+- Shows up to nine poseballs depending on the submenu you select
+- Positions can be adjusted and saved into memory or notecard.
+- Portable, can be worn and used everywhere
+- Option to adjust height offset (Z) of all poses at once (for different
+persons/locations).
+- 15 poseball colours:
+    PINK, BLUE, PINK2, BLUE2, GREEN, MAGENTA, RED, ORANGE, WHITE, BLACK,
+    YELLOW, CYAN, RED2, TEAL, GREEN2
+
+OPERATION:
+- Click the MLP object to switch it on.
+- When everything has loaded the main menu will appear.
+- Select a submenu containing poses, and select a pose.  Pose balls will
+appear.
+- Sit on your pose ball (Right-click - LOVE).
+- To remove the balls, select 'EXTRAS>>' then 'STOP', or just walk away,
+it will shut down automatically when no one is around.
+
+TO ADJUST POSITIONS:
+You can adjust the poses to fit your own avatar and those you share MLP
+with.
+- Select a pose you want to adjust and sit on the balls.
+- Select 'EXTRAS>> ' then 'ADJUST'.  This changes the balls into
+translucent beams.
+- Right-click a beam, select Edit and adjust the position (Shift-click to
+select more than one).
+- Position the balls anywhere within the sim.
+- 'EXTRAS>>', 'OPTIONS>>', then 'Save Pos' stores the positions into a
+new notecard.
+
+TO MAKE A BACKUP:
+Saved positions are stored in memory but are not permanent.  They are
+lost on script error (See "Script run-time error / Stack-Heap Collision"
+below).  They are also lost on shutdown/startup, or "Pos Reset".  To
+back the positions up more permanently you have to copy them into a
+new .POSITIONS notecard:
+- Select 'EXTRAS>>', 'OPTIONS>>', then 'Save Pos' .
+All original .POSITIONS* cards are copied to .backup.POSITIONS* cards.
+Prop positions are saved to .PROPS, so the same applies.
+
+Note: After changing any *.POSITIONS* files, use the 'Pos Reset' command
+to verify your changes, if desired.  This also helps to avoid losing
+changes due to Stack-Heap collisions.
+
+TO ADJUST HEIGHT OFFSET (Z):
+Select 'EXTRAS>>', 'OPTIONS>>', then'Height>>' and click the 'Z'-buttons,
+this will adjust the height for all poses.  Note: the offset height is
+stored in the objects Description, so any descriptions will be replaced.
+
+TO ADD POSES:
+Copy all animations into the MLP object (if you want to use existing pose
+balls, open them to rip their animations).  Note: you can use any object
+as MLP, just copy the MLP contents in the object of your choice. Open the
+.MENUITEMS and add the animations:
+
+POSE name | animation1 | animation2 ... 
+
+The changes will become active after MLP is (re)started.  Use the 'Menu
+Reset' command after changing 
+*.MENUITEMS* files.
+
+To give an expression to an animation, add one of the following suffixes
+to the anim name in the POSE line.  (Just add it to the POSE config line,
+don't change the anim name.)
+
+   Suffix / expression
+    *        open mouth
+    ::1      open mouth
+    ::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    sleeping (combination of disdain and smile, closest I could find)
+
+To make the expression happen periodically rather than constantly, add
+another extension and the period (in seconds).  This is mostly needed for
+those expressions that only last a short time.  For example, to use MyAnim 
+with open mouth every 5.5 seconds:
+
+    POSE Mypose | MyAnim::1::5.5
+
+TO ADD SOUNDS (buttons to play sounds), in a menu (just like a POSE
+button), add a line like this:
+
+    SOUND She moans | female-moan
+
+where "She moans" will be the button label, and "female-moan" is the
+sound to play, which must be in object inventory.  For sounds in menus
+with poses (rather than in a menu specifically for sounds) I recommend
+you begin the pose name with "☊" (which looks a bit like headphones, the
+best I could find for the purpose).  This serves as a clue to the user
+that the button plays a sound.
+
+TO CREATE ANIMATION SETS (menus):
+Create .MENUITEMS.xxx and .POSITIONS.xxx files (where xxx is whatever you
+want) and put the corresponding menu configs and poses in them.  This
+way you can deliver a bed with folders of add-on menus so the customer
+can choose what types of anims they want to add to the menu.  Note that
+you get at most 12 top menu choices.  The scripts read the .POSITIONS
+files in alphabetical order (and 
+.POSITIONS must be first).
+
+This also allows you to sell furniture with "enhancement packs", which
+are simply collections of .MENUITEMS.xxx, .POSITIONS.xxx, and the
+associated animations for the customer to drop into the furniture. 
+Customers can easily select furniture appearance and pose bundles
+independently!
+
+SWAPPING POSES:
+Each menu can have a swap command:
+
+    SWAP | 21
+
+Would be the default.  Note that this means before you hit the SWAP 
+button, the balls will be in the same order as listed in the MENU and
+POSE commands, after they would be reversed.  SWAP always assumes
+the unswapped condition is the order things are listed.  So 21 in the 
+above command means swap the first two balls.
+
+The default for more than two balls is to just fill out both strings with
+the remaining integers:
+
+    SWAP | 213456789
+
+This might be used to swap the last two balls only:
+
+    SWAP | 132
+
+Any number of swap patterns can be used:
+
+    SWAP | 132 | 321 | 312
+
+You can also use a different name for the button:
+
+    SWAP switch men | 213
+
+Also, the original one should be supported, that uses the default:
+
+    SWAP
+
+ACCESS TO THE MAIN MENU:
+The owner is the only one who can shutdown, in all cases.  Anyone
+can start it.
+- if 'MenuUser' is set to OWNER: the owner is the only one who can access
+the menus
+- if 'MenuUser' is set to ALL: anyone can access the MAIN MENU
+- if 'MenuUser' is set to GROUP: members of the same Group as the MLP
+object can access the 
+MAIN MENU (the MLP Group can set by right-clicking MLP and selecting
+Edit, More >> General tab - Group: Set) Note: even if "MenuUser" is set
+to ALL or GROUP, individual SUBMENUS can still be blocked (you can 
+define access for each submenu in .MENUITEMS, see examples in
+.MENUITEMS).
+
+PORTABLE USE:
+Attach the object to the HUD, you can use it's default shape and colour
+for clickable bar on one of the edges of your screen (to move HUD
+position: Right-click - Edit), you can edit
+colour/transparency/size/position.  Adjust the height offset (Z). Note:
+the balls will appear relative to the initial MLP position (to reset 
+where the balls appear, press STOP to remove the balls, and reselect a
+submenu to rez them again).
+
+================================================
+
+FAQ for END USERS:
+
+- Will my animations be lost if I lose a poseball?
+
+No.  The animations are not placed the balls, they remain in the main MLP
+object.  Don't worry about the poseballs, they are copies of the one in
+the MLP object.  A balls will commit suicide if left behind somewhere
+(the MLP object needs to be within the same sim).
+
+- Sometimes notecards or scripts won't open for editing, why?
+
+If the MLP object contains many things, access to it's contents can be
+slow, just keep waiting until it's all loaded.  Can take over a minute
+sometimes.
+
+- "Script run-time error / Stack-Heap Collision"?
+
+Right-click/Edit the object, and use SL menu: "Tools -> Reset Scripts in
+Selection" to reset. Any saved positions that were not backed up in
+.POSITIONS files are lost, so if your furniture has lots of poses (over
+50) and you save positions, be sure to back up regularly.  Use OPTIONS ->
+Pos Reset after changing .POSITIONS* files.
+
+FAQ for those who edit *.MENUITEMS files:
+
+- "Script run-time error / Stack-Heap Collision"?
+
+After a restart, this is a clue that there are too many items in
+*.MENUITEMS* or *.POSITIONS* files.  Trim the menu.
+
+- My new menu appears on the main page, rather than as a submenu where I
+configured it.  Why?
+
+Most likely, you named it differently in the MENU line versus the TOMENU
+line.  When MPL sees a MENU line, it looks for the same name in a TOMENU
+line.
+
+================================================
+
+UPGRADE GUIDE:
+
+For the sake of these instructions, let's say you want to upgrade the
+scripts in an object called "My Old Bed", this is what you would do.  
+These instructions assume that everything has copy permission.
+
+First rez My Old Bed in world somewhere.  If it is already in world, take
+a copy, in case things don't work out and you want to revert to the old
+scripts.  You could also move the scripts and things you are about to
+replace to a new folder, so you can put things back the way they where
+before.  Or just ignore any backups and cross your fingers.
+
+Remove the old MLP scripts, they will be named ~memory, ~menu, ~menucfg,
+~pos, ~pose, ~poser, ~poser 1, ~poser 2, ~poser 3, ~poser 4, ~poser 5,
+~run,  and you might also have optional scripts ~props, ~sequencer, and
+~timer.  Also remove the ~ball object.  There may be another script, I
+have never seen  one, that deals with PRIMTOUCH, my guess is it might be
+called ~primtouch.  Leave it alone, this new script should be compatible
+with it.  Since I have never seen that script, nor needed it, I dunno
+for sure.
+
+Drag the "~MLP lite for OpenSim" script into My Old Bed, and the new
+~ball object.  You should see "My Old Bed: OFF (touch to switch on)" in
+chat.
+
+My Old Bed might have some props in it, they will be objects other than
+~ball.  In typical examples I have seen there is a pillow, so lets use
+that as an example.  Drag pillow out of My Old Bed and into your
+inventory, into the same folder you are backing up everything else. 
+Remove pillow from My Old Bed.  Drag pillow onto the ground, edit it, and
+remove the ~prop script.  Replace that script with the new ~ball script. 
+Take pillow, then drag it into My Old Bed.  Add the "~MLP lite props"
+script to My Old Bed.
+
+You may want to update your .MENUITEMS, or just leave them as is.  Look
+at the examples for how it is now recommended to have them setup.  If you 
+do this take care of the OPTIONS menu, which is now called OPTIONS>> in
+this new .MENUITEMS.
+
+If you still want to edit the poses / props, or do any of the other
+tweaking, then you might want to add the "~MLP lite tools" script to My
+Old Bed.  Leave it out, or remove it, once My Old Bed is fully set up.
+
+================================================
+
+DIFFERENCES FOR THE MLP lite v3.0 for OpenSim VARIATION:
+
+As mentioned above, this variation drops a few rarely used features, and
+tries to make things a bit better for OpenSim users.  Note that some of
+the dropped features may be added back again in later versions, I dunno
+yet.
+
+- Up to nine avatars can be animated at once.
+
+- Menus no longer lock out other users when someone else is using it.
+
+- The SWAP command has been changed to something like the XPOSE SWAP
+command.  It's documented above.  The original MLP SWAP command works as
+it used to.
+
+- Changing menus no longer reverts any SWAP commands.  Though if the swap 
+command is different between menus, it wont let you swap again in the
+different menu.
+
+- Anyone can start up an MLP lite object, and they automatically shutdown
+if no one is around for a couple of minutes.  This makes it easy to setup
+public areas with publicly usable objects that don't soak up resources 
+when people forget to turn them off after using them.  The startup also
+prints the startup time.
+
+- After turning on an MLP object by touching it while it is turned off,
+the MAIN MENU is shown automatically to the person that started it.  I
+assume that the person that turned it on is just waiting for it to finish
+starting up so they can actually use it.  Actually the menu shows after
+loading menus, but before loading positions, but you can start to use it
+straight away.
+
+- The CHECK command no longer reloads things.  It also checks for
+permissions and animations that are not used, as well as a few other
+things.  It's in the ~MLP lite tools script.
+
+- Less scripts.  There are only two scripts now, "~MLP lite for OpenSim"
+is the main script, and ~ball in the ~ball and prop objects.  OpenSim
+doesn't seem to have any memory limits per script (usually the main 
+reason to split scripts like that), and it simplifies the code a lot if
+there is just one main script.  The ~ball script is much simpler.  Props
+use the ~ball script instead of ~prop.  There are two optional scripts,
+"~MLP lite props" is used in the main MLP object if you have any props,
+and "~MLP lite tools" is used by creators and editors if needed.
+
+- It may use a bit more CPU time when expressions are being used.  You
+may not notice.  A lag tester was added to help with this, expressions
+may slow down when it gets laggy.
+
+- Since we use some OpenSim functions that are considered high threat,
+you might need to tweak your OpenSim settings.  See below for details.
+
+- The default .MENUITEMS note card now includes an EXTRAS menu, for all
+those functions that usually go at the bottom of each menu, so you can
+fit more poses on each menu.  I suggest that "TOMENU EXTRAS>>" be added
+to the end of menus, along with "BACK" and maybe "SWAP"
+
+- Various creator and editing functions have been moved to the TOOLS>>
+menu, and the "~MLP lite tools" script.  You can leave this out if
+the MLP object is fully set up.
+
+- You no longer need to have the first two lines of .MENUITEMS as the
+"stand" and "default" POSE commands.  It wont hurt to include them.
+
+- MENUORDER is no longer supported, menu buttons appear in the same order
+they are on the .MENUITEMS* cards, coz that's the only sane way of doing
+it.
+
+- The MAIN MENU, first menu in .MENUITEMS, no longer needs a bunch of
+"TOMENU -" commands.
+
+- While the DUMP command still prints the positions in chat, SAVE now
+saves that to a fresh .POSITIONS notecard, so you no longer have
+to cut and paste to your old .POSITIONS cards.  The old cards are
+backed up, and the same applies to .PROPS cards that store props.
+
+- MLP lite remembers all editing of the pose balls, not just those done
+while in ADJUST mode, ADJUST now just makes the pose balls easier to
+edit.  This makes editing of lots of poses a lot quicker, and means you 
+can make quick fixes on the fly, and save them at the end if you want to.
+
+- The BALLUSERS, OFF, REDO, INVISIBLE, STAND, SHOW, HIDE, and AGAIN
+commands no longer exist.  They are rarely used, or just not needed.
+
+- The code that slices up long menus into shorter ones with "BACK" and
+"MORE", to fit in the Second Life 12 button menu limit has all been
+removed.  I was gonna rewrite that, but for various reasons decided to
+just drop it completely.  People can chop up their own submenus if they
+need this, and that's exactly what I have seen other furniture makers do. 
+As a bonus, there are no hard coded English menu or button names left in
+the code, so you can easily use MLP lite for other languages.  On  the
+other hand, all the messages are in English.  CHECK will let you know if
+your menus are too long.
+
+- Old ~prop scripts are not supported, use the new ~ball script instead,
+which means a bit of surgery needed on old props.
+
+- Sequences are not currently supported.
+
+- The REORIENT command, and various link messages, are not currently
+supported.  Some or all of these may come back.  Some of the existing
+link messages changed as well.  Combining the scripts meant that a lot
+of these link messages are no longer needed, but some external scripts
+may depend on them.
+
+- ZHAO support is gone.  None of the ZHAO based AOs I have seen in
+OpenSim support that.  Note that the ~MLPT-AutoZhao script says "This
+one supports AutoZhao, which is a ZHAO variant that turns of 
+automatically when you sit."  Which seems pointless, it's already doing
+the correct thing.  My own AO / swimmer does the correct thing to.
+
+- No Xcite support.  Xcite doesn't exist in OpenSim.
+
+- The STOP command now just stops all animations and puts away the balls,
+instead of switching to the "stand" animation.
+
+- Strided lists are used internally, in theory should use a little less
+memory than having separate lists for everything.
+
+- osMessageObject() is used instead of llSay() to communicate with the
+pose balls.  This will stop any cross talk issues, and save some script
+running time.  As a bonus, balls can be anywhere in the sim.
+
+- The OpenSim notecard reading functions are used instead of the clunky
+Second Life dataserver() functions.  Faster and cleaner code.
+
+- While the PRIMTOUCH command is still supported, it's script isn't here. 
+I never did have a copy of that script, and haven't needed to use it
+anyway.
+
+- There may be a thing or two I forgot to mention here.
+
+================================================
+
+OPENSIM THREAT LEVELS:
+
+OpenSim developers introduced a concept of "threat levels" for their new
+os* LSL functions.  In my not so humble opinion, they where very
+paranoid in assigning threat levels.  For this reason, these scripts may
+or may not work in any given grid or sim.  In my version of OpenSim I
+have removed or reduced the more insane threat levels, so YMMV.
+
+Refer to the OpenSim documentation for how to deal with this, or ask the
+person that runs your OpenSim grid / sim.
+
+- osAvatarPlayAnimation() and osAvatarStopAnimation()
+Threat level: VeryHigh, disabled by default.
+
+These two functions can animate any avatar with any animation in the
+objects inventory, without asking permission.  So I guess this threat
+level is warranted.  Also means one script can manage animations for more
+than one avatar, a limitation of the LL variety.
+
+Used to get rid of one of the annoying aspects of how MLP works, which
+often confuses newbies.  Also allowed me to reduce the code complexity
+and get rid of all those ~poser X scripts.
+
+- osGetRezzingObject()
+Threat level: none, enabled by default.
+
+Wow, no threat level, the only one.  lol
+
+Used to reduce the complexity of the communication between the MLP object
+and the balls.
+
+- osGetNumberOfNotecardLines(), osGetNotecard(), and osGetNotecardLine()
+Threat level: VeryHigh, only enabled for estate owners and managers by
+default.
+
+A faster and less complex way of being able to do what you could always
+do, gets a VeryHigh threat level?  WTF are the OpenSim developers
+smoking?
+
+Used to speed things up and reduce code complexity, exactly what they
+where designed for.
+
+- osMakeNotecard()
+Threat level: High, only enabled for estate owners and managers by
+default.
+
+Slightly less WTF than the other notecard functions, but still.  Allows
+to script what the object owner can do manually, why is that a high
+threat?
+
+Saves having to cut and paste to notecards after editing ball and prop
+positions.
+
+-osMessageObject()
+Threat level: Low, only enabled for estate owners and managers by
+default.
+
+More WTF, allows to send messages between objects better.  Nothing you
+couldn't do before.
+
+Used to reduce the complexity and increase the reliability of messages
+between the MLP object and balls / props.
+
+-osReplaceString()
+Threat level: VeryLow , enabled by default.
+
+Why isn't this threat level none?
+
+Used to reduce script complexity.
+
+-osSetPrimitiveParams()
+Threat level: High, disabled by default.
+
+Once again, allows scripting of something that can be done manually, and
+only works on objects the script owner actually owns.  With that later
+restriction, total WTF.
+
+Used to reduce complexity and speed things up.
+