- Joined
- Aug 18, 2009
- Messages
- 4,099
Investigating about SYLK (.slk) format and its relations in Warcraft III. Those files describe matrices and are used to define objects in Warcraft III. Like so often, there are quirks and a lacking standard, see SYmbolic LinK (SYLK) - Wikipedia, which is why it may be troublesome to get a clean implementation. Also, the format possesses more features than actually needed in Warcraft III.
Faulty SYLK files are prone to crash Warcraft III and some of those that Warcraft III is able to handle unfortunately cause errors in Microsoft Excel. One may want to view or edit the files in Microsoft Excel before using them in Warcraft III. That is why it may make sense to consider both, which only works partially, however, as the following quotations and theses will indicate. I will furthermore collect my own findings.
SYLK files consist of records read line by line. The first character states the type of record. B, for example, tells the matrix dimensions (columns and rows) and, according to the Wikipedia page, should come before cell data. C is for cell data. You may specify the column and row per cell data record. If you do not, it will take the next cell compared to the previous record. Warcraft III employs the first row as the table header. So the cells of this row define the properties for each dataset thereafter.
-----------------------------------------
1.
Warcraft III can handle more. I have tested a C (cell data) record where the string value alone is 300 characters + double quotes and confirmed that Warcraft III interprets it without trim. In this respect, I have to mention it's difficult to test string values of SYLK files in Warcraft III because there are so few string properties. Most strings are exported to text (.txt) files instead. Here, I have made use of the name property in the unitUI.slk. It can be used in conjunction with the UnitId jass native for example. Jass strings with only ASCII characters can definitely be longer than 300 characters.
2.
For Warcraft III, the doubling of the semicolon is not required, so the semantics differ. I have tested this again with the name property. If the string contains a semicolon, it must always be put into double quotes.
3.
String values in Excel must always be put into double quotes to appear correctly. In Warcraft III, it's only necessary under certain circumstances. Non-exhaustive: containing a semicolon, containing a double quote
4.
In Microsoft Excel, double quotes as parts of string values are not to be escaped, it simply accepts "abc"def". I am unsure about Warcraft III.
5.
When Warcraft III tries to read a property of an object and this property is not set, it takes a default value, which is zero for numbers, false for booleans (booleans are expressed as 1/0*) and empty string for string. In this respect, if you take a look at the standard .slks of Warcraft III, you will find that there are a lot of gibberish values like "-" sometimes used for cargoSize, which obviously should rather be an integer. Together with point 3, this implicates that you cannot safely infer the data type of a cell with the data .slk alone. The data types of properties are stated in the meta SYLK files (like UnitMetaData.slk) except for a few ones that do not possess an objMod/meta variant.
*I did not test how it behaves if you give other values.
Note that some properties do not accept everything even when reverting to a default. The auto (autocast) property in the UnitAbilities.slk causes a crash when unset, for instance. Blizzard used "_" to indicate no autocast there.
6.
Warcraft III crashes if you use the SetUnitInvulnerable jass native (with true parameter) while the AbilityData.slk does not contain an Avul object.
What also should not be missing is Abdt (Burrow Detection (Flyers)) and Aalr (Alarm). Both are hidden abilities and Warcraft III tries to use them with some unit interaction, which will cause a crash ingame if not the entry is not available. Declaring them is enough, they do not have to set properties, not even code (the specific internal ability logic the ability object uses).
7.
Warcraft III crashes if you have columns whose index is greater than the declared column count.
8.
Warcraft III crashes if the declared row count is greater than actual rows. If the declared row count is less, it still considers more rows. This hints at Warcraft III preparing an array with the capacity according to the declared row count but still progressively reading the file until EOF (which must be done anyway because you could potentially have the cell data with the least indexes at the very bottom).
9.
For some reason, beginning with a declared column count of 97 upwards, all columns from 1 to the declared column count must be set. Otherwise, Warcraft III crashes.
Warcraft III crashes if any read SYLK file has more than 96 columns.*
*I tested the UnitData.slk and it crashed during loading screen. I also tested the AbilityData.slk, which crashed right after loading screen.
10.
Warcraft III crashes when encountering empty lines before the E (EOF) record.
11.
Warcraft III crashes if an object in the UnitBalance.slk does not set the Primary (main hero attribute) property. Blizzard uses "_" to indicate none there.
Faulty SYLK files are prone to crash Warcraft III and some of those that Warcraft III is able to handle unfortunately cause errors in Microsoft Excel. One may want to view or edit the files in Microsoft Excel before using them in Warcraft III. That is why it may make sense to consider both, which only works partially, however, as the following quotations and theses will indicate. I will furthermore collect my own findings.
SYLK files consist of records read line by line. The first character states the type of record. B, for example, tells the matrix dimensions (columns and rows) and, according to the Wikipedia page, should come before cell data. C is for cell data. You may specify the column and row per cell data record. If you do not, it will take the next cell compared to the previous record. Warcraft III employs the first row as the table header. So the cells of this row define the properties for each dataset thereafter.
-----------------------------------------
1.
Each line of a SYLK input file must be no longer than 260 characters. Otherwise, Microsoft Excel will issue an error message and skip loading the overlong line.
(Source: SYmbolic LinK (SYLK) - Wikipedia)
Warcraft III can handle more. I have tested a C (cell data) record where the string value alone is 300 characters + double quotes and confirmed that Warcraft III interprets it without trim. In this respect, I have to mention it's difficult to test string values of SYLK files in Warcraft III because there are so few string properties. Most strings are exported to text (.txt) files instead. Here, I have made use of the name property in the unitUI.slk. It can be used in conjunction with the UnitId jass native for example. Jass strings with only ASCII characters can definitely be longer than 300 characters.
2.
The semicolon is treated as a field separator in SYLK, so cannot be used unescaped in data values. If a character string in the SYLK file is to contain a semicolon (; ) then it should be prefixed with another semicolon so the string would appear as e.g., "WIDGET;;AXC1254". MS Excel will strip the first semicolon on import and the data element will appear as "WIDGET;AXC1254".
(Source: SYmbolic LinK (SYLK) - Wikipedia)
For Warcraft III, the doubling of the semicolon is not required, so the semantics differ. I have tested this again with the name property. If the string contains a semicolon, it must always be put into double quotes.
3.
String values in Excel must always be put into double quotes to appear correctly. In Warcraft III, it's only necessary under certain circumstances. Non-exhaustive: containing a semicolon, containing a double quote
4.
In Microsoft Excel, double quotes as parts of string values are not to be escaped, it simply accepts "abc"def". I am unsure about Warcraft III.
5.
When Warcraft III tries to read a property of an object and this property is not set, it takes a default value, which is zero for numbers, false for booleans (booleans are expressed as 1/0*) and empty string for string. In this respect, if you take a look at the standard .slks of Warcraft III, you will find that there are a lot of gibberish values like "-" sometimes used for cargoSize, which obviously should rather be an integer. Together with point 3, this implicates that you cannot safely infer the data type of a cell with the data .slk alone. The data types of properties are stated in the meta SYLK files (like UnitMetaData.slk) except for a few ones that do not possess an objMod/meta variant.
*I did not test how it behaves if you give other values.
Note that some properties do not accept everything even when reverting to a default. The auto (autocast) property in the UnitAbilities.slk causes a crash when unset, for instance. Blizzard used "_" to indicate no autocast there.
6.
Warcraft III crashes if you use the SetUnitInvulnerable jass native (with true parameter) while the AbilityData.slk does not contain an Avul object.
What also should not be missing is Abdt (Burrow Detection (Flyers)) and Aalr (Alarm). Both are hidden abilities and Warcraft III tries to use them with some unit interaction, which will cause a crash ingame if not the entry is not available. Declaring them is enough, they do not have to set properties, not even code (the specific internal ability logic the ability object uses).
7.
Warcraft III crashes if you have columns whose index is greater than the declared column count.
8.
Warcraft III crashes if the declared row count is greater than actual rows. If the declared row count is less, it still considers more rows. This hints at Warcraft III preparing an array with the capacity according to the declared row count but still progressively reading the file until EOF (which must be done anyway because you could potentially have the cell data with the least indexes at the very bottom).
9.
Warcraft III crashes if any read SYLK file has more than 96 columns.*
*I tested the UnitData.slk and it crashed during loading screen. I also tested the AbilityData.slk, which crashed right after loading screen.
You CAN declare any amount of lines in SLKs, the only exception I've got is UnitData, which should strictly define amount of line. All lines past the defined value will be ignored, and if there are less lines than declared game will crash.
10.
Warcraft III crashes when encountering empty lines before the E (EOF) record.
11.
Warcraft III crashes if an object in the UnitBalance.slk does not set the Primary (main hero attribute) property. Blizzard uses "_" to indicate none there.
Last edited: