VFX WIZARD FILE FORMAT
----------------------

Copyright VFX Systems Pty Ltd 2009



Wizard variables
----------------

To assign the string "bar" to the variable "foo":

    foo: bar

To assign data lines (one line per index) to array
variable "foo":

    foo:
    ...
    line1
    line2
    etc
    ...


Standard variables
------------------

Example from sampletank wizard:

    id: 991629
    dll_name: IK SampleTank 2 SE/SampleTank2 SE.dll
    name: SampleTank2 SE
    is_synth: 1
    parameter_count: 97
    program_count: 1
    has_editor: 1
    editor_width: 851
    editor_height: 470
    name_abbreviation: ST2se


Other variables
---------------

dont_free_library_on_mac 
- Never unload dll on mac.

dont_free_library_in_vfx_application - Never unload dll on mac/pc.

must_be_licensed_on_vmachine
licence_required            
license_required
- Don't run on v-machine unless licensed (these all mean the same thing).

no_vst_chunks 
- Don't use vst chunks, just use parameter dumps instead.

no_set_program_before_chunk
- Don't set a plugin's program before setting it's chunk.


Special array variables
-----------------------

"dirs_to_copy"

Each line specifies a directory to copy into the plugin folder when the
plugin is imported.

    src:dst;patterns

"src" can be an absolute path, or can start with "/" to represent a
path relative to the "C:" drive.

"dst" is optional, and specifies a path relative to the plugin's folder
in the vfx library.

"patterns" is a semicolon-separated list of include/exclude patterns.
Each pattern has a keyword "include:" or "exclude:". If the keyword
is left out, then an "include" operation is assumed.

The match is performed on the full source path, and not just the filename. An
initial '*/' is implied if it is not explicitly written in, so "exclude: Organ"
will match against only the final path component.

e.g.  foo:bar;include:*.foo;exclude:fred
      foo:bar;exclude:foo*.txt
      foo:bar;exclude:*/Organ


"files_to_copy"

Each line specifies a file to copy into the plugin folder when the
plugin is imported.

    src:dst

"src" can be an absolute path, or can start with "/" to represent a
path relative to the "C:" drive.

"dst" is optional, and specifies a path relative to the plugin's folder
in the vfx library.


"vmachine_files_to_create"

Each line specifies a wizard array variable whose name happens to be the
path to a file to create, at assimilation time, relative to the plugin folder.
The array variable contains the file contents.

    vmachine_files_to_create:
    ...
    SampleTank 2 SE/ST2SEPref/ST2SEPref.txt
    ...
    SampleTank 2 SE/ST2SEPref/ST2SEPref.txt:
    ...
    contents of prefs file
    ...


"files_to_create"

Each line specifies a wizard array variable whose name happens to be the
path to a file to create, at import time and at licensing time, relative
to the plugin folder. The array variable contains the file contents.

    files_to_create:
    ...
    SampleTank 2 SE/ST2SEPref/ST2SEPref.txt
    ...
    SampleTank 2 SE/ST2SEPref/ST2SEPref.txt:
    ...
    contents of prefs file
    ...


"registry_keys"

Each line in this array variable is the line of a windows ".reg" file. The .reg
file as represented here is imported at plugin assimilation time.


"import_sequence"

A wizard array variable containing commands to execute at import time.


"license_sequence"

A wizard array variable containing commands to execute at license time.



Sequence commands
-----------------

input_prompt;variable;user_prompt;inital_value

Prompts user with "user_prompt" for value of wizard variable "variable".
"initial_value" is optional. If left out, then the intial value is either
the existing value of "variable" or else the variable mnemonic itself.


info_prompt;value;user_prompt

Shows user the string in "value" in a text box, with prompt string
"user_prompt".


gui_msg;message

Shows "message" to user.


execute_tool;variable;response_start;response_length;tool;arg1;arg2;etc

Runs special tool "tool" on V-MACHINE and stores it's output beginning at
"response_start" and of length "response_length" into wizard variable
"variable". The tool is executed with arguments "arg1", "arg2", "etc".


check;value1;operator;value2

Compare values "value1" and "value2" with comparision "operator". Operator
can be "==" or "!=". The sequence is aborted if the comparison fails.


save_file_prompt;file;user_prompt

Prompts the user with "user_prompt" for where to save the file "file".
The contents of wizard variable "file" are saved to the file "file"
in the location chosen by the user.


parse_input_file;variable;file;start_delim1;end_delim1;start_delim2;end_delim2;etc1;etc2

