Friday, 8 January 2016

Sneak Peek: Paramour Clubmaster v2.0

I've spent the last ten days or so working on an updated version of my widely used club danceball system since I'm still being flooded with support requests from people trying to use it with 0.9.

Since ensuring compatibility with both the new code changes as well as regions running under 0.8.x involved some significant rewrites in places, I thought while I was at it I might as well go ahead and make any other changes to it that seemed useful to me or had been requested.

We did the first beta-test of the new system on Wednesday with a dozen people, encountering only one small corner-case bug, and I'll continue to put it through its paces for the next few weeks at my Sunday Hedonism dances to hopefully find and purge any remaining bugs and ensure that it works under both old and new code versions.

Barring discovery of any major new bugs, the final system should be ready for public consumption by the end of the month or early in February.

If there are any bugs with the existing version that you're aware of and haven't reported to me, or if there are any feasible new feature requests, I would be open to considering them if you get in touch with me in the next week or two.

Here's a sneak peek at the change log so far, although this is subject to change between now and the actual time of release if I discover issues with it:

Change Log Paramour Clubmaster Dance Machine 2.0



There is now a new "GROUP" option available in the initial dialog that you can choose for dancing.

The danceball owner can specify any one of the singles styles to be the group dance style (it's a setting at the top of the script in the BASIC USER SETTINGS section) or, if left blank, the first singles dance style will be assigned automatically. Unfortunately this selection can only be made in the danceball's can't change it during use (you'd have to do it the "old 1.x way" where you choose singles dance when you join, then agree up which style you should all pick).

Anyone who touches the danceball and picks "GROUP" will play that dance style and be kept in perfect synch with everyone else who's using it (the synch doesn't happen until the next time the dance advances so they'll be out of synch for the first minute or two). The group will cycle through the animations assigned to that style in much the same way singles dances work. Touching the danceball again stops you from dancing.

A NPC who touches the danceball is automatically added to the group dance, allowing you to use external scripts to rez a NPC and have it touch the danceball and start dancing whereas in the past this wasn't possible. Having the NPC touch the danceball again will stop it from dancing but not kill have to have your NPC controller script do that if you want to remove the NPC. You can just kill the NPC with your external script at any time and the danceball will detect it the next time the group dance changes.

