Nuts & Bolts

So What do You Want to Do?

Having some some idea of what you want your zscript to do is clearly the first step. But also you will need to know how ZBrush goes about things if your zscript is to work as you wish. Some actions are only possible after other things have been done first; for example, the Morph Brush is only available if a Morph Target has first been stored.

Examining ZScript Recordings

One way of getting this sort of information is to do the thing you’re interested in while recording a zscript of your actions. When you’ve finished, switch off zscript recording and save the file. You can then open this in a text editor and examine it. This method provides a good way of getting to know more about zscripting.

Pressing the right Buttons

In its most basic form, a zscript can be used to press ZBrush interface buttons, one after another. If, as suggested above, you’ve tried examining a zscript recording you will probably have come across the [IPress command. It will appear something like this:

[IPress,Tool:PolyMesh3D]

It’s clear that this command is in two parts – the IPress bit that tells ZBrush to press something and the Tool:Simple Brush which is the interface item that is to be pressed. In zscripting we indicate a ZBrush interface item by using the Interface Button Path.

 

The ZBrush Interface Button Path

Everything that makes up the ZBrush interface has a Button Path. (It’s called the button path but applies to any interface item, whether it’s a button, a switch or a slider.) Generally the button path describes the menu and submenu (if there is one) before the interface item itself. Each is separated by a colon : like this:

Tool:PolyMesh3D
To find the button path for any item on the interface, place the cursor over the item and hold down Ctrl on the keyboard. A descriptive note will appear and the button path is given at the bottom of the descriptive note.

We now have a way of pressing buttons on the ZBrush interface: combining the command [IPress with the button path. That’s a good start but before exploring more ZScript commands we’ll consider a good way of keeping track of what we’re trying to do. That way we won’t get our code tied into knots that we can’t untangle.

 

Make it Meaningful

The whole point of a language is to allow dialogue, and in order to have a dialogue both sides need to understand what’s being said. In zscripting, the ZScript commands are there to provide the computer’s side of things. For the human zscripter there are a couple of ways that help to keep things meaningful: comments and variable names.

No Comments? No Comment!

A comment is just a note made by the person writing the zscript, explaining the purpose of a particular bit of the code. The whole point is to make the code more understandable. Why bother? Well, it’s surprising how something that was as clear as day when it was written can be as clear as mud a few weeks later. But also commenting code is good practice for any sort of programming, ensuring that it can be understood by others, and if necessary updated (or ‘maintained’) by them.

Comments need to be written in such a way that they are ignored by the computer, otherwise it might try to interpret them as code. In ZScript this can be done in either of two ways; by using two forward slashes at the start of the line like this:

//This is a comment

or by enclosing the whole comment in a forward slash-asterisk, asterisk-forward slash combination like this:

/*This is another comment*/

This first method is useful for short single lines; the second method is good for larger blocks of text.

These comment marks can also be used for temporarily removing code from the zscript (sometimes referred to as commenting out ). This can be useful when trying to track down errors, or when you’re making changes for which you are not sure of the effect. This line of code has been commented out:

//[CanvasZoomSet,1]

The computer will ignore the command and it won’t form part of the zscript.

 

What’s a Variable? Define it…

A variable is a way of storing information for use later. It’s simply a chunk of the computer’s memory that you identify with a name. It’s called a variable because the information can be changed (or varied) at any time. When you want to use that bit of information you simply put in the name of the variable and the computer gets the information from its memory.

You create a variable by defining it. This is done with the [VarDef command which stands for Variable Definition and after the command you enter the name you want it to have and also an initial value. This is the basic form:

[VarDef, variable name,initial value ]

When you create a variable, give it a name that easily identifies it; that way your code will not only make sense while you are writing it but will be easy to understand later. You can write variable names pretty much how you want but here we will start variable names with a lower case letter, to distinguish them from other code. So, for a variable that we want to use to store the width of a texture, we might write:

[VarDef,textureWidth,0]

The 0 here is the initial value. This serves primarily to define the type of variable; in this case clearly it is a variable that will store numbers. There’s only one other type of variable in zscripting – one that stores words or groups of characters (which are known as strings ) but we will deal with that type later.

So now we have a variable named textureWidth which we can use to store the width of the texture. You might think that’s all very well but how do you find out the texture width in the first place? We’ll explore that in the next section.

 

Getting & Setting : information To and From ZBrush

There are two words that crop up often within the ZScript command names: Get and Set. You’ve already come across one example:

[CanvasZoomSet,1]

and naturally there’s the other one of the pair:

[CanvasZoomGet]

As you will have guessed, the Get commands get information or values from the ZBrush interface and the Set commands set a ZBrush interface item to a particular state or value.

For the majority of buttons and sliders on the ZBrush interface you can use

[IGet,interface item path]

or

[ISet,interface item path,value]

with the relevant button path.

These two groups of commands are among the most useful in zscripting.

Setting Variables

There is also Set command for variables (though no Get equivalent; it’s not necessary as specifying the variable is enough). The basic form of the variable Set command is:

[VarSet, variable name,value to set ]

So how do we set the textureWidth variable we created earlier? First we need to find out the width of the current texture. This is given in the Width slider in the Texture palette. To use this value in our zscript we first find the Button Path, then combine it with the [IGet command. That way we can be sure that we are using the width of the current texture. We can then store the amount in our variable like this:

[VarSet,textureWidth,[IGet,Texture:Width]]

You might have already thought of how this could be useful. We’ll now explore one possibility in a complete zscript.

A First ZScript

Having got this far, that old adage ‘there’s no better way to learn than by doing’ is probably appropriate so we’ll build a whole zscript.

We’ll start by defining the variables that we want to store certain values. It’s good policy to define variables at the start of a zscript; you can then be sure that they are available throughout the code. For this reason they are sometimes called global variables. We are going to define just two for this zscript. They will store the width and height of the current texture, so we’ll call them textureWidth and textureHeight. We’ll also give them both an initial value of 0, that way they are defined as storing numbers. Here’s the code:

[VarDef,textureWidth,0]
[VarDef,textureHeight,0]

Now we’ll add a button. This will contain the main commands of our zscript – the stuff we actually want ZBrush to do. The beginning of the button goes like this:

[IButton,"FillCanvas","Fill Canvas with Texture",

The FillCanvas will be the button label, and Fill Canvas with Texture will be the popup info that appears when the cursor is over the button. After this come the commands, listed one after another with no commas between them:

[IPress,Texture:Txtr01] //select a texture
[VarSet,textureWidth,[IGet,Texture:Width]] //set variable to texture width
[VarSet,textureHeight,[IGet,Texture:Height]] //set variable to texture height
[IUnPress,Document:Pro] //turn of document proportional button
[ISet,Document:Width,textureWidth] //change document width to value of textureWidth
[ISet,Document:Height,textureHeight] //change document height to value of textureHeight
[IPress,Document:Resize] //resize document
[IPress,Material:Flat Color] //select Flat Color material
[IPress,Color:FillLayer] //fill canvas with texture image

As you’ll see, each command has been commented so that it is clear what action is performed. When all the commands have been entered we need to finish off the button with its closing bracket:

]//end of button

That’s it, a complete zscript! To test the zscript, save as a text file (*.txt) and then load it into ZBrush using the Load button in the ZScript palette. The button will show in the ZScript Tutorial window. (If you can’t see the button enlarge the Tutorial window by dragging on the handle.) Press the button to run the zscript.

Important!

The ZScript Tutorial window is at the bottom of the interface. Either drag on the handles to show it or press H on the keyboard. You may need to click and drag up or down in the window to show the button.
Standard zscripts and zscript recordings will always display in this window. If the zscript is a plugin then the buttons will be in one of the palettes, usually with its own sub-palette. You can tell where by examining the button name in the code. Writing plugins is dealt with later in this documentation.

Note: There are some circumstances where running this zscript will produce warning messages. How to deal with such messages, or making sure that things don’t go wrong when the user runs the zscript, is an essential part of zscripting. That’s why it is important to test a zscript. Some methods for dealing with different sets of circumstances will be dealt with in the next section.

 

Getting in Deeper: Advanced Techniques

That’s the basics of zscripting wrapped up. Now move on to the next page: Advanced Techniques