Difference between revisions of "LlSensor"

From Second Life Wiki
Jump to: navigation, search
m (testing - will revert)
m (Changed the caveat about sensors in attachments to refer to the root prim of the attachment only. Added a caveat after to describe what happens with sensors in non-root prims of attachments.)
 
(20 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
{{LSL_Function
 
{{LSL_Function
<!--|inject-2={{LSL_Function/uuid|id|object=*|sim=*}}{{LSL Constants/Sensing|type}}-->
+
|inject-2={{LSL_Function/uuid|id|object=*|sim=*}}{{LSL Constants/Sensing|type}}
 
|func_id=28|func_sleep=0.0|func_energy=10.0
 
|func_id=28|func_sleep=0.0|func_energy=10.0
 
|sort=Sensor|func=llSensor
 
|sort=Sensor|func=llSensor
|func_desc=Performs a single scan for '''name''' and '''id''' with '''type''' within '''range''' meters and '''arc''' radians of forward vector
+
|func_desc=Performs a single scan for {{LSLP|name}} and {{LSLP|id}} with {{LSLP|type}} within {{LSLP|radius}} meters and {{LSLP|arc}} radians of forward vector
|p1_type=string|p1_name=name|p1_desc=object or avatar name
+
|p1_type=string|p1_name=name|p1_hover=object or avatar name|p1_desc=object or avatar name[[#NameFormat|<span style="color:red;">!</span>]]
<!--|p2_type=key|p2_name=id|p2_desc=
+
|p2_type=key|p2_name=id|p2_desc=
|p3_type=integer|p3_name=type|p3_desc=mask ({{#var:AGENT}},{{#var:AGENT_BY_LEGACY_NAME}},{{#var:AGENT_BY_USERNAME}},{{#var:ACTIVE}}, {{#var:PASSIVE}}, and/or {{#var:SCRIPTED}})|p3_hover=mask (AGENT, AGENT_BY_LEGACY_NAME, AGENT_BY_USERNAME, ACTIVE, PASSIVE, and/or SCRIPTED)
+
|p3_type=integer|p3_name=type|p3_desc=mask ({{#var:AGENT}}, {{#var:AGENT_BY_LEGACY_NAME}}, {{#var:AGENT_BY_USERNAME}}, {{#var:ACTIVE}}, {{#var:PASSIVE}}, and/or {{#var:SCRIPTED}})|p3_hover=mask (AGENT, AGENT_BY_LEGACY_NAME, AGENT_BY_USERNAME, ACTIVE, PASSIVE, and/or SCRIPTED)
|p4_type=float|p4_name=range|p4_desc=range {{Interval|gte=0.0|center=range|lte=96.0m}}|p4_hover=range 0.0 to 96.0m inclusive
+
|p4_type=float|p4_name=radius|p4_desc=distance from center {{Interval|gte=0.0|center=radius|lte=96.0m}}|p4_hover=radius 0.0 to 96.0m inclusive
|p5_type=float|p5_name=arc|p5_desc=the max angle between the local x-axis of the prim and detectable objects, range 0.0 to {{#var:PI}}|p5_hover=the max angle between the local x-axis of the prim and detectable objects, range 0.0 to PI-->
+
|p5_type=float|p5_name=arc|p5_desc=the max angle between the local x-axis of the prim and detectable objects, range 0.0 to {{#var:PI}}|p5_hover=the max angle between the local x-axis of the prim and detectable objects, range 0.0 to PI
|func_footnote=If '''name''' or '''id''' is empty then that empty constraint is ignored.<br/>If '''id''' is an invalid key or [[NULL_KEY]] it is treated as empty.
+
|func_footnote=If {{LSLP|name}} and/or {{LSLP|id}} are empty, they are ignored.<br/>If {{LSLP|id}} is an invalid key or [[NULL_KEY]] it is treated as empty.<br id="NameFormat"/>Depending upon which AGENT* flag is used determines the format requirements for {{LSLP|name}}
 +
 
 +
See: [http://www.lslwiki.net/lslwiki/wakka.php?wakka=llSensor llSensor] for an excellent explanation of {{LSLP|arc}}.
 
|return_text
 
|return_text
 
|spec
 
|spec
 
|caveats=
 
|caveats=
 
*Objects do not detect themselves, and attachments cannot detect their wearers (this includes HUD attachments).
 
*Objects do not detect themselves, and attachments cannot detect their wearers (this includes HUD attachments).
 +
*Attachments cannot be detected by llSensor.
 
*For an object to be detected, the center of its root prim (the same point it would report with [[llGetRootPosition]]) must be within the sensor beam.
 
*For an object to be detected, the center of its root prim (the same point it would report with [[llGetRootPosition]]) must be within the sensor beam.
 
*For an agent to be detected, a point near the pelvis must be inside the sensor beam (the same as llGetRootPosition would report in a script attached to that avatar). This point is indicated by red crosshairs when Advanced>Character>Display Agent Target is turned on.
 
*For an agent to be detected, a point near the pelvis must be inside the sensor beam (the same as llGetRootPosition would report in a script attached to that avatar). This point is indicated by red crosshairs when Advanced>Character>Display Agent Target is turned on.
 
**If the agent is sitting on an object, the root prim of the sat upon object becomes a second sensor target for the agent (but not if the avatar is outside the sensor arc, see {{Jira|SVC-5145}}).  
 
**If the agent is sitting on an object, the root prim of the sat upon object becomes a second sensor target for the agent (but not if the avatar is outside the sensor arc, see {{Jira|SVC-5145}}).  
*Sensors placed in attachments will use the direction the avatar is facing as their forward vector. In mouselook, this means that it will be wherever the avatar is looking, while out of mouselook, this means whichever way the avatar is pointing. This does not include where the avatar's head is pointing, or what animation the avatar is doing, just the direction the avatar would move in if you walked forward. This is the case, regardless of where the object is attached.  
+
*Sensors placed in the root prim of attachments will use the direction the avatar is facing as their forward vector. In mouselook, this means that it will be wherever the avatar is looking, while out of mouselook, this means whichever way the avatar is pointing. This does not include where the avatar's head is pointing, or what animation the avatar is doing, just the direction the avatar would move in if you walked forward. This is the case, regardless of where the object is attached.
*If '''type''' is zero, the sensor will silently fail, neither [[sensor]] or [[no_sensor]] will be triggered.
+
*Sensors placed in prims other than the root prim of an attachment will have their forward direction offset relative to the root prim's forward direction, e.g. a sensor in a prim whose +X direction is the reverse of the root +X will look backward.
 +
*llSensor does not detect objects or agents across region boundaries
 +
*If {{LSLP|type}} is zero, the sensor will silently fail, neither [[sensor]] or [[no_sensor]] will be triggered.
 
*Only 16 objects will be scanned each time.
 
*Only 16 objects will be scanned each time.
 
|examples=
 
|examples=
This sensor scans a 45 degree cone about the x-axis([[PI]]/2 or [[PI_BY_TWO]] scans a hemisphere. [[PI]] is a spherical scan.)
+
This sensor scans a 45 degree cone about the x-axis ([[PI]]/2 or [[PI_BY_TWO]] scans a hemisphere; [[PI]] is a spherical scan). Also it will only match an agent with the {{LSLGC|Avatar/Name|legacy name}} "Governor Linden".
<lsl>llSensor( "Gigs Taggart", NULL_KEY, AGENT, 96.0, PI/4 );</lsl>
+
<source lang="lsl2">llSensor( "Governor Linden", NULL_KEY, AGENT_BY_LEGACY_NAME, 96.0, PI/4 );</source>
  
 
This sensor detects all prims and agents with a given name within 15m of the sensor.  (AGENT, PASSIVE and ACTIVE behave inclusively.  SCRIPTED is not inclusive and will exclude non-scripted targets (like avatars) from the detected set.)
 
This sensor detects all prims and agents with a given name within 15m of the sensor.  (AGENT, PASSIVE and ACTIVE behave inclusively.  SCRIPTED is not inclusive and will exclude non-scripted targets (like avatars) from the detected set.)
<lsl>llSensor( "", NULL_KEY, ( AGENT | PASSIVE | ACTIVE ), 15.0, PI );</lsl>
+
<source lang="lsl2">llSensor( "", NULL_KEY, ( AGENT | PASSIVE | ACTIVE ), 15.0, PI );</source>
 
+
<gallery>
+
File:sensor_pi_by_four.png|arc = PI / 4
+
File:sensor_pi_by_two.png|arc = PI / 2
+
File:sensor_pi.png|arc = PI
+
</gallery>
+
  
 
Basic example script that when touched executes a sensor scan of agents. When the sensor event is processed it spits out messages to the owner of each detected agents' name.
 
Basic example script that when touched executes a sensor scan of agents. When the sensor event is processed it spits out messages to the owner of each detected agents' name.
<lsl>
+
<source lang="lsl2">
 
default
 
default
 
{
 
{
Line 50: Line 49:
 
     }
 
     }
 
}
 
}
</lsl>
+
</source>
  
 
|helpers
 
|helpers
Line 61: Line 60:
 
|also_articles
 
|also_articles
 
|notes=
 
|notes=
 +
{{LSL Tip|You might want to use [[llGetAgentList]] instead of using sensors to get a list of all avatars within the same parcel or region.}}
 
====Loops & Repetition====
 
====Loops & Repetition====
Using [[llSensor]] in a [[for]] loop is a beginners mistake, as events will not interrupt each other (the sensor event will not interupt whatever event is currently being executed). To perform repeat sensor sweeps, [[llSensorRepeat]] is the better solution. While it is possible to call llSensor from a [[timer]] event, it is less efficient to do so; there is a limit to the number of events that can be processed in a second and using the timer just to call llSensor will result in your script getting less timeslice.
+
Using [[llSensor]] in a [[for]] loop is a beginners mistake, as events will not interrupt each other (the sensor event will not interrupt whatever event is currently being executed). To perform repeat sensor sweeps, [[llSensorRepeat]] is the better solution. While it is possible to call llSensor from a [[timer]] event, it is less efficient to do so; there is a limit to the number of events that can be processed in a second and using the timer just to call llSensor will result in your script getting less timeslice.
 
|permission
 
|permission
 
|negative_index
 
|negative_index
Line 69: Line 69:
 
|cat3=Username/As A Parameter
 
|cat3=Username/As A Parameter
 
|cat4=Legacy Name/As A Parameter
 
|cat4=Legacy Name/As A Parameter
 +
|haiku={{Haiku|The hounds are straining.|Elusive quarry sighted.|The game's afoot!}}
 
}}
 
}}
 +
<div id="box">
 +
==Gallery==
 +
<gallery>
 +
File:sensor_pi_by_four.png|arc = PI / 4
 +
File:sensor_pi_by_two.png|arc = PI / 2
 +
File:sensor_pi.png|arc = PI
 +
</gallery>
 +
</div>

Latest revision as of 08:08, 21 June 2015

Summary

Function: llSensor( string name, key id, integer type, float radius, float arc );

Performs a single scan for name and id with type within radius meters and arc radians of forward vector

• string name object or avatar name!
• key id group, avatar or object UUID that is in the same region
• integer type mask (AGENT, AGENT_BY_LEGACY_NAME, AGENT_BY_USERNAME, ACTIVE, PASSIVE, and/or SCRIPTED)
• float radius distance from center [0.0, 96.0m]
• float arc the max angle between the local x-axis of the prim and detectable objects, range 0.0 to PI

If name and/or id are empty, they are ignored.
If id is an invalid key or NULL_KEY it is treated as empty.
Depending upon which AGENT* flag is used determines the format requirements for name

See: llSensor for an excellent explanation of arc.

type Flag Mask Description (llDetectedType()) Description (llSensor() and llSensorRepeat() mask)
AGENT_BY_LEGACY_NAME 0x1 Agents This is used to find agents by legacy name.
AGENT 0x1 Agents This is also used to find agents by legacy name, and is functionally identical to AGENT_BY_LEGACY_NAME
AGENT_BY_USERNAME 0x10 Reserved This is used to find agents by username.
ACTIVE 0x2 Physical tasks. (Physical objects & agents) Physical objects that are moving or objects containing an active script. Thus, it is using SL server resources now.
PASSIVE 0x4 Non-physical objects. Non-scripted or script is inactive and non-physical or, if physical, not moving. Thus, it is not using SL server resources now.
SCRIPTED 0x8 Objects containing any active script. Objects that has any script, which is doing anything in simulator just now.
llDetectedType() Scripted Not Scripted Agent Standing Agent Sitting
Physical Movement 10 (ACTIVE|SCRIPTED) 2 (ACTIVE) 3 (ACTIVE|AGENT) 3 (ACTIVE|AGENT)
Non-Physical 12 (PASSIVE|SCRIPTED) 4 (PASSIVE) 1 (AGENT) 5 (PASSIVE|AGENT)
Float Constants Arc
PI_BY_TWO A hemisphere scan
PI A full sphere scan

Caveats

  • When searching for an avatar but not by name, it doesn't matter which AGENT flag is used.
  • Objects do not detect themselves, and attachments cannot detect their wearers (this includes HUD attachments).
  • Attachments cannot be detected by llSensor.
  • For an object to be detected, the center of its root prim (the same point it would report with llGetRootPosition) must be within the sensor beam.
  • For an agent to be detected, a point near the pelvis must be inside the sensor beam (the same as llGetRootPosition would report in a script attached to that avatar). This point is indicated by red crosshairs when Advanced>Character>Display Agent Target is turned on.
    • If the agent is sitting on an object, the root prim of the sat upon object becomes a second sensor target for the agent (but not if the avatar is outside the sensor arc, see SVC-5145).
  • Sensors placed in the root prim of attachments will use the direction the avatar is facing as their forward vector. In mouselook, this means that it will be wherever the avatar is looking, while out of mouselook, this means whichever way the avatar is pointing. This does not include where the avatar's head is pointing, or what animation the avatar is doing, just the direction the avatar would move in if you walked forward. This is the case, regardless of where the object is attached.
  • Sensors placed in prims other than the root prim of an attachment will have their forward direction offset relative to the root prim's forward direction, e.g. a sensor in a prim whose +X direction is the reverse of the root +X will look backward.
  • llSensor does not detect objects or agents across region boundaries
  • If type is zero, the sensor will silently fail, neither sensor or no_sensor will be triggered.
  • Only 16 objects will be scanned each time.
All Issues ~ Search JIRA for related Bugs

Examples

This sensor scans a 45 degree cone about the x-axis (PI/2 or PI_BY_TWO scans a hemisphere; PI is a spherical scan). Also it will only match an agent with the legacy name "Governor Linden".

llSensor( "Governor Linden", NULL_KEY, AGENT_BY_LEGACY_NAME, 96.0, PI/4 );

This sensor detects all prims and agents with a given name within 15m of the sensor. (AGENT, PASSIVE and ACTIVE behave inclusively. SCRIPTED is not inclusive and will exclude non-scripted targets (like avatars) from the detected set.)

llSensor( "", NULL_KEY, ( AGENT | PASSIVE | ACTIVE ), 15.0, PI );

Basic example script that when touched executes a sensor scan of agents. When the sensor event is processed it spits out messages to the owner of each detected agents' name.

default
{
    touch_start(integer total_number)
    {
        llSensor("", NULL_KEY, AGENT, 30.0, PI);
    }
 
    sensor( integer detected )
    {
        while(detected--)
        {
            llOwnerSay(llDetectedName(detected));
        }
    }
}

Notes

KBcaution.png Important: You might want to use llGetAgentList instead of using sensors to get a list of all avatars within the same parcel or region.

Loops & Repetition

Using llSensor in a for loop is a beginners mistake, as events will not interrupt each other (the sensor event will not interrupt whatever event is currently being executed). To perform repeat sensor sweeps, llSensorRepeat is the better solution. While it is possible to call llSensor from a timer event, it is less efficient to do so; there is a limit to the number of events that can be processed in a second and using the timer just to call llSensor will result in your script getting less timeslice.

See Also

Events

•  sensor Triggered when a sensor detects something
•  no_sensor Triggered when a sensor detects nothing

Functions

•  llSensorRepeat Runs a sensor on a timer
•  llSensorRemove Stops the llSensorRepeat timer

Articles

•  Object Type

Deep Notes

Search JIRA for related Issues

Footnotes

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

Signature

function void llSensor( string name, key id, integer type, float radius, float arc );

Haiku

The hounds are straining.
Elusive quarry sighted.
The game's afoot!

Gallery