Friday, 21 August 2015

TUTORIAL: New PMAC System From Scratch

This tutorial is for users of the PMAC system who want to create a new item from scratch rather than convert an old MLP system. Once you've done it once or twice you'll find that it's pretty easy. The instructions are also relevant to someone with an existing PMAC system (perhaps one converted from MLP or one made by someone else) who wants to add a new group to the system.

I'll start by giving a quick overview of what we'll be doing:
  1. Getting ready: figuring out what object we're going to use and and what animations we're likely to want to put in it.
  2. Create one of more blank menu cards.
  3. For each menu card, populate it with the animation names and a guessed-at starting position.
  4. Add anything else we want and add the core items.
  5. Use PMAC's built-in position editor to get the real positioning we want.
An object with a very large number of animations in it is going to take a little while to do so don't plan it as a quick one-hour task. Make sure you've got some time and do it right the first time.


Getting Ready

One common mistake is to just jump in and start doing something without thinking ahead to what you really need and how best to achieve it. The "dive in" approach works, but you can later find that you've wasted quite a lot of time or limited the flexibility of your object. Instead, planning it carefully in advance will save you a ton of effort later.

Here's what I do:

My very first consideration is "what object am I going to put this in?" The PMAC system can go into anything: a chair, a sofa, a bed, a blanket, a rock, a flower, a tree, a coffee cup...all you need is a single prim or mesh or sculptie, or a linkset of multiples of these (PMAC must always go in the root prim). While it's possible to put the system into a slow-moving object, I don't recommend it and would advise strongly against attempting something like that until you've set up a number of other more simple systems first.

The example I'll be working with for this tutorial is a divan that I made for my Paramour region. The object doesn't have to be in its final position...you can rez a copy of it in your sandbox or anywhere else you like and work on it there. In many cases, though, it's better to have it in situ since the way you position your animations may depend on the surrounding space.

Next, we need to think about how we intend to use our chosen object in terms of the sorts of animations we will want to have in it. As you can see, my divan is very large, easily seating 3 or 4 people at once while they're chatting with one another, and having plenty of room for a several people to recline or sleep on it...or get extra-friendly. So this means we'll have several different purposes to the object, hence we'll want several different groups of animations.

The fundamental way that PMAC animations are organized is in "Groups" where a group is a set of similar animations which I think of as "poses". That's the "top level menu" and in PMAC each group has a separate notecard that contains the data for those poses.

A "pose" is one animation. If it's just a single person, a pose is the inventory animation I want to that person to play and a bit of data saying where to position them on the divan (or whatever object you're using). If it's two people, a "pose" is two inventory animations (even if they're actually both going to play the same animation) and the position data for each person. If it's three people, a "pose" is three animations....etc. PMAC supports up to nine simultaneous avi (or NPC) for each pose.

For example with my divan the sorts of groups I might want are:
  • one person sitting or lounging on it by herself
  • two people sitting/lounging and casually chatting
  • three people sitting/lounging and casually chatting
  • four people sitting/lounging and casually chatting
  • two friends wanting to cuddle together
  • two very good friends want to do more than just cuddle
  • potentially for the adventurous, three people wanting to cuddle or more-than-cuddle ensemble
The list could get pretty long if I also want further subdivisions of some of those categories. For instance I might want to break the "more-than-friendly" couples poses into gender combinations of M-F, M-M and F-F. I might conceivably want to try shoe-horning five people on it, too. As you'll see in a moment, it's good practice to think about that in advance.

It's also possible that I might want to add a few things that don't specifically involve the object itself, such as a handful of couples slow-dances that I might want to be able to use to dance with someone on the nearby carpet. As long as the positions aren't going to be too far away (try to stay within 10m although you can push that distance quite a lot further) and it makes some sense to have them in the object, why not?

