Libraries

In a Quest game, libraries are used to add things to your game. By default, your game already has two libraries, Core.aslx and English.aslx (if you are using another language, you will also have one for that language).

To see what these libraries add to your game, go to the bottom left of the Quest GUI, click on Filter, and select Show Library Elements. You will see a shed load of stuff appears in the hierarchy on the left. Everything in grey has come from a library, and if you click on it, Quest will tell you what library in a yellow banner across the top. Core.aslx adds most of the functions, all the types, commands and verbs, while English.aslx adds the templates (some of the more fundamental functions and all script commands are built-in).


How to Add a Library to Your Game

There are several libraries available that you might want to add to your game. They are a quick way to add extra features without you doing too much work. Libraries for handling clothing, conversation and combat are good examples, but other exist not starting with the letter 'C'.

To add a library, go the bottom of the left pane in the GUI, and expand Advanced, then click on Included Libraries. Click Add, and navigate to the library. Quest will copy the file to your game folder, and add a line of code to your game so the library is part of it. If the library includes enhancements to the GUI (and the three mentioned all do), save your game, close it, and re-open it, so the GUI gets updated, and the new tabs will appear.

By the way, if you are adding my Combat library, it is contained in several files; you will need to ensure they are all in your game directory; Quest will not do that for you.


Publishing Your Game

When you use the publish tool before uploading your game, Quest creates a .quest file. This file includes everything from all the libraries you use, including Core.aslx (this means if Core.aslx is updated, it will not break your game because it will still be using the same version).


Conflicts and The Order of Libraries

In general, if there are several things with the same name in your game, later ones will overwrite form ones. This is good as it allows you to change the fundamentals of Quest. For example, the ShowRoomDescription function is used by Quest to display the description for the current room. You might want to do that differently. Just create a new function with the same name.

The upshot of this is that your libraries should be after the standard libraries. Except...

Templates (but not dynamic templates) are different. They need to go before everything else, because the change happens as the game loads and needs to affect the other libraries. Therefore English.aslx goes first, then any of your libraries that change templates, then Core.aslx, and then your custom libraries.

You need to go into code to change the order, but it is pretty easy. Each is on a line on its own, and they are all at the top of the file. Here is an example:

<!--Saved by Quest 5.6.5783.24153-->
<asl version="550">
  <include ref="English.aslx" />
  <include ref="Shipwise.aslx" />
  <include ref="Core.aslx" />
  <include ref="UtilLib.aslx" />

The Shipwise.aslx changes the compass directions to port and starboard, and it does that by changing templates, so has to be before Core.aslx. On the other hand, UtilLib.aslx has a load of utiliy functions, some changing the standard ones, so that has to go after.

As an aside, built-in functions and script commands cannot be overwritten; if you create a function called, for example, msg, it will be ignored. Also, note that for once filenames are not case-sensitive (everything else in Quest is).


How to Create Your Own Library

So you want to create your own library...

It is pretty easy. Library files are just text files, so you need a text editor; I recommend Notepad++. Quest itself cannot handle them unfortunately. Like Quest itself, library files must be in XML, and a simple understanding of XML is useful.

The first line of the file, then, should be this:

<library>

And the last line should be this:

</library>

Everything inbetween will be XML elements, as in the main game.

The easiest way to create those XML elements is to create them in Quest, and then cut-and-paste into your library. For example, for a new function, create the function in Quest, check it works okay, then go into the code view, cut the relevant code, paste into you library. Test again.

The only tricky bit is ensuring you get the whole XML element, but remember for a function it starts:

<function...

And ends

</function>

And make sure you get whole lines.

Personally, I like to move all turn functions, verbs, commands and types into libraries, and leave objects (rooms and items) in the main game. An important point here is that you do not need to plan to use libraries from the start. In fact, there is not much point until you have a fair number of functions in your game.

NOTE: The point of creatingyour own libraries is you can quickly get to the code if you need to tweak something. If you prefer to use the GUI to create scripts, do not bother with your own libraries.


Tips for Large Games

If your game is big, you might find it convenient to break it up across several libraries, so it is easier to find things. Arrange the contents of libraries systematically. For example, put commands in one library, functions in another. Notepad++ allows you to search all files in a folder, which is a big help.

Only put objects in libraries if you are sure they will not change. It is far easier to edit objects in the GUI, so generally not worth putting them in libraries.

Give libraries a .xml extension. You can then tell Windows to use Notepad++ (or whatever; I have no shares in Notepad++, honest) with that file type, whilst .aslx files are opened by Quest. Obviously you need to change the code in the game to load that file, not the old file name.

Use comments. In libraries you can use XML comments, which look like this (if you do this in the main game, Quest will delete them!). Make it clear enough that someone else will understand what it does - that way you will when you look at it again in three months.

  <!--
  Returns the given object list as a string in the form a one, a two, a three.
  -->

If you have multiple libraries, organise them so those higher in the list do not require any lower in the list (i.e., do not use types or use functions in them). Quest does not care; as long as the function is there somewhere, it will be happy. However, occasionally you will screw up, and your game will not load, and you will have no idea where the error is. Create a new test game in the same folder, and add your libraries one by one, in order. When you add one and it refuses to load, the error is in that library. This will only work, however, if libraries higher do not use verbs, types, dynamic templates or functions lower in the list.

With that in mind, as a general rule, put verbs and dynamic templates at the top (but below the default libraries), followed by general functions, then types, followed by the specific function, then commands. Or put the general functions at the top, under the defaults, followed by each library dedicated to a specific part of your game, if you prefer to break it up that way. But think about it; I cannot predict what your game is, so you need to work out the details yourself.

Somehow I missed this post last night while I spent three hours digging through all the libraries in notepad before I found the ordering conflict that was breaking my game. Thank you for all this info. Luckily I'm a fair hand with XML so I had some idea what to look for. But this really helps me conceptualize more clearly how the libraries work with each other.

if worse comes to worse, just copy and paste all of your libraries' contents/code into your game file, laughs. No conflicts (for the most part) then, hehe.

As I've had (and still have) trouble with file linking with some of the coding/programming languages and/or the (grr, I'm getting old, I can't remember the name of it - compiler software, the term for it, argh), understanding how to set it up in ... such as VS, I often do this, lol.

HK edit:

quick google search got the answer: using 'sdk' as the search (I knew of SDK, but couldn't remember 'IDE', argh)

I couldn't think of 'IDE', lol.

One note about objects in libraries, which hit me and at least one other person I know of (I'm assuming this behavior hasn't been changed): if you assign an object in a library a "parent" attribute pointing to another object residing in the main game file (e.g. you want to break your hierarchy out but still have the parentage static), then when you save your game, Quest will pull all the objects with main-game parent references into the main game file - with the result being that you will have duplicate definitions for the objects, and the game won't load. (You can override functions with later library files, but redefining an object is an error.)

It is a bit of an edge case, and definitely a case of "knowing too much for your own good" if you work out how to do it. So just don't do it.