Scripting 101: the Wikibook

(I originally posted this in the "Is the scripting wiki helpful to you?" thread, but decided it would be more appropriate to start a new one.)

Let's take as given that a gentle, but thorough, course in LSL programming would be a good addition to the SL Scripting Wiki. Who here would be interested in collaborating on creating something like that? It's the kind of thing I would enjoy doing, but I know that working mostly by myself, I would soon wander off to something else. But as one of, say, a dozen people who were interested enough in the give and take of collaboration to get past their disappointment when their contributions get mercilessly revised, I could put a lot of energy into it.

I'm posting this here, in preference to the scripting forum, on purpose. Undoubtedly, there is more scripting expertise in the scripting forum, but I suspect there is more of an audience for this effort here. And in my mind, audience participation would be at least as important as technical knowledge in a project like this.

I'd gladly help teach people how to script in-world, with classes and such, if that is what you are talking about. The main problem is that people don't want to learn HOW to do something, they just want something that works right away. I think the dedication is there for some people to teach, but you also will need students who want to work and put in the time to learn, instead of the fast self gratification of getting their one little item to work right and don't care how it works.

That's true for builders and texture artists too. We certainly see plenty of impatient, gotta-get-my-project-made people, but we also see a lot of genuine students who want to learn the ropes. Heck, that's how WE started. So long as there are people out there who really want to learn, it's worth putting together tutorials and classes to help them.

If I can be of any help, don't hesitate to call on me. I'm certainly an eager member of the audience you describe. I don't know a whole lot about scripting, but I do know writing. I'm not sure if I can beneficial or not, but I can, I'd like to be. Let me know.

My post was motivated by Chosen Few's (and other's) observation that the bulk of the SL scripting Wiki is structured as a reference work, mostly useful for those who already have a pretty good understanding of what SL scripting is all about.

What I'm thinking of would be more akin to a user's guide than a reference manual. It would have a narrative style and a carefully planned sequential presentation, trying to make the learning curve as smooth as possible.

I would certainly hope that anything we produced would be very useful for teaching in-world classes, perhaps only as an instructor's guide or supplemental material, but possibly as in-class lecture slides that could be displayed using the parcel media capabilities.

Does that clarify anything? Would you be interested in being part of that?

Chosen, I hoped you would raise your hand. I think you would be a key contributor. I've got to run right now, so I'll have to put off any elaboration.

I can probably come up with some "exercises" and stuff, and maybe do some intro stuff, but it would have to be edited and dumbed down, I know I tend to get technical way to much, and tend also to ramble and mix things up. But if someone is willing to basically be an editor, don't see why we can't get our own version of something out. As I said before, I'd be happy to teach classes in-world on it too. Sometimes the best thing to do is just to walk someone through the things.

I'll be glad to help too. I'm a novice scripter in LSL, but I have been writing programs for my own use since the early Fortran IV days. As a retired academic, I also have fair experience with figuring out better ways to say technical things for the benefit of new learners. I'm a bit leery about overextending myself. If you can use another editor, though, I'm willing to pitch in.

Add diagrams. I would, but my diagramming skills suck.

I'm not sure what kind of diagrams you have in mind, Lee. Can we count on you to let us know where you think they are needed?

I'd be happy to. You'll have to explain to me what specifically you mean, though.

I'm happy to help with explanations and examples (so long as I don't have to spend days learning to wiki ).

I agree (of course) that this is a good idea, but where should it start? Most of the tutorials on LSL assume that the reader is familiar with the basics of programming, and in other threads that's been brought up as a problem.

Like:

1. Variables and constants
2. Calculating results - expressions and equations
3. Controlling your program - tests and loops

Or jump right into use cases?

Would a list of other guides that people have written be useful, either as structure or (where the creator of the guides agree) as source material?

I guess a good place to start would be here:

https://wiki.secondlife.com/wiki/Help:Getting_started_with_LSL

Looking through them I do not see anything that really works in the "Beginner Tutorials" as a Beginner Tutorial, specifically this one:

https://wiki.secondlife.com/wiki/Help:Getting_started_with_LSL

But I have not looked through the external tutorials if there is one that is a better stepping stone. I mentioned earlier finding an ebook on LSL about a year ago that was decent. I will take a look later today if that is one of those externals or if it is elsewhere.

There's a couple of actual printed books. This one has a lot of material online:

http://www.heatonresearch.com/articles/series/24

I was definitely thinking of the former as the place to start. For someone who already knows how to program, I think the current Wikis do a more than adequate job of documenting the SL API. (Better than the average API I encounter in RL).

