LSL 101/Event Handler Parameters

← The Structure of a Script

↑̲  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

Events

Understanding events and event handlers is crucial from the very start especially if you have prior experience with programming, because unlike a traditional computer program, events occurring outside of your script determine when the various parts of your script get executed. (If none of that made sense and you've never had a computer class don't worry, start on the next line!)

When something happens we say an event has happened. LSL knows about many kinds of events and can respond to them depending on what kind of event happened.

Events include things like when an avatar or object

• types something in chat (listen events)
• gets close to your prim ( sensor events)
• touches your prim ( touch events)
• collides with your prim (collision events)
• changes the prim's inventory (change events)
• pays your prim ( money) ... and others.

There's also events which seem to happen by themselves but are indeed triggered. For example, the timer event is used to move the action along, or to repeat actions on a regular basis. See Events for full list of events.

Events can also pass information back to the server. This includes things like the name or UUID of the object or avatar that interacted with it, the channel on which it "hears" things, the speed of objects that hit it, and many other interesting things.

Events in a script happen in "FIFO" order (First In First Out), however *state_entry* comes first.

Events contain a *block* of code within two curly brackets which is called the *event handler* - often the two terms are used interchangeably.

When you change states in a script, all the event handlers, including listen event handler, will be cleared out and the state_entry of the new state will execute. We saw that in the previous example of two states.

If the prim is taken to inventory during the execution of a script and there is no provision for resetting the script when it comes back out, it will return to world running as it was when it was taken. Either of these routes may be advantageous to the scriptor.

The On Rez Event

Here's the format for resetting scripts when an object returns to world from inventory.

<lsl> default {

    on_rez(integer param)
    {
         llResetScript();
    }

    state_entry()
    {
         llOwnerSay("I have been reset.");
    }

// other events go here...

} </lsl>

One caution: Don't reset the script inside *state_entry* event. Always use the syntax above and use the on_rez event to reset the script back to state_entry.

And now a few words about some common events.

The State Entry Event

The *state_entry* event occurs when the script first starts running either

• when a script from your inventory is added to the prim's inventory or
• when you save > reset your changes after editing a script that is in a prim's inventory.

When the sim server detects the state_entry event, it executes any commands (and only those commands) that occur between the { and } of the state_event handler block.

State_entry event is not required in a script; many scripts do just fine without one.

The Touch Start Event

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

Here's what it looks like in a script snippet ... <lsl> touch_start( integer num_detected )</lsl>

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.

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 you'd like to learn more about *touch_start* before moving on, please click on this sidebar.

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.