Data Wizard Documentation
- 1 Overview
- 2 File Format
- 3 Element: wizard
- 3.1 Attribute: id (required)
- 3.2 Element: name (required)
- 3.3 Element: description
- 3.4 Element: category
- 3.5 Element: hidden
- 3.6 Element: objecttypes
- 3.7 Element: instructions
- 3.8 Element: condition
- 3.9 Element: input
- 3.10 Element: validate
- 3.11 Element: macro
- 3.12 Element: entry
- 4 String Evaluation
A "data wizard" is a template for the creation and modification of catalog entries and field values within the Data Editor. Wizards may be used to simplify and standardize complex or repetitive data work.
Data wizards are defined within XML files using the extension .BlizWiz. For complete details on the file format, please see the File Format section. Wizard files may exist within these locations:
- EditorWizards folder within the user-specific game folder. These will always be loaded. The user folder may be disabled in File > Preferences > Wizards.
- Additional external folders which may be configured in File > Preferences > Wizards. These will always be loaded.
- Anywhere inside a map or mod archive (or folder). These will be loaded when the document is active in the editor, either directly or as a dependency.
The editor will automatically detect and reload any modifications made to wizard files while it is running, including adding or removing files. The wizard dialog itself will not reload the wizard on the fly, however, and must be closed and reopened.
Data wizards are defined within XML files using the extension .BlizWiz. A wizard file may contain any number of wizard definitions. The global element of the file should be wizardfile. Any element marked with (evaluated) below will make use of the wizard string evaluation mechanism. See the String Evaluation section for details. Creating a wizard will generally follow these steps:
- Define input elements for the values you want the user to enter in the dialog
- Define entry elements for catalog entries to be generated based on the inputs
- Use condition elements to control both UI flow and data generation
- Use validate elements to enforce rules and/or avoid generating bad data
- Use macro elements to factor out common expressions and avoid copy/paste duplication as much as possible
Attribute: id (required)
Arbitrary text identifying the wizard internally. May be used to refer to the wizard from other data.
Element: name (required)
Name of the wizard as displayed in the editor.
Text describing the wizard in detail. Shown in the Manage Wizards dialog, but not in the wizard dialog itself.
<description>Example wizard definition illustrating the complete file format</description>
Text defining the category path to the wizard in the menu. Subcategories should be delimited with forward slashes.
Optional element which indicates that the wizard is not shown within the wizard menu. This is primarily useful for embedded wizards that are not run directly.
Defines which game object types are supported by the wizard. Each attribute defines a different wizard usage case, and the value should be a list of game object type identifiers delimited by semi-colons.
- create - supported types when creating new objects through the wizard dialog
- load - supported types when loading existing objects in the wizard dialog
- view - supported types when viewing existing objects directly in the Data module with wizard view
<objecttypes create="Unit;Actor;Model" load="Unit;Actor" view="Unit"/>
Defines optional instruction text which will appear at the top of the wizard dialog. Multiple elements may exist, where each one is associated with a different wizard page. Text contents may contain multiple lines, and is expected to be indented within the element. This indenting will be removed when parsing the file.
- page - one-based index of the wizard page where the instructions appear. Default: 1.
<instructions page="1"> This wizard illustrates all possible wizard functionality. - Creates a unit, actor, and model entry - Enter 'math' in the string input for sample arithmetic expressions </instructions>
Conditions define boolean operations applied to input values. When defined directly within a wizard element, represents a named condition to be referenced elsewhere. When defined inside other elements, this may be either a reference to a named condition, or an inline condition with no name.
- id - At the wizard level, defines the identifier for the condition. At other levels, this is the id of the already-defined condition to be used. If no id is specified, the element will define a new inline condition.
- input - Identifier of the input from which the value will be checked. Inputs within embedded wizards may be referenced by using a semicolon to separate the embedded wizard input id and the input id within that wizard (ex: SubWizardId:InputId)
- value - (evaluated) The required value to be compared with the input value.
- match - String matching option to use when comparing values. Default: equal.
|equal||entire string must be the same|
|begin||input value must begin with the required value|
|end||input value must end with the required value|
|contain||input value must contain the required value anywhere|
- operator - Numerical comparison operator to use when comparing values. Both values must evaluate to numbers. Not used by default.
|equal||both values must be equal|
|greater||input value must be greater than the required value|
|greaterequal||input value must be greater than or equal to the required value|
|less||input value must be less than the required value|
|lessequal||input value must be less than or equal to the required value|
- nocase - If set to 1, indicates that string comparisons will not be case sensitive. Default: 0.
- empty - If present, indicates a required state for the input value.
|0||input must have a non-empty value|
|1||input must have an empty value|
- visible - If present, indicates a required state for the input visibility.
|0||input must not be visible|
|1||input must be visible|
- logic - Defines operation used to combine results of all condition requirements. Default: and.
|and||all requirements must be true|
|or||at least one requirement must be true|
|not||at least one requirement must be false|
- condition - Nested condition elements combined using the defined logic operation.
<condition input="SimpleString" empty="1"/> <condition input="SimpleString" value="party" match="end" nocase="1"/> <condition id="HasOlives" input="ExtraMenu" visible="1" value="oliv"/> <condition id="BestPizza" logic="and"> <condition input="ExtraMenu" value="oliv"/> <condition input="OliveType" value="black"/> <condition input="CrustType" value="deep"/> </condition>
Inputs define values which may be entered by the user in the wizard dialog. The user interface is created based on the input type, and will be arranged in the order defined in the file.
- id - (required) Defines the identifier for the input, which may be referenced elsewhere
- type - (required) Specifies the value type and corresponding controls
|<any game type>||Any type recognized by the game catalog system may be used. This will use the same interface as the Detail View in the Data module. Ex: int32, CStringLink, CModelPath.|
|WizardCheckbox||A simple checkbox control. The value will be either "0" or "1".|
|WizardMenu||A popup menu control. Items are defined using item elements.|
|WizardRadio||A mutually exclusive set of radio buttons. Item elements define the individual buttons.|
|WizardText*||Static text used for read-only display. This input will have no value.|
|Wizard:<wizardid>||Creates an embedded wizard. See the String Evaluation section for details on referencing embedded wizards.|
- While not having a true value, WizardText inputs do support setting the text through the default and loadvalue elements, which is useful to display evaluated expressions based on loaded data
- name - Label text displayed in the wizard dialog
- tooltip - Tooltip text displayed when the user hovers the cursor over the input controls
- item - Used to populate WizardMenu and WizardRadio controls
|value||(evaluated) The value of the input when this item is selected|
|text||(evaluated) Text displayed in the control for this item|
|count||(evaluated) Optional number of times to repeat this item. Use the ITEMINDEX string token to refer to the current item index. Default: 1.|
- sorted - If present, items will be sorted by their text when displayed
- simpletext - Limits text entry to simple characters suitable for object identifiers: letters, numerals, and underscores. Only applies to string field types.
- color - Color applied to the input control. Only supported by WizardText.
|value||Comma-delimited ARGB color value. Example: <color value="255,128,0,0"/>|
- default - Value initially set in the control
|value||(evaluated) Value string|
- minimum - Minimum value for numerical inputs
|value||(evaluated) Value string|
- maximum - Maximum value for numerical inputs
|value||(evaluated) Value string|
- increment - Value increment when clicking up/down buttons for numerical inputs
|value||(evaluated) Value string|
- loadvalue - (evaluated) Value set in the control only when loading existing data into the wizard. This is considered an explicit value, and takes precedence over any implicit load values found through entry definitions, including the loadinput element
- reloadfrom - List of input identifiers, delimited by semi-colons. When any input in this list is modified, the current input will reload its value from the loadvalue element.
- nosave - If present, modifications to this input will not cause data to be saved. Useful for inputs which only affect other inputs, and do not directly modify data.
- nopreview - If present, hides any preview controls which are normally displayed for the type. Applies to all asset file path types (ex: CImagePath).
- layout - Options affecting the way the control is positioned in the dialog
|page||One-based index of the wizard page where this input appears. Pages are automatically created as necessary to accommodate all inputs. Default: 1.|
|column||One-based vertical column where this input appears. Columns are automatically sized as necessary to accommodate all inputs. Default: 1.|
|minheight||Minimum height used for this input. By default, the exact height of the control is used.|
|minwidth||Minimum width used for this input when calculating column widths. By default, the exact width of the control is used.|
- condition - Conditions which must be true for this input to be visible in the dialog. See the Element: condition section for details.
<input id="SimpleReal" type="real32"> <name>Real</name> <tooltip>Simple real value input (real32)</tooltip> <default value="0"/> <minimum value="-100"/> <maximum value="100"/> <condition input="SimpleString" value="math"/> </input> <input id="OliveType" type="WizardRadio"> <name>Olive Type</name> <item value="green" text="Green"/> <item value="black" text="Black"/> <default value="green"/> <condition id="HasOlives"/> </input>
Validate elements define rules that are checked and enforced in the wizard dialog. Any validations which fail will be displayed in the error list at the bottom of the dialog.
- type - (required) Determines what happens when the validation fails.
|error||The wizard will be unable to proceed beyond the active page until the error is resolved.|
|confirm||The wizard will only be able to proceed if the user explicitly chooses to confirm the result of the validation.|
|warning||A warning message is displayed in the error list, but it does not prevent the wizard from proceeding.|
- condition - Conditions which must be true for the validation to succeed. See the Element: condition section for details.
- text - (evaluated) Text displayed to the user when the validation fails.
<validate type="error"> <condition input="SimpleString" empty="0"/> <text>String is empty</text> </validate> <validate type="warning"> <condition input="SimpleString" value="math" logic="not"/> <text>Math test #1: i * 2 + 1 = ^TestMath1^</text> </validate>
Macro elements define value strings which may be referenced from other value strings. These are useful for factoring out common and/or complicated expressions. See the String Evaluation section for more details. Macro text is (evaluated).
- id - (required) Identifier used to refer to the macro from value strings
- replaceSrc - (evaluated) Text to be replaced with replaceDst within the value, after evaluation
- replaceDst - (evaluated) Text which will replace occurrences of replaceSrc within the value, after evaluation. This may be left empty to remove replaceSrc entirely.
- truncate - Maximum length of the value text, after evaluation. Zero is the default, and indicates no truncation.
<macro id="EntryId">PrototypeWizardUnit_^SimpleString^</macro> <macro id="TestMath1">^SimpleInteger^ * 2 + 1</macro> <macro id="RemoveSpaces" replaceSrc=" " replaceDst="">^BaseValue^</macro> <macro id="SpaceToUnderscore" replaceSrc=" " replaceDst="_">^BaseValue^</macro> <macro id="Truncate" truncate="4">^BaseValue^</macro> <macro id="RemoveSpacesThenTruncate" truncate="4">^RemoveSpaces^</macro>
Entry elements define game objects, aka catalog entries, which will be created or modified by the wizard.
- catalog - (required) Game catalog type of the entry. Ex: Actor.
- type - (required) (evaluated) Catalog entry type. Ex: CActorUnit.
- id - (required) (evaluated) Identifier of the entry being created or modified.
- useloaded - Indicates to use the identifier of the loaded entry, if any, regardless of the id element.
- allowmodify - When the wizard is being run to create entries, allows modification of an existing entry instead, if the given id already exists.
- parentid - (evaluated) Identifier of the catalog entry to be used as the parent of the current entry. Defaults to the entry type catalog default.
- count - (evaluated) Optional count of the number of entries to be processed. Use the ENTRYINDEX string token to refer to the current entry index. Default: 1.
- condition - Conditions which must be true for this entry to be processed. See the Element: condition section for details.
- field - Catalog field value to be set within the entry.
|id||required) Name of the catalog field. For fields within structures, this should be the full field path delimited by underscores. Ex: ScoreKill,|
|value||(evaluated) Value text to be applied to the field.|
|stringid||(evaluated) Defines the string identifier for fields representing localized text, typically CStringLink. If not specified, the default string id defined in catalog data will be used (if any).|
|count||(evaluated) Optional count of the number of times to process this field. Primarily useful for filling out arrays. Use the VALUEINDEX string token to refer to the current index. Default: 1.|
|index||(evaluated) Index for values within array fields. Two forms are supported: Single value (used as the index within the last array field in the field path) and Multiple values delimited by semi-colons (Useful for embedded arrays. The number of values must match the depth of the field path, and will be applied to each level appropriately. )|
|loadinput||Identifier of the input into which to apply the existing value of this field when loading entries. If the value text specifies an input identifier token by itself, the value will be loaded there without needing this element|
|cache||if present, modified values of this field will be temporarily cached in memory before the wizard dialog is accepted. This is useful to preserve all values for fields which can modify multiple different values in data depending on the current wizard state.|
|condition||Conditions which must be true for this field to be processed. See the Element: condition section for details.|
- token - Catalog token value to be set within the entry
|id||(required) Identifier of the catalog token.|
|value||(evaluated) Value text to be applied to the token.|
|loadinput||Identifier of the input into which to apply the existing value of this token when loading entries. If the value text specifies an input identifier by itself, the value will be loaded there without needing this element|
|condition||Conditions which must be true for this token to be processed. See the Element: condition section for details.|
<entry catalog="Actor" type="CActorUnit"> <id>^EntryId^</id> <field id="WireframeVariations_Number"> <index>^VALUEINDEX^ + 1</index> <count>5</count> <value>^SimpleInteger^ + ^VALUEINDEX^</value> </field> </entry>
Evaluated strings are first parsed for a variety of tokens. All wizard tokens must be enclosed within ^ characters (use a double ^^ to insert a literal ^ character). The following tokens are supported:
- ENTRYINDEX - Replaced with the zero-based index of the current entry instance
- VALUEINDEX - Replaced with the zero-based index of the current field value
- ITEMINDEX - Replaced with the zero-based index of the current input item instance
- LOADID - Replaced with the identifier of the loaded entry, if any
- Macro identifier - Replaced with the evaluated text value of the macro
- Input identifier - Replaced with the current input value
- Embedded wizard - This is primarily useful for referring to input ids within embedded wizards. Two forms are supported:
|wizardid:subtoken||The subtoken text will be evaluated within the context of the given wizard|
|inputid:subtoken||If the given input corresponds to an embedded wizard, the subtoken text will be evaluated within the context of that wizard|
Once all tokens are replaced, the text is checked for catalog references, which may be used to load values from existing catalog data. A catalog reference must have the following format: ref=TYPE,ENTRYID,FIELDPATH ref=TYPE,ENTRYID,FIELDPATH#
- TYPE = catalog type (ex: Actor, Unit)
- ENTRYID = identifier of the entry from which to load the value
- FIELDPATH = name of the catalog field
* For fields within structures, this should be the full path delimited with periods * For array values, the array index should be specified after the field name within brackets * Example: CardLayouts.LayoutButtons.Row
- # = if the reference ends with a number sign, it represents the array count for the given path, rather than a value
* Example: CardLayouts.LayoutButtons#
Catalog references are expected to be terminated with either a space or closing parenthesis character.
Once all tokens and references are replaced, the resulting text is checked for a valid arithmetic expression. If valid, the expression is evaluated to a single numerical value. Supported arithmetic expressions must contain only these characters:
- Numerals: 0-9
- Period: .
- Operators: +-*/
- Parentheses: ()
By default, the expression type is considered to be integer unless a period is present
<value>^SimpleInteger^ + ^VALUEINDEX^</value> <macro id="TestMath3">((^SimpleInteger^ - 1) * 2) / 8</macro> <macro id="KillPlusLost">ref=Unit,^LOADID^,ScoreKill + ref=Unit,^LOADID^,ScoreLost</macro>