Category:OSSL Functions

2012-04-29T17:47:18Z

Talun: /* NPCs */

== Current OSSL Functions Implemented ==

Updated OSSL Functions as of OpenSim DEV 0.7.4 OpenSim-0007711-r/18206 March 1, 2012
 
'''!''' Partial Update December.10.2010 With commits of this date some functions have been corrected to use standard ossl conventions. The previous are tagged as deprecated with their replacement shown. The deprecated functions will advise you with a msg that they have been deprecated and to use new osFunction name instead. Further Updates are needed to complete existing list of osFunctions.

Special Note: Some Functions as shown use '''"double"''' as a Value instead of '''"float" '''these vary for purposes of accuracy as shown Below.

(Float is short for "floating point", and just means a number with a point something on the end.)

The difference between the two is in the size of the numbers that they can hold. For float, you can have up to 7 digits in your number. For doubles, you can have up to 16 digits. To be more precise, here's the official size: ( float: 1.5 × 10-45 to 3.4 × 1038 ) ( double: 5.0 × 10-324 to 1.7 × 10308 )

Note that some function takes doubles as arguments but may be internally down-casted to floats.

Each of these functions has an threat level associated to it. See [[Threat level]] for more information and an overview of each function's level.

=== Avatar Managements ===
{{multicol}}
*[[osGetAgentIP]]
*[[osGetAgents]]
*[[osGetAvatarList]]
*[[osAvatarName2Key]]
*[[osAvatarPlayAnimation]]
*[[osAvatarStopAnimation]]
*[[osAgentSaveAppearance]]
{{multicol-break}}
*[[osOwnerSaveAppearance]]
*[[osTeleportAgent]]
*[[osTeleportOwner]]
*[[osKickAvatar]]
*[[osCauseDamage]]
*[[osCauseHealing]]
*[[osInviteToGroup]]
*[[osEjectFromGroup]]
{{multicol-end}}

=== NPCs ===
{{multicol}}
*[[osNpcCreate]]
*[[osNpcGetPos]]
*[[osNpcGetRot]]
*[[osNpcGetOwner]]
*[[osNpcLoadAppearance]]
*[[osNpcMoveTo]]
*[[osNpcMoveToTarget]]
*[[osNpcRemove]]
*[[osNpcSaveAppearance]]
{{multicol-break}}
*[[osNpcSay]]
*[[osNpcSetRot]]
*[[osNpcShout]]
*[[osNpcSit]]
*[[osNpcStand]]
*[[osNpcStopMoveToTarget]]
*[[osIsNpc]]
*[[osNpcPlayAnimation]]
*[[osNpcStopAnimation]]
*[[osNpcWhisper]]
{{multicol-end}}

=== Prim Manipulations ===
*[[osGetPrimitiveParams]]
*[[osGetLinkPrimitiveParams]]
*[[osSetPrimitiveParams]]
*[[osSetProjectionParams]]
*[[osSetSpeed]]
*[[osMessageObject]]
*[[osGetInventoryDesc]]

=== Prim Drawings ===
{{multicol}}
*[[osMovePen]]
*[[osDrawLine]]
*[[osDrawText]]
*[[osDrawEllipse]]
*[[osDrawRectangle]]
*[[osDrawFilledRectangle]]
*[[osDrawPolygon]]
*[[osDrawFilledPolygon]]
*[[osDrawImage]]
{{multicol-break}}
*[[osGetDrawStringSize]]
*[[osSetFontName]]
*[[osSetFontSize]]
*[[osSetPenSize]]
*[[osSetPenColor]]
*[[osSetPenCap]]
{{multicol-end}}

=== Dynamic Textures ===
*[[osSetDynamicTextureData]]
*[[osSetDynamicTextureDataBlend]]
*[[osSetDynamicTextureDataBlendFace]]
*[[osSetDynamicTextureURL]]
*[[osSetDynamicTextureURLBlend]]
*[[osSetDynamicTextureURLBlendFace]]

