A script setup tutorial by Plissken.
Table of Contents
- How to put the scripts properly in your file
- What file type you're going to "Save As" from Notepad
- How to Import
- FFC Explanations
- Error Messages
This will only deal with ZScript and not touch upon loading in ZASM scripts. I had trouble on this when starting out with scripting and I feel like it's not covered publicly enough so I'm making a tutorial for any person new to the subject.
How to put the scripts properly in your file
So, you've found a script you want to use and now you want to apply it. If this is the first script you're going to be entering open up a new Notepad file. Don't copy and paste anything yet, first thing you must do is at the very top of the file write in this: import "std.zh"
Without this, the file won't compile. Make sure it's only in there once and make sure it's at the very top, above anything else. So, now we have this:
Now, you have to copy in the script you want to use. I'll be using some fairly simple ones to start off with, first I'll use pkmnfrk's sign post script found here. I learned the setup of all of this with that script, if you read the topic you can see that.
So, I've copied the script into my notepad file underneath my "import "std.zh"" line with a double space in between.
Well, if you've only wanted one script then you're pretty much done right now. Skip the rest of this section and go to the next one, if you want more than one script keep reading.
Many people when they're starting off make the mistake of making a new file for each script (myself included). But what you need to do is just put any script you want into one file. So, let's take the file I put the sign post script in and put a second script into there. I'll use my Bird script found here. Now, putting in another script into your file is very easy, just go down to the last line of your first script hit enter two times, making a double space, and just copy & paste your new script in. The red text I just put in there to specify where the first ends and the second begins, it's not part of the actual scripts.
Whenever you want a new script in your game you've got to put it underneath your last one.
What file type you're going to create and how
The file type needed to import a ZScript script into Zelda Quest is a .z file. Making this file type is very easy. When you're done setting up your script file in Notepad, you must Save As, and after you enter a name put ".z" at the end. This will make it a .z file type and can still be opened in Notepad and be imported into Zelda Quest.
How to Import
I'll be using the latest build's method of doing this. They recently changed the GUI around, I forgot what build they made the switch but it's in the newer ones.
Go to Quest -> Scripts -> Compile ZScript... -> Import -> and then find and open the .z file you put all of your scripts in. Now hit compile, if there are no errors you should get this.
PASS 2: PREPROCESSING
PASS 3: BUILDING SYMBOL TABLES
PASS 4: TYPE-CHECKING/COMPLETING FUNCTION SYMBOL TABLES/CONSTANT/FOLDING
PASS 5: GENERATING OBJECT CODE
PASS 6: ASSEMBLING
-- PRESS A KEY --
So, do what it says and press a key. Since I used two FFC scripts I have two scripts in the right box on the FFC slot. Zelda Classic allows for a whopping 511 FFC script slots, 3 global scripts, and 255 item scripts. So, to put my scripts into Zelda Quest I highlight the script I want to put in a slot and click the little arrow button. You should now see it in the first slot available. Once you've put all the scripts you want in slots hit OK and you should see a dialog box pop up telling you they've been successfully loaded in.
In your FFC edit box you can select the script it'll be using in the first tab using the drop down menu labeled Script:
Each script has it's own instructions to follow, but most use Arguments. Like in pkmnfrks sign post script thread he says, "To use this, give the FFC the number of the string as the first argument." This means enter the string number in D0. All arguments are handled with the D0-D7. Every script is different and instruction for setup should be provided by the author in the thread most of time.
Unfortunately, not all scripts work. Sometimes it's a simple "oh duh" error, and sometimes it was simply a bad script. If the script fails to compile, a short error message will appear that means... most likely absolutely nothing to you. However, there is a brief list of common error message in DarkDragon's Scripting FAQ at AGN. Unfortunately, there are too many to fit neatly into this guide, but on the off-chance that you do experience any kind of compiling error, this resource is invaluable.
This ends what I'm gonna be talking about in this tutorial. I might include ASM later on, but the truth is that I never really used it. I only know of one person who likes to script with it, and there's only a few scripts that use it.