search

Luashine / wc3-file-formats

Project to document the proprietary file formats used by Warcraft 3
3 stars 0 forks source link

Consolidation #3

Open stijnherfst opened 1 year ago

stijnherfst commented 1 year ago

Hi, I'm the author of HiveWE and already have a spec listed that is sometimes referred to, perhaps we can consolidate our efforts to create one unified spec. Here is an example page for instance https://github.com/stijnherfst/HiveWE/wiki/war3map.w3e-Terrain

You can freely edit the page (just press the edit button). Feel free to add any changes as long as they follow the current formatting. If there any formatting changes you think would be good then do feel free to hit me up here, on the Hiveworkshop or on Discord

Luashine commented 1 year ago

Hi I will try to explain my position and hopefully it doesn't sound arrogant.

Why this way

The file format specification is my consolidation attempt. Probably should've said "the consolidation" attempt because of B's immeasurable help with the source. I have outlined the multiple older sources for the format documentation and this one has the ultimate goal to unite them.

I'm hellbent on Hodor's formatting approach. I assume he worked by only testing the resulting output files, but his idea to keep the description very close to pseudocode is awesome. He came up with the idea of conditional branching for the format... which absolutely hit the mark! When I set out to create a standalone parser/serializer for the w3i format to test the 12-24 hybrid maps there was nothing around of that kinda library that I needed. I looked at HiveWE wiki and was... overwhelmed. With Hodor's table I was able to program a roundtrippable w3i reader/writer from scratch within an hour or so. No ambiguities for someone who had no idea about Warcraft 3 or its internals.

Practically, his article is a human-readable Kaitai Struct template. Yes it was at that step that I realized I should websearch for "declarative parser" (quite literally) and found Kaitai Struct. Well, getting into it was too much for a quick and dirty test - I mean to write a ksy definition - and KS writing support is not there yet. So I ended up writing my own.

This should've explained why I didn't touch the HiveWE format definition pages. Finally this will need more SEO visibility, like a Github Pages front. I'm thinking about how to make current editing easier (spreadsheets should be edited in a spreadsheet program). Probably something with Pandoc to ingest a Markdown/CSV(ODS?) mix and give me a nicer Markdown or HTML. Maybe with MkDocs at the end of it.

Why only the format specification

I've explained this in the context of jassdoc before. I see these as different types of documentation, with the file formats, similar to jassdoc, being the foundations of the pyramids if you will.

Next up the chain comes more broad documentation, tying together different internal aspects and explaining them like the page you linked.

Finally there are "normal user facing" tutorials and guides that explain what and how to do to achieve something. These are purposefully targeted or call them restricted, spotty and do not give a full picture...

...or well they could give an overview if there was one to look at, the "broad documentation". So far people only described the puzzle pieces they themselves understood and nothing more. So this layer in between the low-level spec and the tutorials will need even more of game knowledge (I don't possess) and with greater potential to find the puzzles scattered around online.

However as I see it, I will pass on the banner to someone else. I don't have enough motivation or time to write that kind of doc (I could). As far as game API aka natives are concerned, I am fine with the jassdoc. There are more people that could do that kind of work too (the middle layer). And I surely now understand that the git-based model of documentation writing has too much overhead. A wiki-like interface is neater.

But you know yourself, there are not many takers even in that case. The herd needs a shepherd, but volunteers cannot be forced if all their attention and free time is taken up by chatting and other social networks distractions and algorithms. That is, there are great people with deep knowledge on Discord, but they prefer to spend time answering ad-hoc questions than to write a manual to RTFM people to :) This is not a judgement, this is an observation. Ah OK, the question answering part is a judgement, I consider it wasted time in part, because nobody will search for answers in a chat's history.

I will keep this open because consolidation is the ultimate goal. Hurr-durr just set up a Mediawiki for this but I hate this engine, I would rather write on papyrus. And plain Markdown is too static for something that's a project in progress and will evolve with new information, and a need to keep cross-references in check and updated.