=== Notecards ===
*[[osMakeNotecard]]
*[[osGetNotecard]]
*[[osGetNotecardLine]]
*[[osGetNumberOfNotecardLines]]

=== Parcels ===
*[[osParcelJoin]]
*[[osParcelSubdivide]]
*[[osSetParcelDetails]]

=== Terrains ===
*[[osGetTerrainHeight]]
*[[osSetTerrainHeight]]
*[[osTerrainFlush]]
*[[osSetTerrainTexture]]
*[[osSetTerrainTextureHeight]]

=== WindLights ===
{{multicol}}
*[[osSetRegionWaterHeight]]
*[[osSetRegionSunSettings]]
*[[osSetEstateSunSettings]]
*[[osGetCurrentSunHour]]
*[[osGetSunParam]]
*[[osSetSunParam]]
{{multicol-break}}
*[[osWindActiveModelPluginName]]
*[[osGetWindParam]]
*[[osSetWindParam]]
{{multicol-end}}

=== Grid Informations ===
{{multicol}}
*[[osGetGridName]]
*[[osGetGridNick]]
*[[osGetGridLoginURI]]
*[[osGetGridHomeURI]]
*[[osGetGridGatekeeperURI]]
*[[osGetGridCustom]]
*[[osGetScriptEngineName]]
*[[osGetSimulatorVersion]]
*[[osGetSimulatorMemory]]
{{multicol-break}}
*[[osGetMapTexture]]
*[[osGetRegionMapTexture]]
*[[osGetRegionStats]]
*[[osLoadedCreationDate]]
*[[osLoadedCreationTime]]
*[[osLoadedCreationID]]
{{multicol-end}}

=== Administrations ===
*[[osRegionNotice]]
*[[osRegionRestart]]
*[[osConsoleCommand]]
*[[osSetParcelMediaURL]]
*[[osSetPrimFloatOnWater]]
*[[osSetParcelSIPAddress]]

=== Misc ===
*[[osSetStateEvents]]
*[[osList2Double]]
*[[osKey2Name]]
*[[osFormatString]]
*[[osMatchString]]
*[[osUnixTimeToTimestamp]]
*[[osParseJSON]]
*[[osParseJSONNew]]

=== Deprecated ===
*[[osParcelSetDetails|<strike>osParcelSetDetails</strike>]] - Use [[osSetParcelDetails]]
*[[osSetPenColour|<strike>osSetPenColour</strike>]] - Use [[osSetPenColor]]
*[[osSunGetParam|<strike>osSunGetParam</strike>]] - Use [[osGetSunParam]]
*[[osSunSetParam|<strike>osSunSetParam</strike>]] - Use [[osSetSunParam]]
*[[osTerrainGetHeight|<strike>osTerrainGetHeight</strike>]] - Use [[osGetTerrainHeight]]
*[[osTerrainSetHeight|<strike>osTerrainSetHeight</strike>]] - Use [[osSetTerrainHeight]]

== See Also ==

*[[LSL Status|LSL/OSSL Status Page]]
*OSSL
**[[OSSL Status/Types|OSSL Types Status Page]]
**[[OSSL Status/Events|OSSL Events Status Page]]
**[[OSSL Proposals|OSSL Proposed Functions]]
**[[OSSL_Implemented|OSSL Implemented Functions]]
**[[OSSL Enabling Functions]]
**[[OSSL Standards|OSSL Standards]]
**[[Dynamic_textures|OSSL osDynamicTextures Functions Index Page]]
**[[OSSL TextureDrawing|OSSL TextureDrawing Extended Information]]
**[[OSSLNPC|OSSL functions for working with NPCs]]

[[Category:OSSL]]

OSSLNPC

2012-04-29T17:41:42Z

Talun: /* osNpcSay */

=Introduction=

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

The general philosophy in creating these new functions is to

# Give script writers the simple tools needed to create more sophisticated behaviour.
# 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 OpenSimulator 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

# Enabled = true set in the [NPC] section.
# Enabled = true set in the [XEngine] section.
# AllowOSFunctions = true in the [XEngine] section.
# 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.
* OpenSimulator 0.7.3-rc1 introduces the concept of 'owned' and 'unowned' NPC. An 'owned' NPC is one where only the creating script and other scripts with the same owner can manipulate the NPC. An 'unowned' NPC is one where any script with the right permissions (as defined in the [XEngine] configuration section) can manipulate it. In OpenSimulator 0.7.3, all avatars are 'owned' by default unless otherwise specified in the osNpcCreate() call.

= Sensing =

In OpenSimulator 0.7.2, LSL sensors will detect NPCs as ordinary agents.

In OpenSimulator 0.7.3-rc1 onwards, unless otherwise specified, NPCs will only be detected using the OpenSimulator-specific NPC flag, e.g.

<source lang="lsl">
//Author: mewtwo0641

list keys = [];
key npc;
string toucher;
key toucherkey;
vector toucherPos;
integer npc_on = FALSE;

default
{
touch_start(integer x)
{
toucherkey = llDetectedKey(0);
toucherPos = llDetectedPos(0);
vector npcPos = llGetPos() + <1,1,1>;

if(npc_on == FALSE)
{
npc = osNpcCreate("Fred", "Flintstone", npcPos, toucherkey);
npc_on = TRUE;
llSensor("", "", AGENT | NPC, 96.0, PI); //Will always return NPC key regardless of npc create option
return;
}

if(npc_on == TRUE)
{
osNpcRemove(npc);
llResetScript();
}
}

sensor(integer num)
{
keys = [];
integer i = 0;

for(i; i < num; i++)
{
keys += llDetectedKey(i);
}

llOwnerSay(llDumpList2String(keys, "\n"));
}

no_sensor()
{
keys = [];
}
}
</source>

You can get NPCs to be detected as AGENTs again using the OS_NPC_SENSE_AS_AGENT option below in osNpcCreate().

The justification is that detecting NPCs as AGENTs by default may make some scripts unusable (e.g. radars that know nothing about NPCs). However, conversely other scripts may not behave as expected if NPCs aren't sensed as agents (e.g. doors that open automatically for avatars would not open for NPCs).

Please note that this applies only to sensors at this time.

= Functions =

== Create and Remove ==
=== [[osNpcCreate]] ===

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

cloneFrom may be:

* Name of the notecard containing a serialized avatar appearance, or
* Asset UUID of the Notecard, or
* UUID of an avatar logged into the same region. However, please note that this appearance will not be persisted unless osNpcSaveAppearance() is called.

If the NPC is successfully created, then its UUID is returned, which is required for all subsequent functions. Example is available at [[osNpcCreate]]

(OpenSimulator 0.7.3-rc1 onwards only). This creates an NPC that is 'owned' by the creating script and sensed using the OpenSimulator-only NPC flag for sensors.

=== osNpcCreate ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcCreate(string firstname, string lastname, vector position, string cloneFrom, integer options):key

cloneFrom may be:

* Name of the notecard containing a serialized avatar appearance, or
* Asset UUID of the Notecard, or
* UUID of an avatar logged into the same region. However, please note that this appearance will not be persisted unless osNpcSaveAppearance() is called.

integer is a set of flags that may be 0 or one or more of

* OS_NPC_NOT_OWNED - create an unowned NPC.
* OS_NPC_SENSE_AS_AGENT - create an NPC that is sensed as an AGENT with LSL sensors

If the NPC is successfully created, then its UUID is returned, which is required for all subsequent functions. Example is available at [[osNpcCreate]]

=== [[osNpcRemove]] ===

osNpcRemove(key npc):void

Remove the given avatar from the region. Example at [[osNpcRemove]].

== Get and Set ==
=== osIsNpc ===

OpenSimulator 0.7.3-rc1 onwards.

osIsNpc(key npc):integer

Returns TRUE if the given key is an NPC, false otherwise.