On the other hand, I don't see trying to teach general programming concepts independently from useful LSL examples. Many years ago, I taught introductory programming to undergraduate non-CS majors. Because the students wouldn't be taking any other CS courses, I had to be careful not to assume anything beyond "common sense". My general strategy was to structure the course around real examples, where ideally, each example required just a little more discussion than the previous one. Originally, the course used Pascal as the programming language but later it was switched to C. The switch required not just translating the examples, but also reordering the whole development, because of differences in the languages.

That's my mental model for how I would structure the first part of the Wikibook, and I can try to do the same for LSL. But this is going to be a Wiki after all, and it may turn out to be quite different than what I currently have in mind. In fact, I would hope it will.

No worries. This is a group project. You can always make contributions in plain text. Someone else, who knows Wiki formatting but wants to learn what you have to offer about scripting, can make it look better.

I like the idea, we need more and better tutorials. Unfortunately... I'm no good at writing them.

While on this topic. I'm thinking about adding into the LSL Layout a bit of text and a link telling the user where they can find background information they need to know before they can really understand the article. If the wiki were a book this wouldn't be needed because it would be implied as the information would be covered in a preceding chapter. Essentially I would like to link them into a chapter of a high detail tutorial.

This is certainly in line with my vision of what the book should be. My thoughts at the moment are centered around the earlier chapters (what I'm thinking of as the "Essentials", which would mostly be about the language rather than the library functions. But after the essentials, there could be many chapters that covered various groupings of library functions. These could be developed independently and concurrently once there was some concensus on what was going to get covered in the Essentials.

Maybe you can think about a proposal for breaking up the API into "chapter" sized chunks.

EDIT: Even if you have a plugin to see bbcode or are quoting to see the proper formatting, I would suggest you still click on the link at the bottom of this post to see the script in a wiki page. The coloration of the script along with proper formatting differentiates the comments from the code itself making it much more readable and less jumbled.

My writing skills are sorely lacking as I mentioned in the other thread but I can write scripts.

Wondering if something like this will also help. Anyone can use this as a starting point. Or if people like it I would be more the happy to get some feedback on polishing it.

/////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////ANATOMY OF A SCRIPT///////////////////////////////////

//A script ignores everything starting with at least two forward slashes
//This is called commenting a script. You can use them to make notes for
//yourself or others
//Comments do not count against script memory

//////GLOBAL VARIABLES
//Variables declared here can be used throughout the script
//Global Variables make the script easier to read and edit
//Global Variables use less memory if used multiple times in a script
//Global Variables use more memory if only used once or twice, balance this with readability
//Name a variable so that you can remember what it is and references
//This becomes more important as the script grows in length

string strExample = "I am a string";
list lstExample = ["I am a string in a list"]; //lists start at 0
vector vecExample;// Global Variables need to be declared but do not need to be defined yet

//////USER DEFINED FUNCTIONS
//Please see the wiki section on User Defined Functions for more info

my_function(){
	llOwnerSay("I am called from a User Defined Function");
}

/////STATES
//Every script has to have at least one state
//The first state is named default and does not need to be declared as a state
//except to call it from another state
//Any other states need to be declared
//Example: "state next" w/o qoutation marks
//Wherever it is used it will always be both words: "state next" w/o quotation marks
//Declaring state next and calling just "next" will not work
//Multiple states can make a script easier to read and maintain
//It is better to stay within one state if at all possible

default{ //notice that "state" is not necessary
	/////EVENTS
	//Events are declared inside a state
	//You can not declare an event inside another event or User Defined Function

	state_entry() {
		llOwnerSay(strExample + " called from within state_entry");
		//Notice that i have just combined the two strings this will result in
		//this message:
		//"I am a string called from within state_entry"

		my_function();
		//Now I have just called the user defined function

		vecExample = llGetPos();
		//Now I have defined the vector I declared globally
		//This can now be used throught the script and
		//will stay the same unless it is redefined
	}
	touch_start(integer n) {
		llOwnerSay("I have just been touched");

		/////Local Variables
		//Local Variables use less memory then Glabal Variables
		//But can only be used within the current event
		string lstExampleString = llList2String(lstExample, 0);
		llOwnerSay(lstExampleString);

		llOwnerSay("I am a vector cast as a string: " + (string)vecExample);
		//llOwnerSay "says" strings and only strings to
		//"say" anything that is not a string it must be "cast"
		//Please see the wiki section on "typecasting" for more information
		//vecExample is a vector but here I have "cast" it as a string

		state next;
		//Several things occur when you change states
		//Some porcesses are put on hold and you may
		//need to put some on hold yourself
		//to do this use state_exit()
	}
	state_exit() {
		llOwnerSay("I am called from state_exit");
	}
}//Brackets are used everywhere in a script
//A closing bracket has to be used for every opening bracket

state next{
	state_entry() {
		llOwnerSay("WOOHOO! I am called from a different state " +
			"Touch me again to switch back to state default");
		//Notice how I broke the string into multiple parts to keep the line
		//from running off the end"
	}
	touch_start(integer n) {
		llOwnerSay("Switching back to the default state now");
		state default;
		//Notice that here I have had to call default as a state
	}
	//If you do not need it, you do not have to call state_exit
}

EDIT: Looking at it I can see it will help if I provide the links for STATES, USER DEFINED FUNCTION, TYPECASTING etc.
Have some pity though, I HATE COMMENTING SCRIPTS and this was nearly painful

NOTE: If you are not using a plugin to see bbcode, hit the QUOTE key to see the script formatted correctly. It can also be seen here properly formatted in one of my user pages. Anyone can setup a user page to help others learn:

https://wiki.secondlife.com/wiki/User:Jesse_Barnett/Script_Anatomy

Excellent idea Jesse. Personally, I think it should be written in narrative format with examples in lsl format rather than using comments for everything and that more explanation for each thing would be good, but what a great starting place.

STRUCTURE OF A SCRIPT

In this section we will discuss the structure of a script; the various parts of a script and how they are laid out. The order of the parts is important and they are described here in the order they occur in a script:

- Comments
- Global Variables
- User Defined Functions
- States
- Event Handlers

Actually, comments can (and should) be used throughout the script but we will introduce them first.

COMMENTS

Comments in a script are a good idea. They help you and others know what a script does, or what a particular part of a script does, and are particularly important when you do something very clever or unusual. Even if you are not sharing your script with others it is a good idea to use comments because you may come back to change it later and good commenting will make that much quicker and easier.

Comments can be added to a script by using two '/' characters, like this:

// this is a comment

Comments can be at the beginning of a line or they can follow another script statement, like this:

llOwnerSay("We follow this brief statement with a comment:"); // this command sends a message to the owner of the object that contains the script

When you save the script you keep one copy (that has all the comments in and that you can edit) and the compiler makes another copy that is 'compiled' (translated into a format the computer can run as a program). The compiled version doesn't have any comments, so they don't take up any memory in your script.

Your script should have a comment at the top describing what it does, although it is not a requirement to have such a comment; your script will compile just fine without one.

For anyone who has programmed in C, Pascal and similar languages; there is no multi-line comment, like /* */ in LSL.

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. You don't have to use global variables and it is a good idea to think carefully about any you do use but they can help you to have a well-designed script and they can also make things more understandable.

As you read on, you will see that there are parts of a script that are like boxes, containing things only they know about, their own data that no other parts of the script can see or change. This is a good thing because it means you can use the same name to store similar kinds of data (but separate copies of the data) in different parts of your script. Sometimes, though, you need to be able to change some data in different parts of your script and that is where global variables come in.

Before talking about global variables in particular we should discuss variables in general.

Variables have to be declared before they can be used. 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 '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.) You can also give them a value at the same time as declaring them, like this:

integer count = 10;                 // this a number and its value (at least for now) is 10
string myName = "Fred";         // this is a letter, word or sentence and its value is 'Fred'

Giving a value to a variable is called 'defining' the variable, so in the example above we both declared and defined the variables.

You can see from the comments in the example above that different variables can store different types of values. In the declaration we have declared what type of data the variable can hold, in this case an integer number, and we have used the name 'count' to refer to that number. In the second declaration we say we want to store some character data and refer to it with the name 'myName'.

There are a different types you can use in SL, depending on what type of data you want to store and how you want to use that data. Here is a list of all the different types:

integer

In LSL an integer is any number between −2,147,483,648 and +2,147,483,647, so long as it is a 'whole' number (it doesn't have a decimal point, like 1.5).

string

A string can contain a character or symbol or a list of characters and symbols. When defining a string (assigning it a value) you must surround the value with double quotes "like this". You can use any characters in a string, including some special characters like "\n", which is a newline character, as if you pressed the return key on your keyboard. If you want to put a double quote character in a string you have to put a backslash character in front, like this "There are \"double quotes\" in this string".

etc.

I don't mind to turn your skeleton anatomy into something like this Jesse.

Glad to see someone running with it. The one problem that pops out is that we have sections defining each part. I was trying to not only comment but also highlight the structure of the code itself, it is much more clear when viewed in the wiki page.

But then again, as I mentioned I am by no means a writer and I don't think I even conveyed what I was trying to say here

I'll keep working on it and would love to see if you or others come up with more also. There is nothing saying that we need just one example. Plus this is not designed to replace the proposed book which I think is an excellent idea.

Certainly it is much clearer on the wiki. I think it would be of benefit in the narrative to have an abbreviated version of that. I say 'abbreviated' because I think that most of the comments would be better suited to explanation in the narrative and that comments in the structure itself could then be apposite to the structure itself.

Or maybe footnotes with reference numbers? I'll be letting it percolate through my brain today.