Table of Contents

Introduction
Displaying/Formatting ZScript Window Items
Creating Clickable Buttons and Sliders
Displaying Messages
Painting and Working in the Canvas
Working With ZBrush and Its Interface
Reading the Mouse
Working With Files and Filenames
Calculations
Manipulating Variables
Manipulating Strings
Using Memory Blocks
Special 3D Tool Commands
Structuring the Flow
Index

Introduction
ZScripts are pretty simple to create -- all you have to do is type some stuff into a text file. Anything that doesn't fall within square brackets ( [ ] ) is simply displayed as regular text.

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:

Asterisk* Commands marked with an asterisk are "containers" for other groups of ZScript commands. You'll see some explanations that refer to "commands group to execute..."; these are the commands which can contain these commands groups.
Light Blue These are commands that stand alone in a ZScript; they cannot be placed inside "container" commands. They're sometimes called "Top Level commands".
Pink These are commands which can either be placed inside "container" commands, or stand alone in a ZScript.
No Color (white) These cannot stand alone, they must be placed inside "container" commands. If you place them outside of a "container", you'll get an error and your ZScript won't run. Sometimes called "Sub-Level commands".

Return to top

Displaying/Formatting ZScript Window Items
Caption [Caption,Text]
Displays a text line using the current Caption settings (can be changed by PropertySet)
SubTitle [SubTitle,Text]
Displays a text line using the current SubTitle settings (can be changed by PropertySet)
Title [Title,Text]
Displays a text line using the current Title settings (can be changed by PropertySet)
Image [Image,FileName (.psd .bmp + .pct for Mac Systems),Align (0=center 1=left 2=right),Resized Width]
Loads and displays an image
FontSetColor [FontSetColor,Red,Green,Blue]
Sets the color of the text-flow font

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.

FontSetOpacity [FontSetOpacity,Opacity]
Sets the opacity of the text-flow font. 1 = completely opaque, 0 = completely transparent. Half intensity is written as .5, quarter-intensity is written as .25, and so on.
FontSetSize [FontSetSize,Size: 1=Small 2=Med 3=Large]
Sets the size of the text-flow font
FontSetSizeLarge [FontSetSizeLarge]
Sets the size of the text-flow font to large (same as FontSetSize, 3)
FontSetSizeMedium [FontSetSizeMedium]
Sets the size of the text-flow font to medium (same as FontSetSize, 2)
FontSetSizeSmall [FontSetSizeSmall]
Sets the size of the text-flow font to small (same as FontSetSize, 1)
PaintBackground [PaintBackground,Red,Green,Blue]
Paints the ZScript window background using this color
PaintBackSliver [PaintBackSliver,height,Red,Green,Blue]
Draws a full page-width rectangle using this color
PaintPageBreak [PaintPageBreak]
Draws a visual page-break
PaintRect [PaintRect,Width,height,Red,Green,Blue]
Draws a rectangle using the current pen main color See PenSetColor.
PaintTextRect [PaintTextRect,Width,Height,Text]
Draws a rectangle with imbedded text
PenSetColor [PenSetColor,Red,Green,Blue]
Sets the pen main color

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.

BackColorSet [BackColorSet,Red,Green,Blue]
Sets the pen background color
PageSetWidth [PageSetWidth,Preferred PageWidth]
Sets the width of the page for all subsequently-displayed items. The size of the window does not change.
PenMoveCenter [PenMoveCenter]
Moves the pen position to the horizontal center of the page
PenMoveDown [PenMoveDown]
Moves the pen position to the beginning of the next line
PD [PD]
Moves the pen position to the beginning of the next line (Same as PenMoveDown)
PenMoveLeft [PenMoveLeft]
Moves the pen position to the left side of the page
PenMoveRight [PenMoveRight]
Moves the pen position to the right side of the page
PenMove [PenMove,Horizontal Offset,Vertical Offset]
Moves the pen a relative distance
PropertySet [PropertySet,The base command name (Title,SubTitle,Caption),Property Index,The new Value]
Modifies the setting of Title, SubTitle and Caption text

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.

SectionBegin* [SectionBegin,Section Title,Initial state (1=Expanded,0=Collapsed ),Popup Info Text,Commands group to execute when expanding to reveal content,Commands group to execute when collapsing to hide content,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Begins a collapsible section

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.

SectionEnd [SectionEnd]
Ends a collapsible section
TextCalcWidth [TextCalcWidth,The text to be evaluated]
Output: Width of text in pixels
Calculates the pixel-width of the specified string

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

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

See IButton.

HotKeyText [HotKeyText,Interface item path]
Displays a hot-key for the specified interface item

Return to top

Creating Clickable Buttons and Sliders
ButtonFind [ButtonFind,Interface item path,Button Text,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Creates a green button that simply locates a ZBrush interface item

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.

ButtonPress [ButtonPress,Interface item path,Button Text,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Creates a red button that locates and presses a ZBrush interface button
ButtonSet [ButtonSet,Interface item path,Value,Button Text,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Creates a red button that locates and sets a new value to a ZBrush slider
ButtonUnPress [ButtonUnPress,Interface item path,Button Text,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Creates a red button that locates and unpresses a ZBrush interface button
FrontColorSet [FrontColorSet,Description Text,Red,Green,Blue,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled)]
Creates a red button that sets the main interface color to a new value
IButton* [IButton,Button Text,Popup info Text,Commands group to execute when button is pressed,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled),Button width in pixels (0=AutoWidth NonZero=Specified width),Optional HotKey]
Creates an interactive red button that can perform numerous actions.

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).

ISlider* [ISlider,Slider Text,CurValue,Resolution,MinValue,MaxValue,Popup info Text,Commands group to execute when value is changed,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled),Button width in pixels (0=AutoWidth NonZero=Specified width)]
Creates an interactive slider
ISwitch* [ISwitch,Button Text,Initial state (1=pressed,0=unpressed),Popup info Text,Commands group to execute when button is pressed,Commands group to execute when button is unpressed,Initially Disabled? (0=Enabled(ByDefault) NonZero=Disabled),Button width in pixels (0=AutoWidth NonZero=Specified width)]
Creates an interactive switch
ISubPalette [ISubPalette, SubPalette name, Title mode, 8-bit grayscale icon filename, left inset, right inset, left top, right bottom]
Output: 1 if subpalette created successfully; 0 if it could not be added or already exists.
Creates a subpalette in a ZBrush palette

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.

IDialog This command is not currently functional and is intended for future expansion.

Return to top

Displaying Messages
Note [Note,Message,
Optional path of an interface item to be pointed out. (default=none),
Display Duration (in seconds) (zero=default=wait for user action, -1=combine with next note command),
Popup background color. (blue + (green*256) + (red*65536) ) (default=96+(96*256)+(96*65536)),
Preferred distance of the note from the specified interface item (default=48),
Preferred Note width (in pixels, default=400)
Optional marked windows fill color,
Frame horizontal size (1=default=item width),
Frame vertical size (1=default=item height),
Frame left side (0=default=left, .5=center, 1=right),
Frame top (0=default=top, .5=center, 1=bottom),
Optional icon file name]
Output: if the note has NoteIButtons, the index value of the button pressed, otherwise 0.
Displays a note to the user.

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 [NoteIButton, Button Text,
Optional button icon file name
Initially pressed? (default=0=unpressed)
Initially disabled? (default=0=enabled)
Button H relative position (default=0=centered)
Button V relative position (default=0=automatic near bottom)
Button width in pixels (default=0=automatic text width)
Button height in pixels (default=0=automatic text height)
Button color (red*65536 + green*256 + blue)
Text color (red*65536 + green*256 + blue)
Background opacity (0 to 1, default=1)
Text opacity (0 to 1, default=1)
Image opacity (0 to 1, default=1)]
Defines a clickable button, image or text region inside a Note.

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 [NoteISwitch, Switch Text,
Optional icon file name
Initially pressed? (default=0=unpressed)
Initially disabled? (default=0=enabled)
Switch H relative position (default=0=centered)
Switch V relative position (default=0=automatic near bottom)
Switch width in pixels (default=0=automatic text width)
Switch height in pixels (default=0=automatic text height)
Switch color (red*65536 + green*256 + blue)
Text color (red*65536 + green*256 + blue)
Background opacity (0 to 1, default=1)
Text opacity (0 to 1, default=1)
Image opacity (0 to 1, default=1)]
Defines a clickable switch inside a Note.

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.

NoteIGet [NoteIGet, Note-switch index (or name)]
Output: the note-switch status
Returns the status of a NoteISwitch shown in the last displayed Note.
NoteBar [NoteBar,Message,optional progress-bar value (0-1)]
Displays a message in the progress bar.

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]

