Getting started with LSL

Getting started in LSL scripting in Second Life

LSL stands for "Linden Scripting Language" and is used to script the objects you will encounter and make in Second Life.

FOR WHOM IS THIS TUTORIAL:

This tutorial is intended for those who have never programmed before, Second Life or elsewhere. However, this tutorial will make little sense outside of Second Life. LSL is very specific to Second Life.

You will begin by running the standard "hello world" script and eventually move towards making your own. You will need to be familiar with the basic principles of Second Life and have general building skills before you can make use of everything in this tutorial.

What is LSL?

LSL is the Linden Scripting Language. This is the language all scripts in Second Life are written in. Its structure is based on Java and C. A script in Second Life is a set of instructions that can be placed inside any primitive object in the world, but not inside an avatar. Avatars, however, can wear scripted objects. LSL scripts are written with a built-in editor/compiler which we will access in "Running Your First Script".

One thing that makes LSL special is its emphasis on "States" and "Events". A door can be "open" or "closed" and a light can be "on" or "off". A person can be "hyper", "calm", or "bored". Many real life behaviors can be modeled with "states" and the same can be true for LSL programs. Minimally a script will have one state, the default state.

An event can be thought of as a "Trigger". Events are not user defined in Second Life, but rather predefined. They are either caused by objects and avatars interacting in the world, or they are created in a script. Events trigger event handlers (sometimes just called "events" as well). For example, when an avatar touches an object, a touch_start message is sent to the object, which causes the touch_start() event handler to begin executing. So the minimum LSL program must have one state with one event handler in it. Here is a look at a minimal program written in LSL that can loosely be translated as...."When I am in the default state, and I am touched, say "Hello World" on channel zero".

(note: all scripts will be placed in LSL tags when it goes active)

default
{
     touch_start(integer total_number)
     {
          llSay(0,"Hello World");
     }
}

WHAT CAN I DO WITH SCRIPTS?

Scripts can make an object move, listen, talk, operate as a vehicle or weapon, change color, size or shape. A script can make an object listen to your words as well as talk back to you, scripts even let objects talk to each other.

The most basic object in Second Life is the "Prim" or primitive, the basic building block of all objects you can build in Second Life. When several prims are linked, they can each contain a script which speaks to the rest of the object via Link Messages. These are faster and more private than having objects "chat" or email each other. These are beyond the scope of this tutorial and we will instead focus on single scripts in a single prim.

Scripting is harder to learn than basic object manipulation, but is very rewarding once you make progress.

If you've built in Second Life, everything you can define in the edit window can be defined in a script. All interaction you see between objects or between avatars and objects is via scripts.

Learning more about the world and building model is vital to some aspects of scripting, thus I'd recommend a good foundation in building as you learn to script.

Running Your First Script

Traditionally one starts by writing the smallest program possible to print "hello world". Since LSL only runs inside objects, you must know how to create an object and put a script inside it.

You must be on land which allows building. Either your own land, or land where you have permission to build on such as a sandbox. Right click on the ground and choose create (for one button macs use command+click).

By default, you should see a wand icon with which you can click and create a cube on the ground.

You will automatically enter edit mode and an edit window will pop up. To place a script in an existing object, right click it and hit edit to open the edit window.

In the edit window you may see a button marked more>>> click it to reveal five tabs marked general, object, features, content, and texture. Click content.

This window shows the contents of an object which can hold scripts, notecards, even other objects. Press new script to add a new script.

This will open the LSL editor with a default script. This editor will color code your syntax and provide some info about keywords when you hold your mouse over them. It will also do basic syntax checking.

Before explaining the code, lets run it. Hit save and close your edit window (not the LSL editor window).

You should see the words "Hello Avatar" from "object"

If you touch the object, it will say "Touched." The "edit" building window must be closed for touching to work.

Congratulations! You have compiled and run your first LSL script!

Wash / Rinse / Repeat

We now have a running script, however most scripts you make won't run the first time you run them. It will take many tries as you correct errors and make improvements. When you hit "save" on a script, the LSL editor "compiles" the code to something LSL can understand. It will stop however if it finds an error.

