Difference between revisions of "LlCreateCharacter"

From Second Life Wiki
Jump to navigation Jump to search
m
m
Line 1: Line 1:
{{Pathfinding alpha}}
{{Pathfinding alpha}}
{{LSL_Function|
{{LSL_Function
func=llCreateCharacter|
|mode=rc
func_desc=Creates a pathfinding entity, known as a "character", from the object containing the script.  Required to activate use of pathfinding functions.|
|func=llCreateCharacter
func_footnote=By default, the character's shape will be an upright capsule approximately the size of the linkset, adjustable via the options list.  The linkset must use the land impact accounting system introduced with the mesh project.
|func_desc=Creates a pathfinding entity, known as a "character", from the object containing the script.  Required to activate use of pathfinding functions.
If called on an existing character, all unspecified parameters other than character size will revert to their defaults (if not specified, character size will not change). This is STRONGLY preferred over calling llDeleteCharacter() followed by llCreateCharacter() as it is much, much less taxing on the server.|
|func_footnote=By default, the character's shape will be an upright capsule approximately the size of the linkset, adjustable via the options list.  The linkset must use the land impact accounting system introduced with the mesh project.
p1_type=list|
If called on an existing character, all unspecified parameters other than character size will revert to their defaults (if not specified, character size will not change). This is STRONGLY preferred over calling llDeleteCharacter() followed by llCreateCharacter() as it is much, much less taxing on the server.
p1_name=options|
|p1_type=list
p1_desc=Character configuration options.|
|p1_name=options
constants={{LSL_Constants/llCreateCharacter}}|
|p1_desc=Character configuration options.
caveats=(subject to change)
|constants={{LSL_Constants/llCreateCharacter}}
|caveats=(subject to change)
* You only need to use one llCreateCharacter call per object, calling multiple times has no effect.
* You only need to use one llCreateCharacter call per object, calling multiple times has no effect.
* One script can contain an llCreateCharacter call and other scripts can exploit that with other path functions that require it.
* One script can contain an llCreateCharacter call and other scripts can exploit that with other path functions that require it.
Line 16: Line 17:
* If we have multiple scripts containing llCreateCharacter in the same object nothing untoward happens.
* If we have multiple scripts containing llCreateCharacter in the same object nothing untoward happens.
* If multiple scripts use conflicting path functions in the same object (different prims or the same prim) one will take precedence randomly (apparently).
* If multiple scripts use conflicting path functions in the same object (different prims or the same prim) one will take precedence randomly (apparently).
* CHARACTER_DESIRED_SPEED ranges from 0.02 to 50.0. (Assumption: Related to and expected to be <= CHARACTER_MAX_SPEED)
* [[CHARACTER_DESIRED_SPEED]] ranges from 0.02 to 50.0. (Assumption: Related to and expected to be <= CHARACTER_MAX_SPEED)
* CHARACTER_MAX_SPEED - See JIRA PATHBUG 42 - In testing, we have found a desired speed of 10m/s to be plenty fast most uses and that higher speeds may produce unexpected results (particularly when navigating tight spaces or making sharp turns). March 15, 2012
* CHARACTER_MAX_SPEED]] - See {{JIRA|PATHBUG-42}} - In testing, we have found a desired speed of 10m/s to be plenty fast most uses and that higher speeds may produce unexpected results (particularly when navigating tight spaces or making sharp turns). March 15, 2012
* CHARACTER_MAX_ANGLAR_ACCEL min = 1.5708
* [[CHARACTER_MAX_ANGLAR_ACCEL]] min = 1.5708
* CHARACTER_RADIUS ranges from 0.1 to 5.0.
* [[CHARACTER_RADIUS]] ranges from 0.1 to 5.0.
* CHARACTER_LENGTH ranges from 0.0 to 10.0.
* [[CHARACTER_LENGTH]] ranges from 0.0 to 10.0.
* <nowiki>[TRAVERSAL_TYPE, TRAVERSAL_TYPE_SLOW | TRAVERSAL_TYPE_FAST | TRAVERSAL_TYPE_NONE] - only use one of these parameters or omit. Defaults to TRAVERSAL_TYPE_NONE to if omitted. This affects whether a character moving on terrain that is less than 100% walkable will move faster (e.g., a cat crossing a street) or slower (e.g., a car driving in a swamp).</nowiki>
* <nowiki>[</nowiki>[[TRAVERSAL_TYPE]], [[TRAVERSAL_TYPE_SLOW]] | [[TRAVERSAL_TYPE_FAST]] | [[TRAVERSAL_TYPE_NONE]]] - only use one of these parameters or omit. Defaults to TRAVERSAL_TYPE_NONE to if omitted. This affects whether a character moving on terrain that is less than 100% walkable will move faster (e.g., a cat crossing a street) or slower (e.g., a car driving in a swamp).
* <nowiki>[CHARACTER_TYPE, CHARACTER_TYPE_A | CHARACTER_TYPE_B | CHARACTER_TYPE_C | CHARACTER_TYPE_D | CHARACTER_TYPE_NONE] - only use one of these parameters or omit. Defaults to CHARACTER_TYPE_NONE to if omitted. This determines which of the 4 walkability coefficients the character pays attention to.</nowiki>
* <nowiki>[</nowiki>[[CHARACTER_TYPE]], [[CHARACTER_TYPE_A]] | [[CHARACTER_TYPE_B]] | [[CHARACTER_TYPE_C]] | [[CHARACTER_TYPE_D]] | [[CHARACTER_TYPE_NONE]]] - only use one of these parameters or omit. Defaults to [[CHARACTER_TYPE_NONE]] to if omitted. This determines which of the 4 walkability coefficients the character pays attention to.
* The character's shape is a capsule (cylinder with spherical ends) with a length (from tip to tip) and a circular cross section of some radius. These two size parameters are what is controlled by the CHARACTER_LENGTH and CHARACTER_RADIUS params respectively.
* The character's shape is a capsule (cylinder with spherical ends) with a length (from tip to tip) and a circular cross section of some radius. These two size parameters are what is controlled by the [[CHARACTER_LENGTH]] and [[CHARACTER_RADIUS]] params respectively.
* Note that the character's true "length" cannot be smaller than twice the radius plus 0.1m; however, you're welcome to specify a value lower than that (but more than zero) -- the script shouldn't complain.  
* Note that the character's true "length" cannot be smaller than twice the radius plus 0.1m; however, you're welcome to specify a value lower than that (but more than zero) -- the script shouldn't complain.  
* The capsule is usually oriented vertically. Use [CHARACTER_ORIENTATION, HORIZONTAL] if you need your character to be horizontal.
* The capsule is usually oriented vertically. Use <nowiki>[</nowiki>[[CHARACTER_ORIENTATION]], [[HORIZONTAL]]] if you need your character to be horizontal.
** Use a vertical capsule whenever possible; horizontal capsules may become stuck more easily than vertical capsules.
** Use a vertical capsule whenever possible; horizontal capsules may become stuck more easily than vertical capsules.
* Removing the script from a prim will not stop pathing behavior, in the same way that particles and hover text remain. To stop a pathing command use llExecCharacterCmd(CHARACTER_CMD_STOP, []).
* Removing the script from a prim will not stop pathing behavior, in the same way that particles and hover text remain. To stop a pathing command use <code>[[llExecCharacterCmd]]([[CHARACTER_CMD_STOP]], [])</code>.
*  The root prim's position determines the characters height above the surface; if your character sinks under the surface or is too high above it adjust the relative position of the root prim to the rest of the linkset (or create a new root prim, which you might texture invisible, to control your character's apparent height).|
*  The root prim's position determines the characters height above the surface; if your character sinks under the surface or is too high above it adjust the relative position of the root prim to the rest of the linkset (or create a new root prim, which you might texture invisible, to control your character's apparent height).
examples=
|examples=
<lsl>
<lsl>
default
default
Line 45: Line 46:
     }
     }
}
}
</lsl>|
</lsl>
notes=This function is currently in alpha testing.|
|notes=This function is currently in alpha testing.
also_functions=
|also_functions=
* [[llCreateCharacter]]
* [[llCreateCharacter]]
* [[llDeleteCharacter]]
* [[llDeleteCharacter]]
Line 58: Line 59:
* [[llPursue]]
* [[llPursue]]
* [[llUpdateCharacter]]
* [[llUpdateCharacter]]
* [[llWanderWithin]]|
* [[llWanderWithin]]
also_events=
|also_events=
* [[path_update]]
* [[path_update]]
}}
}}

