ABML – Beyond the Basics

O.K., so you have mastered the art of creating an adventure that simply takes you from page to page, you have played quite a few adventures and know there is an awful lot more to a good adventure story than clicking from page to page.

“How about character sheets?” you say. “I want my readers to pick up items!”, “I only want certain options to be available IF they have the Great Hammer of Andurin/have got the note from Roy asking her to meet him at the ice-skating rink”

Well as you may have guessed there is a bit more to ABML than the <tt> and <bookend> tag – not much more though – Currently 6 more tags to be precise.

(edit there are now a number of more advanced Turn-To tags which I will document here later but details may now be found on the ABML reference)

These are:

• <event event=”SEL code”></event>
• <option option=”SEL code”></option>
• <if condition=”SEL code”></if>
• <else></else>
• <info info=”SEL code”></info>
• <script script=”SEL code”></script> (not detailed here)

Always remember – Don’t Panic! As usual, we will be making efforts to put all this stuff in the online editor for you to make it easier to just write your exciting adventures. It is important however that you have at least a vague idea of what those bits of strange language are that the editor puts into your pages, and also that you know just what you can write into your adventures.

The first thing you are probably thinking is ‘what on earth is SEL code?’. SEL code is the magic that makes genuinely interactive books possible. It can be as simple or as complicated as you please. To begin with we recommend you keep it as simple as possible – by using predefined code, from examples or from defaults in the editor.

Please note that the SEL functions mentioned here e.g. &GetItem, &HasItem etc. are not actually part of the core SEL function library and are used for illustrative purposes only.  SEL functions are explained a little here under the <script> definition and more thoroughly in the SEL references.

What SEL enables you to do is make statements such as ‘The character picks up the Electronic Keycard’, that will actually be recorded and remembered so this information can be used later on. That example would look something like this:

<event event="&GetItem('Keycard')">You pick up the Keycard</event>

Very similar in some respects to the tt tag you know, except that with this particular example the ‘You pick up the keycard’ will just be highlighted rather than turned into a link. The book will automatically add the item to the characters items list, and do anything else the GetItem function for that book tells it to do when getting an item.

If you wanted to make the action a choice for the reader to click on however, you would use the option tag instead, in exactly the same way, like this:

<option option="&GetItem('Keycard')">You may up the Keycard if you wish</option>

This would make a link just like a tt tag for the reader to click on, and the GetItem function will happen only if the user clicks on it, i.e. the Keycard will not be picked up unless the reader clicks the link

Now we know how to get the book to do things for us, we need to know how to make different choices available depending on certain circumstances, like we want to say ‘You have come up to a closed door. If you have a Keycard you may go through it if you wish (turn to 123) otherwise you must carry on down the corridor (turn to 456)’

It doesn’t take a genius to figure out which tag we are going to use now:

You have come up to a closed door. <if condition="&HasItem('Keycard')">If you have a Keycard you may go through it if you wish (<tt ref="123">turn to 123</tt>) </if> otherwise you must carry on down the corridor (<tt ref="456">turn to 456</tt>)

What this will do will only enable the ‘turn to 123’ link if the condition in the IF tag is ‘true’. In this example the HasItem function will be true if the reader has the Keycard, and false if they do not. Simply put, every tag that is surrounded by <if> and </if> tags will only be ‘activated’ if the Condition=”” part is True (note: programmers will not be surprised that True means ANY non-zero value).

Note this means you can have <event> and <option> as well as <tt> turn to tags inside an <if> statement that will only happen/be available to choose if the <if> condition is True. You can have as many tags in between an <if> and </if> as you please. And yes, you can have more <if> and </if> in between, this is called nesting. Beginners should avoid this as you can get confused quickly and easily. For advanced users that feel comfortable doing this, just make sure you close each <if> with an </if>.

The <else> tag is basically stuck on after an <if> </if> and does as it sounds – every tag between the <else> and </else> tags is only ‘activated’ if the condition of the preceding <if> tag was false. For those of you who have no programming this may seem not very useful, but if we look carefully at the example we gave before with they Keycard and the door, you may see that readers who have the card still have the option to carry on down the corridor and not go through the door, but you as the writer may want to force Keycard holders through the door. You could acheive this with another <if> </if> tag block and a bit of jiggery pokery inside the condition part, but it would be a lot easier to do this:

You have come up to a closed door. <if condition="&HasItem('Keycard')">If you have a Keycard you decide to go through it (<tt ref="123">turn to 123</tt>) </if><else> otherwise you must carry on down the corridor (<tt ref="456">turn to 456</tt>)</else>

Put simply this means that readers who have picked up a Keycard will only be able to turn to page 123, and those without will only be able to turn to 456.

Now we have the <info> tag. This is simply for those places where you want to put some information into your text that depends on what information the character has stored. For example, if we need to say ‘You must have collected 12 Red Roses from Jeremy to go to his party, you have only collected X Roses’ when we obviously do not know at the time of writing the adventure how many X is, we would do this:

You must have collected 12 Red Roses from Jeremy to go to his party, you have only collected <info info="&CountItem('Roses')">Roses</info>

<info> basically just puts the value returned from the SEL code directly into the text (this may a number or may be some text), followed by the text in between the info and /info tags.

 

Finally we have the <script> tag.  In complex gamebooks, e.g. Fighting Fantasy itself, we often have situations that cannot be replicated simply with the previous tags, most noteably gamebooks that have a combat system, or an inventory system or usually both.  This requires quite complex coding and interactivity.  The <script> tag enables this complexity by allowing the output of SEL functions to be placed into a reference directly, noting that SEL may actually output ABML tags this does allow for a great deal of depth.

When I say the output of SEL, this currently only means anything generated by the SEL &print function.  This is different from the <info> tag since <info> takes the return value of SEL code (it’s a technical difference which may seem hard to grasp but once you’ve used <info> and <script> appropriately it’s quite straightorward).

For example, the classic Hello World applies here, and goes like this:

<script script="&print 'Hello World';" />

Which will display the phrase ‘Hello World’ at that point in the ABML document.  This may not seem very useful!  To quote Polonius ‘Good madam, stay awhile, I will be faithful’.

SEL requires some programming knowledge to create SEL yourself, however you do not need to know SEL very well to use predefined functions.  A function is some pre-written code that ‘does stuff’ like handle your combats.  You need to find out what the SEL function wants to know however.  Currently there is a fighting fantasy combat function called &combat_1on1 (all functions start with the ‘&’ symbol), which simply needs to know:

1) The reference number of the page you are putting the combat in to, we will use ‘123’ for this example.
2) An ID of your choice for the combat on that page (because you might want to put more than one combat on a page), we will simply say ‘1’ for this example
3) Your choice of the ‘escape’ option, where ‘0’ means the reader may not escape, ‘1’ means escaping is allowed and uses the normal (from Warlock of Firetop Mountain first edition) rules, and ‘2’ means escaping is allowed using another common escape rule (enemies automatically get a hit on you when escaping and don’t have to do an attack roll).  We will use the option 2 here.
4) The Name, Skill and Stamina of every enemy the reader must fight in this combat.

Example:

<script script="&combat_1on1(123,1,2,'Goblin',5,7,'Orc',6,8);" />

Using the script tag this way allows the &combat_1on1 function to make a combat on your page against a Goblin and an Orc.  Note that you will have to have set up a character sheet with Skill Stamina and Luck as well though.  I will write a specific guide to basic Fighting Fantasy SEL system at some point, but this was intended to show how <script> tags may be powerfully used.