Difference between revisions of "LlRegionSayTo"

From Second Life Wiki
Jump to navigation Jump to search
m (added caveats)
(Revert the previous change and fix it the right way)
(30 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{LSL_Function/chat|channel|msg|np=*}}{{LSL_Function/uuid|target|sim=*}}{{LSL_Function
{{LSL_Function
|mode=pre-release
|inject-2={{Issues/SCR-66}}
|func_id=331
{{LSL_Function/uuid|target|sim=*|group=}}
|func_id=363
|func_sleep=0.0
|func_sleep=0.0
|func_energy=10.0
|func_energy=10.0
|func=llRegionSayTo
|func=llRegionSayTo
|p1_type=key|p1_name=target|p1_desc
|sort=RegionSayTo
|p2_type=integer|p2_name=channel|p2_desc
|p1_type=key|p1_name=target
|p3_type=string|p3_name=msg|p3_desc
|p2_type=integer|p2_name=channel
|func_desc=Says the string '''msg''' on channel number '''channel''', that can be heard anywhere in the [[region]] only by scripts in '''target''' [[listen|listening]] on '''channel'''.
|p3_type=string|p3_name=msg
|func_footnote=Regardless of where the prim is, the message will not travel over region borders.
|func_desc=Says the text supplied in string {{LSLP|msg}} on channel supplied in integer {{LSLP|channel}} to the object or avatar specified by {{LSLP|target}}
|return_text
|return_text
|spec
|spec
|constants
|caveats=
|caveats=*This function cannot transmit on the {{#var:PUBLIC_CHANNEL}}, this is a design feature and not a bug.
*Text is spoken directly to the object or avatar within the same region as the script.
*If '''msg''' is longer than 1023 bytes it is truncated to 1023 bytes.
*Scripts in tasks other than {{LSLP|target}} can not listen for and receive these text messages, with an exception for attachments as described below.
*A prim can '''not''' hear itself, to prevent problems with recursion.
*Text can be a maximum of 1024 bytes. This can convey 1024 ASCII-7 characters, or 512 UTF-8 characters such as á
*If sent to an agent '''not''' on channel 0, all of the agents attachment's will hear the message.
*A prim cannot hear itself, to prevent problems with recursion.
*If sent to an agent '''on''' channel 0, it will appear to the agent as a normal talking prim.
*Sending text on {{LSLP|DEBUG_CHANNEL}} is not supported
|examples=<lsl>default
*Text sent to an avatar's ID on channel zero will be sent to the receiver's viewer.
*Text sent to an avatar's ID on non-zero channels can be heard by any attachment on the avatar
*A quick series of messages sent by llRegionSayTo cannot be relied on to arrive at their destination in the same order as sent.
*There is a per-destination throttle of 200 messages sent over 10 seconds on channel zero.  Thereafter, there is also a per-sending-object throttle of 100 messages on channel zero over 300 seconds (5 minutes).  This throttle is relevant only after the first throttle is activated.  Messages sent on channels other than zero do not trigger the throttle but, once it is triggered, the block applies to all channels. The block is region-wide and applies to all objects with the same owner. The block apparently lasts until the region is restarted.
|examples=
<source lang="lsl2">
default
{
{
     collision_start(integer i)
     touch_start(integer num_detected)
     {
     {
         llRegionSayTo(llDetectedKey(0), DEBUG_CHANNEL, "Ouch! That hurts!" );
         key id = llDetectedKey(0);
 
        // send a message to the chat window of the avatar touching
        llRegionSayTo(id, 0, "You touched this!");
 
        // send a message to the attachments of the avatar touching
        // example channel: -12345
        llRegionSayTo(id, -12345, "Hello there attachments!");
     }
     }
}</lsl>
}
</source>
|helpers
|helpers
|also_events=
|also_events=
{{LSL DefineRow||[[listen]]|}}
{{!}}-
{{!}}{{!}}{{!}} style="width:9em;" {{!}}
{{LSL DefineRow||[[listen]]|Receives chat}}
|also_functions=
|also_functions=
{{LSL DefineRow||[[llListen]]|}}
{{!}}-
{{LSL DefineRow||[[llOwnerSay]]|Sends chat to the owner only}}
{{!}}{{!}}{{!}} style="width:9em;" {{!}}
{{LSL DefineRow||[[llWhisper]]|Sends chat limited to 10 meters}}
{{LSL DefineRow||[[llListen]]|Ask for listen events}}
{{LSL DefineRow||[[llInstantMessage]]|Sends chat to a specific avatar, inside our outside the current region.}}
{{LSL DefineRow||[[llOwnerSay]]|Sends chat to the owner only to avoid spamming the PUBLIC_CHANNEL}}
{{LSL DefineRow||[[llRegionSay]]|Sends chat region wide}}
{{LSL DefineRow||[[llSay]]|Sends chat limited to 20 meters}}
{{LSL DefineRow||[[llSay]]|Sends chat limited to 20 meters}}
{{LSL DefineRow||[[llShout]]|Sends chat limited to 100 meters}}
{{LSL DefineRow||[[llShout]]|Sends chat limited to 100 meters}}
{{LSL DefineRow||[[llRegionSay]]|Sends chat that can be heard anywhere in the region}}
{{LSL DefineRow||[[llWhisper]]|Sends chat limited to 10 meters}}
{{LSL DefineRow||[[llInstantMessage]]|}}
{{LSL DefineRow||[[llDialog]]|}}
{{LSL DefineRow||[[llTextBox]]|}}
|also_tests
|also_tests
|also_articles
|also_articles={{LSL DefineRow||[[Hello Avatar]]}}
|notes=If one object 'says' something to another object (e.g., a button that, when touched,
|notes=
turns on a lamp), it is a good idea to use a very negative channel, e.g.,
* If one object 'says' something to another object (''e.g''., a button that, when touched, turns on a lamp), it is a good idea to use a very negative channel, ''e.g.'',
<lsl>   llRegionSay(-5243212,"turn on");</lsl>
<source lang="lsl2">
Negative channels are popular for script communications because the client is unable to chat directly on those channels ("/-xxxx message" won't chat "message" on channel "-xxxx", it will chat "/-xxxx message" on channel zero). The only way to do so prior to [[llTextBox]] was to use [[llDialog]] which was limited to 24 bytes.
    llRegionSayTo("55499a64-45c3-4b81-8880-8ffb5a7c251b", -5243212, "turn on");
 
</source>
If {{#var:DEBUG_CHANNEL}} is used as '''channel''', the script will say '''msg''' to the Script Warning/Error window.  
Negative channels are popular for script communications because, before September 2016, the standard Second Life client was unable to chat directly on those channels ("/-xxxx message" wouldn't chat "message" on channel "-xxxx").
* Messages sent on channel zero via LLRegionSayTo() are blocked after 200 messages on to the same destination in a 10 second period.  After this throttle is activated, there is a further throttle, on objects belonging to the owner of the object that triggered the first throttle, of 100 messages per object over 5 minutes (see https://jira.secondlife.com/browse/BUG-5457). The block is region-wide and applies to all objects belonging to the owner, so if a script triggers the throttle, all objects in the same region belonging to the same owner will also be blocked. Messages sent on channels other than zero do not trigger the throttles.  The throttles apparently reset only when the region is restarted.  


* As of 1.18.3, using llRegionSay on the {{#var:DEBUG_CHANNEL}} will wrap around and display on channel 0, with a range of 100m.
Therefore, llRegionSayTo() is unsuitable for (say) verbose script debugging, and even moderate use can break users' content completely unrelated to the script for an indeterminate (and potentially very long) period of time.   Consider using llOwnerSay() for debugging instead or, if this not appropriate, try llRegionSayTo(avatar, non-zero-channel, message) and have an attachment relay the message using llOwnerSay().  
|history=
|cat1
*Introduced with SL 1.16.0
|cat2
|cat1=Communications
|cat2=Chat
|cat3
|cat3
|cat4
|cat4
|history = Date of Release  [[ Release_Notes/Second_Life_Server/11#11.04.26.227686 | 26/04/2011 ]]
}}
}}

Revision as of 10:44, 24 September 2022

Summary

Function: llRegionSayTo( key target, integer channel, string msg );

Says the text supplied in string msg on channel supplied in integer channel to the object or avatar specified by target

• key target avatar or prim UUID that is in the same region
• integer channel
• string msg

Caveats

  • Text is spoken directly to the object or avatar within the same region as the script.
  • Scripts in tasks other than target can not listen for and receive these text messages, with an exception for attachments as described below.
  • Text can be a maximum of 1024 bytes. This can convey 1024 ASCII-7 characters, or 512 UTF-8 characters such as á
  • A prim cannot hear itself, to prevent problems with recursion.
  • Sending text on DEBUG_CHANNEL is not supported
  • Text sent to an avatar's ID on channel zero will be sent to the receiver's viewer.
  • Text sent to an avatar's ID on non-zero channels can be heard by any attachment on the avatar
  • A quick series of messages sent by llRegionSayTo cannot be relied on to arrive at their destination in the same order as sent.
  • There is a per-destination throttle of 200 messages sent over 10 seconds on channel zero. Thereafter, there is also a per-sending-object throttle of 100 messages on channel zero over 300 seconds (5 minutes). This throttle is relevant only after the first throttle is activated. Messages sent on channels other than zero do not trigger the throttle but, once it is triggered, the block applies to all channels. The block is region-wide and applies to all objects with the same owner. The block apparently lasts until the region is restarted.
All Issues ~ Search JIRA for related Bugs

Examples

default
{
    touch_start(integer num_detected)
    {
        key id = llDetectedKey(0);

        // send a message to the chat window of the avatar touching
        llRegionSayTo(id, 0, "You touched this!");

        // send a message to the attachments of the avatar touching
        // example channel: -12345
        llRegionSayTo(id, -12345, "Hello there attachments!");
    }
}

Notes

  • If one object 'says' something to another object (e.g., a button that, when touched, turns on a lamp), it is a good idea to use a very negative channel, e.g.,
    llRegionSayTo("55499a64-45c3-4b81-8880-8ffb5a7c251b", -5243212, "turn on");

Negative channels are popular for script communications because, before September 2016, the standard Second Life client was unable to chat directly on those channels ("/-xxxx message" wouldn't chat "message" on channel "-xxxx").

  • Messages sent on channel zero via LLRegionSayTo() are blocked after 200 messages on to the same destination in a 10 second period. After this throttle is activated, there is a further throttle, on objects belonging to the owner of the object that triggered the first throttle, of 100 messages per object over 5 minutes (see https://jira.secondlife.com/browse/BUG-5457). The block is region-wide and applies to all objects belonging to the owner, so if a script triggers the throttle, all objects in the same region belonging to the same owner will also be blocked. Messages sent on channels other than zero do not trigger the throttles. The throttles apparently reset only when the region is restarted.

Therefore, llRegionSayTo() is unsuitable for (say) verbose script debugging, and even moderate use can break users' content completely unrelated to the script for an indeterminate (and potentially very long) period of time. Consider using llOwnerSay() for debugging instead or, if this not appropriate, try llRegionSayTo(avatar, non-zero-channel, message) and have an attachment relay the message using llOwnerSay().

See Also

Events

•  listen Receives chat

Functions

•  llListen Ask for listen events
•  llInstantMessage Sends chat to a specific avatar, inside our outside the current region.
•  llOwnerSay Sends chat to the owner only to avoid spamming the PUBLIC_CHANNEL
•  llRegionSay Sends chat region wide
•  llSay Sends chat limited to 20 meters
•  llShout Sends chat limited to 100 meters
•  llWhisper Sends chat limited to 10 meters

Articles

•  Hello Avatar

Deep Notes

History

Date of Release 26/04/2011

All Issues

~ Search JIRA for related Issues
   llRegionSayTo() Fails to send messages to attachments on sitting avatars

Signature

function void llRegionSayTo( key target, integer channel, string msg );