=== [[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.

=== [[osNpcGetOwner]] ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcGetOwner(key npc):key

Return the owner of the given NPC (i.e. the owner of the script that created it). If the NPC is unowned or the input key does not belong to an NPC then returns NULL_KEY.

== Movement ==

=== [[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.

== Sitting and standing ==

=== osNpcSit ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcSit(key npc, key target, int options):void

Sit an NPC on a prim target. As yet there are no options, so always input 0.

=== osNpcStand ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcStand(key npc):void

Make an npc stand up.

== Communication ==

=== [[osNpcSay]] ===

osNpcSay(key npc, string message):void also osNpcSay(key npc, int channel, string message):void

Get the NPC to say the given message. Using the second version the chat is said on the given channel.

=== [[osNpcShout]] ===

osNpcShout(key npc, int channel, string message):void

Get the NPC to shout the given message on the given channel.

=== [[osNpcWhisper]] ===

osNpcWhisper(key npc, int channel, string message):void

Get the NPC to whisper the given message on the given channel.

== Animations ==

=== osNpcPlayAnimation ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcPlayAnimation(key npc, string animation):void

Get an NPC to play an animation. The animation can either be a key or the name of an animation in the same inventory as the script.

=== osNpcStopAnimation ===

In OpenSimulator 0.7.3-rc1 there is a bug which makes this play the animation instead. This will be corrected for the final release but in the mean time please use osAvatarStopAnimation() instead.

osNpcStopAnimation(key npc, string animation):void

Get an NPC to stop playing an animation. The animation can either be a key or the name of an animation in the same inventory as the script.

== 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.

= Examples =

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

<source lang = "lsl">
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,45>; // This is to define a 45 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 + "]");
}
}
}
}
</source>

= Questions/Comments =

