Difference between revisions of "LlListen"

From Second Life Wiki
Jump to: navigation, search
m
(Copy editing)
Line 12: Line 12:
 
|func_footnote=If '''msg''', '''name''' or '''id''' are blank they are not used to filter incoming messages.
 
|func_footnote=If '''msg''', '''name''' or '''id''' are blank they are not used to filter incoming messages.
 
If '''id''' is an invalid key or a [[NULL_KEY|null key]], it is considered blank.<br/>
 
If '''id''' is an invalid key or a [[NULL_KEY|null key]], it is considered blank.<br/>
|spec=For the [[listen]] [[event]] to be triggered it must first match the criteria set forth by the filters; only when all the criteria have been met is a listen event generated. First the message must have been transmitted on channel '''channel'''. If '''name''' is set then the speaker's name must match '''name''' exactly. If '''id''' is a valid non [[NULL_KEY|null]] key then the speakers key must be equivalent. If '''msg''' is set then the spoken message must match '''msg''' exactly.
+
|spec=For the [[listen]] [[event]] to be triggered it must first match the criteria set forth by the filters; only when all the criteria have been met is a listen event generated. First the message must have been transmitted on channel '''channel'''. If '''name''' is set then the speaker's name must match '''name''' exactly. If '''id''' is a valid, non-[[NULL_KEY|null]] key then the speaker's key must be equivalent. If '''msg''' is set then the spoken message must match '''msg''' exactly.
 
|also_functions={{LSL DefineRow||[[llListenRemove]]|Removes a listen}}
 
|also_functions={{LSL DefineRow||[[llListenRemove]]|Removes a listen}}
 
{{LSL DefineRow||[[llListenControl]]|Enables/Disables a listen}}
 
{{LSL DefineRow||[[llListenControl]]|Enables/Disables a listen}}
Line 24: Line 24:
 
|notes
 
|notes
 
|constants={{LSL Constants/Chat}}
 
|constants={{LSL Constants/Chat}}
|caveats=*On [[state]] change or [[llResetScript|script reset]] all listens are removed automaticaly.
+
|caveats=*On [[state]] change or [[llResetScript|script reset]] all listens are removed automatically.
 
**A state change can be used as a shortcut to releasing listens.
 
**A state change can be used as a shortcut to releasing listens.
 
*Only 64 listens can simultaneously be open in any single script.
 
*Only 64 listens can simultaneously be open in any single script.
Line 30: Line 30:
 
*Avoid channel 0 and set name or id where possible to avoid lag. ([http://rpgstats.com/wiki/index.php?title=Lag Lag])
 
*Avoid channel 0 and set name or id where possible to avoid lag. ([http://rpgstats.com/wiki/index.php?title=Lag Lag])
 
**llListen(0,"","","") is extremely laggy as it listens to all chat from everyone in chat range and should be avoided at all cost.
 
**llListen(0,"","","") is extremely laggy as it listens to all chat from everyone in chat range and should be avoided at all cost.
*Negative channel numbers can only be used for inter object communication (and are preferable in that case).
+
*Negative channel numbers can only be used for inter-object communication (and are preferable in that case).
 
**This may just be an artificial limitation placed on the client and not the underlying protocol.
 
**This may just be an artificial limitation placed on the client and not the underlying protocol.
 
|examples=
 
|examples=

Revision as of 04:25, 2 October 2007

Summary

Function: integer llListen( integer channel, string name, key id, string msg );

Sets a callback for msg on channel from name and id.
Returns an integer that can be used to deactivate or remove the listen.

• integer channel any valid integer, positive or negative.
• string name
• key id
• string msg

If msg, name or id are blank they are not used to filter incoming messages. If id is an invalid key or a null key, it is considered blank.

Specification

For the listen event to be triggered it must first match the criteria set forth by the filters; only when all the criteria have been met is a listen event generated. First the message must have been transmitted on channel channel. If name is set then the speaker's name must match name exactly. If id is a valid, non-null key then the speaker's key must be equivalent. If msg is set then the spoken message must match msg exactly.

Channel Constant Description
DEBUG_CHANNEL 0x7FFFFFFF Chat channel reserved for script debugging and error messages, broadcasts to all nearby users.
PUBLIC_CHANNEL 0x0 Chat channel that broadcasts to all nearby users. This channel is sometimes referred to as: open chat, local chat and public chat.

Caveats

  • On state change or script reset all listens are removed automatically.
    • A state change can be used as a shortcut to releasing listens.
  • Only 64 listens can simultaneously be open in any single script.
    • If this number is exceeded an error is shouted.
  • Avoid channel 0 and set name or id where possible to avoid lag. (Lag)
    • llListen(0,"","","") is extremely laggy as it listens to all chat from everyone in chat range and should be avoided at all cost.
  • Negative channel numbers can only be used for inter-object communication (and are preferable in that case).
    • This may just be an artificial limitation placed on the client and not the underlying protocol.
All Issues ~ Search JIRA for related Bugs

Examples

Trivial example to listen to any chat from the object owner and respond once. To reduce lag and avoid spamming surrounding users, it is vastly preferable to listen on channels other than 0 and to trigger the listen event by chatting on an alternative channel such as '/5 hello'.

// says beep to owner the first time owner says something in main chat;
integer listen_handle;

default
{
    state_entry()
    {   //Registers the listen to the owner of the object at the moment of the call.
        // This does not automatically update when the owner changes.
        // Change 0 to another positive number to listen for '/5 hello' style of chat.
        listen_handle = llListen(0, "", llGetOwner(), "");
    }
    listen( integer channel, string name, key id, string message )
    {
        llOwnerSay("beep");
        // Stop listening until script is reset
        llListenRemove(listen_handle);
    }
    on_rez(integer param)
    {   //Triggered when the object is rezed, like after the object had been sold from a vendor
        llResetScript();//By resetting the script on rez it forces the listen to re-register.
    }
    changed(integer mask)
    {   //Triggered when the object containing this script changes owner.
        if(mask & CHANGED_OWNER)
        {
            llResetScript();
        }
    }
}

See Also

Events

•  listen

Functions

•  llListenRemove Removes a listen
•  llListenControl Enables/Disables a listen
•  llWhisper Sends chat limited to 10 meters
•  llSay Sends chat limited to 20 meters
•  llShout Sends chat limited to 100 meters
•  llRegionSay Sends chat limited current sim

Deep Notes

Search JIRA for related Issues

Signature

function integer llListen( integer channel, string name, key id, string msg );