Revision as of 02:08, 12 August 2011

Introduction

Since 12th August 2011 in the Git master development code branch, OpenSim had provided a number of functions for creating and manipulating NPCs. These replace the previous functions, that had stopped working by OpenSim 0.7.1.1 (possibly broken since OpenSim 0.6.9).

The general philosophy in creating these new functions is to

1. Give script writers the simple tools needed to create more sophisticated behaviour.
2. Avoid duplicating existing LSL and OSSL functions. For instance, finding out what state an agent is in can be done through llGetAgentInfo() rather than creating a special NPC function.

NPCs are controlled via a script which must be in the same region as the NPC. This could be housed in an attachment that is attached to the avatar.

NPCs created user these scripts cannot leave the region in which they were born. If you want region crossing behaviour, please look at the options on the NPC wiki page.

NPC appearance is saved and loaded by serializing the appearance data structure to a notecard present in the same prim as the script. The required textures should be preserved when an OAR is saved and loaded.

This functionality is at an early stage and method signatures could change, certainly before the release of OpenSim 0.7.2. However, we hope to avoid this.

Enabling

To use these functions, in the OpenSim.ini file you will need the following config

1. Enabled = true set in the [NPC] section.
2. Enabled = true set in the [XEngine] section.
3. AllowOSFunctions = true in the [XEngine] section.
4. OSFunctionThreatLevel = VeryHigh in the [XEngine] section. The functions osAgentSaveAppearance(), osAvatarPlayAnimation() and osAvatarStopAnimation() need this level. If you don't need these functions, then a "High" level will suffice.

Notes

When using your avatar to model appearance before saving, you will need to wait a few seconds before invoking any save appearance command. This is because appearance saving currently operates on a timer in order to manage multiple appearance updates from the viewer.

Functions

Create and Remove

osNpcCreate

osNpcCreate(string firstname, string lastname, vector position, string notecard):key

The notecard is the name of the notecard containing a serialized avatar appearance, or its asset UUID. In previous versions of create, the user UUID could also be used, assuming that they were logged in to the region. However, for security and interface simplicity, this option has been removed. Please save an appearance to a notecard first, using osOwnerSaveAppearance() or osAgentSaveAppearance().

It's also possible to pass a user ID as the notecard parameter. If that user currently has an avatar on the sim, then their appearance will be used for the NPC. However, please note that this appearance will not be persisted unless osNpcSaveAppearance() is called.

If the NPC is successfully created, then its id is returned, which is required for all subsequent functions.

osNpcRemove

osNpcRemove(key npc):void

Remove the given avatar from the region.

Get and Set

osNpcGetRot

Gets the rotation of the avatar. Only the rotation around the Z plane in Euler rotation (horizontal rotation) has any meaning.

osNpcGetRot(key npc):rotation

osNpcSetRot

osNpcSetRot(key npc, rotation rot):void

Set the rotation of the avatar. Only setting the rotation in the Z plane in Euler rotation will have any meaningful effect (turning the avatar to point in one direction or another). Setting X or Y Euler values will result in the avatar rotating in an undefined manner.

osNpcGetPos

osNpcGetPos(key npc):vector

Return the current position of the NPC.

osNpcMoveTo

osNpcMoveTo(key npc, vector position):void

An older function that performs an osNpcMoveToTarget() by flying and landing at the target.

osNpcMoveToTarget

osNpcMoveToTarget(key npc, vector target, int options):void

Move the avatar to a given target over time. How the avatar will get there depends on the following options.

• OS_NPC_FLY - Fly the avatar to the given position. The avatar will not land unless the OS_NPC_LAND_AT_TARGET option is also given.
• OS_NPC_NO_FLY - Do not fly to the target. The NPC will attempt to walk to the location. If it's up in the air then the avatar will keep bouncing hopeless until another move target is given or the move is stopped
• OS_NPC_LAND_AT_TARGET - If given and the avatar is flying, then it will land when it reaches the target. If OS_NPC_NO_FLY is given then this option has no effect.

OS_NPC_FLY and OS_NPC_NO_FLY are options that cannot be combined - the avatar will end up doing one or the other. If you want the avatar to fly and land at the target, then OS_NPC_LAND_AT_TARGET must be combined with OS_NPC_FLY. For instance,

osNpcMoveToTarget(npc, llGetPos() + <9,9,5>, OS_NPC_FLY|OS_NPC_LAND_AT_TARGET);

osNpcStopMoveToTarget

osNpcStopMoveToTarget(key npc):void