Brackets, parenthesis, and semicolons must all be perfectly in place before a script will run. If you are new to programing this can be one of the most infuriating steps and lead you to screaming DWIM (Do what I mean!) Part of becoming a programmer in ANY language is learning how to precisely define steps and correctly type them into the language you are working in. Thus you will find yourself writing, running, then RE-writing your code several times.

The script you made runs the instant you hit save. If you take it into inventory, it will "suspend" what it was doing but go right back to it when rezzed (resurrected) again. (If you are not familiar with "taking" and "rezzing" an object you may need to revisit your building skills).

Each time you re-write your code you'll want to reset the script.

Try resetting the script in the following ways.

1. Press Reset in the script window. 2. Select the object and go to TOOLS>RESET SCRIPTS IN SELECTION

Also try stopping and starting the script from running via checking and unchecking the "running" button, or the TOOLS>SET SCRIPTS TO NOT RUNNING IN SELECTION and then TOOLS>SET SCRIPTS TO RUNNING IN SELECTION.

Once you get comfortable with stopping, starting, and resetting a script, try changing the words "Hello Avatar" and see what else you can make it say.... for goodness sakes keep it PG.

WHY STOP AND START?

Scripting in Second Life can be a little bit like fixing your car...while going 60mph down the freeway. Thus you need ways to stop the programs for they may affect others.

Objects can hold more than one script and they will all run at once. This can be used in the following manner. Say you write a script that makes a prim change color every few seconds. You also write one to make it follow you. Put them both in one object and it will follow you while changing colors!

For simplicity's sake, the following examples will all be used individually so be sure not to put two or more into the same object.

A Closer Look

Lets take a look at the default code.

default
{
     state_entry()
     {
         llSay(0, "Hello, Avatar!");
     }

     touch_start(integer total_number)
     {
         llSay(0, "Touched.");
     }
}

The code above contains 2 comments, 1 state, 2 events and 2 functions. Lets look at them individually.

Any line starting with two forward slashes is a comment. It will not run and is used to help you document your code.

// This is a comment

STATES

A "State" in LSL is a section that is running, and waiting for events. Only one state can be active at any one time per script. Every script must have a default state with at least one event in it. Except for the default state, each state is defined by the word STATE followed by the name of the state. The contents of the state are enclosed in two curly brackets.

default
{
// contents of state go here
}

state playing
{
// this is a state called "playing"
}

EVENTS

Events are inside of states. By "inside" I mean it is between the open and closed curly brackets that represent the body of the state. When that state is active, those events wait to be triggered and run the code inside them. We've seen "state_entry" which is triggered by the state being entered, and "touch_start" which is triggered when you, or anyone, touches an object.

Lets take a look at the default code.

// Code start
default
{
     touch_start(integer total_number)
     // this is an event
     {
     // this is the content of the event
     }
     // end of event
}
// end of state

FUNCTIONS

Functions lay inside of events and are either defined by you or built-in. Those built in to LSL all start with two lowercase Ls. We've seen llSay() so far. Functions take "arguments" or values in the parentheses that follow it. If you hover over the function in the editor, a popup will show that tell you what the function is expecting. In the case of llSay it expects a number and a string. We send it the number zero and the string "Hello, Avatar!" separated by commas. The function is "expecting" a number and strings and won't take anything else.

Putting it all together

Line by line, here is the hello avatar script. Copy and paste this to a new script to see it color coded.

// All Scripts need a Default State
default
// this open curly bracket denotes the start of the state
{
    state_entry() // an event
    // another curly bracket starts the  body of the event
    {
        llSay(0, "Hello, Avatar!"); // a  function inside the event
    }
    // closed curly bracket closes the state_entry event

    touch_start(integer total_number)  // another event inside default state
    {
        llSay(0, "Touched."); // a function between the brackets of the touch_start body
    }
    // end of touch start
}
// Code end

The instant you save your script, it enters default state, which in turn runs the "state_entry" event which in turn runs the function llSay() which makes the object talk.

After this, the program waits idle in the default state until a new event is called.