There is no limit to the number of different groups you can have in PMAC and there are only two rules:
  1. Group Rule #1: The number of simultaneous users for the poses in any one group must all be identical. I can have one group for single person poses and another group for two-person poses, but I can't mix one-person and two-person poses in the same group. One very important thing to keep in mind, though, is that each position in a pose doesn't have to be occupied in order to play it.
     
  2. Group Rule #2: The name I use for a group has to be relatively short (under 20 characters and ideally under 10) because it has to fit on a dialog button in the menu system; and the group name must be unique. I can have some sit poses for one person and some sit poses for two people, but I have to give them different group names...perhaps "Sits (single)" and "Sits (couples)"
Here's where thinking about it a little in advance can be handy: I have four different groups of "sit/lounge" poses in my list above, depending on the number of people involved, but most likely I'll be using the same general poses for all of them and simply moving adjusting the locations for each person (and probably trying not to have everyone playing the same pose at the same time).
 
Because PMAC can play the pose even if all positions aren't occupied, I could actually just do a single "Sits  (max 4)" group and position things to "fit" nicely for four simultaneous users. If fewer people are using it they'll still look fine and there will be an added bonus that you can use PMAC's "Swap" feature to switch positions around between  people.

If I do this and am using it by myself, each pose actually becomes 4 different places I can put myself depending on which position I swap to. If I have just one guest I'm chatting with, I can use swap to move us into 12 different position-animation combinations. All with just a single pose and only having to set up 1 group! Much less work than setting up four different groups (being lazy, that sort of economy appeals to me).

I'm also going to skip doing the "3+ very friendly people" group because my divan isn't really intended to be used as an orgy bed (just not my style :p). I can envision using it for more than just cuddling, though, so I will include those (which I normally break into a number different groups because that's my preference but for this tutorial I'll treat that as two groups: "snuggle" which is sort of foreplay type things, and "together" for more explicit ones).

Now that I have my "groups plan" and I know roughly which animations I want to use, I can get started.

Create A Blank Menu Card For Each Group

In my inventory I now create one (blank) notecard for each group I plan to put into my object. The names of the notecards are extremely important in PMAC and detailed in the Read-Me notecards that come with the builder's kit. The naming format must be exactly:
.menussup group name
where:
  • the name must begin with ".menu" (the leading dot is important, and it must be lower case)
  • replace "ss" with any two valid characters (numbers or letters, upper or lower case) that are only used for sorting the order of the groups in inventory. Whatever order they appear in object's inventory is the order they'll be listed in the groups menu. The don't even have to be unique...you can have several groups that all use the same two sort characters and they'll simply be sorted by whatever follows them in the card name.
  • replace the "u" with a number between 1 and 9 to indicate how many simultaneous users this group's poses will be set up for. For a set of singles-only poses you'd use 1, for couples you'd use 2, and for larger groups you'll use however many the max is.
  • replace the "p" with one of three letters: O, G, or A to tell PMAC who is allowed to use (or even see) this group. If you use "O" only the owner can see this group in the menu and access it. If you use "G" only a group member can see and use that group (someone with the same active group set as the group assigned to the object). If you want everyone to be able to see and use that group, use A.
  • Then a space, and then lastly a fairly short, unique, group name.
When assigning a group name, remember the rules that each group name must be unique for this object and has to be fairly short. Anything more than about 20 characters will actually generate an error in the system when you try to use it. Anything longer than about 8 or 10 characters will tend to have the end shopped off on the button but will be shown in the dialog box above.

I should stress (because several people have asked me) that it's the group name itself that must be unique. You can't use the same group name twice, even if the sort or number of users or permission setting is different. PMAC needs the name itself to be unique. The names are case sensitive, though, so "Sits" and "sits" and "SITS" are all different groups names (if you can remember which one is for which group...).

For my divan I created four notecards:
  • .menu004A Lounging (4)
  • .menu012A Cuddle (2)
  • .menu022G Snuggle (2)
  • .menu032O Together (2)