MessageOK [MessageOK,The Message that will be shown,The Title of the message]
Displays a user message with a single OK button
MessageOKCancel [MessageOKCancel,The Message that will be shown,The Title of the message]
Output: Returns the button that the user clicked. (0=CANCEL, 1=OK)
Displays a user message with CANCEL and OK buttons

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.

MessageYesNo [MessageYesNo,The Message that will be shown,The Title of the message]
Output: Returns the button that the user clicked. (0=NO, 1=YES)
Displays a user message with YES and NO buttons
MessageYesNoCancel [MessageYesNoCancel,The Message that will be shown,The Title of the message]
Output: Returns the button that the user clicked. (0=NO, 1=YES CANCEL=-1)
Displays a user message with YES, NO and CANCEL buttons

Return to top

Painting and Working in the Canvas
CanvasClick [CanvasClick,X1,Y1,X2,Y2,X3,Y3,X4,Y4,X5,Y5,X6,Y6,X7,Y7,X8,Y8]
Emulates a click within the current canvas area

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]

CanvasGyroHide [CanvasGyroHide]
Hides the Transformation Gyro

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).

CanvasGyroShow [CanvasGyroShow]
Shows the Transformation Gyro
CanvasStroke [CanvasStroke,StrokeData,Delayed update until end of stroke,Rotation,HScale,VScale,HOffset,VOffset]
Emulates a brush stroke within the current canvas area

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.

CanvasStrokes [CanvasStrokes,StrokesData,Delayed update until end of stroke,Rotation,HScale,VScale,HOffset,VOffset,HRotateCenter,VRotateCenter]
Emulates multiple brush strokes within the current canvas area

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".

PixolPick [PixolPick,Component Index,H Position,V Position]
Output: The value of the specified Pixol
Retrieves information about a specified Pixol (depending on the ComponentIndex)

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

StrokeGetInfo [StrokeGetInfo, Stroke-type Variable, Info number, Point index (0 based)]
Output: StrokeInfo result
Retrieves the information from a specified Stroke (depending on the Info Number)

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.

StrokeGetLast [StrokeGetLast]
Output: StrokeData
Retrieves the last drawn brush stroke
TransformGet [TransformGet, X Position, Y Position, Z Position, X Size, Y Size, Z Size, X Rotation, Y Rotation, Z Rotation]
Gets current transformation values for the active 3D object.

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.

TransformSet [TransformSet,xPos,yPos,zPos,xScale,yScale,zScale,xRotate,yRotate,zRotate]
Sets new transformation values for the active 3D object.

Return to top

Working with ZBrush and Its Interface
IPress [IPress,Interface item path]
Presses a ZBrush or ZScript interface item

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

IUnPress [IUnPress,Interface item path]
Unpresses a ZBrush or ZScript interface item
IGet [IGet,Interface item path]
Output: The item value
Returns the current value of a ZBrush or ZScript slider. Returns 1 for a pressed button, 0 for an unpressed button.
ISet [ISet,Interface item path,value]
Sets a new value to a ZBrush or ZScript slider.
IColorSet [IColorSet,Red (0-255),Green (0-255),Blue (0-255)]
Sets the active color to a new value
IReset [IReset,Optional item to reset (default=All). 0=All,1=Interface,2=Document,3=Tools,4=Lights,5=Materials,6=Stencil]
Output: Returns the button that the user clicked. ( 0=NO, 1=YES )
Interface Reset

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.