Touching the box triggers the event "touch_start" which also makes the object speak.

Introducing States and Events

LSL scripts will not run beginning to end. Instead, they will look for a default state and wait for an event. Within those events, there can be a call to go to a new state.

All programs must contain the default state, inside of which must be one event. Events are triggered either by actions happening to or around the object the script resides in, or are triggered from the script itself.

Let's look at a script with two states with two events in each.

default //default state is mandatory
{
    state_entry() // runs each time the state is entered
    {
        llSay(0, "turning on!"); //object speaks!
        llSetColor(<1.0, 1.0, 1.0>, ALL_SIDES); // sets all sides to most bright
        // note the semicolons at the end of each instruction (do not put them at the end of if statements)
    }
  
    touch_start(integer total_number) // another event with only one function  inside
    {
        state off; // sets the script to a new "state" and starts running "state off"
    }
} // this curly bracket ends the body of the default state.
 
state off // a second state besides "default"
{
    state_entry() // this is run as soon as the state is entered
    {
        llSay(0, "turning off!");
        llSetColor(<0.0, 0.0, 0.0>, ALL_SIDES); // sets all sides as dark as possible
    }
 
    touch_start(integer total_number)
    {
        state default;
    }
}

A simplification of this would be

default
{
//set color to light and, if touched, enter the "off" state.
}

state off
{
//set color to dark and, if touched, enter the "default" state.
}

Note that after "default" all new states begin with the word "state". Also, while the object has a texture, the color will affect the "tint" more than the true color.

A closer look

Let's examine the default state.

First we see the "state_entry" event, which gets triggered each time the default state is entered.

SPEAK TO ME!

The first line in the event state_entry is...

llSay(0, "turning on!");

This makes the object speak "turning on!" on channel zero. What is channel zero? It is the same channel you see all public chat on.

A semicolon ends the line and yet another instruction follows.

llSetColor(<1.0, 1.0, 1.0>, ALL_SIDES);

This turns the prim to its brightest tint. If you take the texture off the prim, you'd see it as bright white; with a texture, it looks "normal." The three 1s stand for the Red, Green, and Blue values of the tint.

At this point the event is finished with the two lines of commands. Then the script waits idle in the default state for more events to happen.

TOUCHED BY AN AVATAR

While idle in the default state a touch will trigger the "touch_start" event.

Inside of the "touch_start" event is only one command:

state off;

This is a command to move immediately to a new state named "off".

This state is defined after the default state and nearly mirrors the default state, except that it turns the prim dark and, when touched, will put the script back into default mode, thus creating a loop.

1. Enters default state
2. Runs code in "state entry"
3. Waits to be touched
4. When touched enters "state off"
5. Enters "state off"
6. Runs code in "state entry" (note in the "off" state's body)
7. Waits to be touched
8. When touched enters "default" state

Then the whole thing starts over.

A final word on words

Making your object speak is a great way to know what a script is doing, but everyone can hear it for 30m all around you. As you get into more complex scripts this can get pretty noisy! Three alternative ways to see what is going on exist.

SHHHH WHISPER

llWhisper( ) is just like llSay( ) but only broadcasts at half the distance. You still must state what channel. So...

llWhisper(0,"turning on!");

...might work a bit to save the sanity of your neighbors.

Using llShout( ) doubles the distance heard, but can cut the amount of friends you have in half.

llOwnerSay( ) uses no channel and is heard only by you. Very useful and can triple the amount of friends you have!

llOwnerSay("turning on!");

THE SOUND OF SILENCE

You can make a totally silent message via llSetText( ) like this.

llSetText("I am on", <1.0, 1.0, 1.0>,1.0);

What do the numbers mean? The <1.0, 1.0, 1.0> we've seen before. It represents the values for red, green, and blue. For now just know that <1.0, 1.0, 1.0> means "white" and <0.0, 0.0, 0.0> means "black". Replace the llSay(0,"turning off!"); with...

llSetText("I am off", <0.0, 0.0, 0.0>,1.0);

The 1.0 is the alpha setting. 1.0 means fully opaque, and 0.0 would be completely transparent (invisible).