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.)

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!" );
     }
}

The event is called "touch_start" because it is the event that is raised at the beginning of a left mouse click on the object. If you want an event to occur when the click ends (when the mouse button is released) you would use the event "touch_end". Also available is the event "touch" which keeps firing repeatedly during the time that the mouse button is depressed.

integer num_detected

By default, the script editing tools follow "touch_start" by (integer num_detected). This is telling you that the server is passing an integer value to your script as part of the touch event. This integer tells you how may avatars "simultaneously" clicked on the object during the last clock frame (22mS) - it is NOT necessarily a cumulative count of clicks since the last touch_event was raised.

You can rename the variable to any name of your own choosing, but it must be defined as being an integer. e.g. your could write: touch_start(integer num) The major use of this integer is in determining what parameter values can be passed to any of the llDetected... functions when executing the touch event.

Consider this script:

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
     }
}

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.