|
|
|
|
End User License Agreement
(EULA)
This eBook and accompanying videos, herein referred to as the product , is provided as-is with no warranties either expressed or implied. The publisher retains all copyright ownership and reserves all rights to this product. This product is only available directly from the publisher or an authorized reseller. If you obtained a copy from any other source, please visit the publisher's website to purchase a legal copy for yourself.
* You MAY NOT copy, share or distribute copies of this product in any form without prior written permission from the publisher. You MAY NOT modify, change or create derivative works based upon this product in any form or fashion or by any method. You MAY NOT sell this product or include this product in any package or collection that is for sell. You MAY NOT claim authorship in any form to this product.
* You MAY create, copyright and sell Daz Scripts using the techniques contained within this product.
Copyright (c) 2015-2017, Winterbrose Arts & Graphics. All Rights Reserved.
TABLE OF CONTENTS
To use DAZ Scripting, you must first install the DAZ Studio application. For the purposes of this tutorial, we used versions 4.8 and 4.9. The latest version is available free from DAZ 3D using the link below.
{https://www.daz3d.com/get_studio}
DAZ Script
For more information and technical references about DAZ Scripting, please visit the DAZ3D website by clicking the following link:
{http://docs.daz3d.com/doku.php/public/software/dazstudio/4/referenceguide/scripting/start}
{http://www.daz3d.com/forums/categories/daz-script-developer-discussion}
-------------------------------------------------------------------------------------------------------
Qt Script
For more information about Qt Script, you can visit the Qt Homepage at this link:
{http://www.qt.io/}
-------------------------------------------------------------------------------------------------------
ECMA Script
For more information about ECMA, you can visit several websites for more information about the ECMA language and standards:
{http://www.ecmascript.org/index.php}
forwards to
{https://github.com/tc39/ecma262}
{https://en.wikipedia.org/wiki/ECMAScript}
For this tutorial, we will be using the Layout "City Limits Lite" and the Style "Darkside". If you are already comfortable with the DAZ Studio working environment, you may choose to use whatever Layout/Style that best suites your needs. If you want to change your layout to match, on the main menu select the option Window / Workspace / Select Layout.
In the popup window, select City Limits Lite in the Layout field near the top and click the Accept button at the bottom.
If you want to change your style to match, on the main menu select the option Window / Style / Select Style.
In the popup window, select Darkside in the Style field near the top and click the Accept button at the bottom.
Scripting is another word for "programming". The biggest difference between the two terms is that Scripting is usually application specific whereas Programming is usually Operating System (O/S) specific (ie Windows/Linux/PC/MAC). You may also hear people refer to scripting/programming as "coding". Scripting as used in this tutorial allows you to write a set of instructions for DAZ Studio to execute. In this manner, you can automate and even extend the wide range of features already available in the DAZ Studio application. For those with some programming experience, DAZ Script is an extension of the QtScript and ECMAScript languages and looks similar to JavaScript.
You will be using the built-in Script IDE pane in DAZ Studio for the scripts we will be writing. Depending on your DS workspace configuration, the Script IDE pane may be free floating or a tab docked into another pane.
Free Floating Pane
As you can see in screenshot below, the Script IDE pane is nowhere to be found.
If you do not see the Script IDE pane or tab anywhere on your workspace, you can open it up from the main menu using Window / Panes (Tabs) / Script IDE.
Once you have opened the Script IDE pane, you can leave it free floating or you can click on its header bar and drag-n-drop it (referred to as docking) onto the section of your choosing where it will appear as a tab now. We have chosen to dock our Script IDE pane in the same section as the Viewport.
Most scripts that you wish to write will need to interact with the end user. One of the biggest joys when scripting is when your script runs perfectly the first time. So before we write our first DAZ Script, we will give you some quick pointers that will keep you from scratching your head when your script won't function properly.
When writing DAZ Script, you must be aware that it is a case-sensitive language. That means a small letter like "a" is treated differently than a capital letter like "A". For humans, it may all read the same but it will be treated totally different by the Script interpreter. Here are some examples of similar looking identifiers that are recognized as different identifiers by the IDE:
johnny......... Johnny
Watson dr......... Watson Dr
mr reynolds......... Mr Reynolds
We have used bold to show you what is different in each entry above, but as far as DAZ Scripting is concerned, each of the items listed above are different.
The end of each instruction line in script (code) should end with a carriage return or enter character (sometimes referred to as a new line). If you want to have more than one instruction on a line, you will need to separate each instruction set with the semi-colon ";" character. This will all make sense later on as you create longer and more useful scripts.
You will type each line of instructions directly into the IDE on its own line or separated by semicolons. Let's start with the classic Hello World message used by other languages. Even though it may look strange, just type the following on line 1 in the editor:
MessageBox.information( "HELLO WORLD!","","")
Did you notice that the IDE has its own menu bar? When we address items on the menu bar, use the Script IDE menu unless stated otherwise. To run your script, you can click on File / Run [Continue] Script or press the F5 key.
If you typed everything correctly, then you should see a popup message box.
NOTE:
If nothing happened, be sure that the Capitalization is correct.
Wasn't that fun? You won't believe all the power available through scripting.
You will find that DAZ Studio has a default folder for scripts located under the DAZ Studio Formats in the My DAZ 3D Library section.
Most Windows users can find it here:
C:\Users\Public\Documents\My DAZ 3D Library\Scripts\
When creating scripts for distribution, you should save them to this folder or your own sub-folder created in this location. You can create the sub-folder (if needed) at the time you first save your new script. You can find the scripts that accompany this tutorial in the sub-folder titled Winterbrose.
We know that the script is very small, but let's go ahead and save it anyhow so that you can see how to save your work. The title/filename of your script is displayed in its own tab. If you have not saved your script, it will be shown as "Untitled".
On the menu, select File / Save Script.
If this is the first time you are saving your script, use the popup to browse to where you wish to save your script, give it a filename, and click the Save button. Otherwise, it will save to the already designated location with the same filename.
We chose to name our script file as "HelloWorld". The default file extension will be ".dsa" for routine/regular saving of script files. You will also notice that the title in the tab has changed to "HelloWorld.dsa" to match our filename.
Since we are writing our script in DAZ Studio 4.8, it has kindly inserted that information and a blank line so that we (and others) will know which version was originally used to create and test this script.
If you have previously saved your script and wish to save it under a new filename or in a new location, you can select File / Save Script As.
When you save a script in the My DAZ 3D Library, it will not have a thumbnail image other than the default DAZ logo.
If you decide to create a custom thumbnail image, be sure to make it 91x91 pixels in size and use the PNG format with transparency for a higher quality thumbnail. Also, try to avoid placing anything important in the upper-right portion of your thumbnail image where the Script text overlay may appear.
Here are some sample thumbnails used with other DAZ Scripts.
To begin a new script, choose File / New Script from the Script IDE menu bar.
You can work on more than one script at the same time which will each appear in separate tabs in the IDE pane. You can see in this screenshot that there are 2 scripts opened in the Script IDE pane:
Move My Character.dsa and Hello World.dsa .
If your script is loaded on a tab in the IDE, you can execute/run it by using File / Run [Continue] Script on the menu or by pressing the F5 key. However, once it has been saved and is part of you re My DAZ 3D Library, you can simply browse to its location and then double-click on its thumbnail icon to run it. For instance, to execute/run our Hello World example we would double-click the thumbnail.
Once you have saved your script, you can reload or open it again at a later time using File / Open Script from the menu bar.
Use the File Browser to locate and load your script file.
When you have loaded a script, if you have made changes to the script without saving it, you can use the Reload Script command to recover the original script.
When you are finished with one or more scripts, you can close them. For a single script, use File / Close Script from the IDE menu. To close all open scripts, use File / Close All Scripts.
When you open up the IDE, you normally would just write your script and save it as a non-encrypted script with an extension of .dsa . While you re developing and running your scripts, this is probably the mode you will use the most. You can even save them in the non-encrypted format if you are going to share them with friends, family, or even on the social media pages. However, for your scripts that you want to sell or to share without revealing the code, you are going to use encrypted scripting which we will demonstrate in the next section. In a nutshell, non-encrypted scripts are readable by yourself and anyone else wants to look at the code.
Encryption is simply a way of hiding your actual code from the prying eyes of others. In the beginning, you will not need to worry much about saving your files using encryption. However, if you continue to learn DAZ Scripting and eventually write an awesome utility, you may want to consider saving the "published" version with encryption.
To save an encrypted version of your script, select File / Save Encrypted Script.
Please note that an encrypted script is saved with the ".dse" extension.
Below is how our nice little Hello World app looks when saved normally (.dsa) and with encryption applied (.dse). As you can see below, the encrypted version is not easy at all to interpret (read).
When an encrypted script file is loaded into the IDE, the contents (code) will not be shown.
If you feel that you need to encrypt your work before distributing or publishing it, then you will definitely want to save a "dsa" version as well.
NOTE:
Always save a non-encrypted version of your file for updates/changes that may be required later on.
WARNING:
Encrypted scripts will not execute in version of DAZ Studio whose version is earlier than that version which it has been encrypted with. If you use DS 4.8 to create dse, it will not run in DS 4.6.
Up to now we have just used one line of code, but just imagine that your script consisted of hundreds of lines of code. Before we move on to creating longer script files, we will quickly discuss the Line number and Column number locators.
You will find that when your scripts provide a lot of functionality in DS, they may be composed of many lines of code. To make things a bit easier on you, the bottom of the IDE displays the line (Ln) and column (Col) location of the current cursor position within the editor.
Another benefit of having the line numbers in the editor is for tracking down errors. In the example below, we have intentionally inserted an error ("ccc") at the end of Line 26. DS reports the error at line 28 but by its description "variable: ccc" you can quickly see that it is at the end of Line 26.
As you progress in writing your own scripts, you will find line numbers and column numbers quite useful for debugging (correcting errors).
Before we move on to our last exercise, we will briefly discuss the print function. You can use the print function to help test and debug your scripts. When you run a script from within Daz Studio, the output from the print function will go into the Log file. You can view the log file from Help on the main menu.
When running a script in the IDE, using the print function will output the specified information to the Log File and to the output panel located below your script code.
NOTE:
New Log File entries are appended to the end of the existing log of information. Start your review at the bottom for the latest additions.
Practice Exercise - 01
It is time for some hands-on practice. Using the HelloWorld.dsa script, let s go ahead and try to insert an intentional error. At the end of the message box line, type some obvious garbage or as we did just type three x characters ( xxx ).
Now Run the script to see if it works properly or errors out.
You can see below that we have a Script Error on Line 1. This example demonstrates why it is important to understand the basic syntax of commands/functions you will use in DAZ Script. The actual error is not directly indicated but we do know it is on Line 1. If needed, we could search the online Docs for the syntax required for MessageBox.
Before we move on, be sure to either remove the changes you have made or exit the IDE without saving your script.
Comments are a way of adding information to your script that is ignored when it is run. Comments are very useful to document the various steps in the script for yourself and others so that you do not need to remember "why" you did it later on. Comments do not get executed when your script is run so you should make it a habit to heavily comment any portion of your script which is not self-explanatory. There are two types of ways to insert comments into your code; single line or multi-line.
Single-Line
A single line comment begins with two forward slash marks "//". Everything you type after the slashes on the line will be ignored by the Script IDE when run. Remember previously when DS politely added the following line of code for us:
// DAZ Studio version 4.8.0.56 filetype DAZ Script
Your single-line comments do not have to begin at the beginning of the line. They can also be used as "rest of the line" comment markers. In the following example, the "Yes" located at the end will be completely ignored.
MessageBox.information("HELLO WORLD","","")//Yes
Multi-Line
For multi-line comments you will mark both the beginning and end of the section encapsulating the comments. The forward slash and asterisk "/*" are used to mark the start of the comment section and the asterisk and forward slash "*/" are used to mark the end of the comment section. Everything between these sets of characters is ignored by the Script IDE when your script is executed. Here is an example:
/* This script was written exclusively for customers
of Winterbrose Arts and Graphics and can be used
for your own non-commercial scripting projects */
You can use the multi-line method to ignore portions of script for testing purposes or portions that are for development only and not necessary for distribution.
Practice Exercise - 02
Let s try adding single-line and multi-line comments before and after the message box portion of our previous Hello World example. Run the script after each change to ensure it works properly. Refer to the previous page for assistance.
EXAMPLE-1: Adding Comments AFTER instructions on line
MessageBox.information("HELLO WORLD","","")//Yes
EXAMPLE-2: Adding Comments BEFORE instructions on line
/*NO*/MessageBox.information("HELLO WORLD","","")
When writing your own scripts, you will eventually find yourself needing to name a variable, function or label. Don't worry about what these things are for now, you will soon enough. The names you choose are called identifiers.
In order for your script to properly use things like variables, they will have to be given unique names called identifiers that refer to them. And like everything else in scripting, there are some rules to be followed.
1. Identifier names consist of underscore(s), letters (a-z/A-Z) and numbers (0-9).
2. Identifier names must begin with an underscore "_" or letter of alphabet.
3. Identifier names cannot contain special/accented characters or punctuation.
4. Identifier names must be contiguous and cannot contain space characters.
5. Identifier names cannot be the same as any reserved words used by DAZ Script.
boolean
break
byte
case
catch
char
class
const
continue
debugger
default
delete
do
double
else
enum
export
extends
false
finally
float
for
function
goto
implements
import
in
instanceof
int
interface
long
native
new
return
short
static
switch
synchronized
this
throw
throws
transient
true
try
typeof
var
volatile
while
with
There are several categories of data that can be used in DAZ Scripting. We will focus here on variables. You can use variables to store numbers, strings (groups of letters, numbers and special characters), objects, and Boolean values (true/false values). We will demonstrate how they are used after we give you a short description.
The designation "variable" comes from the very fact that the data is varying and can be changed, just like the meaning of the real world word variable .
variable means Changing
If we were to track how much time is passing from the moment an event occurred, we might use a variable like this:
var MinutesElapsed
Before you can use a variable, it must be declared using the var statement in your script. This tells DAZ Studio that you are defining a variable to be used with your script and some memory needs to be set aside for it in the computer.
You can think of variables as short term memory in that they store data (information) that is not part of your written script but is necessary for your script to run properly. For instance, if your script was going to ask the user for his/her name, then it would need to be stored somewhere so you could refer to it.
var FirstName
You are going to find variables very useful in your scripting and will rarely write a script without them.
In order to use your variables, you will have to give them some value or data to store. In DAZ Script, you use the equals sign (=) to assign values to variables. The information contained within a variable can change as often as needed for your script. Please note that a variable only needs to be declared one time or the first time it is used. You should make it a habit to go ahead and assign it a value similar to how you intend to use it.
var AgeInYears = 0
Once the variable has been declared, you can change its value at any time using the assignment operator = (the equals sign).
AgeInYears = 21
CAPITALIZATION:
When typing anything into your script files, please remember that the DAZ Script environment is case-sensitive. This applies to built-in commands and functions as well as items you define like variables.
You can think of Camel Case as the method of mixing caps and small letters to enhance the readability of your variable names. It gets its name from how the shapes of the caps and small characters cause rises in the upper edge of your chosen name similar to how the humps of a camel look on the camel s back.
There are a couple of styles for Camel Case, but we recommend that you use the form often referred to as Title Case in which identifier names begin each word with a capital letter followed by lower case letters for the rest of the word. In comparing the following examples, you can see how much easier it is to recognize or distinguish the variable using Camel Case when reading or scanning your code.
Use This or This but not this
FolderCount folderCount foldercount
You do not have to use prefixes with your identifiers, however it is common practice to prefix the given name with a lower case letter indicating the variable type. In this fashion, you will always know the type of data being stored within the variable without having to search for its declaration line. For example, if you were using plain numbers (or integers) to count how many "actors" you found in a scene, you might name your variable "nActors". Here are some common prefixes:
a......... Array
b......... Boolean
n......... Number
o......... Object
s......... String
NOT DEFINED:
Variables that are declared without an assigned value will be considered undefined until such time as you assign an initial value.
Practice Exercise - 03
In this exercise, we will use print function to show both undefined and assigned variable results. Let s start a new script and declare a few variables without any assignment operators. Start a new script and type this code:
var myScriptName;
var nNodes;
var nHoursInDay;
print (myScriptName,nNodes,nHoursInDay);
When you run/execute the script in the IDE, the output from the print function will appear in the panel beneath your script editor.
You can see that the variables are undefined in the output panel and Log File:
Each line is preceded with DEBUG: because this is output from the debugging utility built in to the editor.
Try assigning some values to the variables and run the script again to test it. You can use any values you like, but here is what we used:
var myScriptName = Assigning Values ;
var nNodes = 0;
var nHoursInDay = 24;
If everything went well, your output panel should display the values you used.
Did you notice the quotation marks used for the first variable value assignment? When assigning a string value, the alphanumeric characters must be encapsulated in quotation marks. We will cover strings in the next section.
NOTE:
You should make it a habit to run your script after any changes have been made to ensure you did not make any typos or errors in your coding.
We hope that you have enjoyed this tutorial and have found some inspiration to perhaps code your own scripts to control the Daz Studio environment. Be sure to check out the Forums referenced in the Important Links section.
The Scripting Made Simple DS series consists of six volumes covering a wide-variety of topics to you you started with Daz Script.
SMSv1 - Volume 1 Intro To Daz Script (available as MP4, PDF, and WMV)
SMSv2 - Volume 2 Mathematics and Looping (available as MP4, PDF, and WMV)
SMSv3 - Volume 3 Strings, Dates and More (available as MP4, PDF, and WMV)
SMSv4 - Volume 4 Arrays and Creating Functions (available as MP4, PDF, and WMV)
SMSv5 - Volume 5 Input and Output Controls (available as MP4, PDF, and WMV)
SMSv6 - Volume 6 Manipulate Objects in Scene (available as MP4, PDF, and WMV)
| Best
viewed at 1024 x 768 or higher. |
 |
Thanks for Visiting WINTERBROSE Arts & Graphics |