ZBrushCentral

ZScript Lesson I: IButtons and Formatting

<font color="#ffa000" size=“3”>Welcome to ZScripts 101!</font>

You’re on your way to harnessing the awesome power of ZScripts. In many ways, ZScripts resemble complex computer programming languages – but you don’t have to be a programmer to take advantage of them. All you need is ZBrush v1.23b or later, a text editor, and an imagination.

Some notes about this ZScript lesson:

Perhaps you’ve opened some of the ZScripts included with ZBrush, and become overwhelmed by the technological, codelike nature of the ZScript commands. In these lessons I’m hoping to de-mystify them – if you finish today’s lesson and you’re still as confused as ever, I haven’t done my job.

I can appreciate that each of you has a different level of computer experience; some of you are well familiar with other computer codes and languages (such as HTML, JavaScript, Commodore 64 Basic :wink: ). Others have only recently learned how to turn on a computer. It’s a challenging task, but I’ll try to make these lessons easy enough for novice users to follow, yet instructive enough for advanced users.

Before following this lesson, you should:

      :white_small_square: have a pretty fair knowledge of how ZBrush works
      :white_small_square: familiarize yourself with the basic structure of ZScripts -- I highly recommend reading the Composition page of the tutorial "[Creating ZScript Tutorials](http://pixologic.com/index.cgi?go&download/creating_zscripts/cz-composition.html)".

You’ll want to bookmark this link: ZScript Command Reference. It’s got all the ZScript commands categorized by function, with lots of helpful notes and tips.
<font color="#ffa000">Novice Users:</font> Don’t feel you need to understand everything you read in the ZScript Command Reference. For now, browse the categories, so you get a good idea of what kinds of tasks are possible in the ZScript command set.
<font color="#ffa000">Advanced Users:</font> If you’ve been tinkering with your own ZScripts, or you’re too impatient to wade through this lesson, there’s lots of useful information in the ZScript Command Reference to help you write your own. As needed, you can return to the Reference and browse through the Index for tips on accomplishing various tasks.

<hr>

      [img]/images/lessons/01_final.jpg[/img]          

In this lesson, you’ll create the ZScript shown above. Each button selects a color; if there is an active 3D object in Edit mode, each button also creates a new texture filled with that color. Then you’ll learn some of the display/formatting commands that give your ZScript some visual appeal.

<font color="#ffa000" size=“3”>1) Examining the IButton Command</font>
In this section you’ll become familiar with the IButton command, the real workhorse of any ZScript. If you’re already familiar with the IButton command, you can skip to section 2.

First, examine the IButton command. The IButton command can be given several pieces of information (called arguments) separated by commas. Not all arguments need to be typed; if they’re missing, ZBrush assumes each argument has a certain (default) value.

<blockquote> </blockquote>

In this example, each argument is displayed with a different color so you can tell them apart. Also, in this and other examples in this lesson, each argument is placed on a separate line, with some of the lines indented. Again, this is just done to avoid confusion; you may choose to structure the text in your ZScripts differently.

The reason ZBrush knows which argument is which is that they’re separated by commas. Here’s a typical way you might type the IButton command:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Select the SimpleBrush”,“This button selects the Simple Brush”,
[IPress,Tool:SimpleBrush]
]
</font></td></tr></table></blockquote>
This button looks like this:

If you float your cursor over the button, the popup appears:

… and if you click this button, the command [IPress,Tool:SimpleBrush] is executed, meaning the SimpleBrush is selected in the Tool palette.

But what about the last three arguments? You can leave them out completely, and ZBrush assumes you want to have certain default values assigned. If you’re curious, here are the default values:

Initially Disabled? = No.
Button Width = A little wider than the Button Text.
Hotkey = no hotkey.

