Data Wizard Documentation

Overview

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.

File Format

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:

1. Define input elements for the values you want the user to enter in the dialog
2. Define entry elements for catalog entries to be generated based on the inputs
3. Use condition elements to control both UI flow and data generation
4. Use validate elements to enforce rules and/or avoid generating bad data
5. Use macro elements to factor out common expressions and avoid copy/paste duplication as much as possible

Element: wizard

Attribute: id (required)

Arbitrary text identifying the wizard internally. May be used to refer to the wizard from other data.

<wizard id="PrototypeWizard">

Element: name (required)

Name of the wizard as displayed in the editor.

<name>Prototype Wizard</name>

Element: description

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>

Element: category

Text defining the category path to the wizard in the menu. Subcategories should be delimited with forward slashes.

<category>Test/Prototypes</category>

Element: hidden

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.

<hidden/>

Element: objecttypes

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.

Attributes:

• 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"/>

Element: instructions

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.

Attributes:

• 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>

Element: condition

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.

Attributes:

• 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.

Type	Description
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.

Type	Description
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.

Type	Description
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.

Type	Description
0	input must not be visible
1	input must be visible

• logic - Defines operation used to combine results of all condition requirements. Default: and.

Type	Description
and	all requirements must be true
or	at least one requirement must be true
not	at least one requirement must be false

Elements:

• 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>

Element: input

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.

Attributes:

• id - (required) Defines the identifier for the input, which may be referenced elsewhere
• type - (required) Specifies the value type and corresponding controls

Type	Description
<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

Elements

• 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

Attribute	Description
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.

Attribute	Description
value	Comma-delimited ARGB color value. Example: <color value="255,128,0,0"/>

• default - Value initially set in the control

Attribute	Description
value	(evaluated) Value string

• minimum - Minimum value for numerical inputs

Attribute	Description
value	(evaluated) Value string

• maximum - Maximum value for numerical inputs

Attribute	Description
value	(evaluated) Value string

• increment - Value increment when clicking up/down buttons for numerical inputs

Attribute	Description
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

Attribute	Description
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>

Element: validate

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.

Attributes:

• type - (required) Determines what happens when the validation fails.

Attribute	Description
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.

Elements:

• 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>

Element: macro

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).

Attributes:

• 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>

Element: entry

Entry elements define game objects, aka catalog entries, which will be created or modified by the wizard.

Attributes:

• catalog - (required) Game catalog type of the entry. Ex: Actor.
• type - (required) (evaluated) Catalog entry type. Ex: CActorUnit.

Elements:

• 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.

Attribute	Description
id	required) Name of the catalog field. For fields within structures, this should be the full field path delimited by underscores. Ex: ScoreKill,

Elements	Description
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

Attributes	Description
id	(required) Identifier of the catalog token.

Elements	Description
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>

String Evaluation

Tokens

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:

Types	Description
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

Catalog References

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#

where

• 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[0].LayoutButtons[2].Row

• # = if the reference ends with a number sign, it represents the array count for the given path, rather than a value

 * Example: CardLayouts[0].LayoutButtons#

Catalog references are expected to be terminated with either a space or closing parenthesis character.

Arithmetic

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: ()
• Spaces

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>