Prompts user to find file "file", then scans text into "variable" that is
the concatenation of text inside the given delimiters.


store;variable;value

Puts the literal expanded text from "value" into "variable". Useful for
capturing PC information at import/licensing time.



Wizard functions
----------------

$VFX_EXPAND(foo)

The string value of wizard variable "foo".


$VFX_REG_STRING(key,value,default)

The windows registry value "value" in key "key".
"default" is optional.
If key is an integer key, then the value will be the string representation
of the value.
If key is a binary key, then the value will be a string of comma-separated
2-digit hex numbers. e.g. "00,F3,0A,51,34,35"


$VFX_CLOSE_BRACKET()

Puts in a ")", in case you need one inside a $VFX_FOO()


$VFX_FORWARD_SLASHES(foo)

All slashes and repetitions of slashes in "foo" become a single "/".

e.g. "foo/////nod\hon\\nork\\\\\\potato" -> "foo/nod/hon/nork/potato"


$VFX_BACK_SLASHES(foo)

All slashes and repetitions of slashes in "foo" become a single "\".

e.g. "foo/////nod\hon\\nork\\\\\\potato" -> "foo\nod\hon\nork\potato"



$VFX_DOUBLE_BACK_SLASHES(foo)

All slashes and repetitions of slashes in "foo" become "\\".

e.g. "foo/////nod\hon\\nork\\\\\\potato" -> "foo\\nod\\hon\\nork\\potato"


$VFX_BUILTIN(foo)

Expand VFX builtin variable "foo". If "foo" expands to a path, then
the path contains forward slashes.

If "foo" is prefixed with "win_" (e.g. "win_foo"), then the path
is relative to a windows "drive" with forward slashes. (e.g. "X:/foo/bar").


$VFX_BUILTIN(user_name)
The windows user's username.
JoeBlow


$VFX_BUILTIN(program_files)
The path to the windows "Program Files" folder.
C:/Program Files


$VFX_BUILTIN(win_program_files)
The path to the windows "Program Files" folder.
C:\Program Files

$VFX_BUILTIN(common_program_files)
The path to the windows "Program Files/Common Files" folder.
C:/Program Files/Common Files

$VFX_BUILTIN(win_common_program_files)
The path to the windows "Program Files/Common Files" folder.
C:\Program Files\Common Files


$VFX_BUILTIN(user_documents)
The path to the current windows user's documents folder.
C:/Documents and Settings/UserName/My Documents

$VFX_BUILTIN(win_user_documents)
The path to the current windows user's documents folder.
C:\Documents and Settings\UserName\My Documents


$VFX_BUILTIN(common_documents)
The path to the windows common documents folder.
C:/Documents and Settings/AllUsers/Documents

$VFX_BUILTIN(win_common_documents)
The path to the windows common documents folder.
C:\Documents and Settings\AllUsers\Documents


$VFX_BUILTIN(application_data)
The path to the common application data folder.
C:/Documents and Settings/All Users/Application Data

$VFX_BUILTIN(win_application_data)
The path to the common application data folder.
C:\Documents and Settings\All Users\Application Data


$VFX_BUILTIN(user_application_data)
The path to the current windows user's application data folder.
C:/Documents and Settings/UserName/Application Data

$VFX_BUILTIN(win_user_application_data)
The path to the current windows user's application data folder.
C:\Documents and Settings\UserName\Application Data


$VFX_BUILTIN(user_local_application_data)
The path to the current windows user's local application data folder.
C:/Documents and Settings/UserName/Local Settings/Application Data

$VFX_BUILTIN(win_user_local_application_data)
The path to the current windows user's local application data folder.
C:\Documents and Settings\UserName\Local Settings\Application Data


$VFX_BUILTIN(dll_dir)
The path to the directory containing the plugin DLL.
C:/Program Files/Steinberg/VstPlugIns (example if called on import)
C:/Documents and Settings/UserName/My Documents/My Music/VFX Library.vfxlibrary/plugs/Albino3 (example if called after import)
P:/Albino3 (example if called from inside of V-Machine)


$VFX_BUILTIN(destination_dll_dir)
The "destination" path to the directory containing the plugin DLL.
Only expands to a non-empty string when called inside the import sequence,
in which case the destination dir is the plugin dir to be copied to
inside the active library.
C:/Documents and Settings/UserName/My Documents/My Music/VFX Library.vfxlibrary/plugs/Albino3