If you want to provide one argument, but not the arguments before it, simply type enough commas to separate them. For instance, suppose you want to assign the hotkey ‘B’ to this button:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Select the SimpleBrush”,“This button selects the Simple Brush”,
[IPress,Tool:SimpleBrush]
, , , ‘B’
]
</font></td></tr></table></blockquote>
<hr><font color="#ffa000" size=“3”>2) The IColorSet Command</font>
In this section, you’ll create a button that changes the ZBrush Main Color.

The ZScript command that changes the ZBrush main color is IColorSet. The way it’s written is
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IColorSet, red, green, blue]</font></td></tr></table></blockquote>
To set the color, simply replace IColorSet’s arguments with the red, green and blue components of the color. These can be determined by picking your color in ZBrush’s Color palette, and reading the R, G and B sliders.

Let’s start with a red that is R=255, G=0, B=0:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IColorSet, 255, 0, 0]</font></td></tr></table></blockquote>
Place the command inside an IButton:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
]
</font></td></tr></table></blockquote>
Now you have a working button that changes the ZBrush main color to red. To add a finishing touch, set a HotKey for this button – let’s make it SHIFT+ALT+‘R’ for ‘Red’ – so whenever you press the HotKey, the color changes to Red.
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
, , , SHIFT+ALT+‘R’
]
</font></td></tr></table></blockquote>
(Note to Mac users: the ALT key and OPT key can be used interchangeably).

<hr>
<font color="#ffa000" size=“3”>3) The If, IGet and IPress Commands</font>
Here’s the plan for this section: Check if there’s an active 3D object in Edit mode. If there is, press the New button in the Texture:Inventory palette:

How do you check if there’s an active object in Edit mode? The easiest way is to check if the Edit Object button, in the Transform palette, is pressed:

The IGet command checks any ZBrush interface item. If the interface item is a slider, IGet yields the numeric setting of the slider; if it’s a button, IGet yields 1 if it’s pressed, 0 if it’s unpressed.

The IGet command is written like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IGet,Interface Item Path]</font></td></tr></table></blockquote>
Substitute the Edit Object button path:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IGet,Transform:Edit Object]</font></td></tr></table></blockquote>
If this equals 1, you know the Edit Object button is pressed. But what do you do with that information? You need to execute one set of commands if the Edit Object button is pressed, another if it’s not pressed.

That’s where the If command comes in. The If command is written like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[If, something is true or false ,
commands to execute if true… ,
commands to execute if false…
]
</font></td></tr></table></blockquote>
In this case, you don’t want to do anything if the Edit Mode button is unpressed. So the third argument, the commands to execute if false, will be empty.

To press a button, use the IPress command. The IPress command is simply written
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IPress,Interface Item Path]</font></td></tr></table></blockquote>
So put these three elements together. In plain English, you’d say, “If the Edit Button is pressed (equals 1), press the New Texture button.” In ZScript-ese, you’d say
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
</font></td></tr></table></blockquote>
Put this inside the button you created earlier, and you get:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,SHIFT+ALT+‘R’
]
</font></td></tr></table></blockquote>
Now that you have a Red button, copy and paste the whole IButton, to create a Yellow, Green and Blue button. Of course, you’ll want to put different arguments into the different IColorSet commands, as well as change the names of the buttons and the hotkeys.

When you’re finished, try out your ZScript – save it as “MyZScript.txt”, and load it into ZBrush (using the ZScript:Inventory:Load button). It should look like this:

<hr>
<font color="#ffa000" size=“3”>4) Creating the Graphics</font>
Use ZBrush to create the individual box graphics for the ZScript.

Start with a blank black canvas. Select a Cube3D, change the color to white, and select the Bumpy Metal material. Draw it anywhere on the canvas, press the Transform:Rotate button, and hold the Shift key while dragging inside the Canvas Gyro to make it perfectly level:

Press the Transform:Scale button, and open the Transform:Info sub-palette. In each of the sliders, type 40:

The number 40 means that from the center of the cube to each of the sides, the distance is 40 pixels. That means this cube has a width and height of 80 pixels.

Mark it (Transform:Mark).

Now, select a Sphere3D. Change the color to red, and press the Draw:ZSUB button. Draw the sphere on top of the cube, using the marker for placement:

Now, select the MRGBZGrabber, and make sure Shaded RGB and Auto Crop are pressed:

Grab it by clicking inside and dragging so the white rectangle completely surrounds the box:

Your Texture palette should now look like this:

Now, press Undo to remove the red sphere, change the color to Yellow, and draw another sphere. Grab it and do the same for Green and Blue.

You’ve created all four graphics needed for your ZScript. Select each in the Texture Palette. Notice that the Texture:Inventory sub-palette tells you each graphic’s width and height:

Select each texture, and export each by pressing the Texture:Inventory:Export button. Name the files ‘RedBox.psd’, ‘YellowBox.psd’, ‘GreenBox.psd’ and ‘BlueBox.psd’, and be sure to save each image in the same folder as your ZScript resides.

<font color="#ffa000">Note for Demo users:</font> You can’t Export from the Demo version, so here are the four graphic files for download. Right-click to download each file:
RedBox.psd
YellowBox.psd
GreenBox.psd
BlueBox.psd

The box graphics are now ready to display in your ZScript.

<hr>
<font color="#ffa000" size=“3”>5) Formatting the ZScript</font>
First, you’ll want to display the box graphics you just created inside your ZScript. The command for displaying images is
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[Image, Filename,
Alignment (0=center, 1=left, 2=right),
Resized width
]
</font></td></tr></table></blockquote>
For this lesson, you’ll want to left-align the images, and you won’t need to resize them (omit the third argument). So beginning with the red box, the command looks like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[Image, RedBox.psd,
1
]
</font></td></tr></table></blockquote>
The ‘1’ looks a little funny floating on it’s own, so why not put everything on one line?
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[Image, RedBox.psd,1]</font></td></tr></table></blockquote>
When formatting your ZScripts, it’s helpful to think of an invisible “pen” that “writes” every item in the ZScript window. For the Image command, the “pen” displays the image, then moves to the top right edge of the image.

This means, to set the box graphics next to each other, you only need to repeat the Image command once for each box, one command appearing after another:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[Image, RedBox.psd,1]
[Image, YellowBox.psd,1]
[Image, GreenBox.psd,1]
[Image, BlueBox.psd,1]
</font></td></tr></table></blockquote>
After the “pen” has displayed all four images, ask yourself, where is the “pen” now? It’s at the top right edge of the blue box:

Notice something interesting: The black background from the ZBrush canvas doesn’t appear where the corners of the boxes are. That’s because, in any image you display in the ZScript window, if the upper-leftmost pixel is solid black (color red=0, green=0, blue=0), any black pixel becomes transparent. If you want to display a black color, simply paint the upper-leftmost pixel with an almost-black color, say red=1,green=1,blue=1.

Now, where to put the IButtons you created earlier?

You’ll want to move the “pen” down 80 pixels, because the height of each box is 80 pixels. You’ll also want to move the pen to the left edge of the page, because that’s where all four boxes start.

The convenient command for moving the “pen” to the left edge of the page is
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PenMoveLeft]</font></td></tr></table></blockquote>
… and it has no arguments at all.

The command for moving the “pen” a certain number of pixels is
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PenMove,
horizontal distance ,
vertical distance
]
</font></td></tr></table></blockquote>
Since PenMoveLeft takes care of our horizontal placement, you can omit the first argument, and use PenMove to move the “pen” down 80 pixels. Putting the two together, it looks like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PenMoveLeft]
[PenMove,80]
</font></td></tr></table></blockquote>
What if you wanted to move the “pen” up instead of down? You’d type -80 instead of 80. Any negative number means “move up”, any positive number means “move down”. For horizontal movement, a negative number means “move left”, and a positive number means “move right”.

After the pen movements, place the four buttons you created. Your ZScript now looks like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[Image, RedBox.psd,1]
[Image, YellowBox.psd,1]
[Image, GreenBox.psd,1]
[Image, BlueBox.psd,1]

