SEL Introduction: Getting Gory

Using SEL

SEL is invoked in your Adventure pages in tags that require/support them, such as the EVENT tag. SEL allows for a greater level of complexity in your adventures than would otherwise be allowed by a strict set of ABML tags – you can perform most common mathematical and logical actions in SEL which isn’t possible in ABML, as well as being able to keep records of values and lists for various purposes throughout your adventure.

Although SEL is essentially a stripped down scripting language, you don’t have to be a programmer to know how to use it. For the most part, 90% of common gamebook actions can be performed with 1 very small sentence of SEL in the right ABML tag

here is an example of how you can let a reader ‘pick up’ an item – say a wand – in your adventure

You are walking down the passage, when you notice a rod of some kind on the floor. You pick it up and see that it is some kind of magic wand. Thinking it may come in useful <EVENT event="&addtolist $items, 'wand' ">you put it in your backpack</EVENT> and carry on down the passage

In the above example, the value of ‘wand’ is added to the list called $items, using a function called &addtolist. If that is gobbledegook to you, don’t worry, I’ll explain.

Anything with a $ in front of it is called a variable, and may contain any value you like – a word, a whole sentence, a number, or a list made of any of those things. You can call your variables whatever you like, but it must be a single word of some kind. You can have numbers in the name if you like – e.g. $items2, but the number cannot be the first character of the name, so $2items would be wrong. You cannot have any kind of punctuation in the name of your variable except the underscore _ which may be put anywhere in the name, so you could have $my_items which may make the name more readable

So, we know that we have this thing, a variable, called $items. But how do we get the value of ‘wand’ into it? Well, if the variable was only allowed to have one item we could just say “$items=’wand’ “, which would make the variable $items hold the value of ‘wand’, and only that. But obviously $items is meant to be a list, and may already have other values in it, so doing that would lose all the other values in it. So, we use a function to add ‘wand’ to that list of things in $items. Think of a function as a command that ‘does some stuff’ for you. Every function, like a variable has a name, but so we can see it is a function, it must have a ‘&’ in front of it. So we are using the function ‘&addtolist’, and I think you will agree that the name of the functon pretty much tells you what it does.

Now, how do we use a function? Well, most functions require what is called ‘parameters’, which means stuff to work on. The stuff that &addtolist needs to work on is detailed in the SEL reference, but simply put, you just need to put after it 1) the variable name of the list you want to add stuff to and 2) a list of the things you want in that variable. We have our variable, $items, and we want to put the value ‘wand’ into it. So, to do this we say

"&addtolist $items, 'wand' "

It’s pretty easy isn’t it? There are a few things I need to clear up here though. Those single quote marks around the word ‘wand’ are necessary – whenever you want to use a sentence, or word, literally, in SEL, you have to quote it. Otherwise SEL will think you are trying to use a command of some kind. You *can* use double quotes, but because we are using the SEL inside an ABML tag here, putting quotes inside the ABML quotes would confuse the interpreter. If that’s confused you, just stick to single quotes for now. Numbers – like 1, 24, or 2000435 don’t have to have quotes however, you can chuck them in wherever you like – as long as its appropriate!

The other thing I need to point out is that the parameters to functions must be seperated with commas, so you have the function name, then the first parameter then a comma, second parameter then a comma and so on.

Let’s move on now, and see what we can do with this information we can store now. Let’s say that the point of your adventure is to collect 3 wands. So, how do we tell when we get to the Gate of Doom or wherever, that your reader has collected 3 wands? Well, using the ABML ‘IF’ tag, and a little bit of SEL it’s quite easy. Heres how we do it:

You finally reach the Gate of Doom. To close it and stop evil spreading through Allansia, you see that there are 3 slots on the gate, and some writing that says "The 3 Wands of Power are the keys to this door".
<IF condition="&countinlist($items,'wand') == 3"> If you have the 3 wands you put them in the slots and step through <TT ref="400">Turn to 400</TT></IF>
<ELSE> Otherwise, you realise you have failed in your quest, and sit down to wait for your fate. <BookEnd adventure="Failed">Your adventure ends here</BookEnd></ELSE>

Hopefully, apart from the bit of SEL in the condition section of the IF tag you know whats going on here from using ABML. Basically, if the condition is true, then the reader gets to turn to 400 (hurrah!), but if it isn’t then the link to 400 wont work, and the BookEnd tag will be the only option for the reader (boo!) – note also the BookEnd tag will not be available for someone that can turn to 400

The condition part needs a bit of explaining though. We can see we have our variable, $items, which we know is a list of values, and we have a new function, &countinlist. Again we can guess from the name of the function what it does – its counts stuff in a list. But why do the parameters have brackets round them? Well, you can put brackets round the parameters to any function, and in some cases its very useful – if we hadn’t done it here, the ‘== 3’ part would just have become part of the second parameter. What’s happening here is we are using the fact that many functions will return a value of some kind. This function, &countinlist, returns the number of times the second parameter appears in the list variable it was given as its first parameter. In our example that means it returns the number of times ‘wand’ appears in our list variable $items. If there are 3 ‘wand’ values in $list, then we end up with 3==3, which is true.

NOTE: ‘==’ is used as a comparison operator. The single ‘=’ is used for assigning a value to a variable. Trying to say ‘3=3’ would try and assign the value 3 to a constant value of 3, which would make an error. It’s very important to remember the difference as it is an easy mistake to say ‘IF $health=4’ instead of ‘IF health==4’ – the first one will actually change the value of $health, the second one will just compare the two and if the value of $health is 4 then it returns true (false otherwise)

One last point I should make, in case you go raring off to try this example for yourself, is the &permvar function. Once you have made a variable, like $items, somewhere in your adventure, if you want to be able to refer to it later in the book, you must make the variable permanent, by saying ‘&permvar $items’ somewhere. Otherwise the variable is just known as a Temporary variable, and will only exist for as long as it takes to process the page it has been made in. Once a variable is permanent, it will exist for as long as the book does and can be referred to, or have its value changed as you please.

Leave a Reply

Straight outta Blacksand

Skip to toolbar