Revision as of 08:27, 27 June 2012

KBcaution.png Important: This feature is currently only available on the release candidate server channels.

Summary

Function: llCreateCharacter( list options );

Creates a pathfinding entity, known as a "character", from the object containing the script. Required to activate use of pathfinding functions.

• list options – Character configuration options.

By default, the character's shape will be an upright capsule approximately the size of the linkset, adjustable via the options list. The linkset must use the land impact accounting system introduced with the mesh project. If called on an existing character, all unspecified parameters other than character size will revert to their defaults (if not specified, character size will not change). This is STRONGLY preferred over calling llDeleteCharacter() followed by llCreateCharacter() as it is much, much less taxing on the server.

Option Default Range / Values Description
CHARACTER_DESIRED_SPEED 1 6 [0.2, 40.0] Speed of pursuit in meters per second.
CHARACTER_RADIUS 2 [0.125, 5.0] Set collision capsule radius.
CHARACTER_LENGTH 3 (0.0, 10.0] Set collision capsule length

If the value is less than twice the radius plus 0.1m, it will be set to twice the radius plus 0.1m.

CHARACTER_ORIENTATION 4 VERTICAL VERTICAL, HORIZONTAL Set the character orientation.
TRAVERSAL_TYPE 7 TRAVERSAL_TYPE_SLOW TRAVERSAL_TYPE_FAST, TRAVERSAL_TYPE_SLOW, TRAVERSAL_TYPE_NONE Controls the speed at which characters moves on terrain that is less than 100% walkable will move faster (e.g., a cat crossing a street) or slower (e.g., a car driving in a swamp).