[PenMoveLeft]
[PenMove,80]

[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,SHIFT+ALT+‘R’
]
[IButton,“Yellow”,“Pick a Yellow Color”,
[IColorSet, 255, 255, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,SHIFT+ALT+‘Y’
]
[IButton,“Green”,“Pick a Green Color”,
[IColorSet, 0, 255, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,SHIFT+ALT+‘G’
]
[IButton,“Blue”,“Pick a Blue Color”,
[IColorSet, 0, 0, 255]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,SHIFT+ALT+‘B’
]</font></td></tr></table></blockquote>

If you load it into ZBrush, it looks like this:

Uh-oh. The buttons aren’t aligned with the graphics. What now?

Remember that the IButton command has an argument that sets the ButtonWidth. It’s the argument right before the HotKey.

Since you know that each box graphic has a width of 80, you can set the width of each IButton to match. For example, edit the Red button to look like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,80,SHIFT+ALT+‘R’
]
</font></td></tr></table></blockquote>
Do the same for the other three buttons, and they should align perfectly.

One more thing: why not center the whole ZScript in the ZScript window? You could go through the tedious task of moving the “pen” to the center, moving to the left a certain number of pixels, etc. But the easier way is to use the PageSetWidth command:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PageSetWidth, Preferred Width]</font></td></tr></table></blockquote>
PageSetWidth not only sets the width of the page, it moves the left and right margins inward so the whole page is centered in the window.

So how wide should the page be? Are you going to have to dig the calculator out of the desk drawer? No. ZBrush can do the math for you.

Instead of entering a number for the Preferred Width, you’re going to enter a numeric expression. This tells ZBrush how to calculate a number, and you don’t have to know the answer yourself.

You know the width of each button (80) and you know there are four buttons. So you need to tell ZBrush that the Page Width is 4 times 80. Just to give ZBrush a little breathing room, add one more pixel. In ZScript-ese that’s:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PageSetWidth, 4*80+1]</font></td></tr></table></blockquote>

FYI, the add, subtract, multiply and divide symbols are: + (plus sign, add), - (hyphen, subtract), * (asterisk, multiply), / (slash, divide).

Place the PageSetWidth command at the top of your ZScript. You’re done!

The final ZScript looks like this:
<blockquote><table border=“0” cellpadding=“6” cellspacing=“0” bgcolor="#cccccc"><tr><td bgcolor="#cccccc"><font color=“black” size=“2”>[PageSetWidth, 4*80+1]

[Image, RedBox.psd,1]
[Image, YellowBox.psd,1]
[Image, GreenBox.psd,1]
[Image, BlueBox.psd,1]

[PenMoveLeft]
[PenMove,80]