Please leave your questions and comments on [[Talk:OSSLNPC|this article's talk page]].

[[Category:OSSL Functions]]
[[Category:Scripting]]

OSSLNPC

2012-04-29T17:39:49Z

Talun: /* Communication */

=Introduction=

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

The general philosophy in creating these new functions is to

# Give script writers the simple tools needed to create more sophisticated behaviour.
# 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 OpenSimulator 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

# Enabled = true set in the [NPC] section.
# Enabled = true set in the [XEngine] section.
# AllowOSFunctions = true in the [XEngine] section.
# 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.
* OpenSimulator 0.7.3-rc1 introduces the concept of 'owned' and 'unowned' NPC. An 'owned' NPC is one where only the creating script and other scripts with the same owner can manipulate the NPC. An 'unowned' NPC is one where any script with the right permissions (as defined in the [XEngine] configuration section) can manipulate it. In OpenSimulator 0.7.3, all avatars are 'owned' by default unless otherwise specified in the osNpcCreate() call.

= Sensing =

In OpenSimulator 0.7.2, LSL sensors will detect NPCs as ordinary agents.

In OpenSimulator 0.7.3-rc1 onwards, unless otherwise specified, NPCs will only be detected using the OpenSimulator-specific NPC flag, e.g.

<source lang="lsl">
//Author: mewtwo0641

list keys = [];
key npc;
string toucher;
key toucherkey;
vector toucherPos;
integer npc_on = FALSE;

default
{
touch_start(integer x)
{
toucherkey = llDetectedKey(0);
toucherPos = llDetectedPos(0);
vector npcPos = llGetPos() + <1,1,1>;

if(npc_on == FALSE)
{
npc = osNpcCreate("Fred", "Flintstone", npcPos, toucherkey);
npc_on = TRUE;
llSensor("", "", AGENT | NPC, 96.0, PI); //Will always return NPC key regardless of npc create option
return;
}

if(npc_on == TRUE)
{
osNpcRemove(npc);
llResetScript();
}
}

sensor(integer num)
{
keys = [];
integer i = 0;

for(i; i < num; i++)
{
keys += llDetectedKey(i);
}

llOwnerSay(llDumpList2String(keys, "\n"));
}

no_sensor()
{
keys = [];
}
}
</source>

You can get NPCs to be detected as AGENTs again using the OS_NPC_SENSE_AS_AGENT option below in osNpcCreate().

The justification is that detecting NPCs as AGENTs by default may make some scripts unusable (e.g. radars that know nothing about NPCs). However, conversely other scripts may not behave as expected if NPCs aren't sensed as agents (e.g. doors that open automatically for avatars would not open for NPCs).

Please note that this applies only to sensors at this time.

= Functions =

== Create and Remove ==
=== [[osNpcCreate]] ===

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

cloneFrom may be:

* Name of the notecard containing a serialized avatar appearance, or
* Asset UUID of the Notecard, or
* UUID of an avatar logged into the same region. However, please note that this appearance will not be persisted unless osNpcSaveAppearance() is called.

If the NPC is successfully created, then its UUID is returned, which is required for all subsequent functions. Example is available at [[osNpcCreate]]

(OpenSimulator 0.7.3-rc1 onwards only). This creates an NPC that is 'owned' by the creating script and sensed using the OpenSimulator-only NPC flag for sensors.

=== osNpcCreate ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcCreate(string firstname, string lastname, vector position, string cloneFrom, integer options):key

cloneFrom may be:

* Name of the notecard containing a serialized avatar appearance, or
* Asset UUID of the Notecard, or
* UUID of an avatar logged into the same region. However, please note that this appearance will not be persisted unless osNpcSaveAppearance() is called.

integer is a set of flags that may be 0 or one or more of

* OS_NPC_NOT_OWNED - create an unowned NPC.
* OS_NPC_SENSE_AS_AGENT - create an NPC that is sensed as an AGENT with LSL sensors

If the NPC is successfully created, then its UUID is returned, which is required for all subsequent functions. Example is available at [[osNpcCreate]]

=== [[osNpcRemove]] ===

osNpcRemove(key npc):void

Remove the given avatar from the region. Example at [[osNpcRemove]].

== Get and Set ==
=== osIsNpc ===

OpenSimulator 0.7.3-rc1 onwards.

osIsNpc(key npc):integer

Returns TRUE if the given key is an NPC, false otherwise.

=== [[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.

=== [[osNpcGetOwner]] ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcGetOwner(key npc):key

Return the owner of the given NPC (i.e. the owner of the script that created it). If the NPC is unowned or the input key does not belong to an NPC then returns NULL_KEY.

== Movement ==

=== [[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.

== Sitting and standing ==

=== osNpcSit ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcSit(key npc, key target, int options):void

Sit an NPC on a prim target. As yet there are no options, so always input 0.

=== osNpcStand ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcStand(key npc):void

Make an npc stand up.

== Communication ==

=== [[osNpcSay]] ===

osNpcSay(key npc, string message):void

Get the NPC to say the given message.

=== [[osNpcShout]] ===

osNpcShout(key npc, int channel, string message):void

Get the NPC to shout the given message on the given channel.

=== [[osNpcWhisper]] ===

osNpcWhisper(key npc, int channel, string message):void

Get the NPC to whisper the given message on the given channel.

== Animations ==

=== osNpcPlayAnimation ===

OpenSimulator 0.7.3-rc1 onwards.

osNpcPlayAnimation(key npc, string animation):void

Get an NPC to play an animation. The animation can either be a key or the name of an animation in the same inventory as the script.

=== osNpcStopAnimation ===

In OpenSimulator 0.7.3-rc1 there is a bug which makes this play the animation instead. This will be corrected for the final release but in the mean time please use osAvatarStopAnimation() instead.

osNpcStopAnimation(key npc, string animation):void

Get an NPC to stop playing an animation. The animation can either be a key or the name of an animation in the same inventory as the script.

== 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.

= Examples =

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

<source lang = "lsl">
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,45>; // This is to define a 45 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 + "]");
}
}
}
}
</source>

= Questions/Comments =

Please leave your questions and comments on [[Talk:OSSLNPC|this article's talk page]].

[[Category:OSSL Functions]]
[[Category:Scripting]]