The triple advantage of this new feature is:
  • no need to coordinate which singles dance style you should all select to dance as a group...just pick "GROUP" and you'll join
  • greatly expanded NPC support and flexibility (particularly in conjunction with Ferd's excellent NPC controller)
  • from a load standpoint, the danceball is able to cycle through group dances slightly more efficiently than individually selected singles dance styles, so there will be a tiny reduction in sim load abd script memory use for each dancer who uses the GROUP option instead of picking their own singles style (while still leaving that as an option)


In version 1.x of the danceball, changing NPCs involved adding/removing their appearance notecards from the ball, then also manually editing the appropriate list in the Advanced User Settings section to match them. Many users with limited scripting experience found this an intimidating task so...

With version 2.x, I have changed the way this works. NPC lists are now built during the ball initialization based on a specified naming prefix (by default, ".NPCM" for a male NPC and ".NPCF" for a female one but you can change this if you like) so all you have to do is name your notecards correctly and reset the main will take care of the rest. You can also expand the use of this feature by having a number of different NPC notecard sets with different prefixes for different occasions. To swap sets, all you need to do is edit the Advanced user settings to indicate which prefix notecards to load.

More details on this feature are in a separate section below.


You can (optionally) include a notecard in inventory that specifies a specific NPC to initially rez for a specific user. When that user picks NPC COUPLES and sits, if their UUID is in the list it will rez whatever NPC is specified in the notecard. Note that this NPC can be *any* valid appearance card, even if its name doesn't conform to the new auto-list-building feature above. This would allow you to set up a custom NPC that only that specific user can dance with.

To make this work without unduly expanding the script size, this NPC is only rezzed when you first sit down (and it doesn't matter which ball you pick to sit will rez your NPC to whichever one you don't occupy) and then after that the NEW M and NEW F buttons in the Options menu will continue to work as before, allowing you to change to a different NPC if you want. You would have to stand up and start over again to get your specific, custom NPC rezzed for you again.

Anyone not in the custom list will have the danceball work exactly as normal.

More details on this feature are in a separate section below.


This new feature is intended to allow the danceball to accomodate the changes made to sit target positions in Opensim 0.9 while remaining compatible with regions running under 0.8.x as well.

Added a zGlobal offset value to the basic setup values which allows you to easily adjust the couples dance positions.  The default value of 0.0001 is suitable for any region running under Opensim 0.8.x. People using Opensim 0.9 will need to determine the best value for your various Opensim.ini settings -- please consult any Opensim documentation available for your version or, if you're unable to find any and if you see couples floating above the ground, I'd suggest starting with an offset value of -0.15 and tweak from there since this appears to be the approximate (undocumented) change made to sit targets in the newer code.

This z-offset value is sent to the poseballs which apply it as a direct offset to the ball's sit target to avoid having to do extensive ongoing position calculations during actual danceball operation...the calculation is only done once at the time the avatar/NPC sits. This method is a little clumsy but at least allows you to easily adapt the danceball to whatever version of Opensim you're using and will add flexibility to handle any other changes of this nature if/when they occur to the code.

The value is set in the BASIC USER VARIABLES section at the very top of the script.


The main danceball mesh object has been remade as a single mesh instead of linkset. It is approximate the same poly counnt as the old one but was uploaded with higher LOD values and simplified physics shape (even though it's set phantom by default). The couples poseball object has been remade as a single mesh with lower poly count, and uploaded with higher LOD values and simplified physics shape (even though it, too, is phantom by default). This should make it easier to spot both objects from greater distances and/or with lower viewer LOD settings and reduces the LI for grids where LI is used.

Other Main Danceball Script Changes

  • Changed the initializing and live handling of singles dances to now allow for a (virtually) unlimited number of different styles to be defined for it and presented in navigable dialog pages. Note that having a very large number of them will result in a (small) increase in the script's memory usage. It's still not possible to allow selecting a specific dance animation to play (it would require a level of dialog/menu tracking that would drastically increase the memory footprint when the danceball is in use) but I'm hoping people will enjoy the increased flexibility and ability to customize. For much the same reason, it wasn't practical to make this sort of change to the couples dances (nor do I think there are enough additional ones out there in the Metaverse to require it since there are already two empty style slots available which can accomodate 18 more dances).
  • The basic user settings now has a "errorCheck" variable (TRUE/FALSE) that determines whether to run extened error checking and has a large impact on initialization speed. Due to Opensim 0.9 code changes, disabling error checking may be required for some regions unless you greatly increase the value of the EventLimit variable in Opensim.ini [XEngine].
    • TRUE will do a full error-check on start-up, strips strings, confirms animation names, confirms inventory, warns about excess animations, etc (old behaviour from 1.x but slower)
    • FALSE is now the default value and does only minimal critical error checking and assumes everything is correctly configured and string-stripped (much faster but if you edit your notecards incorrectly the errors won't be detected and fixed)
    If you're using the danceball version I supply, without content edits, you can safely leave this at its default FALSE value.
  • Because NPC lists are now build from inventory, added an option to randomize the order after building the lists. This is only done once, at start-up, after which the order will remain the same until the main script is reset.
  • Added a QUIT button to the couples options menu (except for owner when in edit mode) to allow you to quit from there as well as from the styles menu (or by standing up).
  • Added a script global integer constant "osNpcObjectGroup" with value of 8 which is used as a switch to the NPC creation method, allowing the NPC feature to be used in a region running Opensim 0.9 with group perms but also won't break functionality under 0.8.x. I used a global defined variable rather than the new constant OS_NPC_OBJECT_GROUP in order to allow the script to compile in regions running code earlier than Jan 4, 2016.

    Please note that there are additional changes to NPC configuration and functions that may require adjusting your Opensim.ini and osslenable.ini to enable the necessary functions. Consult any available Opensim documentation.

    Any region running a version of Opensim 0.9 with a commit date prior to January 4, 2016 will need to be set to allow full public access to allow NPCs to work (or upgraded to a more recent version or reverted to 0.8.x). IMPORTANT!!!! AT THE TIME OF THIS WRITING, FOR THIS TO WORK IN OPENSIM 0.9 PARCELS YOU NEED TO SET THE DANCEBALL GROUP TO MATCH THE ALLOWED PARCEL GROUP!!!
    If you run Opensim 0.8.x you don't need to worry about this at all since NPCs aren't evicted from group parcels.
  • Added new presence checking to a variety of places to try to catch occasions where asynchronous script handling can result in OSSL error messages being thrown as a result of trying to send issue a command to a non-existent NPC or poseball. This can't completely eliminate the chance of it happening but should make it a much rarer occurrence. The function calls are isolated and an error won't prevent the danceball from continuing to work properly for all other users. This error-catching does add a very slight amount of overhead during use, but not to an objectionable degree.

    The most common action that can still generate an error message is to select COUPLES NPC and sit, then stand rapidly after the NPC has rezzed and before selecting a style or dance. There is no way I can stop this from happening due to the way NPC agent entry is handled so you may need to advise a user not to do this if they're chronic about triggering it (most often it's because they aren't aware that they can use the OPTIONS menu to change to a different partner so they keep having the ball rez new ones until they get the one they want which is hard on sim resources and should be discouraged anyway...please help your newbie guests!)
  • BUGFIX: Fixed an incorrect casting assignment when pulling pos and rot values from a list as string instead of vector (it still worked fine under Opensim 0.8.x because it wasn't used until recast in a function call but could result in compile errors in the future -- and it needed to be corrected anyway).

Couples Poseball Script Changes

  • Made a couple small script tweaks for efficiency
  • Made sure that a poseball doesn't try to unsit a non-existent user which can occasionally happen due to asynch handling of operations
  • In regions that don't recompile scripts on start-up, a stranded poseball will now also be destroyed
  • This script now expects to be given a zGlobal offset value from the main script and adjusts sit target position based on this value (see above). This is only done when the user first sits (all other positions are based on the poseball location rather than avi location) thus doesn't add to the sim load when in use.

Danceball Contents Changes

The main danceball and its poseball have changed as per all of the above, plus...
  • attempted to ensure compatibility with the known Opensim 0.9 changes to date in addition to 0.8x (but I cannot guarantee that it will remain compatible with future code changes)
  • the script inside the poseball has changed and poseballs from versions 1.x ARE NOT COMPATIBLE with version 2.x or visa versa
  • the NPC notecards supplied with the danceball have been renamed to comply with the new naming rules but the actual NPCs are the same.
  • the couples dances are unchanged from v1.3
  • added a huge number of new singles dances more than doubling the previous number (now more than 500 different singles)!!!
  • because of this, a number of the (in my opinion) less-good singles dances from previous versions have been removed...mostly due to either because of tilted stance or poor looping
  • removed a few duplicates (even though they had different UUIDs) although I'm sure there are still more...wish there were a way to compare them at a file level...
  • renamed some of the dances that were in the v1.x ball to help group them a little better in inventory
  • re-arranged, renamed and split up some of the old dance categories since the number of them isn't limited any longer


Version 1.x of the clubmaster system required the user to manually enter the names of all the NPC notecards into the script which many novice users found confusing.

With version 2.x this is now handled a bit differently. Instead of having to manually supply a list, the initialization now looks at the notecard name and matches it to a supplied gender prefix that is set in the Advanced User Variables section at the top of the script. By default, a male NPC must have a name that begins with ".NPCM" and a female must have a name that begins with ".NPCF" but you can change this to anything else you want, making it easy to have multiple custom sets of NPCs in the ball for different events and simply changing the prefix filter to load the set you want.


If you've already made a set of custom NPCs for your v1.x danceball you can easily transplant them to your new v2.x system as follows:
  1. Select your old danceball in edit mode and go to the inventory tab
  2. Copy your NPC notecards into a folder in your own personal inventory
  3. While they're still in your own inventory, rename the male ones to begin with ".NPCM" (not including the quotation marks but including the dot at the start) and the female ones to begin with ".NPCF"
  4. Drop these renamed cards into your new v2.x danceball
  5. Press the "reset scripts" button to have the danceball reinitialize and pick up the changes


You can now easily add a new NPC by using any of the normal NPC appearance notecard creation utilities (you can get one free from my shop in RefugeGrid) which will hand you the notecard. Rename this card to begin with either .NPCM or .NPCF and drop it into the danceball's inventory. Then reset the script. You no longer have to edit the lists in the script itself.


You can now easily remove a NPC from the danceball by opening its inventory, deleting the appearance notecard, and then resetting the script. You no longer have to edit the lists in the script itself.


This is a new feature to v2 of the danceball and allows you to include an extra notecard in the danceball's inventory where you can set up a specific NPC to always be rezzed as the partner for someone. The NPC's appearance notecard has to be in inventory too, of course, but it doesn't have to use the naming convention of the normal NPC notecard prefix so this even allows you to have a specific NPC that is reserved for only a single user's use.

The matchmaker notecard can be any name you want (assuming it doesn't conflict with anything else) and needs to be specified in the BASIC USER VARIABLES section at the top of the script. When the danceball initializes, if it finds that notecard it will read in the contents.

Each line of the notecard needs to be in the format:
which is:
  • the UUID of the user you want to assign a custom NPC to
  • followed immediately by the pipe symbol (|) ...DO NO add any spaces between the end of the UUID and the pipe symbol
  • then followed immediately by the exact NPC appearance notecard name...DO NOT add a space between the pipe symbol and the notecard name...the name can be any valid appearance notecard even if it doesn't have the prefix that your normal "public" NPC notecards are using.

Let's pretend that my UUID is "12345678-90ab-cdef-1234-567890abcdef" and that when I use the NPC partners I always want the one with the appearance notecard called "Aine's Partner". My matchmaker notecard would therefore include the line:
12345678-90ab-cdef-1234-567890abcdef|Aine's Partner

Now, whenever I use NPCs it won't matter which of the two poseballs I sit on...that NPC will always be the one that is rezzed for me to dance with even though its notecard name doesn't have the prefix I've assigned for the normal male and female NPC cards. If I want to change to use one of the other NPCs instead, I can go into the OPTIONS sub-menu of the dialog and pick "NEW M" or "NEW F" to replace my NPC with the next one from the "public" list, but after that it would only give me access to the ones in the regular public list on future swaps. To get my own custom partner back I'd need to stand up and start again.

Whenever you add or alter this notecard you will need to reset the main script to have it pick up these changes so it's something you'd set up ahead of time and probably limit to only yourself and perhaps a few regular guests.

The only error-checking done is to ensure that the specified notecard actually exists in inventory during initialization. You'll be notified it it isn't and it will be ignored (using the "public" NPCs instead). If a user's UUID is listed twice, it will rez the NPC associated with the first instance of it in the notecard. If you delete the NPC notecard without resetting the script, this WILL NOT be detected at time of rez and could cause issues so always be sure to reset the master script any time you make any inventory changes (preferably with error-checking enabled, too).

I had originally hoped to provide a more automated and flexible method for doing this (and even letting users select and store their own, in real time) instead of the owner having to manually edit the  notecard. Unfortunately it resulted in too much additional complexity and performance degradation to the danceball for this to be practical. In future, if I can come up with an efficient method for doing so I'll consider adding it.