If a casual visitor uses the divan they'd only see and be able to pick the first two menu items. A group member would also see the Snuggle group but I'm the only person who would see the Together group (because my Paramour region isn't a place for people to come and have sex...go use your own beds! :p).

As a side note: yes, if they inspect the contents of the divan they'll see the animations, extra "invisible" group notecards, etc. so you're not really hiding anything from anyone...you're just not making it accessible to them.

Now that we have our four empty notecards in inventory, we're going to work on them one by one until we've got a complete system assembled.

Contents of a Group Notecard

We need to do this section for each of the groups in our system (each of our notecards).

Each line in a group notecard is a "pose" that will have a dialog button when that group is selected. There is no limit to the number of poses you can have in a notecard although just for the sake of memory conservation and speed of use you'd want to keep it to under a hundred. PMAC only loads data for the currently active group -- not the entire system -- so you can easily have hundreds of poses available to you...just break them up into smaller groups.

My general rule-of-thumb is to try to keep it to about 24 or fewer poses in a single group because that's 4 pages to flip through in a group when looking for a specific pose and it keeps the memory usage to a minimum. Most people won't want to flip through 40 pages of poses just to find the one they're after anyway.

For each pose (each line in the notecard) we need to supply a name for the pose and it needs to be fairly short -- ideally short enough to fit completely on a dialog button but in any event it can't be longer than about 20 characters. It cannot contain the pipe symbol ( | ) because that's used as the data separator in the notecards; and it has to be a unique name within the group.

You can have a pose "Sit" in one group and use that same name again in a different group, but you can't use if for another pose in this group.

There is one further complication about "unique" names: if you use a pose name that is identical to the name of an animation in inventory that is being used in this group, that animation name can't appear anywhere earlier in the notecard. So, for instance, say you have an animation that you want to use that has the name "Sit 4". You can only name a pose "Sit 4" if that pose appears in the notecard before any other time the "Sit 4" animation is being used. The pose "Sit 4" could use the animation "Sit 4" because it will be later on the same line, but you couldn't have an earlier pose called "Sit 1" that also uses the "Sit 4" animation.

A good rule of thumb for avoiding these problems is to use naming conventions for your inventory animations that aren't likely to conflict with the names you want to use for a pose.

Pose (and animation) names are case sensitive, so an animation "sit 4" wouldn't cause any problems at all if your pose names always begin with a capital letter. Similarly, if you really wanted to you could have a pose "Sit 1" and another one called "SIT 1" and yet another one called "sit 1" and then even three more that don't have a space in the name.

In the notecard line, the next thing PMAC expects after the pose name is the pipe symbol ( | ) which is acting as our data field separator. PMAC doesn't trim leading or trailing spaces so be careful not to add any!

The next field for a pose is called the "commands field" which contains data for any add-ons you might want to use. Each add-on will have a specific format for the way it needs its data so you'll need to refer to the add-on's instructions for what it needs. It's beyond the scope of this tutorial to get into any details about that so for our example we won't be using any add-ons at all. This means our command field needs to tell PMAC that we aren't using any, which is done by supplying "NO_COM" as the command (NO_COM is short for "no commands").


Next, another pipe symbol ( | ) to indicate a new field.


Now for each position in this pose we have to supply three pieces of data, each separated with the pipe symbol: the exact name of the animation in inventory, the local reference position we want to move the avatar to when playing that animation, and the local reference rotation we want them to be turned to when playing it. The animation name part is easy: just be very careful to ensure that you spell it correctly, don't insert any extra spaces, and pay attention to capital and lower case letters since, like everything else, names are case sensitive.

The scary part -- particularly when creating a new system -- is the local reference position and rotation because you don't know them yet. They will vary depending on the object you're putting the system into, and on how the animation was made. There is little (if any!) consistency in any of this so that means every single animation is going to need to be custom-positioned and you will never know these values until you've done it. You could guess, if you've done this a lot and are familiar with your animations, but luckily we don't have to worry about it really...we're going to "cheat" and use a built-in PMAC capability to do the dirty work for us instead.


What we're going to do is supply just a generic position and rotation for now, and then later we'll use PMAC's position editor to get the positions where we really want them -- something we'd have to do anyway so why bother jumping through any extra hoops now? So...what values should we use? The answer depends a little bit on the object and also on the number of users the pose is for.

The very first time you do this it's going to feel nasty, confusing,  nd a bit like witchcraft. Once you've done one system you'll probably have a really good sense of how it all fits together. I'd suggest that for a first time user, start by setting up just one group, then adding others later. That way as you add you extra groups you'll have gone through the whole thing once and will have a bit better idea of the workflow.

My recommendations for starting positions and rotations:
  • If your pose is for just 1 person it's simple: a very good starting position is <0.0, 0.0, 0.5> if it's a sitting or lying down pose, or <0.0, 0.0, 1.0> for a standing one. If your object is very thick in the z-axis, you might want to increase that z-value a bit. When we play this animation it will put the avatar just a little bit above the center of the object which is a decent starting place for editing positions.

    Use a starting rotation of <0.0, 0.0, 0.0, 1.0> which will result in the avatar facing in the direction of the object's local x-axis.
     
  • If  you're using a bunch of singles animations for a multi-person pose it's pretty easy...just offset the position in either the x- or y-axis by some reasonable amount (perhaps 0.25m or 0.5m) to make the handles easy to select later. So, for example, for a two-person sitting or lying pose put the first avatar at position <0., -0.25, 0.5> and the second one at  <0.0, 0.25, 0.5>. That will put one a bit to the left and the other a bit to the right of the center of the object. for a three-avatar one you might put the first position in the center, then the other two +/- 0.5m in the y-axis. The idea is to give yourself a little room between each when you go to edit them later, so this half-meter offset will keep the positioning handles nicely apart and easy to select.

    Again, use <0.0, 0.0, 0.0, 1.0> as your rotation.
     
  • If you're setting up couples poses (ones made specifically that way) it depends a bit on the animation creator. Some animation creators set couples animations root positions to be identical, while others will offset them by 0.25m to as much as 0.5m, and it varies from creator to creator (and some creators aren't consistent in what they do either). This means that for some animations it would be better to start both at position <0.0, 0.0, 0.5> while for others you'd want to incorporate that creator-intended offset. Unfortunately there's no easy way to know other than to put them into a pair of poseballs, hop on each, and see what sort of space you need to put between the poseballs (if any) to get the positions right.

    If in doubt, I generally go with the same recommendation I made above and offset them by +/- 0.25m in the y-axis.

    For rotation I'd again use the <0.0, 0.0, 0.0, 1.0> starting point since almost all couples poses are either made that way (relative to one another ) or with one rotated exactly 180 degrees which you'll see instantly when you go to edit it later and can quickly change with no effort.
