The ZScript commands are mixed in with regular text, and they're all placed within square brackets.

Even though they're simple to create, there are over 180 commands, so there is virtually no limit to the ZScripted features you can invent. Some of these commands are very easy to understand, a few might take some practice to get used to.

Whenever you load or reload a ZScript text file, ZBrush automatically copies it to an optimized version (a '.zsc' file) which runs more efficiently and can't be read or modified using a text editor. If a PSD image file with the same name exists in the same folder, the image becomes embedded into the .zsc file as the file's icon. Also, any ZBrush or ZScript features which load image files can interpret this embedded data from the .zsc file.

To help you digest the commands, I've broken them up into categories. For an alphabetical list linking to the commands, you can view the Index at the bottom of this page. Also, within ZBrush, you can press the "CMD" button in the ZScript:Modifiers palette to view this entire list, with explanations, alphabetized.

You don't need to worry about upper/lowercase when writing ZScript commands. [PenMoveDown] is the same as [penmovedown] or [pEnMOvedOWn].

In this reference guide, I've used some special markers to cross-reference the commands; here's what my special markers mean:

Tip: There is a shorthand way to assign color to your text, using HTML-style colors, if you're familiar with them (ffffff = white, 000000 = black, ff0000 = red, etc.). Use the special characters \C, followed by the six-letter color. For example:

\Cff0000This text is red.\Ca0a0a0

makes your text red. The default text-flow color is a0a0a0.

This tip also applies to changing the color of text within Notes.

Note: the Pen is the invisible tool that is "writing" everything in the ZScript window. When you change the position or color of the Pen, you're changing the starting point or color of the displayed items that come afterward.

Here are the Property Indexes you can use, their meanings and possible values:

0 = Font Size (can be 1 = small, 2 = medium or 3 = large)
1 = Alignment (0 for Center, 1 for Left, 2 for Right)
2 = Intensity (0 = no intensity, 1 = full intensity, .5 = half intensity, any decimal inbetween)
3 = Text Color (Red X 65536 + Green X 256 + Blue, see RGB)
4 = Rectangular Border Size (Number of pixels surrounding text)
5 = Gradient Color 1 (Red X 65536 + Green X 256 + Blue, see RGB)
6 = Gradient Type (0 = none, 1 = horizontal, 2 = vertical, 3 = double horizontal, 4 = double vertical)
7 = Gradient Color 2 (Red X 65536 + Green X 256 + Blue, see RGB)

You don't need to issue this command before displaying a Caption, SubTitle or Title -- they have default attributes built into them. To change the attributes, issue this command as many times as needed. This command only affects Captions, SubTitles and Titles appearing later in the ZScript. Example:

[PropertySet, Title, 0, 2]   (font size)
[PropertySet, Title, 1, 0]   (alignment)
[PropertySet, Title, 2, .5]   (intensity)
[PropertySet, Title, 3, [RGB,0,0,0]]   (text color)
[PropertySet, Title, 4, 3]   (border size)
[PropertySet, Title, 5, [RGB,255,255,255]]   (gradient color 1)
[PropertySet, Title, 6, 1]   (gradient type)
[PropertySet, Title, 7, [RGB,0,0,0]]   (gradient color 2)

sets all Titles appearing thereafter to appear as medium-sized text, centered, half-intensity, in a box that blends from white to black horizontally.

Tip: Sections are unique ways to break up the text in your ZScript window. They are displayed as clickable buttons that "expand", when clicked, to reveal everything through the SectionEnd command.

Tip: use TextCalcWidth to make buttons fit neatly underneath text.
Example:

Hello There
[IButton,Button,,,,[TextCalcWidth,"Hello There"]]

See IButton.

Note: This, and all other "Button..." commands, only perform one action at a time. To create a button that performs several commands when you click it, use IButton.

Tip: The Interface item path can locate another ZScript button. As you'd expect, you can use the name of the button, or its popup text, to reference it. For example, suppose there's another ZScript button labeled "Click Me" with a popup of "Click This Button". You could locate that button either of these two ways:

[ButtonFind,ZScript:Click Me, ... ]
[ButtonFind,ZScript:Click This Button, ... ]

There is a third way: use a number that tells ZBrush how far away that button is from the current button. That is, to locate the next button in the ZScript, use the number 1. to locate the previous button, use the number -1. To locate the button after the next button, use the number 2, and so on. For example:

[ButtonFind,1, ... ]

locates the next button, slider or switch. The number 0 means "this button". Maximum allowable values are -99 to 99.

This also works for any other command which locates interface items, like the Note and IPress commands.

See IKeyPress for an explanation of how to specify the HotKey.

The button width is expressed in pixels, unless the button is located inside an ISubPalette. In that case it's a fraction of the palette's width, from 0 (no width) to 1 (full width).

