Tuesday, 24 March 2015

PMAC Tutorial: Creating, adding and removing NPCs

This second PMAC tutorial covers the subject of creating, adding and removing NPCs from the system.

Creating a New NPC

Creating a new NPC is a very simple process that involves cloning an avatar's appearance and storing it to a notecard. The notecard's contents is simply a list of UUIDs of what the cloned avatar was wearing and that they looked like at the time the appearance was stored.

You'll need to be in a region where OSSL is enabled and you have permission to use the OSSL function osAgentSaveAppearance(). Once there, you will first need to make an object to use as your cloning device (a simple container for the script that creates the notecard):
  • Rez a simple cube prim or create any other object you'd like to use as your "cloner".
  • Place this script in it:
    default
    {
        touch_start(integer num)
        {
            key who=llDetectedKey(0);
            string name=llDetectedName(0);
            list parse=llParseString2List(name,[" ","."],[]);    // parse both in case HG
            if (llGetListLength(parse)<2)
            {
                llOwnerSay("ERROR: Unable to parse toucher's name");
                return;
            }
            string cardName=".NPC00A "+llList2String(parse,0)+" "+llList2String(parse,1);
            if (llStringLength(cardName)>33) cardName=llGetSubString(cardName,0,32);
            llRegionSayTo(who,0,"Please wait a moment for the appearance notecard to be created and handed to you. The card name will be "+cardName);
            osAgentSaveAppearance(who,cardName);
            llGiveInventory(who,cardName);
            llRemoveInventory(cardName);
        }
    }
  • Whenever anyone touches the prim they will be handed a NPC appearance notecard of themselves
Now wear the shape, skin, clothing, hair, and anything else you want until you appear exactly the way you want your NPC to look. I highly recommend that you remove any HUDs and avoid wearing any scripted items as Opensim currently has some issues correctly handling them when the NPC is removed from a scene. Some of these issues were corrected with the official 0.8.1 release but potentially not all of them.

Once you look exactly as you intend your NPC to look, touch your "cloner" prim. A few moments later you'll be handed a notecard that's correctly pre-formatted to the PMAC naming convention (see below) using your name. If your name is longer than the maximum allowed PMAC length, the name will be trimmed. You may want to edit the card's name to something else, provided you retain the correct name formatting.

If a friend is willing to be your "model" for the NPC, they can touch the prim, too. They'll then be given the notecard which they can subsequently hand to you.

NPC notecards usually don't work well in grids other than the one they were created in. The grid where the NPC is rezzed must know each and every UUID in the notecard in order to display the NPC correctly. For extremely common items this may not be an issue, but for others it will.

If you also have my Dancemaster Dance ball you can add the notecard to it too. You'll need to manually add the name to either the male or female NPC list in the danceball's script for it to become available. These notecards also work perfectly in my Country Line Dance machine or in anything else that is designed for NPCs. Consult each item's NPC handler script to determine the naming format (if any) it expects and adjust your notecard's name as required.

Adding a NPC Appearance Notecard to a PMAC Object

Once you have an appearance notecard, adding it to a PMAC object is quite simple.

First, you must ensure that it follows the correct naming format that PMAC expects for NPCs. If you used the above script to make the card, it will already be correctly formatted but you might wish to edit it a little. If you use a different script to create the NPC, you'll need to change the name to adhere to PMAC's format:

.NPCxxP firstname lastname

Example: .NPC01A Aine Clone
Where:
  • The card name must begin with ".NPC" (including the dot in front and must be capital letters) 
  • The next two characters can be any letter or number but not any special characters. These two characters are only used to determine the sort order of NPCs so you can easily change the order they're shown in the dialog box for adding NPCs during use. The order they appear in PMAC's inventory is the order they'll be shown in the dialog. The don't have to be unique to that card (you can have multiple NPCs with the same sort order characters, in which case they'll be additionally sorted by the permission letter and name).
  • The "P" character that follows is the load-permission assignment and must be either:
    • "A" which means that anyone has access to adding this NPC during use
    • "G" which means it can only be used by the owner or an avatar that has an active group tag that is the same as the PMAC object's group
    • "O" which means it can only be used by the owner.
  • There are additional PMAC settings that may affect those permission settings (see PMAC documentation)
  • Those first 8 characters can't contain any spaces and must then be followed by a single space.
  • You then supply a first name to be used for the NPC when it's rezzed
  • Then a (optional) last name. If you don't supply one, PMAC will use "~" as the last name.
  • The combined length of the first and last names (including the single space between them) must not exceed 25 characters -- it has to be valid for a dialog button which has this LSL-imposed limit. I try to keep the name short enough to be easily distinguished on the actual dialog button rather than having to look at the dialog box's text at the top to differentiate.
  • If you use the script, above, to create a notecard it will be correctly formatted with the permission set to A (all) and the sort order at 00.
  • The combined first and last names cannot be duplicates of another first and last name even if the sort characters and/or permission is different. This has to do with the way PMAC handles your dialog responses and allows much greater speed this way but forces you to manually check this yourself.
Once you're sure the card is the correct format and the name doesn't conflict with an existing card, just place it into the PMAC object; then reset the PMAC core script. The NPC will now be available.

Removing a NPC from a PMAC Object

Removing a NPC from a PMAC system is extremely easy. Just delete the notecard from inventory and reset the PMAC core script.