User:haravikk Mistral/LlCastRay

From Second Life Wiki
Jump to navigation Jump to search
Emblem-important-yellow.png LSL Feature Request
The described function does not exist. This article is a feature request.

Summary

Function: llCastRay( vector origin, vector normal, float range, integer type, list detect );
REQUEST Function ID
0.0 Forced Delay
10.0 Energy

Casts a ray from origin along the direction described by normal until either range is reached, the ray hits a region boundary, or the results limit is reached.

• vector origin
• vector normal
• float range
• integer type
• list detect

Specification

  • Results are filtered by type (see below), and the data to capture is described by detect (see below, default is [DETECT_KEY, DETECT_TYPE]).
  • This function will trigger a sensor() event with any results found, or a no_sensor() event if no results were detected. The usable llDetected*() functions within the sensor event are determined by detect.

Constant Description
AGENT Avatars, optionally identified by their display name.
AGENT_BY_LEGACY_NAME Avatars, optionally identified by their legacy name.
AGENT_BY_USERNAME Avatars, optionally identified by their username.
ACTIVE Physical objects that are moving or objects containing an active script.
PASSIVE Non-scripted or script is inactive and non-physical or, if physical, not moving.
SCRIPTED Objects that has any script, which is doing anything in simulator just now.
LAND The simulator's ground segments (only supported by llCastRay()).


Constant Description
DETECT_ALL Convenience entry to return all available data. Essentially this is the same as providing a list with all other DETECT_* constants valid for the current function, excluding those asking specifically for root-prims, avatar username, or avatar legacy name.
DETECT_GROUP Populates llDetectedGroup() with the key of the group that the detected object, avatar, or land belongs to.
DETECT_KEY Populates llDetectedKey() with the key of the primitive or avatar that was detected. If land is detected this value will be NULL_KEY.
DETECT_ROOT_KEY Populates llDetectedKey() with the key of the object root or avatar that was detected. If land is detected this value will be NULL_KEY.
DETECT_LINK_NUMBER Populates llDetectedLinkNumber() with the link-number of the primitive that was detected. If an avatar or land were struck then this will be zero.
DETECT_NAME Populates llDetectedName() with the name of the primitive or the display name of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_ROOT_NAME Populates llDetectedName() with the name of the object root or display name of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_LEGACY_NAME Populates llDetectedName() with the name of the primitive or the legacy name of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_ROOT_LEGACY_NAME Populates llDetectedName() with the name of the object root or legacy name of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_USERNAME Populates llDetectedName() with the name of the primitive or the legacy name of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_ROOT_USERNAME Populates llDetectedName() with the name of the object root or username of the avatar that was detected. If land is detected this value will be an empty string.
DETECT_OWNER Populates llDetectedOwner() with the UUID of the avatar that owns the detected object or land. If an avatar is detected then their key is returned here.
DETECT_POSITION Populates llDetectedPos() with the position of the primitive that was detected.
DETECT_ROOT_POSITION Populates llDetectedPos() with the position of the object root that was detected.
DETECT_ROTATION Populates llDetectedRot() with the rotation of the primitive that was detected.
DETECT_ROOT_ROTATION Populates llDetectedRot() with the rotation of the object root that was detected.
DETECT_TOUCH_BINORMAL Populates llDetectedTouchBinormal() with the tangental normal vector of the point at which the object was detected.
DETECT_TOUCH_FACE Populates llDetectedTouchFace() with the primitive face that was detected. If an avatar or land were detected then this will be TOUCH_INVALID_FACE.
DETECT_TOUCH_NORMAL Populates llDetectedTouchNormal() with the normal vector of the point at which the object was detected.
DETECT_TOUCH_ST Populates llDetectedTouchST() with the face coordinates of the point at which the object was detected. If an avatar or land are detected then this will be TOUCH_INVALID_TEXCOORD.
DETECT_TOUCH_UV Populates llDetectedTouchUV() with the texture coordinates of the point at which the object was detected. If an avatar or land are struck then this will be TOUCH_INVALID_TEXCOORD.
DETECT_TYPE Populates llDetectedType() with the type of object that was detected.
DETECT_VELOCITY Populates llDetectedVel() with the velocity of the object that was detected.

Caveats

  • A range of 0.0 or less will be ignored. Under LSO-LSL the maximum value of float can be used for what is effectively an infinity value, while under Mono true infinity can be provided.
  • This function will return a maximum of 16 results (the limit of the sensor() event). The results are ordered such that the nearest result is first, followed by the second, and so-on.
  • Only a single ray-cast can be performed by a script at a time; calling this function again before the sensor() event is triggered will interrupt the in-progress ray-cast and begin a new one.
  • The sensor() and no_sensor() events may not trigger (ray-cast silently fails) if your script is triggering too ray-casts. The simulator will make a best effort to complete requests, though these may be delayed depending upon script-lag for the region.
All Issues ~ Search JIRA for related Bugs

Examples

<lsl>default {

   state_entry() {
       llSetTimerEvent(30.0);
   }
   timer() {
       llCastRay(llRot2Fwd(llGetRot()), 20.0, AGENT, [DETECT_NAME]);
   }
   sensor(integer x) {
       string message = "Hi there"; integer first = TRUE;
       while ((--x) >= 0) {
           if (first) first = FALSE;
           else if (!x) message += " and ";
           else message += ", ";
           message += llDetectedName(x);
       }
       llSay(PUBLIC_CHANNEL, (message = "") + message + "!");
       // Produces a message such as:
       // "Hi there, Haravikk Mistral, Strife Onizuka and Kelly Linden!"
   }
}</lsl>

Notes

To support this version of the llCastRay() implementation, please vote on SVC-6442

Deep Notes

All Issues

~ Search JIRA for related Issues
   llCastRay() - detect objects by ray-casting
   Allow us to decide which llDetected*() functions are populated to save on memory/processing

Signature

//function void llCastRay( vector origin, vector normal, float range, integer type, list detect );