The SubPalette name should be the path to the enclosing palette plus the new name. For example:

[ISubPalette,ZPlugin:MySubPalette]

creates a subpalette in the ZPlugin palette.

Note that a subpalette is created only if another interface item is created within it. So the above example would produce a subpalette if followed by an IButton, ISwitch, or something like it, i.e.:

[ISubPalette,ZPlugin:MySubPalette]
[IButton,"ZPlugin:MySubPalette:Sample Button", "This is a sample button", [Note,"You pressed the sample button."]]

Remember to enclose the subpalette's name, or item's name, in quotes if you intend to include spaces within it.

The inset values are expressed in pixels.

Tip: Insert a hard line break into the Message by typing the special characters \n .

See FontSetColor for an explanation of changing text color within a Note.

If the path to an item is specified, the note is displayed with a pointer indicating that item. By default an orange rectangle is drawn around the borders of the item. This rectangle can be adjusted using the Frame horizontal size, Frame vertical size, Frame left side and Frame top. This is especially useful for pointing out items on the canvas (Item ID number 1004). Each value is expressed as a fraction of the item's width/height. If Marked windows fill color is specified, this rectangle is filled with a translucent color.

NoteIButton enables you to define clickable buttons within Notes. It also provides a versatile means of laying out text and images, even if they're not clickable (Initially disabled set to 1). The NoteIButton commands precede the Note command in which they're intended to appear.

Clicking a NoteIButton closes the Note. By placing the NoteIButtons and Note command in a Loop, and changing text or other values, it can appear that NoteIButtons are acting as switches (see also the NoteISwitch command).

By default, buttons are centered and fall at the bottom of the Note, beneath the Note text. The button's position can be specified using these special rules:

Setting H relative position to 0 centers horizontally; setting to a positive number N places its left edge N pixels from the left side of the Note; setting to a negative number -N places its right edge N pixels from the right side of the Note.

Setting V relative position is similar: 0 places it near the bottom; positive N places its top edge N pixels from the top of the Note; negative -N places its bottom edge N pixels from the bottom of the Note.

