ZScript Code Samples & Suggested Functionalities

With the release of ZBrush 3, there are some new zscript commands and new zscripting possibilities. This thread is intended as a repository for code samples and suggestions, extending these two earlier threads:

Code Sample: Full ZScripts and other code

Code Sample: Suggested ZScript Functionalities

but with emphasis on ZBrush 3 and above. Those two threads still have much valuable information in them, and are recommended reading for anyone interested in zscripting, but some of the suggestions are less relevant or are problematic in ZBrush 3. In the interests of clarity, it seemed sensible to start a new thread.

Please post code samples and suggestions with solutions in this thread; zscripting questions should be posted as a new thread.

Happy zscripting! :slight_smile:

The ability to record macros is a great addition to ZBrush but with a little zscripting knowledge it is possible to edit the recordings for greater efficiency, or even write a macro from scratch.

If you look at a recorded macro text file in a text editor you will see that it begins something like this:

//ZBRUSH MACRO - Recorded in ZBrush version 3.1
[IButton,???,"Press to run this macro. Macros can be aborted by pressing the ‘esc’ key.",
/*main macro commands here*/
]//end of macro button

The button has a special name - ??? - and this is what identifies it as a macro. The commands that are wrapped inside the button begin with [IShowActions,0]. This is a useful command - it temporarily switches off the Show Actions button in the ZScript palette, so that the commands that follow are executed without the cursor opening palettes and so on. The [IConfig,3.1] identifies the ZBrush version and then the main macros commands follow. The button ends with a final square bracket.

Changing the button size:
The default size of the macro button will depend on the filename you give it, as the filename becomes the button label. But by adding a little code you can make the button exactly the size you want. This is very useful if you want to fit the button neatly onto a custom interface. All you need to do is add this code instead of the final square bracket:

,,.5 /*width*/,,,.25 /*height*/]

The width and height are proportions of the palette size, so in this example the button would be half a palette in width, and a quarter in height. The exact size will depend on the setting you have in the Preferences:Interface: Button Width slider but whatever that is a value of .5 for the macro button width should fit neatly below the color selector. There’s no need to enter a height value, but in this example the .25 will give a button the same size as the Projection Master button.

Avoiding Error Messages
Sometimes a recorded macro can throw up an error message when the button is pressed. This is usually because ZBrush is not in the same state as it was when the macro was recorded, so that an option that the macro requires is not available. It is possible to use zscript commands to test for the right conditions, and avoid errors of this sort. The following code is for toggling Y symmetry on or off. It first checks that the symmetry option is available before carrying out the necessary actions:

[IButton,"???","Toggles Y symmetry on or off",
[If,[IExists,Transform:ActivateSymmetry],//check for the 'Activate Symmetry' button
[If,[IsEnabled,Transform:ActivateSymmetry],//if the button is enabled (can be pressed) proceed
	[If,[IGet,Transform:ActivateSymmetry],//will return 1 (true) is the button is already pressed
		[If,[IGet,Transform:>Y<],//will return 1 (true) is the button is already pressed
			[NoteBar,"Y symmetry OFF"]
		,//else button is not pressed so:
			[NoteBar,"Y symmetry ON"]
	,//else button is not pressed so:
		[NoteBar,"Y symmetry ON"]
,,.5 /*width*/,,,.25 /*height*/]

ZScripting, like any computer language, requires an iterative approach. You will reload the script many times to test changes and to solve problems. ZScripts that display in the Tutorial Window can be reloaded as many times as you want within the current ZBrush session. But with ZPlugins (ZScripts that are located in the ZBrush palettes and subpalettes) it is problematic to reload.

A reloaded ZPlugin will most likely not function as intended from where the script code was changed and downwards. Normally you would just write the zscript to display in the Tutorial Window and during the finishing stages move all the ZScript buttons into the ZBrush interface where they become ZPlugin buttons. But even tweaking a ZPlugin during the late stages of development can become tiresome as it requires a restart of ZBrush to reflect the change to a button’s size or a button’s icon, for example.

Luckily it is quite easy to reload a ZPlugin as many times as you want within the same session, without losing any reliability in code execution.

Zplugins are normally placed within a Subpalette, often created by the ZScriptor. By expanding the palette and subpallete of the ZPlugin into one of the trays to the left or right (important) you are able to execute an [IClose, interface path] command. The command will remove the interface path which can be a whole subpalette or a single button. This allows you to reload the Zplugin within the same session.

Note: [IClose,…]'ing a zscript generated subpalette while it is not docked to the left or right tray may leave the subpalette name floating around the menu area.

All this may sound terribly dangerous but it has worked for me without problems. Well, you could perhaps accidently [IClose,…] a ZBrush default subpalette but that is restored after restarting ZBrush.

The easiest way to implement this is to create a seperate ZPlugin for your current WIP ZPlugin. It could go something like this:


It should be noted that the current [IClose,…] behaviour is perhaps not quite what Pixologic intended. In other words do not expect this to work in ZBrush versions other than 3.1.

Addendum : You may have realised that you can update the size and look (icon) of zplugin buttons this way. Unfortunaly the Window ID for ZPlugins is fixed and merely increases upon each reload. At some point within the current session you will not be able to reload anymore.



good i like it