IConfig [IConfig,ZBrush version-configuration (1.232=v1.23b, 1.5=v1.5 and newer.)]
Sets ZBrush internal version-configuration. This command is provided for optimum compatibility when newer versions of ZBrush introduce changes to tools and features. When ZBrush encounters an [IConfig... command, it causes these tools and features to behave the same way as in the version specified.
IShow [IShow,Interface item path,Show Zoom Rectangles?]
Locates an interface item and makes it visible.
IHide [IHide,Interface item path,Show Zoom Rectangles?, Target parent window? (0 or 1)]
Hides an interface item.
IMaximize [IMaximize,Interface item path,Maximizeall sub palettes? (0=no, NonZero=yes)]
Locates an interface item and (if possible) maximizes its size.
IMinimize [IMinimize,Interface item path,Minimize all sub palettes? (0=no, NonZero=yes)]
Locates an interface item and (if possible) minimizes its size.
IClose [IClose, Interface item path, Show zoom rectangles? (0 or 1), Target parent window (0 or 1)]
Closes an interface item.
IClick [IClick,Interface item path,X1,Y1,X2,Y2,X3,Y3,X4,Y4,X5,Y5,X6,Y6,X7,Y7]
Emulates a click within a specified ZBrush interface item
IStroke [IStroke,Interface item path,StrokeData]
Emulates a brush stroke within an interface item

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

IToggle [IToggle,Interface item path]
Toggles the state of a ZBrush or ZScript interface item. Presses a button if unpressed, and vice-versa.
IGetMax [IGetMax,Interface item path]
Output: The item maximum value
Returns the maximum possible value of a ZBrush or ZScript interface item
IGetMin [IGetMin,Interface item path]
Output: The item minimum value
Returns the minimum possible value of a ZBrush or ZScript interface item
ISetMax [ISetMax,Interface item path,New max value ]
Sets the maximum value for an ISlider interface item (can only be used for ZScript-generated interface items)
ISetMin [ISetMin,Interface item path,New min value ]
Sets the minimum value for an ISlider interface item (can only be used for ZScript-generated interface items)
IDisable [IDisable,Window path,Window ID or relative windowID(-100<->100)]
Disables a ZScript interface item (can only be used for ZScript-generated interface items)
IEnable [IEnable,Window path,Window ID or relative windowID(-100<->100)]
Enables a ZScript interface item (can only be used for ZScript-generated interface items)

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.

IExists [IExists,Interface item path]
Output: 1 if item exists,0 otherwise
Verifies that a specified interface item exists.

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.

IsDisabled [IsDisabled,Interface item path]
Output: The item 'Disabled' status (1=Disabled 0=Enabled)
Returns 1 if the specified ZBrush or ZScript interface item is currently disabled, returns 0 otherwise
IsEnabled [IsEnabled,Interface item path]
Output: The item 'Enabled' status (1=Enabled 0=Disabled)
Returns 1 if the specified ZBrush or ZScript interface item is currently enabled, returns 0 otherwise
ISetStatus [ISetStatus,Interface item path,New status ( 0=Disable NotZero=Enable )]
Enables or Disables a ZScript interface item (can only be used for ZScript-generated interface items)
IGetStatus [IGetStatus,Interface item path]
Output: The item status: 0=Disabled, 1=Enabled
Returns the Enabled/Disabled status of a ZBrush or ZScript interface item. Usually the same as IsEnabled.
IShowActions [IShowActions, show actions?]
Temporarily sets the status of Show Actions during ZScript playback

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.

IFreeze* [IFreeze,Commands group to be executed without updating the interface]
Disables interface updates while executing commands. [IFreeze... is useful when performing lengthy tasks, and you'd prefer the user sees only the finished product.

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 [IUpdate, Repeat count (default=1), Redraw UI? (default=no, 1=yes)]
Updates the ZBrush interface

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

IModGet [IModGet,Interface item path]
Output: The item value
Returns the current modifiers binary state of a ZBrush or ZScript interface item

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.

IModSet [IModSet,Interface item path,value]
Sets the modifiers binary value of a ZBrush or a ZScript interface item

See IModGet.

IWidth [IWidth, Interface item path]
Output: The width of the interface item
Returns the width, in pixels, of the specified interface item
IHeight [IHeight, Interface item path]
Output: The height of the interface item
Returns the height, in pixels, of the specified interface item

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

IHPos [IHPos, Interface item path, Global coordinates? (0=default=canvas coordinates, nonzero=global coordinates)]
Output: The horizontal position of the interface item
Returns the horizontal position of an interface item

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).

IVPos [IVPos, Interface item path, Global coordinates? (0=default=canvas coordinates, nonzero=global coordinates)]
Output: The vertical position of the interface item
Returns the vertical position of an interface item
IGetID [IGetID,Interface item path]
Output: The interface item ID number
Returns the ID number of the interface item specified by path/name
IGetTitle [IGetTitle, Interface item ID number, return full path? (0=no, nonzero=yes)]
Output: The title of the specified item
Returns the name, and optionally the path of the interface item specified by ID number
IGetInfo [IGetInfo,Interface item path]
Output: The popup info
Retrieves the main popup info about an interface item as a string
IGetSecondary [IGetInfo,Interface item path]
Output: The secondary popup info
Retrieves the secondary popup info about an interface item as a string

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.

IGetHotkey [IGetHotkey,Interface item path]
Output: The ASCII/keyboard value of the item's hotkey
Retrieves the hotkey (key shortcut) of an interface item
ISetHotkey [ISetHotkey,Interface item path, Hotkey (0=no hotkey)]
Sets the hotkey (key shortcut) of an interface item

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.

IKeyPress* [IKeyPress,The key to press with an optional CTRL/CMD, ALT/OPT, SHIFT or TAB combination. ,Commands group to execute while the key is pressed,Optional H cursor position prior to key press,Optional V cursor position prior to key press]
Simulates a key press

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.

IGetFlags [IGetFlags, Interface item path]
Output: interface item's status flags
Returns the status flags of the specified interface item.

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

CanvasPanGetH [CanvasPanGetH]
Output: the current H pan value
Returns the horizontal pan value of the active document view

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).

CanvasPanGetV [CanvasPanGetV]
Output: the current V pan value
Returns the vertical pan value of the active document view
CanvasPanSet [CanvasPanSet, H value, V value]
Pans the canvas within the document window

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.

CanvasZoomGet [CanvasZoomGet]
Output: the current zoom value
Returns the zoom value of the active document view

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.

CanvasZoomSet [CanvasZoomSet,Zoom value]
Sets the zoom value of the active document view
ZBrushInfo [ZBrushInfo, The info type]
Output: a numeric value indicating the type of info queried
Returns information about ZBrush and the filesystem.

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

ZBrushPrioritySet [ZBrushPriorityGet]
Sets the task priority for ZBrush (Windows only).

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.

ZBrushPriorityGet [ZBrushPriorityGet]
Output: the task priority
Returns the task priority for ZBrush (Windows only).

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


Return to top

Reading the Mouse
MouseHPos [MouseHPos]
Output: The H position of the mouse
Returns the current H position of the mouse in Canvas coordinates

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.

MouseVPos [MouseVPos]
Output: The V position of the mouse
Returns the current V position of the mouse in Canvas coordinates
MouseLButton [MouseLButton]
Output: Returns 1 if mouse button is pressed, returns zero if unpressed
Returns the current state of the left mouse button

Return to top

Working With Files and Filenames
FileNameSetNext [FileNameSetNext,File name including the extension (such as .psd ). If omitted the stored file name will be cleared.]
Pre-sets the file name that will be used in the next Save/Load action

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,""].