The Button Text can be the name of an existing memory block. In this case, the text displayed is the contents of the memory block (as long as the memory block already contains data by the time of this command's execution).

When placing a number of buttons in a Note, it's often a good idea to first create an invisible NoteIButton that is invisible and disabled, with the desired width and height of the entire Note. For example, if you wish to display a Note that's 500x350, the first NoteIButton should look like this:

[NoteIButton,,,0,1,1,1,500,350,,,0,0,0]

If you intend to display text using NoteIButtons, positioning is often easier if the enclosing Note's text is left empty.

To determine which NoteIButton has been clicked, set a variable to the Note command which encloses it. A value of 0 means the user pressed the Enter key instead of clicking any buttons. Higher numbers correspond to the NoteIButtons in the order of definition, whether disabled or not. For example:

[NoteIButton,,,0,1,1,1,500,350,,,0,0,0]
[NoteIButton,"First Choice",,0,0,4]
[NoteIButton,,"image.psd",0,1,4,2]
[NoteIButton,"Second Choice",,0,0,-4]
[VarSet,NoteResult,[Note,""]]

The value of NoteResult is 2 if the First Choice is selected, and 4 if the Second Choice is selected. The first and third buttons are not clickable but are counted when determining the output value.

NoteISwitch enables you to define clickable switches within Notes. When clicked, they toggle on and off, without exiting the Note.

The value of a NoteISwitch can be retrieved using NoteIGet.

The progress bar, located just above the canvas, is cleared from time to time, but you can clear it immediately by issuing a NoteBar with empty quotes ("") as the Message.

The Progress-bar value yields a "thermometer" effect giving the user an indication of an action's progress. This is especially useful in loops:

[Loop,100,
[NoteBar,"Processing...",IndexCount/100]
[some commands...
,IndexCount]

Tip: You can use this inside an [If... command to give the user a choice. Example:

[If,[MessageOKCancel,"Are You Sure?","Warning"],
[commands if OK ],
[commands if Canceled ]
]

The same is true of MessageYesNo and MessageYesNoCancel. See the If command.

Note: you can perform one click, or one click with up to seven drags, like a mini-stroke. This is perfect for placing a 3D object on the canvas -- once it's selected, you can click once in the middle of the canvas, and drag downward. Example:

[IPress,Tool:Sphere3D]
[CanvasClick,320,240,320,340]

Note: Good for creating splashy moving displays in the ZBrush window. Caution: if you use CanvasGyroHide more than once, you'll have to issue a CanvasGyroShow command that many times before it'll show again (until the ZScript finishes running, or is aborted).

Note: StrokeData can be a filename, or can be copied & pasted from a Stroke file. To create a Stroke file, press the "Export Last" button in the Stroke:Inventory palette.

Here are some options for the CanvasStroke command:

[CanvasStroke, (ZObjStrokeV02n5=YH9FV7CPXHA1V7FHA7V84HAFV8AHB7V90)]
[CanvasStroke,[StrokeLoad,[Brushstroke.txt]]]
[CanvasStroke,[StrokeGetLast]]

CanvasStroke can only draw one brushstroke, from the mouse/tablet click to its release. To draw multiple brushstrokes, use CanvasStrokes. See StrokeLoad, StrokeGetLast.

Note: Similar to CanvasStroke, with multiple brushstrokes. To create a Strokes file, first press the "Record" button in the ZScript:Inventory palette, then draw the brushstrokes, then press "Export All".

Component Index can be 0 through 8:
0 = CompositeColor (red*65536+green*256+blue)
1 = Z (-32576 to 32576)
2 = Red(0 to 255 )
3 = Green(0 to 255 )
4 = Blue(0 to 255)
5 = Material ItemInfo
6 = Horiz. Normal (orientation information)
7 = Vert. Normal
8 = Z Normal

Info Number can be 0 through 9:
0 = Total Number of Points
1 = Indexed H Position
2 = Indexed V Position
3 = Indexed Pressure
4 = Minimum H Position Overall
5 = Minimum V Position Overall
6 = Maximum H Position Overall
7 = Maximum V Position Overall
8 = Maximum Radius
9 = Index of Point at Maximum Radius
10 = Maximum Horizontal Distance Traveled
11 = Maximum Vertical Distance Traveled
12 = Total Distance
13 = Twirl Count
14 = Indexed Z (deduced)
15 = Indexed Key Press

The Point Index is the sequential number of the point you wish to study. A Point Index of 0 means the first point in the stroke. Supply a Point Index only if Info Number is "Indexed", that is 1, 2, 3, 14 or 15.

Note: StrokeGetInfo only works on a single stroke, created by pressing "Export Last" in the "Stroke:Inventory" palette, by using StrokeGetLast, or by loading from a file with StrokeLoad.

Example:

[StrokeGetInfo,[StrokeGetLast],0]

gives you the total number of points in the last stroke drawn.

Note: These nine transformation values are displayed in the Transform:Info sliders when the "Move", "Resize", and "Rotate" buttons are pressed. Replace each of the components with variable names to place these values into the variables.

See ButtonFind for notes on locating other ZScript buttons, sliders and switches.

Note: When you record ZScripts, you are asked if you'd like to reset the interface ([IReset,0]). This is because the result of running a ZScript can be unpredictable unless you're sure ZBrush settings are the same each time it is run.

This means all customized tools, materials or stencils are deleted if the appropriate palette is reset, and the document is wiped clean.

You can use IReset inside an [If... statement in the same way as you'd use one of the Message... commands. See MessageOKCancel.

Note: This is useful for manipulating ZCurves, like the ones inside Material modifiers.

Note: In the section Creating Clickable Buttons and Sliders, notice that each command has an option listed as "Initially Disabled?". A value greater than zero in this position means the button is disabled until you enable it with IEnable.

Note: When doesn't an interface item exist? For instance, when a 3D object is selected in the Tool palette, the sliders in the Tool:Modifiers:Deformation sub-palette exist. However, they don't exist when a painting tool (such as SimpeBrush) is selected.

You can control whether actions are shown for certain blocks of ZScript code, regardless of the status of the ZScript:Show Actions button. Setting Show Actions? to 0 turns it off; setting to a positive number turns it on, and setting to a negative number resets to the status of the Show Actions button.

IShowActions is especially useful when building tutorial ZScripts. You may perform a series of actions which might confuse novice users or distract from the central point of the tutorial, and this provides a way of suppressing highlighting and animation during playback.

An added bonus to freezing the interface is that the process executes more quickly.

Tip: While the interface is frozen, ZBrush still displays information using the NoteBar command. Thus you can provide a 'thermometer' indicating the operation's progress.

IUpdate refreshes the ZBrush interface while within an IFreeze commands group.

The Modifiers in ZBrush 1.23b are the tiny X, Y and Z buttons in the Tool:Modifiers:Deformation sliders when a 3D object is selected. IModGet returns the following values when these modifiers are pressed:

0 = (all off)
1 = X
2 = Y
3 = X+Y
4 = Z
5 = X+Z
6 = Y+Z
7 = X+Y+Z

Use these values to set the appropriate modifiers with IModSet.

See IModGet.

IHeight is good for checking if a palette is expanded, collapsed, in novice mode or in expert mode.

If Global coordinates is blank or set to 0, the value represents the horizontal postion relative to the left edge of the canvas. If the interface item is to the left of the canvas, the value will be negative. Otherwise, the value is the position from the left of the ZBrush window (normally the left edge of your monitor).

Certain interface items display useful information in the "secondary" portion of the popup window. For example, 3D tools display information about point and polygon counts, among other things.

Using this command, you can customize hotkeys for any interface item. The value of Hotkey should be an ASCII value or keyboard number, which can be determined using the Preferences:Utilities:View Keyboard Status slider.

Examples:

[IKeyPress, 'N', ... ]
[IKeyPress, ALT, ... ]
[IKeyPress, ALT+'N', ... ]
[IKeyPress, ALT+SHIFT+'N', ... ]

Tip: Useful for simulating an ALT key press while drawing in the canvas area with CanvasStrokes. The 'key to press' can be a number representing certain characters (the ASCII number, if you're familiar with the term). For an Enter key, the number is 13, for a Spacebar, the number is 32. The same is true for any commands which can have a HotKey assigned to them, like IButton.

This makes IKeyPress useful for bringing up the coin controller when the Stencil is active:

[IKeyPress,32,[some actions ],320,240]

IKeyPress can also be used to suppress a message that usually comes up when a certain action is performed:

[IKeyPress,13,[IPress,Layer:Inventory:MRG]]

merges layers without bringing up the usual confirmation dialog box.

IGetFlag's output is a single number which is the sum of all set flag bits. This is a useful way to get information about an interface item which might otherwise be difficult to find. Values for any iterface item can be determined by experimenting.

For example, you can determine if a light switch is pressed and/or turned on. Here are samples for the first light switch (interface item number 1556)

[IGetFlags,1556] returns:
11 if the light is selected and turned on
9 if the light is not selected but turned on
10 if the light is selected but not turned on
8 if the light is not selected nor turned on

If you think of an imaginary crosshairs fixed in the center of the document window, CanvasPanGetH and CanvasPanGetV return the coordinates of the pixol which falls under the crosshairs. When the canvas is panned all the way to the right and down, these commands return 0 (h) and 0 (v).

H value and V value are set to the coordinates of the pixol which will fall in the center of the window. Thus a 640x480 canvas can be centered by entering

[CanvasPanSet,320,240]

The left- and topmost pixol in the canvas is 0,0.

A zoom value of 1 indicates the canvas is being viewed at actual size. A smaller value indicates the canvas is zoomed out, and a larger value indicates the canvas is zoomed in.

The info type can be:

0: The ZBrush version number
1: Demo/Beta/Commercial version (returns 0 for demo, 1 for beta, 2 for commercial)
2: Runtime in seconds (including millisecond fractions)
3: Memory usage
4: VMemory usage
5: Free Memory
6: Operating system (0=PC, 1=Mac, 2=MacOSX)
7: Unique session ID (useful for determining if the user has restarted ZBrush)
8: Total RAM

The priority can be:

0: Normal
1: A little more
2: Much more
-1: A little less
-2: Much less

This command is ignored on Mac filesystems.

See ZBrushPrioritySet for a description of this command's numeric values.

You cannot set MouseHPos or MouseVPos to other values. However, you can emulate a key press at a specific horizontal and vertical position, by using IKeyPress.

Tip: Load or import an item into a palette by setting a filename, then pressing the appropriate button. For example, to import a texture (making sure the texture is in the same folder as the ZScript first):

[FileNameSetNext,MyTexture.bmp]
[IPress,Texture:Inventory:Import]

This imports the texture named 'MyTexture.bmp', without showing a dialog box to the user. If you later wish to show a dialog box to the user when such a button is pressed, use [FileNameSetNext,""].

Tip: Get more than one of these components by adding specifiers together. For example, to extract both the name and extension, use [FileNameExtract, FileName, 6]

Given a simple file name which exists in the same folder as your ZScript, FileNameResolvePath returns the full system path to the file. Using string-manipulation commands, you can extract parts of the path to use in other operations.

You can also specify nested folders within the current folder, such as "images/filename.ext".

To refer to paths starting at the "root" ZBrush directory, use "ZBRUSH_folder/subfolder...". For example, referring to a file called "MyZScript.txt" in the ZScripts folder would read

[FileNameResolvePath, "ZBRUSH_ZScripts/MyZScript.txt"]

VarSave stores a varaiable's data for later loading using VarLoad. It's a good way to store a user's preferences, for example.

If you intend to read the saved file in another program (such as a text editor), it's better to define a Memory Block and use MemSaveToFile.

FileExecute provides a way to call plugin library files. The types of input, output and result values are defined by the library files themselves.

An example of a library file which is included by default in ZBrush's release is WebZPlug.dll, responsible for opening a webpage from a ZScript. Here's an example which shows how you might open the user's default browser to access ZBrushCentral:

[FileExecute,"ZBRUSH_ZData\ZPlugs\WebZPlug.dll",HTTP_Browse,"http://www.zbrushcentral.com"]

To avoid errors when calling, it's good practice to first ensure the library file exists, using FileExists.