SYLK road

[WaterKnight]

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.

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.

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.

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.

 

[DracoL1ch]

Notice that SLK parser used by wc3 has been changed inbetween 26 and 27 patches, and who knows when later.

Here im speaking of 26 patch state and only valuable SLKs (not metadata etc, just the ones map uses).
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. Any other file won't do that - I have all of them with 9999 lines defined.
I can't recall any crashes with empty lines prior to E as well, probably 27+ only.
SetUnitInvul adds or removes Avul, no wonder it will crash because there are no safety checks for existance of Avul

 

[WaterKnight]

Notice that SLK parser used by wc3 has been changed inbetween 26 and 27 patches, and who knows when later.

I am not insane then. Seemed different than before. Everything I have stated above is in respect to 1.29.

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. Any other file won't do that - I have all of them with 9999 lines defined.

Okay. I did indeed test UnitData.slk. That is strange, though. Ignoring blank lines should not be anything that is specific and that sounds like the specific algorithm hooks on the parser rather than parsing the whole file first.

SetUnitInvul adds or removes Avul, no wonder it will crash because there are no safety checks for existance of Avul

I remember a loading screen crash with the non-existence of another ability. Was it Burrow Detection? It did not seem to be the case in 1.29.

edit:

Here's a list of in one way or another special abilities of which I do not know yet if they could be implicitly used/crash:

ARal (Rally) - pocket factory has it (explicitly) but also used in conjunction with training units probably
Aetl (Ethereal) - it's not referenced by any unit or ability
AIri (ItemRandomItem) - it's not referenced by any unit or ability
Arev (Revive) - it's not referenced by any unit or ability but used in conjunction with altars probably, Aawa (Awaken) is explicitly stated on the other hand

then there are the conjunctional abilities:

Aent (Entangle) - entangles a gold mine
Aegm (Entangled Gold Mine)
Agld (Gold Mine)
Abgm (Blighted Gold mine)

Aent cannot be cast and units with Abgm cannot be built on a unit unless it is tagged by Agld. So yeah, at least the Agld ability must be implicitly queried.

Amil (Militia)
Amic (Militia Conversion)

Peasants/Militia have Amil, human townhalls have Amic. Amic calls for those units that have Amil.

Alam (Sacrifice (Acolyte))
Asac (Sacrifice (Sacrificial Pit))

Alam can only be used that are tagged by Asac and vice-versa.

The archer-hippogryph-coupling abilities seem pretty explicit.

hidden abilities (not visible in object editor):

ACsp (Creep Sleep)
AHer (Hero)
Atlp (Load Pilot)
Atdp (Drop Pilot)
Aalr (Alarm) - as stated above, easily causes a crash when there is more than one unit on map
Abdt (Burrow Detection (Flyers)) - similar to Aalr?
Aatk (Attack) - can be removed from a unit ingame
Amov (Move) - can be removed from a unit ingame
Attu (Tank Turret)
Atol (Tree of life (for attaching art))

build abilities:

ANbu (Build (Neutral))
AHbu (Build (Human))
AObu (Build (Orc))
AUbu (Build (Undead))
AEbu (Build (Night Elf))
AGbu (Build (Naga))

Those are hidden as well and probably implicitly used when a unit has structures it can build.

Afir (On Fire)
Afih (On Fire (Human))
Afio (On Fire (Orc))
Afin (On Fire (Night Elf))
Afiu (On Fire (Undead))

Those are hidden as well.

other curiosities:

Arng (Revenge) - space orcs have it, looks like it has something to do with exploding units like artillery, not sure