FileNameAsk [FileNameAsk,Extension list (up to 3 extensions),Default FileName for SaveDialog. Name should be omitted for Open Dialog]
Output: Result file name or an empty string if user canceled operation.
Presents the standard 'Save' dialog and asks user for a file name
FileNameGetLastTyped [FileNameGetLastTyped]
Output: Latest file name that was typed by the user. Returned Variable will be empty if the user has canceled the action.
Retrieves the latest file name that was typed by the user in a Save/Load action
FileNameGetLastUsed [FileNameGetLastUsed]
Output: Latest file name that was used. Returned Variable will be empty if the user has canceled the action.
Retrieves the latest file name that was used (by the user or by ZBrush) in a Save/Load action
FileNameExtract [FileNameExtract,FileName (Full path),Component specifier (1=path, 2=name, 4=ext)]
Output: The extracted filename component/s.
Given a FileName (from a string or from the result of a FileNameGetLast...), provides the path, name and/or extension

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]

FileNameMake [FileNameMake,Base file name,Index,Number of numeric digits to use]
Output: Combined file name Variable
Combines a base filename with an index number
FileNameAdvance [FileNameAdvance,base file name,Number of digits (0-4) (i.e. 3= 001 ),Add 'Copy' string? (0=no, NonZero=yes)]
Output: Updated file Name
Increments the index value contained within a filename string
FileExists [FileExists, File name including the extension (such as brush1.ztl)]
Output: Returns 1 if the file exists, 0 if it does not exist
Checks if a specific file exists
FileNameResolvePath [FileNameResolvePath, Local file name]
Output: Full system path to a file
Resolves the full system path to a local file

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"]

StrokeLoad [StrokeLoad,FileName (.txt)]
Output: StrokeData
Loads a brush-stroke text file
StrokesLoad [StrokesLoad,FileName (.txt)]
Output: StrokesData
Loads a brush-strokes text file
VarSave [VarSave, Variable name, Filename]
Output: Number of saved values (1 unless the variable is a list)
Saves a variable to a file

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.

VarLoad [VarLoad, Variable name, Filename, Verify only? (0=default=read file, 1=only check existence/number of values)]
Output: Number of loaded or verified values (1 unless the variable is a list)
Reads the value of a variable or list from a file; optionally verifies the existence and quantity of saved value(s).
FileExecute [FileExecute, Filename, Routine to call, Optional text input, Option numeric input, Optional memory block input, Optional memory block output]
Output: The result value defined by the specified file/routine
Calls a plugin library file

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.


Return to top

Calculations
VarAdd [VarAdd,Variable name,Value To Add]
Adds a value to an existing variable
VarSub [VarSub,Variable name,Value To Subtract]
Subtracts a value from an existing variable
VarMul [VarMul,Variable name,Value to Multiply]
Multiplies an existing variable by a value
VarDiv [VarDiv,Variable name,Value to Divide By]
Divides an existing variable by a value
VarInc [VarInc,Variable name]
Adds 1 to the value of an existing variable