[IButton,“Red”,“Pick a Red Color”,
[IColorSet, 255, 0, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,80,SHIFT+ALT+‘R’
]
[IButton,“Yellow”,“Pick a Yellow Color”,
[IColorSet, 255, 255, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,80,SHIFT+ALT+‘Y’
]
[IButton,“Green”,“Pick a Green Color”,
[IColorSet, 0, 255, 0]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,80,SHIFT+ALT+‘G’
]
[IButton,“Blue”,“Pick a Blue Color”,
[IColorSet, 0, 0, 255]
[If, [IGet,Transform:Edit Object] = 1 ,
[IPress,Texture:Inventory:New]
]
,80,SHIFT+ALT+‘B’
]</font></td></tr></table></blockquote>

<hr>
<font color="#ffa000" size=“3”>Exercises</font>
To get a little more practice, try these challenges on your own:

      :white_small_square: Create a button that sets the color to its Color-Wheel Complement (the color on the opposite side of the color wheel). Hint: a color's complement can be determined by taking the red, blue, and green components and subtracting each from 255.

      :white_small_square: Create a painter's palette with different color swatches located on it. Here's a blank palette to get you started:
      [img]/images/lessons/01_blank_palette.jpg[/img]           [Right-click here to download the PSD file.](http://pixolator.com/images/lessons/01_blank_palette.psd)

Hint: You can display one image, then use PenMove commands to move on top of it, and display another image.

Feel free to post your results in this thread.

Happy ZScripting!
dave

<hr>
Next lessons: Lesson II: ISliders
Lesson III: CanvasStroke and Loops
Lesson IV: TransformSet and CanvasClick

Man, I’ve been waiting for this thread for ages!! You must of worn your fingers to the bone writing all this and the Pixologic webpages!
Thanks Davey! :+1: :+1:
Gotta hit the ZScript books! Study study!
Upham :slight_smile:

Well done! The Zscript Bible to happiness

I’ll be burning some paper in the ole printer

Awsome job Davey! You have taught me two very-good-to-know-things, the PageSetWidth and that a ZScript doesn’t mind you making it figure out what a number is by using the +,-,*, and / commands. Thank you!!! :slight_smile:

Rock on! PageSetWidth was exactly what I’ve been wanting to know.

Thank you for taking the time to put this together. It’s very clear, and I can’t imagine it giving anyone difficulty. :+1:

Thank Davey i just woke up scaning threw some post im wonder do you offer (onMouseOver) or Blinking or skrolling text inside the buttons.
and just a thought what about setting up another forum by it self like the make a wish section?
that way it would be better focused on the subject and not mixed in here with all the picture’s.
you know i will be over there every day :+1:
thanks for posting the I.N.F.O.
and i Think if you offered .GIF in the tutorial veiw window you could make some cool button as a clickable image…

Hey is there anyway to make a button a (image) it self instead of the Text.
some thing like this [IButton,"IMG SRC=“Click.BMP”

Thanks Davey,
You’ve just made me want to learn zscript.
In fact I started my first script today. Nothing like trying to fly after you’ve just started to crawl.
Caio
john :slight_smile:

Thanks Davey, I,m going to try and get my none technical head into a technical mode.
Dave

Fabulous work this tutorial, :eek: well explained and even usefull for me as a DemoUser.
Thanx a lot and keep on gooing :slight_smile:

Sascha

Thanks for the tutorial and an idea just came to me. I created a ZScript folder on my PocketPC and will save the ZScript command reference to my PocketPC as well and then I can work on ZScripts on the go! :slight_smile:

I’m looking forward to more upcoming lessons.

:+1:

I’d be interested in seeing scripts demonstrating the use of math functions to generate images (tan, cosin, sin, abs, etc.) and the uses of the pixolpick command.

Hey Winged one…SNAP…

I wrote some of my QUICK-DEFORMER on my HP JORNADA…Really hard but really cool!!!

Glen

…and I have the command reference and Daveys tuts saved on my Compact Flash card (Along with the latest Steriophonics album in MP3)

I’d like to second WingedOne on “seeing scripts demonstrating the use of math functions to generate images (tan, cosin, sin, abs, etc.) and the uses of the pixolpick command.”

Hi
I’m trying to learn ZScripting and as this thread is seems to be the main source for learning that (correct me if I’m wrong) I think it will be good if it could be refreshed so the pictures which were here before appear here again.
btw, the other chapters needs that refresh also.
or, am I dumb and there is a new complete source that teach zscripting? (I’m not talking bout those command lists and I also know there are dosens of good threads about zscripting. it is the global and organized bible of zscripting that I seek.
anyone?

There is no definitive lesson collection for ZScripting though something like that is anticipated soon, along with the long-awaited SDK.

I saved out Davey’s four lessons before ZBCentral was redesigned last year, so here are the zipped versions of the .html files and the accompanying images.

Sven

cool sven…i had checked out these links about 6 or 7 months ago and was kind a disappointed the links to pics were broken but that was about when they were switching over, had siggraph to worry about plus the mac version so wasn’t going to gripe about the missing pics.

thanks for saving em and reposting em!!

It helped me a lot in my first steps in these zscripting field and here’s my “homework” (I did the first exercise that Davey gave us here).