Stop a current move to a target.

Communication

osNpcSay

osNpcSay(key npc, string message):void

Get the NPC to say the given message.

Appearance

NPC appearance is manipulated by saving and loading appearance data to notecards from the same inventory as the invoking script.

osOwnerSaveAppearance

osOwnerSaveAppearance(string notecard):key

Save the owner's current appearance to a notecard in the prim's inventory. This includes body part data, clothing items and attachments. If a notecard with the same name already exists then it is replaced. The owner must be present in the region when this function is invoked. The baked textures for the owner (necessary to recreate appearance on the NPC) are saved permanently.

osAgentSaveAppearance

osAgentSaveAppearance(key agentId, string notecard):key

Save an arbitrary avatar's appearance to a notecard in the prim's inventory. This includes body part data, clothing items and attachments. If a notecard with the same name already exists then it is replaced. The avatar must be present in the region when this function is invoked. The baked textures for the avatar (necessary to recreate appearance on the NPC) are saved permanently.

osNpcSaveAppearance

osNpcSaveAppearance(key npc, string notecard):key

Save the NPC's current appearance to a notecard in the prim's inventory. This includes body part data, clothing items and attachments. If a notecard with the same name already exists then it is replaced. The avatar must be present in the region when this function is invoked. The baked textures for the avatar (necessary to recreate appearance) are saved permanently.

osNpcLoadAppearance

osNpcLoadAppearance(key npc, string notecard):void

Load appearance from a notecard. This notecard must contain appearance data created with one of the save appearance functions.

Example

This is a rough example script for most of the current NPC functionality. Please feel free to improve it.

key npc;
default
{
    state_entry()
    {
        llListen(10,"",NULL_KEY,"");
    }  
 
    listen(integer channel, string name, key id, string msg)
    {
        if (msg != "")
        {
            if (msg == "create")
            {
                osOwnerSaveAppearance("appearance");
                npc = osNpcCreate("Jane", "Doe", <115, 165, 23>, "appearance");
            }   
            else if (msg == "remove" && npc != NULL_KEY)
            {
                osNpcSay(npc, "You will pay for this with your liiiiiivvveeessss!!!.....");
                osNpcRemove (npc);
            }   
            else if (msg == "say" && npc != NULL_KEY)
            {
                osNpcSay(npc, "I am your worst Nightmare!!!!");
            }   
            else if (msg == "move" && npc != NULL_KEY)
            {
                osNpcMoveTo(npc, llGetPos() + <9,9,0>);
            }   
            else if (msg == "movetarget" && npc != NULL_KEY)
            {
                osNpcMoveToTarget(npc, llGetPos() + <9,9,5>, OS_NPC_FLY|OS_NPC_LAND_AT_TARGET);
            }
            else if (msg == "movetargetnoland" && npc != NULL_KEY)
            {
                osNpcMoveToTarget(npc, llGetPos() + <9,9,5>, OS_NPC_FLY);
            }            
            else if (msg == "movetargetwalk" && npc != NULL_KEY)
            {
                osNpcMoveToTarget(npc, llGetPos() + <9,9,0>, OS_NPC_NO_FLY);                
            }
            else if (msg == "rot" && npc != NULL_KEY)
            {
                vector xyz_angles = <0,0,10>; // This is to define a 10 degree change
                vector angles_in_radians = xyz_angles * DEG_TO_RAD; // Change to Radians
                rotation rot_xyzq = llEuler2Rot(angles_in_radians); // Change to a Rotation                
                rotation rot = osNpcGetRot(npc);
                osNpcSetRot(npc, rot * rot_xyzq);
            }
            else if (msg == "animate" && npc != NULL_KEY)
            {
                osAvatarPlayAnimation(npc, "stabbed+die_2");
                llSleep(3);
                osAvatarStopAnimation(npc, "stabbed+die_2");
            }   
            else if (msg == "save" && npc != NULL_KEY)
            {
                osNpcSaveAppearance(npc, "appearance");
            }
            else if (msg == "load" && npc != NULL_KEY)
            {
                osNpcLoadAppearance(npc, "appearance");
            }
            else if (msg == "clone")
            {
                osOwnerSaveAppearance("appearance");
            }
            else if (msg == "stop" && npc != NULL_KEY)
            {
                osNpcStopMoveToTarget(npc);
            }
            else
            {
                llOwnerSay("I don't understand [" + msg + "]");
            }
        }   
    }   
}

Questions/Comments

Please feel free to write any questions or comments you have about OSSL NPC functionality here.