I'm sure the above is going to be confusing for someone doing a set-up for the first-time so just try to follow along with those recommendations as best you can, and if all else fails set everything to a position of  <0.0, 0.0, 0.0> and rotation of <0.0, 0.0, 0.0, 1.0> and sort it out later when you're editing the positions.

Here is an example of one notecard line for one pose for 2 people:

Hugging|NO_COM|hold_f|<0.0, -0.25, 0.5>|<0.0, 0.0, 1.,0>|hold_m|<0.0, 0.25, 0.5>|<0.0, 0.0, 0.0. ,1.0>

This would be a pose that will have the (unique!) button name "Hugging" where the first avatar plays the animation called "hold_f" and is positioned a little to the left of center, while the other plays the animation "hold_m" and is a little to the right.

Note that I have been careful not to insert any extra spaces before or after the pipe symbols. It makes it slightly harder to read a notecard line but PMAC does this because by not having to strip leading and trailing spaces from all names it can greatly increase the script's efficiency during operation. This would normally be the only time you'd ever need to manually edit or even look at a PMAC notecard.

If your group is for three avatars, each line would need another animation name, position and rotation. For four it will need 4 sets of those. For a single person item it would have only one.

Now you just need to repeat that for each pose you want in this group. Then repeat that for any other groups you want to add. I did mention at the beginning that setting up a new system from scratch wasn't a short process, didn't I? It isn't. If it makes you feel any better, setting up MLP from scratch is significantly more time-consuming and prone to error.

