LSL 101/The touch start Event

← Event Handler Parameters

↑̲  LSL 101  ̲↑

Variables →

---

LSL 101: The Wikibook

• A Gentle Introduction
• The Structure of a Script
  • Simple Script Skeleton
  • Comments, White-space and Formatting
• Events & Event Handlers
  • The touch start Event
• Variables
  • Strings and Simple Output
    • String Concatenation
  • Integers
  • Using Variables
    • Global vs Local Variables
    • Variable Initialization
• Functions
  • Functions That Return a Value

The End Game

• Creating a Script
• Compile Time Errors
• Logic
• Conclusion

The Touch Start Event

Here's our sample program, with a second event handler added. The touch_start event occurs whenever any avatar clicks on the object containing the script. Note again that the name of the event must be typed touch_start, with the underscore. (The underscore doesn't show up in the title of this page just because the Wiki software displays underscores in titles as spaces.)

<lsl> default {

    state_entry()
    {
         // Let the object's owner know the script is working
         llOwnerSay( "Congratulations! Your script has started to execute." );
    }

    touch_start( integer num_detected )
    {
         // Let the object's owner know the script is working
         llOwnerSay( "I've been touched!" );
    }

} </lsl>

The start part of the event named 'touch_start' refers to the fact that this event is generated whenever a user presses the left mouse button while the cursor is over the object. If for some reason you wanted your code to execute when the user lifted the button instead of pressing it, the event would be named 'touch_end'.

integer num_detected

Whenever you see *touch_start* in a script it is followed by a parenthesis and a variable named "num_detected" or just "num" or even silly things like "beer".

The words integer num_detected is (in fancy computer terms) a declaration of a local variable that has been created and initialized by the sim server. The server initializes it with the number of distinct touches that have occurred since the last time the touch_start handler was called.

For the rest of us, that means this box can count the number of touches it has received, save and use that information, and it does it automatically, you don't have to write some code to make the box count how many times it has been touched. However, here is a script that demonstrates just that.

Consider this script:

<lsl>integer TotalTouches = 0; // we set the initial touch value to zero // Every time the box it touched, it will count up one round number ("integer")

default {

    touch_start( integer num_detected )
    {
         TotalTouches = TotalTouches + num_detected;
              // Update the total number of touches

         llOwnerSay( "I have been touched a total of " + (string)TotalTouches + " times." );
             // Announce the current total
    }

}</lsl>

The variable set above default (global variable) called TotalTouches counts the total number of times our object is touched. Each time the touch_start event handler is called, the sim server initializes num_detected to be the number of times the object was touched since the previous execution of touch_start. If you test this by yourself, chances are that TotalTouches will always be incrementing by one. But if you get a bunch of your friends together and have them all touch the object as rapidly as they can, sometimes you will see TotalTouches incrementing by more than one.

If a user clicks on your object many times, the touch_start event handler code will generally get executed many times, once for each click. But if multiple users click on your object at approximately the same time, SL may not invoke your code for each one separately. Instead, it may combine two or more of the touches into one event. In case your script really needs to respond separately to each touch, SL will tell you how many touches an execution of the touch_start event handler represents. That's the purpose of the phrase "integer num_detected" between the parentheses following touch_start. But before fully explaining how that works, we need to learn some other things, so we won't elaborate on that yet.

Summary

There are many events (about 38 different ones) and most of them have one or more parameters (that's those things like "integer num_detected" that follow them in the parenthesis). The details will differ with the event, but the idea is always the same. Each event handler handles one particular type of event and the parameters in the event handler provide the script with the specific details of the event.

Please continue this tutorial with Variables.