Viz Artist User Guide
Version 5.0 | Published December 20, 2022 ©
Script Editor
This section explains how to work with the Script Editor. To switch to the scripting perspective, select Scripting from the workspace menu.
Viz Artist can be scripted on two levels - using Scene Scripts or Container Scripts. In addition you can write Viz Engine Shaders within the scripting environment. The following chapters mainly refer to Viz Scripting. For information on how to write Viz Engine Shaders, see Viz Engine Shader Techniques.
Before adding scripts and code, the designer needs to think about where the logic should reside.
This section contains the following topics:
Scene Scripts
-
If there are functions that act like an interface to the scene, it's a good idea to add this logic as a scene script.
-
If functions or variables are used throughout several other scripts within the scene, the scene script is the proper location for those.
On the other hand, if the script code is container-specific or planned for a container prototype-instance(s) approach, the script code should be hosted in a container script.
Script Editor Properties
Although the Scene Script Editor and the Container Script Editor have the same properties and functionality, a script created in one editor can not be placed in the other editor's folder. This section provides details on the Script Editor's properties and context menu.
The Script editor is divided into the following sections:
-
Editing Area
-
Function, Callbacks and Symbols
-
Search and Replace
-
Scripting Reference
Editing Area
Select which type of script you wish to edit by clicking the tabs at the top of the menu:
Container Script: Container scripts reside on containers and are mainly responsible to add logic onto single container(s).
Scene Script: All global functionality or logic that apply to the whole scene can be defined as a Scene script.
Shader Design Environment: Introduced in Viz Engine 4. See Viz Engine Shader Techniques for more information.
A script can have three states: running, editing mode or error mode.
To toggle between run mode and edit mode, click on the 
respective the 
button.
A script that has been successfully compiled and runs without any errors, can be saved as a Script plugin. This is done by clicking on the 
button. For more information, please see chapter Create Script-based Plug-ins.
The status of the compile status is shown under the editor area: 
To start editing your script, simply start by typing one of the keywords, for instance "dim" or "Sub". the Editor automatically offers you a list of possibilities and auto-completes your selection. Example: Start adding a new sub by typing "Sub O...". A list of valid options immediately shows up:
The script editor automatically colorizes keywords for a better reading.
Once an error occurs (when pressing the Compile & Run), the editor shows an error and automatically jumps to the line the (first) error occurs.
Right clicking inside the Editor opens the Context menu:
Changing the font size: The font size of the script can be changed using CTRL + mouse wheel.
Function, Callbacks and Symbols
The function tab shows a list of pre-defined functions within your script, including the built-in Callbacks and self-defined functions. Clicking on a function automatically moves the view of your editor to this selected function:
The callback tabs shows a list of all built-in callbacks Viz is using. For example the OnInit is called whenever the script get initialized. Callbacks written in Bold are used by the current script.
Note: Callbacks differ between Scene and Container Scripts.
Symbols represents a list of fixed values and Enums, for example the fixed values for the Texture quality levels like TX_QUAL_MIPMAP. These values are pre-defined in Viz Engine.
Search and Replace
The search functionality is very easy to use. It allows you to search for simple terms or even replace them automatically.
Add the term you want to search for and press either:
show the next or the previous occurrence of your search term.
When a replace term has been entered, you can
replace a single or all occurrences of your search term with your replace term.
To better define your search criteria, specify your options on the right:
Switches between upper and lowercase search
Searches for whole words (separated by a white space character) or by a sequence.
Allows to search by a Regular Expression, based on Perl's regexp language.
Example
To match strings containing 'test' or 'my' or 'search' but only match whole words (not 'searches'), enter \\b(test|my|search)\\b in the Find field.
Tip: You can also search for the occurrence of a word within scripts from the Scene Tree. For example, to show all scripts that contain an "onExecPerField" procedure.
Scripting Reference
The Scripting documentation is usually located on your hard drive in C:\Program Files\Vizrt\VizEngine\Documentation\viz-script-doc-webhelp. This view allows you to browse the documentation without opening a browser window and switch between Viz Artist and the documentation.
Lets you open the scripting reference in a browser window.
Navigation buttons:
Navigate through the documentation by clicking on the home button to return to the main page or use the back and forward buttons to browse through your navigation history.
Tip: Sync your documentation view with the script editor. Click on a keyword within the editor and the Scripting Reference automatically shows you the correct chapter within the scripting documentation. For example, if you click on "vertex", the Script reference automatically shows you the chapter about vertex, as in the screenshot below:
