Setting up your scripts in 2.55
This tutorial deals with ZScript in 2.55, and is based upon the original tutorial by Plissken; I've just updated it for 2.55 and beyond, as it is much easier to add and set up scripts into ZC now.
This tutorial will cover the following:
- the things you'll need to get started,
- setting up your main script file,
- adding scripts to your main script file,
- compiling and assigning scripts,
- setting up your first FFC with a script, and
- the quick assign function, script organisation, import scripts and error messages.
Setup
To get yourself started, you will need the following:
- ZQuest and ZC
- A text editor. Your standard operating system's text file editor like Notepad will work fine! There are text editor programs out there that are much more flexible, and easier to work with all round. For Windows, Notepad++ (which you can download here) is the go to. If you're on OSX, BBEdit (download here) is a good option. If you have any other suggestions for good text editing software, post them in this thread!
- A general idea of how you want to organise your scripts alongside your quest file.
Setting up your main script file
So, you've decided you want to put scripts into your quest. To start, you will need a "main" script!
Open up your text editor of choice, and make a new file. The first thing you must do is write "import std.zh" at the top of the file, like so:
std.zh is the standard header for ZScript - without it, any scripts that you might want to add won't work!
Follow this up by saving your file in the ZScript format. This is done with the following steps:
- Select "Save as".
- In the "Save as type" dialog box, choose "All files".
- Save the file under whatever name you want, as long as it has a .z or .zs extension on the end!
If you've followed these instructions, it should look something like this in your "Save As" window:
Press the "Save" button to save your file.
Congratulations! You've just made your main script file.
So I have a main script file, now what?
When you import scripts into ZQ, you will only be able to import a single file at the time, like so:
So how do you import multiple scripts at once? In a different time, you would be required to add every script to a single file. This way, all the scripts in that file can be read in the buffer in ZQ. This can get out of hand very quickly, especially if you're using a lot of scripts in your quest!
Adding scripts from the PureZC database
These days, ZScript allows you to import scripts into your "main" file. Many scripts can be found on the PureZC database, so let's import Moosh's NPC script as an example. To add the script, let's start by clicking the "View script" link on the database page to view the script.
Because of a website bug, "Copy to clipboard" does not copy the script to your clipboard - so manually selecting all of the script, copying it with CTRL+C and then pasting it into a new file with CTRL+V is the main way to "download" a script. Some scripts may have files included in a zip download - in which case, you can just drag and drop them into your quest folder, and ignore these next few steps.
If you've copied and pasted the script into another new file in your text editor, it should look like this:
Save the file with a .z extension, and make sure you save it in the same folder as your main script file.
Adding scripts to your main script
Let's go back to our main script for a moment. Add import "npc.z" and save your file. Your main script should now look like this:
Now, let's go back to ZQuest and try to import our main script. Load "main.z", and press the "Compile" button.
If your main script has compiled correctly, the following should be displayed:
[INFO] External ZScript Parser [Info] Compiling the ZQuest buffer... [Info] Pass 1: Parsing [Info] Pass 2: Preprocessing [Info] Pass 3: Registration [Info] Pass 4: Analyzing Code [Info] Pass 5: Generating object code [Info] Pass 6: Assembling [Info] Success!
After a successful compile, press the "OK" button. This will take you to the "Assigned Compiled Script" window, where you can assign your scripts to any slots you may have free in your quest. There are 12 types of scripts you can assign to empty slots, but for this tutorial we are going to assign scripts to just the FFC tab.
Assign NPCScript to slot 1 in the FFC tab, like so...
... and then press "OK" to assign your scripts to the quest's script slots. When it has been completed, you will get a message in ZQ that says:
ZScripts successfully loaded into script slots Assign Slots took x.xx seconds (xx cycles)
With that, Moosh's NPCscript will be in your quest. But how do we use it?
Setting up FFCs
It is important to note that the different script types have different ways to assign scripts, either through menus such as Screen, or through editors such as the Combo and DMap editors. For the sake of this tutorial, we will only be setting up FFCs, or Freeform Combos, as that is the script type we are using.
From the menu, click on Screen , and then Freeform Combos - you open the FFC editor. Clicking on the "Script" tab will open the "Script" window. With the dropdown menu on the right hand side, assign NPCScript to the FFC like so:
Each script has its own instructions to follow, but most use arguments. If you've downloaded a script from the database, these instructions will usually be under the "Setup" tab on its respective database page. It's also important to note that FFC editors in 2.55 update the arguments to match what can be modified in the script with the FFC editor. In the case of NPCScript for instance, it will assign the title "String" to InitD[0] - which, as Moosh's setup instructions for his NPC script states:
D0: Set this to the string that should play when you talk to the NPC.
From here, you can set up your FFC to do whatever you want it to do. Have fun!
Quick assign
If you've edited a script and you want to just update it without wanting to go through the "Assign slots" window, just click the "Quick Assign" button when your scripts have compiled. This will only update scripts that are already assigned to the quest's script slots, though.
Script folder organisation
So you've read this tutorial, you've set up your first script, and now you're contemplating putting dozens of scripts in your quest. You can continue to add additional scripts using the above guide, but if you don't want to have your quest's main folder full of disorganised scripts, you can place your scripts in a subfolder:
You can do this with as many folders as you want, but make sure that your main script file has the folder location in the import name. In this case, you will need to edit it to read as import "swagquest2023/myscripts/npc.z":
If you don't update your script's location like the above message (or vice-versa), then you will get an error like this when compiling:
[INFO] External ZScript Parser [Info] Compiling the ZQuest buffer... [Info] Pass 1: Parsing [Info] Pass 2: Preprocessing [Error] ZQ_BUFFER Line 3 @ Columns 1-20 - Error P083: Could not find included file 'swagquest2023\myscripts\npc.z'. Please check your include paths! [Info] Failure!
It is also important to note that you keep your directory pathway unique. For instance, adding import "scripts\npc.z" will look for the file in the script folder included with ZC and ZQ, and not the script folder that you have your file in.
Setting up an import script
Additionally, if you keep editing your main script file to add or remove scripts, you will need to reload it into ZScript's buffer each time you do so before compiling. A simple workaround of this is having a dedicated script file that imports your main script. For our example, you would need to write import "swagquest2023/main.z" as the only line of code in this script, and make sure ZScript uses this script, your "import" script, to compile all your other scripts - your main script included.
Error messages
Not all scripts work. This may be because there's a simple error in a script somewhere, or sometimes it can just be a bad script. If your compiler comes up with an error message, it may mean not a lot to you, particularly if you're not very familiar with scripting. There are four common errors (thanks Moosh for pointing these out!):
- when it can't find a file,
- when it can't find a function or constant,
- when there is a duplicate function or constant, and
- when a script uses a 2.55 keyword.
There is a list of other error messages listed in DarkDragon's Scripting FAQ on AGN, but this list is from 2006 (a very long time ago!), so I personally can't verify how many of these are still relevant in 2.55 in 2023 and beyond. It's still a good resource to verify any errors you may have against, but I also highly recommend just contacting the ZC Devs - either through a forum post or message, or on Discord - with any issues you may be running into when you're compiling your scripts.
This rounds out what I wanted to talk about in this tutorial - specifically, just an updated version of Plissken's original tutorial from 2008, brought forward into the present to make scripts a little less intimidating for those starting out.
