Scripting 101: the Wikibook

Well, my feeling is that a narrative description is much less intimidating for a newcomer than a lot of code and comments. The idea of writing an anatomy is excellent and to have the structure laid out, as you have done, is also very useful. But I would keep that code as simple as possible and have the bulk of explanation in the narrative. I suggest that there be a short introduction, then the code and, finally, a dissection and explanation in narrative.

Wow, that is a good write!!! I liked to read it. It sounds easy and gives enough information at the correct places. There are still some small issues. See below. I added some text snippets to better describe what i want to point out. But please take them as my ideas only and not fully developed text...

STRUCTURE OF A SCRIPT

...snipped...

GLOBAL VARIABLES

Global variables allow you to store data (like a colour or the name of an avatar, etc.) in a place where you can access that data from anywhere in your script. Global variables can help you to have a well-designed script and they can also make things more understandable. But you need to be carefull with them, because they burry some hidden pitfalls, which we will introduce later in more detail. So you have to think carefully about their usage.

But before we can tell you when global variables are usefull and even necessary, and when they have to be avoided, and what we mean by "think carefully about their usage", we need to discuss variables in general and we have to introduce local variables and with that we have to tell you about the variable context...

declaration and definition of variables

Variables have to be "declared" before they can be used. Declaring a variable is somewhat like teaching the computer about a new location for information and as the name allready tells, this information is not necessarily constant, but it may change over time. So lets us "declare" some variables now:

They are declared like this:

integer count;            // this a number
string myName;         // this is a letter, word or sentence

When they are declared in this way they have a "name" and a 'type' but not a value. (Actually, they are given a value automatically, called the 'default value', and this value will depend on the type of the variable.) By the way. Have you seen how nicely comments can help to enhance understandability of your program code ?

You can also give them a value ...snipped...

the variable context...

(remark: i moved this from the beginning down here)

As you read on ...snipped...

So depending on where you place your variable, it is either global (visible from everywhere) or local (visible in the current context) Now we know all about variables ? Now how do we decide when to use global variables and when not ... to be continued...

I wonder if there would be any use to using one of the numerous methods of collaborative writing other than a wiki to produce something like "The Beginner's Guide to Using Linden Scripting Language", Such as Adobe Buzzwords, Google Docs, or an alternate wiki with a WYSIWYG editor.

I'm sure it would be easier, Sue. I have just begun playing with my user page on the wiki and see that there will be a chunk of learning to be done before I become fluent in formatting things nicely. Probably not a bad skill to develop, though, since it will prepare me to get involved with updating other sections of the wiki. Also, since we are integrating it with the wiki, where it is most likely to be discovered by aspiring scripters, it is probably best written in wiki format to begin with.

@Gaia: yes, some good additions. 'twas just a short demonstration of what I described to Jesse in commenting on her structure.

Probably it is about time we set up a page and set to work, yes?

/me goes back to learning wiki editing...

Easiest way on wiki editting; Find someone's page you like and click on the edit button! You can then see how it was all done.