To use _FAST or _SLOW, you must specify a CHARACTER_TYPE.

CHARACTER_TYPE 6 CHARACTER_TYPE_NONE CHARACTER_TYPE_A, CHARACTER_TYPE_B, CHARACTER_TYPE_C, CHARACTER_TYPE_D, CHARACTER_TYPE_NONE Specifies which walkability coefficient will be used by this character.
CHARACTER_AVOIDANCE_MODE 5 AVOID_CHARACTERS | AVOID_DYNAMIC_OBSTACLES Combinable Flags: AVOID_CHARACTERS, AVOID_DYNAMIC_OBSTACLES, AVOID_NONE Allows you to specify that a character should not try to avoid other characters, should not try to avoid dynamic obstacles (relatively fast moving objects and avatars), or both. This is framed in the positive sense ([CHARACTER_AVOIDANCE_MODE, AVOID_CHARACTERS] would create a character that avoided other characters but not agents or moving vehicles). Setting this parameter to AVOID_NONE causes the character to not avoid either category.
CHARACTER_MAX_ACCEL 8 20 [0.5, 40.0] The character's maximum acceleration rate.
CHARACTER_MAX_DECEL 9 30 [0.5, 60.0] The character's maximum deceleration rate.
CHARACTER_DESIRED_TURN_SPEED 12 6 [0.02, 40.0] The character's maximum speed while turning--note that this is only loosely enforced (i.e., a character may turn at higher speeds under certain conditions)
CHARACTER_MAX_TURN_RADIUS 10 1.25 [0.1, 10.0] The character's turn radius when traveling at CHARACTER_DESIRED_TURN_SPEED
CHARACTER_MAX_SPEED 13 20 [1, 40.0] The character's maximum speed. Affects speed when avoiding dynamic obstacles and when traversing low-walkability objects in TRAVERSAL_TYPE_FAST mode.
CHARACTER_ACCOUNT_FOR_SKIPPED_FRAMES 14 TRUE TRUE or FALSE TRUE matches pre-existing behavior. If set to FALSE, character will not attempt to catch up on lost time when pathfinding performance is low, potentially providing more reliable movement (albeit while potentially appearing to be more stuttery).
CHARACTER_STAY_WITHIN_PARCEL 15 Depends* TRUE or FALSE FALSE matches traditional behavior. If set to TRUE, treat the parcel boundaries as one-way obstacles (will re-enter but can't leave on it's own).

Caveats

(subject to change)

  • You only need to use one llCreateCharacter call per object, calling multiple times has no effect.
  • One script can contain an llCreateCharacter call and other scripts can exploit that with other path functions that require it.
  • llCreateCharacter status survives state changes, script resets, and rezzing.
  • llCreateCharacter is always required for all pathing functions.
  • If we have multiple scripts containing llCreateCharacter in the same object nothing untoward happens.
  • If multiple scripts use conflicting path functions in the same object (different prims or the same prim) one will take precedence randomly (apparently).
  • CHARACTER_DESIRED_SPEED ranges from 0.02 to 50.0. (Assumption: Related to and expected to be <= CHARACTER_MAX_SPEED)
  • CHARACTER_MAX_SPEED]] - See PATHBUG-42 - In testing, we have found a desired speed of 10m/s to be plenty fast most uses and that higher speeds may produce unexpected results (particularly when navigating tight spaces or making sharp turns). March 15, 2012
  • CHARACTER_MAX_ANGLAR_ACCEL min = 1.5708
  • CHARACTER_RADIUS ranges from 0.1 to 5.0.
  • CHARACTER_LENGTH ranges from 0.0 to 10.0.
  • [TRAVERSAL_TYPE, TRAVERSAL_TYPE_SLOW

Examples

<lsl> default { 

   state_entry()
   {
       llCreateCharacter([CHARACTER_MAX_SPEED, 25, CHARACTER_DESIRED_SPEED, 15.0]);
       //MAX_SPEED is @ 20 by default
   }
   
   touch_start(integer total_number)
   {
       list points = [llGetPos() + <5,0,0>, llGetPos() - <5,0,0>];
       llPatrolPoints(points, []);
   }

}

</lsl>

Notes

This function is currently in alpha testing.

Deep Notes

Footnotes

  1. ^ The ranges in this article are written in Interval Notation.

Signature

function void llCreateCharacter( list options );
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlCreateCharacter&oldid=1169830"