Needless to say, doing this manually for a large number of animations is a lot of typing and therefore a very high risk of typos or other errors. If you have a modest skill in scripting you can automate this task and virtually eliminate the chances of making a mistake.
By using a specific naming convention for your couples animations you can even write a script to automate it for them. For that to work, all you have to do is edit the animation names (if necessary) when you get a new couples animation from somewhere to make them comply with your own naming system. Of course if you haven't already done this with your existing inventory you'd need to spend a while making them conform, too, but you'd only need to do it once. If there's a way to automate that I'm not aware of it (other than having direct database access to the inventory server).

If you're planning to use an add-on you should also put some starting command strings for them into the commands field instead of the default NO_COM. Again that's easy to do if you're automating that process via scripting.

Add The Rest of the PMAC System Stuff

Now that we have our group notecards all nicely prepared with some pose data in them (using generic starting guess positions) it's time to do the next steps.

  1. Place all of those notecards into your object if you haven't already.
  2. Place all of the animations those poses are asking for into inventory.
  3. Place the "~~~positioner" object (from the builder's kit) into the object's inventory
  4. Place the PMAC base animation into the object's inventory (usually the "~~~~~base_DO_NOT_DELETE_ME!!!!!" animation from the builder's kit)
  5. Place the READ ME notecards into the object's inventory (because they really should be there in spite of the fact that many people don't read them)
  6. Place any add-on scripts you're using into the object's inventory (and any objects they might require)
  7. Add any NPC notecards you want to the object's inventory
  8. If you use a PMAC configuration notecard, put that into inventory and specify one of your group notecards as the default one for PMAC to load
  9. The last item you put into the object's inventory should be the core PMAC script (currently "..PMAC 1.02 Core"). If you don't use a configuration notecard the script will complain that you haven't specified a valid default group so you'll need to open the script and change it to have the default group be one of the ones you've created, then save.
If you've done everything correctly, you should be able to sit on your object and PMAC will work perfectly but be using the generic starting positions you've supplied from the previous step. Our final step will be to fix these by using PMAC's built-in position editor.

Edit Poses to Their Final Positions

I am going to assume that you've edited positions for a PMAC system before -- perhaps from a MLP system you've converted -- so I shouldn't need to go into this in detail. Remember that to enter edit mode all positions for that group need to be filled (and no extra positions can be occupied) so you might need to rez or remove NPCs to get the correct number of users.
 
You simply need to pick a group, then enter edit mode and position each pose using the handles, then save notecard. PMAC stores everything for you, correctly formatted, with the correct new relative position and rotation data based on where you moved things with the handles.

Then repeat with each of the other groups. For a large system this is going to take a while...drink lots of coffee and save often!

Congratulations...if you've followed all of the above steps you have a fully working, custom-positioned PMAC system. With my divan (which I haven't yet completed) I expect the process to take about 2-3 days of work, depending on how many animations I use and how many of them I've already used in other PMAC objects where I can simply copy-paste and do a quick position tweak to fit the new object (I can pull a bunch from my bed, for instance, and simply move the location to wherever I want them to play for the divan).

The good news is that the more of these systems you do the faster you'll get at doing it. You'll also be able to copy-paste portions of previous systems into the new one's notecards and then just do a tweak to edit positions for the new item, agains speeding things up and reducing the chances of error. You may even begin storing PMAC group notecards along with your animations just to make it even easier (which is something I've begun to do but haven't gotten around to for all of mine).