Getting Started

ZScript is designed to be easily understood – by humans rather than computers! It’s basically English, written in a special way that ZBrush can interpret and so carry out the relevant tasks. Like any language there are rules that have to be followed but these are pretty simple.

ZScript is written as plain text, so to get started all you need is a text editor. As no fancy formatting is required it can be a basic editor, like NotePad, but there are special text editors available, designed for writing programming code like ZScript, and these will be discussed later.

Once the necessary file has been written it’s saved with a .txt extension. It is then ready to be loaded into ZBrush. (From now on we’ll refer to this text file of zscript commands as a zscript.)


So What’s it All About?

The ZScript language is made up of a series of commands – nearly 200 of them. These commands can be put together in a huge variety of ways so as to get ZBrush to do stuff.

Let’s suppose you’ve written a zscript, or got one from somewhere such as ZBC – what happens next? Well, first the zscript has to be loaded into ZBrush by pressing the Load button in the ZScript menu. At that point ZBrush tries to convert the human-readable zscript text file into computer-readable code (or ‘machine code’ as it is known). This process is called compiling and, if all goes well, the ‘Play’ button or other interface components will appear and the next part of the process can happen – running the thing!

But we’re getting a little ahead of things; first let’s consider the zscript language in a little more detail.


Understanding the Lingo

Brackets and Commas

All the ZScript commands are contained within square brackets: [ like this ]. Inside those brackets the different parts of the command are separated by commas: [ like , this , and , this]. Those are the two essential punctuation marks in zscripting; the rest is made up of the special command words and various options.

The commands all follow the same basic form. There is a starting square bracket followed by the command name. After that come the various options (if there are any) separated by commas and finally there is an ending square bracket. Here is the command for setting the canvas zoom; the 1 is the value which sets the zoom to actual size:


Inside and Outside

One thing to watch when arranging your zscript is how the commands relate to each other. Some zscript commands have to always be on their own in a zscript – these are called Top Level commands. Other commands must always go inside other commands – these are known as Sub-Level. However, the majority can go anywhere; inside or outside.

So how do you tell where to put things? There are no obvious ways to distinguish Top Level or Sub-Level commands. But don’t worry about this now; when you get to look over the ZScript Command Reference you’ll see that the different types of command are clearly indicated.


Descriptive Commands

As has been said, the ZScript language is basically English which has been adapted so that it can be interpreted by a computer. As you may have realised from the example given above, it’s not that difficult to understand what a command does. CanvasZoomSet is simply a compressed way of saying ‘set the canvas zoom to…’. Likewise, the command that creates an interface button is IButton, the I being an abbreviation for Interface. As you’ll see, this particular form, with an I at the start of the command, is used a lot.


Upper or Lower Case?

ZScripting is not case sensitive, in other words it doesn’t matter whether you type your code all in lower case, ALL IN CAPITALS, or a combination of the two. [There are a couple of exceptions (of course!) but we will deal with those later.] The form we will follow here is a mixture of upper and lower case, with a capital letter indicating a new word, as in CanvasZoomSet. This method is generally easiest to read and therefore easiest to understand.

Watch that Syntax!

A big difference between any computer programming language and human speech is that the computer is very unforgiving of errors. If we say ‘the cat white is’ then most people will understand that we mean ‘the cat is white’. But if we were to make a similar mistake in a computer language then the computer would not understand and our code would not be useable. Putting everything in the right place and right order is what’s meant by correct ‘syntax’.

ZBrush first checks the syntax when the zscript text file is loaded. If the syntax is wrong then we can’t get any further – ZBrush can’t make its ‘machine code’ and a message is displayed in the zscript window at the bottom of the ZBrush interface. (You may need to click on the handle or press ‘H’ on the keyboard to get the zscript window to open.) ZBrush will display your code and then a message where it thinks the error is – though sometimes the precise error can be difficult to track down! Here’s an example:

ZScript window

What this all boils down to is this: make sure you check that each opening square bracket has a closing square bracket, and that your commas are in the right places. It can be fiddly getting this right but errors of this sort can be difficult to spot later.


The Nuts & Bolts of ZScripting

Now, to look at zscripts in a bit more detail, move on to the next page: Nuts & Bolts.