Maybe a simple explination of scope for variables as well (I know it's a little more complex then maybe what you are going for, but important).

Scope of variables

Scope is a word to describe the section that a variable exists in code. This is when you can use a variable anywhere within your code, and have the script recognize that variable. An easy way to think of scope is with the brackets { and }. A variable name and its value die or is removed once the script leaves the scope of the variable.

To find the variables scope, look for the nearest open bracket, {, above the variables you wish to find the scope for, then follow down on the script until you see the associated close bracket, }, with the open bracket. Best seen in an example:

Example of Scope

default
{  //default open bracket
      state_entry()
      { //  <---- start of state entry, and start of state entries scope.
          integer number_one = 10;
          integer number_two = 15;
          if(number_one <= number_two)
          {  // <---- start of the scope INSIDE this conditional if statement
              integer index = 0;
              for(index = 0; index <= number_two; index++)
              {  // <-- start of scope INSIDE the for statement
                    number_one = number_one + 1;  
                    // number_one can be used because the scope of the variable is still "alive"
                    // this for statement is between the open bracket "{" and the "}" bracket
                    // that surround the variable number_one and number_two
              } // <-- This is the closing bracket for the for statement
           } //<--- This is the closing bracket for the if statement, any use of index beyond
              // this point will result in an error.
       } // <--- This is the closing bracket for the state entry scope. Any use of number_one
         //  and number_two. Any use of these variables beyond this point will result in
         // an error.
}  //End of default state, and end of it's scope.

I know this is not the greatest example, and there are some missing rules. I'm not terribly good at this, so please, feel free to pick it apart, and add better explinations, like variables with the same name in different scopes, and stuff like that. I just wanted to make sure that we didn't forget to talk about scope in general, as it is important.

Maybe this is one very good example for where to split information ?

I would opt for a brief introduction, simple examples of scope, example of a global scoped variabe. SHORT, SHORTER, SHORTEST (yes, i know i don't follow that rule either in my writings nevertheless, full stop here!

then ... the {further readings, detailed description, definition of scope, full story ...} links(s) will bring you to the deepest details about the current topic (scope here).

keep in mind, that the student should not be plastered with more details than are necessary to follow the current writings. In depth information are for the next round...

or when running along another trail ... (btw that's why i think the java document trails are a goods example for organising information in hyperlink-space)

I have no problem with this, give a short example of scope, and a brief explanation, simple, and then maybe a link for "Want to learn more?" or something along that lines, that goes more in depth on the subject of scope. That is what is nice about a wiki style, you can do links to another article. (even though I can't stomach reading online documents for long).

Like Gaia, I like to see things broken up into small bites, for easy digestion. As a more concrete example, here is how I might see starting off (after an introduction that gives context). Note that when I say "Discuss:", I mean talk about in the context of the example, not explain everything there is to know about the topic.

*** "Lesson" 1 ***

Example script:
default
{
state_entry()
{
}
}

Discuss: LSL is a language for instructing a computer (the SL server) to take some action. Modeled loosely after natural human language, a computer language has words, punctuation, gramatical rules and meaning. In contrast to a natural language, LSL's rules are simple, but ruthlessly enforced. Acknowledge the existence of a notion called "states" (to justify the name state_entry), but put off any further discssion of them until much later.


*** "Lesson" 2 ***

Example script:
default {state_entry(){ }}

Discuss: White space. Formatting.


*** "Lesson" 3 ***

Example script:
// This script instructs SL to do absolutely nothing
default
{
state_entry()
{
}
}

Discuss: Comments. state_entry as an event handler.


*** "Lesson" 4 ***

Example script:
default
{
state_entry()
{
// Let the object's owner know the script is working
llOwnerSay( "Your script has executed" );
}
}

Discuss: Syntax and semantics of statements. llxxx functions. Strings.


*** "Lesson" 5 ***

Example script:
default
{
state_entry()
{
// Let everyone in the vicinity know the script is working
llSay( 0, "Hello avatar" );
}
}

Discuss: Integers. llSay

*** "Lesson" 6 ***

Example script:
default
{
state_entry()
{
// Let everyone in the vicinity know the script is working
llSay(0, "Hello avatar";
}

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

Discuss: touch_start event handler.

*** "Lesson" 7 ***

Example script: same as above, generated by UI

Discuss: Creating a script with the UI.

and so on.



Is there an audience out there for this gradual an approach? I would like to hear from builders who would like to script but can't yet, either because they've tried and given up or have been intimidated enough not to try.

Good creative thinking so far. If I were writing it, though, I don't think I would start by talking about functions and syntax. That's important stuff, but doesn't belong at the start of the story, in my opinion. The beginning needs to be a very high-level view. Back away from the trees and take a look at the whole forest.

What is LSL all about? What does it mean to have a language that uses the logic of states and events? How does this logical approach fit the SL environment better than a language like C++ (or other languages that the reader may know or may have heard of)? What are the most basic building blocks of an LSL script (states, events, functions, variables, constants ...)? THEN you get to the business of what specific functions, etc. look like and how you use them.

I have used quite a number of programming languages over the past 40 years, but LSL's event-driven logic was totally new to me. It required a big mental shift to move from linear/branching flow logic and subroutines to the idea that execution can be interrupted and redirected by events. For me, the biggest barrier to learning was the lslwiki, which is dominated by detail-level discussions of functions and syntax. You have to really dig to discover the bird's eye view that would make sense of it all.

ETA: I just saw Omei's note, which was posted while I was writing. It's a nice model, closer to what I was thinking, but I disagree with his suggestion that we should put off a discussion of states until later. That discussion is a vital foundation. It belongs right up front. Unless the reader understands what states and events are, the rest is details without a context.

Yes, I suppose the relative importance of states will be a point of controversy. No question events are fundamental to LSL. But there is no fundamental need to use more than the default state in a script, and if you only have one state, there isn't any pressing need to know there is a possibility of more than one.

My view of states in LSL is that they are a method for decomposing a large problem into several smaller ones that can be tackled independently. That's an important problem-solving principle in general, and especially so in programming. But I would have a student be comfortable with writing small scripts before discussing strategies for writing large ones. I guess it's kind of like the strategy many of us take when teaching our kids about Santa Claus and sex -- they need to learn everything eventually, but not necssarily everything the first time the subject comes up.

BTW, I'm also influenced by my belief that states in LSL are badly implemented. My experience is that as I develop my LSL scripts, I end up having to collapse states far more often than I add new ones. Reminiscing about his Linden experienceIn in his farewell email, Cory Ondrejka wrote

... Creating a programming language that now had 2.5 billion lines of code written in it – note to self, next time spend more than one night designing language.

I don't know whether states were at the top of his list of things he would do differently, but they are on mine.

Hmmm... how about we use our talk pages on the wiki to make a first stab at it. Then we can compare notes, find what seems most generally promising and incorporate the best points from the other submissions? If we sit and discuss we could be here forever revising before we get anywhere.

Yes, I can see that argument. States ARE often overused. On the other hand, they are part of the backbone of LSL, a conceptual component that makes LSL distinctly different from other languages. Whether you use them commonly or not, they are part of the high-level framework that all the details fit into. It's the forest vs. trees thing.

I actually feel much more comfortable defending an early discussion of what an event-driven language does and why it's particularly well-suited to SL. Many new scripters probably have the mistaken impression that events behave like subroutines in other languages, especially if they have prior experience, as I did. The connection between events and the "real" world environment in SL is rather remarkable.

I'll admit that my perspective is colored by the fact that I am not a computer science professional but a reasonably talented brute force user. I wrote programs in Fortan, VB, C++, etc. for my own use in physical chemistry and was less concerned about formatting niceties and computational efficiency than about getting the right output. My starting point was always the overall logical flow of a program rather than its syntax and grammar. "WHY?" comes before "HOW?" in my own experience.

That's not a bad idea for doing the actual writing. The advantage of continuing some of the discussion here, of course, is that it invites the attention of builders, even if they are reading passively rather than chiming in all the time. Once conversation moves to user pages on the wiki, it's more of a closed shop operation. There's merit in letting the target audience see what's going on so authors don't go running off in some cool direction and leaving them behind.

States are primarily intended to reflect the situation where there are a small number of well defined and distinct states in the problem that the script is modelling. States are appropriate for systems as simple as a poseball, where there are two clearly defined states for the script to be in... one where there is a person sitting on the poseball, and one where there isn't.

It's got little to do with the size of the script. Attempting to use the LSL state system as an arbitrary FSM for something big... like parsing a context-free grammar, for example... is just going to frustrate you. THAT kind of "state" isn't something I'd even try to implement at the language level.

Sure there's merit, Rolig. There are also a lot of limitations in terms of layout and presentation in the forum though. It makes a big difference being able to easily see how the document is organised. Also, since we will be placing it in the wiki somewhere we will be able to copy and paste from the talk pages, formatting and all. Perhaps we could do the editing, or initial work in the talk pages and link from here for people to look and comment.

Absolutely. The forum isn't the place to do the writing. I was just saying that I'd like to see converation about the writing come back here occasionally, perhaps in the form of a progress report or a collection of unresolved questions. If you want to get reality checks about your work before you run off a cliff with it, don't just assume that folks in this forum will remember to wander over to the wiki, that's all.

I see several different, but complementary, presentation models being proposed.

* The gentle step-by-step introduction.

* The comprehensive treatment of a single language topic, e.g. Scoping.

* The comprehensive treatment of a group of related library functions, e.g. the topics that Strife would like to reference from the current documentation pages.

* Super-concise "cheat sheets", e.g. Jesse's script

I suspect different readers will gravitate to different presentation styles, just as different authors will prefer to express themselves differently. I think they should all be part of the "book".

To get the actual Wiki writing started, I have created a starting page at https://wiki.secondlife.com/wiki/LSL_101:_The_Wikibook with a proposed overal structure. I suggest that any pages that want to be seen as being part of "the book" be named starting with "LSL_101:" and be reachable from this main page.

As for discussion on the talk pages vs here, both seem to me to be in order. If one wants to discuss what should or shouldn't be on a particular page, the talk page is the obvious place to do that. If one wants to discuss more global issues, there's a lot more visibility here.

I agree. Events are fundamental to the language. For an SL user who has no prior programming experience, I think they seem quite natural, if not obvious. (How else would it work?) But for someone who comes to LSL with some programming experience and a mindset that thinks of a program as something that takes a set of inputs and produces a set of outputs, you really need to give them a good hard shake and say "You're not in Kansas any more".

I think this all came up because people were looking for something more approachable than the current function reference, Omei, so a gentle introduction is, I think, a prerequisite. Certainly we will get to the point where references back from the function section will be valuable for anyone who feels the urge to run screaming from there but I think the first thing to get together is the most basic and simple introduction. I like Jesse's idea of the anatomy of a script, since it seems to be a good basis for such a guide, and think we should begin with that and flesh it out with some gentle narrative.

Preface is all very well but who actually reads prefaces? I think we have already started to make it look technical by prefacing it with that.

Thanks for setting it up.

I like everyone's input so far. As I said, I DO NOT WRITE, I am horrible at it and glad I finally have a full time assistant at work for that. I am going to work on the script some more to polish it and add in some links. The basics in that script plus a couple more items is where I have seen new people consistently run into problems over time here. I will also add in some more basic scripts like how to do a simple integer switch. Have absolutely no idea where all of this will end up or in what form. Good to see others putting up their ideas in the form of wiki entries.

I also like Omei's Lesson's format. That could end up being very nice. Between all of us we should be able to come up with something workable and very friendly for people to learn from. It will probably end up being more then just one resource by the time all is said and done. No matter what the final outcome is, it will be much more then what is available now.

I like the idea of lesson format as well, break it all down, like it's brand new. An experienced person will flip through the lessons rather fat to find what they need to learn (like events, which seems to be the major problem experienced programmers first run into when starting LSL).

As for the order of these lessons, I think it needs to be broken down rather simply, and not present more then maybe two concepts of programming in general, then to slam a new person with like 5 or 6 new concepts at once. I know some books like to do that, but without a proper instructor to guide them, a lot of people will be lost.

I'd have no problem at all, and I'm sure lots of others wouldn't mind either, coming up with exercises for people to do after each topic. Just like in a math book, or any text book.

My thoughts on the "Preface" material is that it could address questions like "What is scripting good for? Do I need to learn it in order to function in SL? Are there other things I should learn first". Or it might contain a high-level ("forest" view of LSL, for those that like to get that perspective before getting into any details.

But in any case, this is a Wiki, so if you think you see an improvement in either the terminology or the structure, go for it.

For one person, scripting might start with How to Make a Door and proceed to other building builder like topics.

For another, scripting might start with How to Make Self Sizing Hair

For yet another, it might start with How to Make a Pet that Follows you Around

For another, it might start with How to Make a Chat Translation Device

My point it that a beginner might logically start with any of those. There should be Many Tutorials for the different kinds of scripters...If you think of LSL as a big region, each of these tutorials is a gate into the region from a different direction.

At the center of the region, you have the reference material. Everyone that keeps expanding their scripting ability eventually ends up their.

I ALWAYS read the preface. When I was a kid, my Mom taught me that's the fastest way to learn what the author is trying to accomplish. Reading it avoids a lot of misunderstandings about scope, purpose, and motivation.