The same as [VarAdd, VariableName, 1] but neater. Useful when using the [Loop... command.

VarDec [VarDec,Variable name]
Subtracts 1 from the value of an existing variable
RGB [RGB,Red,Green,Blue]
Output: Combined RGB
Combines 3 color-components into one RGB value

Note: Certain commands, such as Note and PropertySet, take this style of combined RGB as input values. As an alternative to the RGB command, you can also specify HTML-style 6-digit colors, using the shorthand '0xRRGGBB'. For example, '0xFF0000' specifies a red color.

Interpolate [Interpolate,Time (0=AtStart 0.5=half 1=AtEnd) ,Value1 (Num, VarName or ListName),Value2 (Num, VarName or ListName),Value3 (Num, VarName or ListName),Value4 (Num, VarName or ListName)]
Output: Interpolated value or list
Performs time-based interpolation
Randomize [Randomize, Optional seed value (0 to 32767)]
Resets the random number generator

To ensure randomized functions, such as fiber and noise drawing, appear the same each time a ZScript recording is replayed, the random-number generator is re-seeded to the same value when an IReset is encountered. Randomize provides a way to seed the random-number generator with any value you choose, so that results can be repeated predictably, or force them to be unpredictably random.

Operators + Plus
-
Minus
*
Times
/
Divided By
^^ To the Power Of

Note: Unlike some programming languages, calculations are always evaluated from left to right. That means

2 + 3 * 4
evaluates to 20.

To make sure certain parts of the calculation are evaluated first, place them inside parentheses:

2 + (3 * 4)
evaluates to 14.

Functions INT(value) Integer Portion of value; removes everything after decimal point
FRAC(value)
Fractional Portion of value; removes everything before decimal point
ABS(value)
Absolute Value (ignores + or - sign)
NEG(value)
Changes the + or - sign of value
MIN(value1,value2)
Finds the lesser of two values
MAX(value1,value2)
Finds the greater of two values
SQRT(value)
Square Root of the value
RAND(value)
Random Number between 0 and value
IRAND(value)
Random Integer between 0 and value
SIN(angle)
Trig Sine of the angle, in degrees
COS(angle)
Trig cosine of the angle, in degrees
TAN(angle)
Trig Tangent of the angle, in degrees
ASIN(value)
Trig ArcSine of the value
ACOS(value)
Trig ArcCosine of the value
ATAN(value)
Trig ArcTangent of the value
LOG(value)
Natural Log of the value
LOG10(value)
Base 10 Log of the value
BOOL(value)
Boolean Evaluation

Return to top

Manipulating Variables
VarDef [VarDef,Variable name,optional Variable defaultValue]
Defines a variable

Use [VarDef, VariableName(number)] to define List Variables. For example, to create a LIst Variable called Width with 50 different possible values:

[VarDef,Width(50)]

Refer to each element in the List Variable as Width(0), Width(1) and so on, through Width(49). Confusingly, there is no Width(50), because the index begins at 0.

VarSet [VarSet,Variable name,New Value]
Sets the value of a named variable

Tip: You can use VarSet to assign different kinds of values to variables:

[VarSet, x, 10+5]
Numeric value

[VarSet, x, [StrokeGetLast]]
Brushstroke

[VarSet, x, "Hello There"]
Text (which can be displayed in a MessageOK or Note).

Var [Var,Variable name]
Output: Value of the named variable
Gets the value of a named variable
Val [Val,Variable name]
Output: Value of the named variable
Evaluates the input and returns a numerical value
VarSize [VarSize,Variable name]
Output: The number of items in a list or 1 if it is a simple variable
Returns the number of items in a variable or in a list

See VarDef.

VarListCopy [VarListCopy,Destination list,Destination initial index,Source list,Source initial index,Number of items to copy. (if omitted or it is 0, then all items will be copied)]
Copies items from a source list to a destination list

See VarDef.


Return to top

Manipulating Strings
StrMerge [StrMerge,String 1, String 2, Optional String 3, Optional String 4, Optional String 5, Optional String 6, Optional String 7, Optional String 8, Optional String 9, Optional String 10, Optional String 11, Optional String 12]
Output: the combined string (cannot exceed 255 characters)
Combines up to 12 strings into a single string.

Strings can be used in a number of other commands, for such things as notes, messages, filenames/paths, names of memory blocks and routines, and more. The total length of any single string cannot exceed 255 characters.

Variables intended to store strings should be defined with empty quote marks:

[VarDef, MyString, ""]

StrMerge can be used to merge text with values of variables:

[Note, [StrMerge,"The width is: ", MyWidth, "\nThe height is: ", MyHeight]]

StrExtract [StrExtract, Input string, Start character index (0=default=first character), End character index (0=first character, default=end of string)]
Output: the extracted portion of the input string
Returns a specified portion of the input string.
StrFind [StrFind, Find this string, In this string, Optional start character index (0=first character)]
Output: Returns the starting index of the first string inside the second string, -1 if not found.
Locates one string inside another.

StrFind must be used to determine if a string matches a certain value. You might be tempted to try something like the following, which does not work:

[If, MyString=="Hello",... (This does not work!)

Instead, use the following:

[If, [StrFind,"Hello",MyString] > -1,... (This does work)

StrLength [StrLength, String to evaluate]
Output: Number of characters in the string
Returns the length of the string.
StrLower [StrLower, Input string]
Output: The input string converted to lowercase letters
Returns a lowercase version of the input string.
StrUpper [StrUpper, Input string]
Output: The input string converted to uppercase letters
Returns an uppercase version of the input string.
StrToAsc [StrToAsc, Input string, optional character offset (default=0)]
Output: ASCII value of the specified character in the input string
Returns the ASCII value of a character in the input string.
StrFromAsc [StrFromAsc, ASCII value]
Output: The character represented by the ASCII value
Returns a single character represented by an ASCII value.
StrAsk [StrAsk, optional input string, Title]
Output: Returns the string typed by the user or an empty string if cancelled.
Asks user to input a string using a popup window.

StrAsk is extremely limited, and the Title should always be included. This command should be used to get minimal string input, since the user cannot enter special characters (such as punctuation).

If Optional input string is specified, text is displayed within the window when it opens.


Return to top

Using Memory Blocks
MemCreate [MemCreate,Mem block identifier,Mem block requested size, initial fill? (omitted=no fill=faster to create)]
Output: returns the size of the new memory block or error code (0=Error, -1=Memory already exists, -2=Can't create memory block)
Creates a new memory block

Memory blocks are especially useful because they can store any kind of data in your system's RAM, and retain it as long as ZBrush remains open. This is different from variables, which are cleared each time a new ZScript is loaded or reloaded. You can define as many memory blocks as needed, at any size, limited only by the amount of RAM available.

Memory blocks created in one ZScript can be referenced by other ZScripts by name. For this reason, it's good practice to create memory blocks with names that are unlikely to be used by other ZScripts. For example, suppose you wish to store some text in a memory block, created in a ZScript called "Resizer":

[MemCreate,Text,400]
Poor choice, because the name "Text" is generic and likely to be used in other ZScripts

[MemCreate,ResizerZScript_Text,400]
Good choice, because the name "ResizerZScript_Text" is less likely to be used in other ZScripts

The memory block size should always be a multiple of 4. This is because some types of data occupy 4 bytes each. If the size is not specified as a multiple of 4, the memory block will expand as necessary and extra random bytes may be appended to it.

If initial fill is specified as a value from 0 to 255, each byte in the block is set to this value.

MemCreateFromFile [MemCreateFromFile,Mem block identifier, File name including the extension (such as brush1.ztl), Optional start file offset for partial file read (default=0), Optional max bytes to read (default=entire file)]
Output: returns the size of the new memory block or error code (0=Error, -1=Memory already exists, -2=Can't create memory block, -3=File not found)
Creates a new memory block from a disk file
MemSaveToFile [MemSaveToFile,Mem block identifier, File name including the extension (such as brush1.ztl), Overwrite if exists? (set nonzero to save the file even if an identically-named file already exists, default=0=don't overwrite)]
Output: returns the size of the memory block or error code (0=Error, -1=Memory does not exist, -2=File already exists, -3=File write error)
Saves an existing memory block to a disk file
MemDelete [MemDelete,Mem block identifier]
Output: returns the size of the deleted memory block or 0 if memory block could not be found.
Deletes an existing memory block
MemWrite [MemWrite, Mem block identifier, value to write, data format (see below), offset (in bytes) from beginning of memory block]
Output: Returns the number of bytes written
Writes data to a memory block

MemWrite is used to write one datum at a time to a memory block. Data can be written in a number of formats, specified by the data format parameter:

0 (default) = floating-point number. This is the most common format for numeric data, and uses 4 bytes per datum.
1 = signed character, 1 byte per datum.
2 = unsigned character. Use this format for text data, which uses 1 byte per datum.
3 = signed short, 2 bytes per datum.
4 = unsigned short, 2 bytes per datum.
5 = signed long, 4 bytes per datum.
6 = unsigned long, 4 bytes per datum.
7 = fixed 16 (16,16), 4 bytes per datum.

The offset value is always entered in bytes, regardless of the data format. Thus, for floating-point data, the first datum would be written to offset 0 (or some other appropriate value), the second would be written to offset 4, the third to offset 8, etc.

MemWriteString [MemWriteString, Mem block identifier, string to write, offset (in bytes) from beginning of memory block, write terminating 0 (default=1=yes)]
Output: Returns the number of bytes written, including the terminating 0 if specified
Writes a string to a memory block

MemWriteString is used to write a string to a memory block. The size of the string to be written is limited to 255 characters.

If the terminating 0 parameter is left blank, or set to a number other than 0, a byte with value 0 is written at the end of the string in the memory block. This terminating 0 is useful when you intend to read strings from the block in another ZScript portion; the MemReadString command reads bytes until it encounters a 0, so it won't be necessary to specify the size of the string when reading.

If you intend to write a text memory block to a file which can then be read by a text editor, the terminating 0 may not be understood properly. In this case it would be better not to include the terminating 0, and instead write a line break at the end of the string. The line break is one byte (ASCII 13) for Mac files, and two bytes (ASCII 13, ASCII 10) for Windows files. In either case, MemReadString reads bytes until one of these line breaks is encountered, so again it won't be necessary to specify the string size when reading.

Here's how a MemWriteString sequence might look when if you intend to read it in a Windows text editor:

[MemCreate, MyZScript_Text, 200, 32] // 32 is a space character
[MemWriteString, MyZScript_Text, [StrMerge,"Hello There!",[StrFromAsc,13],[StrFromAsc,10]]]
[MemSaveToFile, MyZScript_Text, Sample.txt]

MemMultiWrite [MemMultiWrite, Mem block identifier, value to write, data format (see description in MemWrite), offset (in bytes) from beginning of memory block, Repeat count, offset (in bytes) to subsequent writes]
Output: Returns the number of bytes written
Writes repetitive data to a memory block
MemRead [MemRead, Mem block identifier, Read variable, data format (see description in MemWrite), offset (in bytes) from beginning of memory block]
Output: Returns the number of bytes read
Reads one datum at a time from a memory block

The read variable is the name of a variable, and must be defined with [VarDef...] or [VarSet...] before using it in this command.

MemReadString [MemReadString, Mem block identifier, string variable, offset (in bytes) from beginning of memory block, break at line end? (default=0=no), Skip white space? (default=0=no), Max read length (default 255)]
Output: Returns the number of bytes scanned, which may be larger than the number of bytes read into the variable
Reads a string from a memory block

If Break at line end? is set to nonzero, read stops when a character with value 0, 10 or 13 is encountered (see MemWriteString).

If Skip white space? is set to nonzero, spaces and tabs are ignored when read into the variable.

The total size of the scanned string, including white spaces even if ignored, must be 255 bytes or less.

MemCopy [MemCopy, Source mem block identifier, source offset, destination mem block identifier, destination offset, number of bytes to copy (if omitted, maximum possible bytes are copied)]
Output: Returns the number of bytes copied, or -1 if an error is encountered
Copies data from one memory block to another

Source and destination memory blocks must be different. To move data within a single memory block, use MemMove.

MemMove [MemMove, Mem block identifier, source offset, destination offset, number of bytes to move (if omitted, maximum possible bytes are moved)]
Output: Returns the number of bytes moved
Moves data within a memory block
MemGetSize [MemGetSize, Mem block identifier]
Output: Returns the size of the memory block, or 0 if memory block is not found
Determines the size of a memory block

MemGetSize is a good test for determining if a memory block exists. It is also useful when determining if a memory block is large enough to accommodate data which you intend to write to it, or if you need to use MemResize first.

MemResize [MemResize, Mem block identifier, new size, initial fill if larger? (omitted=no fill)]
Output: Returns the new size of the memory block. Zero indicates an error.
Resizes a memory block
MVarDef [MVarDef, Mem block identifier, Number of variables, initial fill? (omitted=no fill=faster to create)]
Output: returns the number of variables in the new memory block, or error code (0=Error, -1=Memory already exists, -2=Can't create memory block)
Creates a new memory block with data format 0 (floating point)

MVarDef, MVarSet and MVarGet are shorthand ways to create, write and read memory blocks with floating-point data formats (format 0). Offsets used in these commands are value indices instead of 4-byte offsets. For example, to access the first and second data from a floating-point memory block, you'd use offsets 0 and 4 in a MemRead command, but offsets 0 and 1 in a MVarGet command. Likewise, the Number of variables parameter is multiplied by 4 to determine the memory block's size in bytes.

These commands are a bit more intuitive to use and are similar to the VarDef, VarSet and Var commands. Memory blocks created with the MVarDef command can also be manipulated using any of the other memory-block commands.

MVarSet [MVarSet, Mem block identifier, Variable index, value to write]
Output: returns the old value of the indexed variable, before writing
Writes a floating-point number to a memory block
MVarGet [MVarGet, Mem block identifier, Variable index]
Output: returns the value
Reads a floating-point number from a memory block
MTransformGet [MTransformGet, Mem block identifier, Optional variable index (default=0)]
Writes current object's transform values into a memory block

MTransformGet writes the nine transform values for an active 3D object into a memory block. The memory block must first be created using MemCreate or MVarDef, and have a size of at least 36 bytes.

The nine transform values are:

Position X, Position Y, Position Z
Size X, Size Y, Size Z
Rotation X, Rotation Y, Rotation Z

MTransformSet [MTransformSet, Mem block identifier, Optional variable index (default=0)]
Sets current (active) object's transform values from those stored in a memory block

An object must be active before changing the transform values can take effect, that is, it must be in a Transform mode (Move, Resize or Rotate), or in Edit mode.

SoundPlay [SoundPlay, Mem block identifier, Optional play mode]
Output: Returns 0 if the command executed successfully
Plays a WAV file which has been loaded into a memory block

Play mode can be:

0=default= Play once, don't wait for end of sound before playing next sound.
1= Play once, wait for end of sound
2= Play loop, don't wait for end of sound

SoundStop [SoundStop, Mem block identifier]
Output: Returns 0 if the command executed successfully
Stops playing a sound.

Return to top

Special 3D Tool Commands
ZSphereEdit* [ZSphereEdit, ZSphere editing commands, store undo? (0=skip undo, 1=store undo)]
Output: Returns 0 if command executed successfully
Prepares a currently-active ZSphere tool for ZScript editing.

ZSphereEdit is a container for the following ZSphere editing commands. You can optionally make the actions undoable. If the output of the command is not 0, it's likely there was no ZSphere tool active (selected, in a Transform or Edit mode) when this command was issued.

ZSphereAdd [ZSphereAdd, xPos, yPos, zPos, Radius, Parent index, Optional color (red*65536 + green*256 + blue), Optional mask (0=unmasked to 255=fully masked), Optional timestamp, optional flag (0=default, 1=gap in link to parent)]
Output: Returns the index of the new ZSphere or -1 if error.
Adds a new ZSphere.

The Parent index is the index of the ZSphere from which the added one descends. If the flag is 1, a gap is created as if the link-spheres were Alt-clicked, thus the new ZSphere may be a magnet if it has no children (added later).

While modeling, ZSpheres added in Symmetry mode are given the same timestamp (usually the number of milliseconds since creation). If you intend to add more ZSpheres symmetrically, you should set each of their timestamps to the same (arbitrary) value.

This command must be placed within a ZSphereEdit command.

ZSphereDel [ZSphereDel, ZSphere index]
Output: Returns 0 if command executed successfully.
Deletes ZSphere.

The ZSphere with index 0 is the root ZSphere and can't be deleted.

This command must be placed within a ZSphereEdit command.

ZSphereGet [ZSphereGet, Property (see below), ZSphere index (if appropriate), 2nd ZSphere index]
Output: Returns the value of the specified property.
Gets information about the current active ZSphere tool.

The information returned by this command depends on the following property indices:

0= ZSpheres count in tool.
1= X position*
2= Y position*
3= Z position*
4= Radius*
5= Color*
6= Mask value*
7= Parent index*
8= Last Clicked index
9= Timestamp*
10= Children count*
11= Child index**
12= Timestamp count*
13= Timestamp index*
14= Flag*
15= Twist angle*
16= Membrane value
17= X Res value*
18= Y Res value*
19= Z Res value*

* requires the ZSphere index, which is the index of the ZSphere you're querying for all properties except 12 and 13 (where it's a timestamp).
** requires both the ZSphere index and 2nd ZSphere index.

Many of these are simple. Here are explanations of some less-intuitive properties:

Property 7 returns the index of the ZSphere's parent.

Property 8 returns the index of the "active" ZSphere (usually colored red while modeling), i.e. the last one clicked.

Property 11 returns the index of a child of the ZSphere queried. ZSphere index is the index of the one queried, and 2nd ZSphere index is the number of the child starting with 0. For example, [ZSphereGet,11,24,0] returns the index of the first child of the ZSphere with index 24, and [ZSphereGet,11,24,2] returns the index of its 3rd child.

Property 12 returns the number of ZSpheres with a timestamp given by the ZSphere index parameter.

Property 13 returns the index of the first ZSphere with a timestamp given by the ZSphere index parameter.

This command must be placed within a ZSphereEdit command.

ZSphereSet [ZSphereSet, Property (see below), ZSphere index (if appropriate), new value]
Output: Returns 0 if executed properly.
Modifies a property of a ZSphere in the currently-active tool.

The property indices are similar to those in the ZSphereGet command, and all require the ZSphere index:

0= unused
1= X position
2= Y position
3= Z position
4= Radius
5= Color (red*65536 + green*256 + blue)
6= Mask value (0=unmasked to 255=fully masked)
7= Parent index
8= unused
9= Timestamp
10= unused
11= unused
12= unused
13= unused
14= Flag
15= Twist angle
16= Membrane value
17= X Res value
18= Y Res value
19= Z Res value
20= XYZ Res value
21= User value (used to store any number you choose for reference)

Using property 7, you can "reattach" a limb to a different ZSphere.

This command must be placed within a ZSphereEdit command.

Mesh3DGet [Mesh3DGet, Property (see below), optional input 1 (vertex/face/group/UV unit), optional input 2, optional output variable 1, optional output variable 2, optional output variable 3, optional output variable 4, optional output variable 5, optional output variable 6, optional output variable 7, optional output variable 8]
Output: Returns 0 if executed properly; any other value indicates an error.
Gets information about the currently-active Polymesh tool and stores it in the specified output variable(s).

The property indices are:

0= Points count in entire object (input variables are ignored)

1= Faces count in entire object (input variables are ignored)

2= Future expansion (feature inactive in current version ZBrush 2)

3= UV Bounds (outputs 4 values: min U, min V, max U, max V).
If input 1 is blank, this yields the UV bounds for the entire object.
Currently (in version 2), ZBrush creates objects with one UV unit per object. However, imported objects may contain multiple UV units, and input 1 may be used to specify the indexed UV unit for which to return the UV bounds. In this case, input 1 is 0-based, so a value of 0 means the first UV unit defined for the object, 1 means the second, and so on.

4= First UV unit reference number (input variables ignored)
For imported objects with multiple UV units defined, each unit may have a unique reference number from 0 to 65535. This property index returns the reference number of the first one encountered in the OBJ file, and stores it in the first output variable. This reference number must be determined before using property 6 (see below), and is used in DispMapCreate and NormalMapCreate commands.

5= Next UV tile (input variables ignored)
Meaningful only when Mesh3DGet with property 4 has already been issued, this property index returns the reference number of the next UV unit encountered. To find the third UV unit encountered, you'd issue three Mesh3DGet commands; the first using property 4, and the next two using property index 5.

6= Polys in UV unit (specified by input 1)
Input 1 must be the reference number read using properties 4 and/or 5.

7= Future expansion

8= Future expansion

DispMapCreate [DispMapCreate, Image Width, Image Height, Smooth (default=yes), SubPoly (default=0), Border (default=8), UV unit reference number (default=ignored)]
Output: Returns 0 if executed properly; any other value indicates an error.
Creates a displacement map for the active 3D object.

This command is similar to using settings and buttons in the Tool:Displacement sub-palette, with some advantages.

Image Width and Image Height enable you to specify the map's dimensions, which can be different values. Using palette items, you can only create a square map.

Smooth, which is similar to the SmoothUV button, can be nonzero (on) or zero (off=faceted). Whether or not to smooth depends on the characteristics of your intended rendering engine.

SubPoly is the value you'd use in the DSubPix slider in the palette.

Border provides a value for overpainting seams in the map.

UV unit reference number is used when generating displacement maps for objects which have multiple UV units. Currently (in version 2), ZBrush creates objects with one UV unit per object. This reference number can be determined using the Mesh3DGet command with properties 4 and 5.

NormalMapCreate [NormalMapCreate, Image Width, Image Height, Smooth (default=yes), Image Res (default=0), Border (default=8), UV unit reference number (default=ignored), Local (tangent) coordinates? (default=0=world coordinates)]
Output: Returns 0 if executed properly; any other value indicates an error.
Creates a normal map for the active 3D object.

This command, which is structured similarly to DispMapCreate, is similar to using settings and buttons in the Tool:Normal Map sub-palette, with some advantages.

Image Width and Image Height enable you to specify the map's dimensions, which can be different values. Using palette items, you can only create a square map.

Smooth, which is similar to the SmoothUV button, can be nonzero (on) or zero (off=faceted). Whether or not to smooth depends on the characteristics of your intended rendering engine.

Image Res is the value you'd use in the NMRes slider in the palette.

Border provides a value for overpainting seams in the map.

UV unit reference number is used when generating normal maps for objects which have multiple UV units. Currently (in version 2), ZBrush creates objects with one UV unit per object. This reference number can be determined using the Mesh3DGet command with properties 4 and 5.

Local coordinates? creates local (tangent) coordinates if nonzero, and global (world) coordinates if zero or blank.


Return to top

Structuring The Flow
Delay [Delay,Delay (in seconds)]
Delays execution of ZScript for specified amount of time
Exit [Exit]
Aborts execution and exits the current ZScript
If* [If,True Or False Evaluation,Commands group to be executed if true (not zero),Commands group to be executed if false (is zero)]
Provides conditional execution of a commands group

You can use these operators in your True or False Evaluations:

= Equal To
>
Greater Than
>=
Greater Than or Equal To
<
Less Than
<=
Less Than or Equal To
!=
Not Equal To, can also be !(a = b)

You can also combine more than one Evaluation using these two operators:

&& And
||
Or

For example:

[If, [IGet,Tool:ItemInfo]=1 && [iGet,Texture:ItemInfo]=0, ... ]

would be considered true only if both the SimpleBrush (tool number 1) AND "Texture Off" (texture number 0) was currently selected.

Loop* [Loop,RepeatCount,Commands group, Optional loop-counter variable]
Repeats execution of the specified commands group

The optional Loop-counter variable can be entered in this command without first being defined using VarDef or VarSet. Its value begins at 0, and increments each time the loop executes.

LoopContinue [LoopContinue]
Continues execution from the beginning of the current Loop
LoopExit [LoopExit]
Exits the current Loop
RoutineDef* [RoutineDef,Name of the routine,Commands group that will be executed when the routine is called,Input Var01,Input Var02,Input Var03,Input Var04,Input Var05,Input Var06,Input Var07,Input Var08,Input Var09,Input Var10]
Defines a named commands group
RoutineCall [RoutineCall,Name of the routine to be called,Input Var01,Input Var02,Input Var03,Input Var04,Input Var05,Input Var06,Input Var07,Input Var08,Input Var09,Input Var10]
Executes the specified defined routine
Sleep* [Sleep, Sleep time in seconds, Commands group to execute when awakened, optional event to awaken (see below), optional variable which will contain the awakening event code, optional variable which will contain the ID of the window under the cursor when awakened]
Exits ZScript, returning control to the standard ZBrush interface, and awakening when a specific event occurs.

Using Sleep, you can exit the ZScript and return to the standard ZBrush interface control and run commands when a specific event occurs, such as a mouse click or key click. Commands are executed once unless you include a SleepAgain command at the end of the group.

To specify the awakening event, add the appropriate codes together:

1 = Timer (sleep time parameter). This is the default.
2 = Mouse movement
4 = Left mouse button down
8 = Left mouse button up
16 = Key down
32 = Key up
64 = Modifier key (Shift, Alt, Ctrl) down
128 = Modifier key up
256 = ZScript startup
512 = ZScript exit/shut down
1024 = Interface item pressed/unpressed
2048 = Tool selected
4096 = Texture selected
8192 = Alpha selected

If you're not using event 1 (timer), set the sleep time to a very low value like 0.001.

SleepAgain [SleepAgain, Optional new sleep time in seconds (default = no change), optional new event to awaken (default = no change)]
Exits ZScript and continues the Sleep command.

This command establishes a loop so that a set of commands can be executed every time certain events occur. It should be placed at the end of the Sleep commands group.

Assert [Assert,True Or False Evaluation,Message that will be shown if the first input is false (zero)]
(ZScript debugging helper) aborts execution and displays Message if specified condition is not true
Comments // Ignores all text until the end of the text line (return is encountered)
/*
Ignores all text until ...
*/
Stops ignoring text

Good for inserting notes to yourself (or other "ZCoders") inside your bracketed ZScript commands. Also good for debugging; you can cause ZBrush to ignore certain commands that aren't working.

<zscriptinsert,> <zscriptinsert,"Filename.txt">
Inserts all the text and commands of an entire ZScript file.

The only "command" that doesn't get placed inside square brackets. Actually this isn't a true ZScript command, it only inserts another ZScript at the point where this is located. The insertion happens once when the ZScript is loaded (or reloaded) into ZBrush.

What if you insert a ZScript that has another <zscriptinsert> inside it? It works just as you'd expect -- the third ZScript is inserted into the second ZScript, which is then inserted into the first ZScript -- up to a maximum of 8 nested ZScripts.


Return to top

Index
Assert

BackColorSet
ButtonFind
ButtonPress
ButtonSet
ButtonUnPress

Calculations, evaluating
CanvasClick
CanvasGyroHide

CanvasGyroShow
CanvasPanGetH
CanvasPanGetV
CanvasPanSet
CanvasStroke
CanvasStrokes
CanvasZoomGet
CanvasZoomSet
Caption
Comments
Comparison operators

Delay
Dialog Boxes, suppressing
  File opens/saves
  Cannot Undo?

DispMapCreate

Exit

FileExecute
FileExists
FileNameAdvance
FileNameAsk
FileNameExtract
FileNameGetLastTyped
FileNameGetLastUsed
FileNameMake
FileNameResolvePath
FileNameSetNext
Font, setting colors
FontSetColor
FontSetOpacity
FontSetSize
FontSetSizeLarge
FontSetSizeMedium
FontSetSizeSmall
FrontColorSet
Functions

HotKeys, specifying
HotKeyText

IButton
IClick
IClose
IColorSet
IConfig
IDialog
IDisable
IEnable
IExists
If
IFreeze
IGet
IGetFlags
IGetHotkey
IGetID
IGetInfo
IGetMax
IGetMin
IGetSecondary
IGetStatus
IGetTitle
IHeight
IHide
IHPos
IKeyPress
Image
IMaximize
IMinimize
IModGet
IModSet
Initially Disabled?
Interpolate
IPress
IReset
IsDisabled
IsEnabled
ISet
ISetHotkey
ISetMax
ISetMin
ISetStatus
IShowActions
IShow
ISlider
IStroke
ISubPalette
ISwitch
IToggle
IUnPressIUpdate
IVPos
IWidth

Line Break, inserting
List Variables
Locating ZScript buttons
Loop
LoopContinue
LoopExit

Math Functions
MemCopy
MemCreate
MemCreateFromFile
MemDelete
MemGetSize
MemMove
MemMultiWrite
MemRead
MemReadString
MemResize
MemSaveToFile
MemWrite
MemWriteString
Mesh3DGet
MessageOK
MessageOKCancel
MessageYesNo
MessageYesNoCancel
MouseHPos
MouseLButton
MouseVPos
MTransformGet
MTransformSet
MVarDef
MVarGet
MVarSet

NormalMapCreate
Note
NoteBar
NoteIButton
NoteIGet
NoteISwitch

Operators

PageSetWidth
PaintBackground
PaintBackSliver
PaintPageBreak
PaintRect
PaintTextRect
PD
PenMoveCenter
PenMoveDown
PenMoveLeft
PenMoveRight
PenMove
PenSetColor
PixolPick
PropertySet

Randomize
Reading
  data from canvas
  stroke information
  stroke files
  mouse
  user input
RGB

RoutineCall
RoutineDef

SectionBegin
SectionEnd
Sleep
SleepAgain
SoundPlay
SoundStop
StrAsk
StrExtract
StrFind
StrFromAsc
StrLength
StrLower
StrMerge
StrokeGetInfo
StrokeGetLast
StrokeLoad
StrokesLoad
StrToAsc
StrUpper
SubTitle

Text, setting colors
TextCalcWidth
Title
TransformGet
TransformSet

Val
VarAdd
VarDec
VarDef
VarDiv
VarInc
VarListCopy
VarLoad
VarMul
VarSave
VarSet
VarSize
VarSub
Var
Variable types

WebZPlug.dll

ZBrushInfo
ZBrushPriorityGet
ZBrushPrioritySet
ZScript buttons, locating
<zscriptinsert>
ZSphereAdd
ZSphereDel
ZSphereEdit
ZSphereGet
ZSphereSet

Return to top

Revision B, November 2004

 links to ZBrushCentral, the online ZBrush community.