Catalog Functions
| Author: mrzwach (hiveworkshop.com) | Tags: advanced trigger catalog | |
| Source: http://www.hiveworkshop.com/forums/... | Added 13 years ago |
This tutorial will teach you how you can use catalog functions to retrieve and set data from the data editor ingame. Requires a basic knowledge of triggering.
Catalog Functions
The first catalog function is Catalog Field Value Get. In short, it tells you what the value of a certain field in the data editor is. In example,
String = Value of [Catalog] [Entry] [Field Path] for player [Any Player] <String>
The [Catalog] is the tab in the data editor the object is, such as Effects or Units.
The [Entry] is the internal name of the object. This is not always the same as the name you would see in the data editor. To find this, double click on the object and look at it's ID (pictured below).
The [Player] is the player for which it is checking the catalog data. This is because fields can be modified exclusively for specific players. Using "Any Player" simply uses the base data in the game.
Now, the Field Path is a bit more tricky. I highly recommend not trying to guess it by the name of the fields. The best way to find it is by looking at XML files (basically just text files that store data).
First, if your object is a normal ingame object, you will need to modify the field you want to look up with catalog functions. This will cause it to show up in your mods XML files, which is a lot easier than having to hunt through the massive XML files for the entire game. For example, if I want to get the movement speed of the Mothership, I would change it to a different value, such as 2. Also note that you cna right click the object and reset it to default if you want to fix any changes you made.
Then, go into the Import Manager and check the button "Show Reserved". This is to allow you to see the XML files, which are normally hidden from you. However, you must first save. Once you save, you should see a folder called "Game Data" that contains various XML files - if you don't, close the import manager and reopen it.
As you can see, the field path to modify a unit's movement speed would be "Speed" (difficult, I know). However, more complex fields can be more tricky to figure out.
Here are some examples of various XML entries, and what you can use to access them.
Named Arrays:
<Attributes index="Robotic" value="0"/>
Unit attributes are named arrays, which means that in order to access the "Robotic" attribute, you would use a field-path of "Attributes[Robotic]". A 1 in this field signifies that the unit is robotic, while a 0 signifies they are not.
Arrays with Subtypes:
<WeaponArray index="0" Link="GlaiveWurm" Turret="AutoTurret"/>
<WeaponArray Link="PsionicShockwave"/>
This is an example of an array with subtypes. In order to get the first weapon, you would use "WeaponArray[0].Link", while if you wanted to get the first weapon's turret, you would use "WeaponArray[0].Turret".
For the second weapon, however, it does not appear to have an index (this is true for many arrays). For the purpose of getting it from a catalog, however, it still has an index, but it just isn't visible. To get the second weapon link, you would use "WeaponArray[1].Link". Essentially, just look at it in the Data Editor and see what position it is to get the index.
Editor Comments:
<!--This is a comment!-->
Unfortunately, you cannot load editor comments ingame. This is due to the fact that they are not actually read by the game engine. :|
Command Cards:
<CardLayouts index="0">
<LayoutButtons Face="TerranInfantryWeaponsLevel1" Type="AbilCmd" AbilCmd="EngineeringBayResearch,Research3" Row="2" Column="3"/>
<LayoutButtons Face="YamatoGun" Type="AbilCmd" AbilCmd="Yamato,Execute" Row="2" Column="4"/>
</CardLayouts>
Command Cards are somewhat tricky to work with, as they do not tell you what index of the array certain things are.
Basically, CardLayouts is the command card array (0 to 3, 0 is the base command card, 1-3 are submenus like building), and LayoutButtons is the button array on the command card.
Therefore, if I wanted to get the Face (or the button) of the Yamato Gun ability, I would use "CardLayouts[0].LayoutButtons[1].Face".
However, you must also consider that there may already be things in the LayoutButtons array if your unit is based off of a standard unit. The easiest way to figure out how many indices have already been used up is to simply count the number of buttons already on the command card, and add that to the value of your array. So I would actually use "CardLayouts[0].LayoutButtons[6].Face", because the unit I gave that ability to already have 5 buttons on it's command card.
External Strings:
<Description value="Button/Tooltip/Zealot"/>
Many "text" values do not actually contain the data which you would enter into them in the data editor. For instance, if you directly pulled out the description of a zealot with catalog functions and displayed it as a debug message, it would appear as "Button/Tooltip/Zealot".
In order to display this properly, you need to use the function "Convert Game Text", and input the string you get from the catalog function.
In example,
Debug Message
Text: Convert Game Text
Path: Catalog Field Value Get
Catalog: Units
Entry: "Zealot"
Field Path: "Description"
Player: Any Player
Type: Type 1
UI: Do
Linked Data Entries:
For many things, you can get strings from catalogs, and use these strings to get other data entries linked to the original data entry. For example,
<CUnit id="Mothership">
<AbilArray Link="Yamato"/>
</CUnit>
<CAbilEffectTarget id="Yamato">
<Cost index="0">
<Vital index="Energy" value="125"/>
</Cost>
<CmdButtonArray index="Execute" DefaultButtonFace="YamatoGun"/>
</CAbilEffectTarget>
<CButton id="YamatoGun">
<Icon value="Assets\Textures\btn-ability-terran-yamatogun.dds"/>
</CButton>
Starting with the Mothership, you can use catalog functions to retrieve the Ability link "Yamato". Then, you can use catalog functions on the Yamato ability to retrieve it's energy cost or to retrieve the button it uses. If you get the ID of the button, you can then use it to get the icon path for that button and thus display it with triggers.
Catalogs
Local Variables
ability = "" <String>
energy cost = 0 <Integer>
button ID = "" <String>
icon = "" <String>
Actions
Variable - Set ability = (Value of Units "Mothership" "AbilArray[0].Link" for player Any Player)
Variable - Set energy cost = (Integer((Value of Abilities ability "Cost[0].Vital[Energy]" for player Any Player)))
Variable - Set button ID = (Value of Abilities ability "CmdButtonArray[Execute].DefaultButtonFace" for player Any Player)
Variable - Set icon = (Value of Buttons button ID "Icon" for player Any Player)
Catalog Field Value Set
For the most part, Set works similarly to Get in that it uses the same paths for arrays and such. However, it is worthy to note that Set does not work on several fields, such as the Description (you cannot change it directly, you can only change the path for it to a different text key, e.g. giving a marine a battlecruiser's description) or Icons for buttons. Additionally, it is currently impossible to actually add new abilities to a unit without them already existing on that unit (which is how they do it in the bonus mission for the campaign).
Fields Set does not work on (known):
If you know any others, I'll add them to the list. :o
Other Useful Catalog Functions
Catalog Entry Scope: Basically, a scope is the type of an object within a catalog. For example, a Mineral Field is a Resource, a Marine is a Unit and a Missile Turret is a Structure. Scopes are useful because they can be used as arguments in other catalog functions, and can be used to differentiate between different object types.
Getting Scopes
Set Variable
Variable: String
Value: Catalog Entry Scope
Catalog: Abilities
Entry: "TerranBuild"
Note: To see the names of scopes properly, you must have "View Raw Data" activated (CTRL+D).
Other Miscellaneous Catalog Functions:
Catalog Entry Parent: Returns the "parent" of a catalog entry, or what it is based off of. Seems rather lacking in use, but hey, maybe someone can find something with it.
Catalog Entry Get: Gets the catalog entry at the specified integer index in a catalog.
Catalog Entry Count: Returns the number of entries in a catalog as an integer.
Catalog Field Count: Gives you the number of fields in a scope (ie, an object type).
Catalog Field Get: Gives you the name of a field at the specified position in a scope.
Catalog Field Value Count: Similar to Catalog Field Value Get, but instead works on arrays and tells you how many values are in the array.
Catalog Functions
The first catalog function is Catalog Field Value Get. In short, it tells you what the value of a certain field in the data editor is. In example,
String = Value of [Catalog] [Entry] [Field Path] for player [Any Player] <String>
The [Catalog] is the tab in the data editor the object is, such as Effects or Units.
The [Entry] is the internal name of the object. This is not always the same as the name you would see in the data editor. To find this, double click on the object and look at it's ID (pictured below).
The [Player] is the player for which it is checking the catalog data. This is because fields can be modified exclusively for specific players. Using "Any Player" simply uses the base data in the game.
Now, the Field Path is a bit more tricky. I highly recommend not trying to guess it by the name of the fields. The best way to find it is by looking at XML files (basically just text files that store data).
First, if your object is a normal ingame object, you will need to modify the field you want to look up with catalog functions. This will cause it to show up in your mods XML files, which is a lot easier than having to hunt through the massive XML files for the entire game. For example, if I want to get the movement speed of the Mothership, I would change it to a different value, such as 2. Also note that you cna right click the object and reset it to default if you want to fix any changes you made.
Then, go into the Import Manager and check the button "Show Reserved". This is to allow you to see the XML files, which are normally hidden from you. However, you must first save. Once you save, you should see a folder called "Game Data" that contains various XML files - if you don't, close the import manager and reopen it.
As you can see, the field path to modify a unit's movement speed would be "Speed" (difficult, I know). However, more complex fields can be more tricky to figure out.
Here are some examples of various XML entries, and what you can use to access them.
Named Arrays:
<Attributes index="Robotic" value="0"/>
Unit attributes are named arrays, which means that in order to access the "Robotic" attribute, you would use a field-path of "Attributes[Robotic]". A 1 in this field signifies that the unit is robotic, while a 0 signifies they are not.
Arrays with Subtypes:
<WeaponArray index="0" Link="GlaiveWurm" Turret="AutoTurret"/>
<WeaponArray Link="PsionicShockwave"/>
This is an example of an array with subtypes. In order to get the first weapon, you would use "WeaponArray[0].Link", while if you wanted to get the first weapon's turret, you would use "WeaponArray[0].Turret".
For the second weapon, however, it does not appear to have an index (this is true for many arrays). For the purpose of getting it from a catalog, however, it still has an index, but it just isn't visible. To get the second weapon link, you would use "WeaponArray[1].Link". Essentially, just look at it in the Data Editor and see what position it is to get the index.
Editor Comments:
<!--This is a comment!-->
Unfortunately, you cannot load editor comments ingame. This is due to the fact that they are not actually read by the game engine. :|
Command Cards:
<CardLayouts index="0">
<LayoutButtons Face="TerranInfantryWeaponsLevel1" Type="AbilCmd" AbilCmd="EngineeringBayResearch,Research3" Row="2" Column="3"/>
<LayoutButtons Face="YamatoGun" Type="AbilCmd" AbilCmd="Yamato,Execute" Row="2" Column="4"/>
</CardLayouts>
Command Cards are somewhat tricky to work with, as they do not tell you what index of the array certain things are.
Basically, CardLayouts is the command card array (0 to 3, 0 is the base command card, 1-3 are submenus like building), and LayoutButtons is the button array on the command card.
Therefore, if I wanted to get the Face (or the button) of the Yamato Gun ability, I would use "CardLayouts[0].LayoutButtons[1].Face".
However, you must also consider that there may already be things in the LayoutButtons array if your unit is based off of a standard unit. The easiest way to figure out how many indices have already been used up is to simply count the number of buttons already on the command card, and add that to the value of your array. So I would actually use "CardLayouts[0].LayoutButtons[6].Face", because the unit I gave that ability to already have 5 buttons on it's command card.
External Strings:
<Description value="Button/Tooltip/Zealot"/>
Many "text" values do not actually contain the data which you would enter into them in the data editor. For instance, if you directly pulled out the description of a zealot with catalog functions and displayed it as a debug message, it would appear as "Button/Tooltip/Zealot".
In order to display this properly, you need to use the function "Convert Game Text", and input the string you get from the catalog function.
In example,
Debug Message
Text: Convert Game Text
Path: Catalog Field Value Get
Catalog: Units
Entry: "Zealot"
Field Path: "Description"
Player: Any Player
Type: Type 1
UI: Do
Linked Data Entries:
For many things, you can get strings from catalogs, and use these strings to get other data entries linked to the original data entry. For example,
<CUnit id="Mothership">
<AbilArray Link="Yamato"/>
</CUnit>
<CAbilEffectTarget id="Yamato">
<Cost index="0">
<Vital index="Energy" value="125"/>
</Cost>
<CmdButtonArray index="Execute" DefaultButtonFace="YamatoGun"/>
</CAbilEffectTarget>
<CButton id="YamatoGun">
<Icon value="Assets\Textures\btn-ability-terran-yamatogun.dds"/>
</CButton>
Starting with the Mothership, you can use catalog functions to retrieve the Ability link "Yamato". Then, you can use catalog functions on the Yamato ability to retrieve it's energy cost or to retrieve the button it uses. If you get the ID of the button, you can then use it to get the icon path for that button and thus display it with triggers.
Catalogs
Local Variables
ability = "" <String>
energy cost = 0 <Integer>
button ID = "" <String>
icon = "" <String>
Actions
Variable - Set ability = (Value of Units "Mothership" "AbilArray[0].Link" for player Any Player)
Variable - Set energy cost = (Integer((Value of Abilities ability "Cost[0].Vital[Energy]" for player Any Player)))
Variable - Set button ID = (Value of Abilities ability "CmdButtonArray[Execute].DefaultButtonFace" for player Any Player)
Variable - Set icon = (Value of Buttons button ID "Icon" for player Any Player)
Catalog Field Value Set
For the most part, Set works similarly to Get in that it uses the same paths for arrays and such. However, it is worthy to note that Set does not work on several fields, such as the Description (you cannot change it directly, you can only change the path for it to a different text key, e.g. giving a marine a battlecruiser's description) or Icons for buttons. Additionally, it is currently impossible to actually add new abilities to a unit without them already existing on that unit (which is how they do it in the bonus mission for the campaign).
Fields Set does not work on (known):
- Image paths
- Command cards
- Models for actors (use model swap instead).
If you know any others, I'll add them to the list. :o
Other Useful Catalog Functions
Catalog Entry Scope: Basically, a scope is the type of an object within a catalog. For example, a Mineral Field is a Resource, a Marine is a Unit and a Missile Turret is a Structure. Scopes are useful because they can be used as arguments in other catalog functions, and can be used to differentiate between different object types.
Getting Scopes
Set Variable
Variable: String
Value: Catalog Entry Scope
Catalog: Abilities
Entry: "TerranBuild"
Note: To see the names of scopes properly, you must have "View Raw Data" activated (CTRL+D).
Other Miscellaneous Catalog Functions:
Catalog Entry Parent: Returns the "parent" of a catalog entry, or what it is based off of. Seems rather lacking in use, but hey, maybe someone can find something with it.
Catalog Entry Get: Gets the catalog entry at the specified integer index in a catalog.
Catalog Entry Count: Returns the number of entries in a catalog as an integer.
Catalog Field Count: Gives you the number of fields in a scope (ie, an object type).
Catalog Field Get: Gives you the name of a field at the specified position in a scope.
Catalog Field Value Count: Similar to Catalog Field Value Get, but instead works on arrays and tells you how many values are in the array.
