In the meantime, I moved to Gitorious.org with most of my projects, so you can checkout the latest version of the ASL following this link. All 2.0 stuff is available, too in the same repository but still not usable. At the moment there is no 1.3 release since two systems (A_MAP and ARoutine) still need to be fixed for the release and I want to take a look on some other systems I usually don’t use myself which makes them hard to be maintained for me. However, this article should give you a digest of the most important changes and of course of all remaining issues.

First of all, I am proud to mention that JassHelper option [forcemethodevaluate] is fully supported by ASL 1.3 which helps you to optimize your function calls. The next “big” thing in 1.3 is the fact that there are many stub “on<identifier>” methods for most structures now which allow you to redefine behavior by extending structures not only by passing custom function objects.  Amongst many many bug fixes, I improved the API documentation based on the Doxygen syntax massively but since my own tool vjassdoc hasn’t been updated by me yet and there is no similar tool I still cannot create a proper HTML API documentation. Anyway, it might help users to understand functions easier (including myself as I’ve figured out when reading old code). I’ve added some text from the German tutorials (of course translated) and documented some Blizzard JASS functions, as well. Besides, I’ve added various sections explaning specific topics like containers.

Please bear in mind that this version may break with the old API completely at some points since I made really big revisions for some systems (such as ARoutine, ATalk and AVideo). This version won’t drop all static initialization stuff but I’ve already made some systems more dynamic which do use default values for dynamic members instead of an annoying .init() method.

Since the creation of the ASL, missing vJass features have always been a big problem because they prevented me from adding some really cool stuff. I really don’t want to blame anyone and I am very happy that the JassHelper has been created but today there isn’t anyone left who is able to maintain it. Vexorian had been the only maintainer at all and this isn’t ever going to change. I’ve taken several looks at JassHelper’s Pascal/Delphi/whatever source code and even if I was familiar with that language I probably wouldn’t be able to maintain it for a long time. Additionally, there is the bad fact that it depends on Windows. In his announcement Vexorian mentioned that he was going to create a new, much better tool but because this announcement was made in February 2010 I wouldn’t expect any initial release anymore. On hiveworkshop.com I’ve seen some ideas for a new scripting language but without any usable results. Using Spirit I could try it on my own but I really, really don’t have the time to create another project, especially if there isn’t anyone who could help me. Let’s see what the future brings to vJass and the ASL. You can check out the file “doc/vJass/vJass suggestions.txt” if you would like to get a list of all annoying lacks of vJass/JassHelper.

Text macro A_MAP has seen a huge revision to make its lookups and insertions as fast as usual dictionary implementations (O(log n)). As mentioned above the revision hasn’t been completed yet, so you’ll have to wait some time for the final 1.3 release. All default container types generated and used by the ASL itself got a huge increase of size required by “Die Macht des Feuers”. Over the weekend, I revised ARoutine completely and dropped many methods which took much performance but provided less features. ATalk and AInfo got much more documentation and dynamic members. There’s more debugging functionality now (including more cheats). Global strings can be configured using custom constants now (look into README file for further information). Deprecated module AObjects has been removed and AVideo provides better actor and custom function support. Some important bug fixes have been made, mainly related to structures AAbstractQuest, AVideo, AUnitCopy, AHeroIcon and functions ShowInterface() and CopyUnit(), as well as debugging cheats. Furthermore, I’ve fixed many compilation issues when setting specific options. The README file includes more details about tool support (e. g. jAPI) and trigger editor integration which is a quite unfinished feature but brings many German strings to your trigger editor since I started with the German version which includes a translation of the existing GUI actions.

The following lists of new features and changes might be incomplete. Please use the ChangeLog file to get all detailed information about the new version.

New functions:

• waitForCondition()
• GetPlayerColorValue()
• GetPlayerColorRed()
• GetPlayerColorGreen()
• GetPlayerColorBlue()
• player only effect functions
• WaitCheckingCondition()
• GetDistanceBetweenPointsWithoutZ()
• KeyIsValid() – available without debug mode now
• CopyItemToItem()
• IsTimeOfDay()

New structures:

• AVideoCharacterData
• AVideoPlayerData
• AUnitSpell

New debugging cheats:

• “remove”
• “execution”

Finally, there aren’t any screenshots this time but I want to thank the user “Pali” for his awesome tool SMPQ which uses StormLib to provide a KDE IO slave and a simple prompt tool. Both helped me to create various bash scripts which make testing “Die Macht des Feuers” including ASL much faster and easier than before. If you’re interested in any contribution please contact me. ASL really needs much better documentation and to become more stable to be used more generally. At the moment, it is very limited to my own project “Die Macht des Feuers” because I usually try to fix stuff which doesn’t work in my modification. If you’re interested in seeing my modification to be finished as soon as possible, you could contribute, as well by creating graphical stuff etc. Any contribution will always be appreciated!

School is annoying and therefore we have to do some project work this year, so I got the idea to combine one of my current projects with this.
Initially, I wanted to do some compiler things with Bison and Flex to create first JASS++ or vJass compiler support but since I haven’t been very familiar with these things (not enough to make sure that I had got finished with everything I would have planned) I dropped the idea. Later I dropped the MPQ support as possible project work as well because I thought it would be too boring only presenting some archive format and tools, so finally I came to MDLX support.
The really big problem about this is the huge amount of things which could be supported by an implementation. Of course I limited my project work goals for that reason and made sure I would be able to use OGRE, Qt, KDE and everything else I needed to finish my program.
Besides, most of MDLX loading had already been supported at the end of my recent summer holidays (2010) when I made that decision.

Let’s come to the point. Here’s a list of things I originally wanted to support with my project work:

• loading MDX files
• loading texture files (as well BLP)
• setup a light configurable model view widget in KDE
• displaying Geosets of a model file with material layers and their corresponding textures
• displaying light sources
• using pivot points
• displaying attachments
• using cameras
• displaying and using collision forms for “hit tests”

In the meantime, some things have changed. Fortunately, I’ve been able to add BLP reading support for JFIF compression. Hence I’m able to add all kinds of “Warcraft: III” BLP textures now. On the other hand unfortunately OGRE does not support image object pixel modification like Qt does. For this reason, I have to read BLP files into a Qt image object and write it as raw data (e. g. PNG/BMP) into another data stream which OGRE has to read from. Recently I’ve come a bit more familiar with OGRE’s class ImageCodec so maybe I’m going to implement more direct read and write functionality for BLP in OGRE in future. Furthermore, I’ve added some team color and glow selection actions and dialogs for displayed models.

Back in 2009 I was already starting to create C++ classes for Blizzard Entertainment’s MDX format by using the unofficial specification. Later I did some more abstraction to it and added classes for “blocks”, “nodes”, “objects”, “scalings”, “translations”, “rotations”, “alphas”, “animated properties” etc.

The whole reading process of MDX files has never been a big problem since it is a simple binary format. Reading MDL files is much more complicated because you have to defined correct, abstract parsing rules.

Actually, the main question was “How should it be displayed?”. There are several ways of doing this:

• converting MDLX files into another format and reading this format – slow but useful for editing it with a format supporting tool like Blender
• reading MDLX files into heap and displaying it by using state functions of OpenGL or Direct3D – fast but complicated and dependent to one renderer implementation
• reading MDLX files into heap and displaying it by using an abstract render library – faster than converting it, more abstract (you could choose your native renderer implementation)

In my opinion, first solution is the best one in most cases. It’s always very useful to have an importing/exporting tool for a common format such as Blend because it allows you to edit models of MDLX format with some great tool and additionally allows you to convert it into many other formats by using Blender’s importing/exporting tools for instance.

The problem about that solution mainly is its waste of performance. Imagine you want to display models like in its corresponding game, as fast as possible. The only possibility to do this would be to use Blender’s renderer which probably is not optimized for games/clearly displaying loaded scenes.

Of course there is a game engine by now but there still would be loaded too much data for being really fast since Blender has always been a tool for editing not only displaying scenes and supports much more rendering features than actually required by MDLX format (besides some physics and game logic features etc.).

Additionally Blend format is very special and not abstract enough to display MDLX files easily. It would be a long and taxing process to create a really good import/export add-on such as 3ds Max one’s which still has a massive lack of supported features as well.

If you want to have the fastest displaying tool you would have to choose the second solution. Calling renderer routines directly probably is the most efficient way to render scenes by using hardware acceleration. The main problem about that solution is that you have to rely on one specific render API (e. g. OpenGL). Besides you can’t expand it easily. It’s like a comparison between C and C++ code. The second one is much more abstract than the first one and therefore can be expanded and maintained much easier.

Mago’s War3 Model Editor uses the second solution by calling Direct3d routines to display MDL and MDx files. Unfortunately that is one of the reasons why it is only available on Windows systems (except you’re using some kind of emulation like wine). The lack of abstraction brings much more further issues if you think of implementing advanced 3d editor and scene rendering functionality to your tool.

That’s the main reason why I’ve chosen the last solution for my project work/the wc3lib.

Implementation

Finally, I handed in my project work on 6th May 2011. At that moment I had finished common loading display of MDX files in an OGRE based scene. By reading and copying some stuff about OGRE and QtOgre on the Internet I was able to create the C++ class “ModelView” deriving from class QWidget. That class probably is the most basic one of the whole project work since it connects the two big frameworks Qt and OGRE and allows you to create 3d graphics scene displaying Qt widgets.

OGRE has some really useful classes which allow you to modularize and split up views and scene data. For example you can add multiple viewports to one single render window. At the moment my class “ModelView” has one primary viewport and render window member but theoretically one view could be expanded to multiple views. Due to this well designed abstraction it’s very easy to add new features once you got used to OGRE’s API.

The actual implementation of my school project work’s goals differs a little bit to its original list. I dropped light sources, attachments and pivot points. The latter was dropped because pivot points are only used by nodes which aren’t a part of the project work at all (originally I thought they would be used by Geosets, too). Light sources and attachments were dropped because they are some kind of animated properties (which aren’t part of my project work as well).

As already mentioned above I have been able to add BLP support which became a new item on my goals list.

Let’s take a look at some screenshots I made for the project work’s documentation:

That’s the famous “dark portal” you may know from the “Warcraft III: The Frozen Throne” alliance campaign. I took it as example since it most people who know the game will know the portal as well.

It’s not animated as you might see when you look at the ray texture.

In wc3lib we have different modules for Blizzard’s file formats which allow us to read and write them actually. There’s the abstract class “Format” which is derived from all format classes such as “Mdlx” and “Blp”.

For all categories of formats there are different modules in wc3lib which are logically separated by sub directories. “mdlx” is the MDLX format’s sub directory, for instance. Indeed, there’s only one module which relies on all formats. It’s called “editor” and combines all formats for graphical usage using Qt, KDE and OGRE libraries. “ModelView” class which was mentioned above is part of it as well since it uses Qt and OGRE for MDLX display.

Actually, “editor” module is optional and has not to be compiled together with the other modules. Initially it had been created as playground module to test the other modules correctness. Now, among class “ModelView” there are some World Editor and World Editor modules emulation classes which allow simple global resource and MPQ archive handling (for data sources, consider MPQ support of wc3lib has been not finished yet). For my school project work the class “OgreMdlx” is one of the most important ones among “ModelView”. It allows you to create ManualObject instances in its corresponding OGRE scene/model view by using its corresponding MDLX data. Simply imagine it as OGRE/MDLX pair.

The initial creation process of the OGRE object can be very time expansive so it wouldn’t be a good idea to use “OgreMdlx” instances for every unit, doodad etc. if you want to display your “Warcraft: III” map rather than creating Mesh instances for all MDLX geosets (via convertToMesh) and using them as entities. Probably, this has to be done anyway since only meshes can use animations. Therefore “OgreMdlx” only represents a bunch of static geometry data which can be used for dynamic animated entities once it has been loaded.

As animations are not part of my school project work the second “secret” class which uses those meshes and can be animated and instanced via OGRE’s entity system hasn’t been created or designed yet.

OGRE allows you to change user’s view easily for example to wireframe mode as you can see in the picture above. For simple user control I’ve added some mouse rotation and translation control to class “ModelView” via Qt’s events. There’s still a massive lack on “when the scene should be rendered”. At the moment member function called “render” of class “ModelView” is called every time something is changed via control/view actions or Qt’s widget paint/resize etc. events.

In my opinion a multithreaded solution would be much nicer and more efficient than calling “render” all the time which can be very annoying if you think of the nearly unlimited range of model editing scenarios which could be added in the future.

As OGRE’s API reference states using Ogre::Root::startRendering() which does exactly what I want to have (automatic rendering cycle) should not be used in model editing programs for example. Probably, because it is much faster to change only things which were changed actually. The best compromise could be optional rendering loop for model views which show you map terrain with placed objects for example where objects are constantly animated.

Some days before I had to hand in my project work I was able to fix an annoying display bug which actually occurred because of one line in my code. There you can read about my problem which fortunately could be solved since it was that simple. I just thought you would have to call the index function not only for creating faces. Thank you Kojack for helping a noob like me finishing his school work on time .

Here’s a picture of the nasty model faces distortion:

As mentioned in my goals list I’ve added collision shapes and team color/glow support as well. Collision shapes are some kind of simplification for Geoset selection which can either be spheres or boxes. Team colors are used in “Warcraft: III” to indicate a unit’s or building’s owner/player. Team glows are nearly the same but used for heroes only.

Team color and glow textures are loaded globally in my project work and can be used by member functions of class “Editor”.  Collision shape “hit test” (as it is called by Blizzard in their Art Tools’ manual) is implemented in class “ModelEditorView” (deriving from class “ModelView”) using an OGRE-based ray query.

Unfortunately, collision shapes seem to be too big at the moment as you can see on the following screenshot (the little thing it the center of the view is an Arachnathid):

Future

At the beginning of the creation of the “editor” module of “wc3lib” I defined the abstract class “Resource” from which class “OgreMdlx” derives. Meanwhile, I’ve expanded it and added some multithreading support via virtual member functions and by the fact that “Resources” derives from QThread. It should be possible to load as many resources as possible at the same time to take advantage of multiprocessor systems. For this reason I will have to take a look on Qt’s classes and their threading support since I’ve got already some issues when creating objects in separated threads etc.. When I begun writing this article I had already taken a look on ImageCodec of the OGRE framework. By the meantime, I was able to implement some read functionality for the BLP format which should heavily improve the speed of loading BLP textures in OGRE (without Qt’s import/export step).

Furthermore, I want to improve the mouse and key control and make some model view settings more customizable. Actually the most important issues I will have to fix are the ones which are related to my school project work’s goals. As I have to present my project work in school on 28th or 29th June 2011 it would be annoying to have some unfinished stuff, so I will try to fix the collision shapes size, the corresponding “hit test” implementation and to improve the team color and glow dialog selection until that date.

Hopefully, the new C++ ISO will be released this year. The new language standard would allow you to create more maintainable code and use some completely new language features.

Publication

Of course I’ve uploaded my school project work which is almost completely written in German (except its required English summary). Some parts are nearly equal to this article but it’s larger, I think and written more detailed for people who don’t know much about the MDLX format (as my teacher(s): one of my teachers thought MDLX must be a Roman number …):

Project Work (German)

All corresponding source code of “wc3lib” can be found in my SVN respository on SourceForge.net.

• new debugging print functions
• added more debugging cheats
• added many new global functions
• added custom trigger and trigger editor UI data that some functions and types can be used in World Editor’s trigger editor now
• added many stub methods (identifiers starting with “on”) which makes structures better extendible
• structure ARoutine supports the same routine type for the same unit several times at one day now
• structure ALayer supports multiple regions with different heights now
• item charges of rucksack created by structure AInventory do always start at one now
• new structure AFormat and old formatting functions support many more arguments now
• added many new container methods for all three container implementations (A_VECTOR, A_LIST and A_MAP)
• improved page implementation and added current page display support to structure ADialog
• quest messages of structures AAbstractQuest, AQuest and AQuestItem are like in Warcraft 3 now and user can call some more methods to show whole updates to the players
• structure AAbstractQuest supports dynamic widgets now (for pings)
• added global damage detection system based on structure ADamageRecorder
• structure AVote uses forces now not all playing players
• added text macro A_MAP
• added GUI system structures AStyle, AFrameBar, AFrame, AWindow and AArrowButton (usable in 2.0, see below)
• added structure AItemSpawnPoint
• added interface ASpawnPointInterface
• added text macro A_NUMERIC_VECTOR
• added RtC 1.0 support
• added text macros A_FOREACH, A_FOREACH_2, A_FOREACH_END, A_REVERSE_FOREACH, A_REVERSE_FOREACH_2 and A_REVERSE_FOREACH_END
• added interfaces AIteratorInterface and AContainerInterface (not usable because of JassHelper bug)
• added structure AFormat
• added default container instance struct APlayerVector
• added structure AForce
• added structures AUnitCopy and AHeroIcon
• added interface ABarInterface which is extended by AMultiboardBar
• added map constants A_MAX_COLLISION_SIZE and A_MAX_COLLISION_SIZE_ITERATIONS
• added text macro A_DESTROY
• improved structure APoint
• added many camera related functions

This is a list of all new global functions:

• PlaySoundFileOnUnit
• PrintIf, PrintFunctionErrorIf and methods of text macro A_STRUCT_DEBUG printIf, printMethodErrorIf and staticPrintMethodErrorIf
• speech2
• ShowShadowStrikeTextTagForPlayer
• CreateCorpseAtRect and CreateCorpsesAtPoint
• EndCinematicSceneForPlayer
• CreateUnitsAtRect
• SetUserUIForPlayer and SetUserControlForPlayer
• GetUnitLevelXP, GetUnitXP and GetUnitHeroXP
• GetHeroLevelMaxXP and GetHeroMaxXP
• GetTimeOfDayElapsedHours, GetTimeOfDayElapsedMinutesInHour, GetTimeOfDayRemainingHours, GetTimeOfDayElapsedMinutes, GetTimeOfDayElapsedSecondsInMinute, GetTimeOfDayRemainingMinutes, GetTimeOfDayElapsedSeconds, GetTimeOfDayRemainingSeconds and GetTimeOfDayString
• String and Format
• FlushUnitCollisionSizes, FlushUnitTypeCollisionSize, GetUnitCollisionSizeEx and GetUnitCollisionSize
• GetPlayingUsers and GetPlayingPlayers
• GetRectX and GetRectY
• StringSplit
• GetTimeOfDayMinutesPercentage and GetTimeOfDaySecondsPercentage

And finally here’s a list of all new debugging cheats:

• xp
• enable
• disable
• pathing
• nopathing
• lumber
• gold
• timeofday
• foodcap
• order
• timer

If you want to contribute something please test systems and functions and report your bugs at the project’s bug tracker.
At the moment I’m trying to fix some bugs of structures AInventory and ALayer and to add some more and better documentation. Help is primarily required for testing RtC and jAPI support but also for general testing.
Consider that structures AMissile, AJump, AFocus and AFight are still unusable since I do not require them for “Die Macht des Feuers”.
Furthermore global options A_DEBUG_HANDLES, A_FPS_MOVEMENT and A_NET should not be used yet.
Structures AUnitCopy and AHeroIcon were added because of requirement in “Die Macht des Feuers” like most new features (including ADialog improvements, AItemSpawnPoint etc.).
Since there are more stub methods now (keyword stub isn’t implemented that long in vJass) extending structures is much easier. Unfortunately keyword “protected” hasn’t been added to vJass yet and probably never will. Therefore many methods are public which should only be used by derived structures. I’ve added todo comments which indicate that those methods should be protected if possible.
By meantime, most stub method identifiers start with “on” and call function pointers in their original implementation of their structure if there are any. Actually they should also be protected because nobody has to call them from outside of their structure.
Please read file “README” before using the new version! File “TODO” contains many current issues which are not all reported on online bug tracker.
If you’re interested in more detailed changes descriptions please take a look into file “ChangeLog” because I try to log most of my changes very exactly.

As you can read in my recent web log article I’ve already changed some project names. The main project (formerly called “vjasssdk”) is called “wc3sdk” now and the original “wc3sdk” which contains ASL and the MPQ archives has been split up into projects “ASL” and “archives”.
Unfortunately I hadn’t have enough time to move SVN sub folders. Anyway, this project is completely separated now although there are some functions which allow you do preload data from the archives.

For those of you who’re interested in the whole development progress and history of the ASL I’ve uploaded several images:

This is some really old JASS-only stuff I had created when did not know vJass yet (long time before I started to work on ASL). As you can see I created custom data types by using global variables for properties and I had to write custom constructors and destructors which I would never recommend anyone.
Anyway, at that time I released a promotion video for “Die Macht des Feuers”. Maybe I will upload it here again someday.

When ASL had been launched it was called “Warcraft 3 Script Engine” and I used TESH and ugly vJass. It was launched after discarding current work on “Die Macht des Feuers” in 2007.

This was the initial custom GUI system which used very ugly code since I didn’t really used object oriented programming.

I’m still using this modified syntax highlighting of Flame_Phoenix’s version. I’ve never created some auto completion stuff. Real nerds have to know all JASS natives .

And this is the RPG modification code. As there had been some mysterious wizards you won’t recognize any quest file name.

Later I got serious problems with pjass since it was limited (Flex/Bison) so I had to move to Zoxc’s JASS parser. Fortunately JassHelper got parser configuration support around that time.

That’s the custom script code of the current “Die Macht des Feuers” map called “Talras”. Again you won’t recognize the mini map – those mysterious wizards must be really powerful.

And finally I would like to recommend you to test all your maps on Linux systems with deprecated versions of wine. Just minimize your game and open it again and you’ll see such beauty textures.

Finally I want to write which systems probably will get more attention next time since they’re used in my project “Die Macht des Feuers”.
First of all I need to improve the interface of structure AInventory since it doesn’t easily allow developer to remove or count items. Besides video, class selection and talk systems may be improved a little bit.
Since custom GUIs won’t be provided by first “Die Macht des Feuers” release ASL’s GUI system will be revised in version 2.0 only!
As there are many different spells which may need some “extra functionality” which isn’t given by the current systems there can be some new ones in version 1.*. All in all version 1.* should support the whole current planning state of “Die Macht des Feuers” so I can get a really stable version.
Therefore I won’t stop supporting and fixing version 1.* until I’ve created a new, stable release of version 2.* which supports my RPG modification, too.
Consider that structures like AMissile, the AI module and RtC/jAPI support will probably suffer from those decisions but I won’t really care about.

Version 2.0:
Of course I’ve already made some planning for version 2.0. I will create a new SVN branch for release 2.0 and continue development of version 1.2 as I wrote above. So there will probably be another release like 1.3 with many bug fixes and other important improvements.
I think version 2.0 will be the last version of the ASL and I will stop development since my other projects need some more attention and vJass has never been my favorite scripting language though I’m very happy I don’t have to use JASS anymore.
The main purpose of the ASL project has always been my modification “Die Macht des Feuers”. For this reason I will primarily add new features to 2.0 which are heavily required by “Die Macht des Feuers” but also some new and better core functionality.
Additionally I want to add some more documentation stuff than the current German tutorials and all those Doxygen comments. Since vjassdoc development had also been stopped it’s hard to create a really nice, automatically generated documentation.
In my opinion there should be a step-by-step tutorial about “How to use ASL?” because it’s hard to see the huge amount of functions, libraries and structures for new users although they mostly won’t need many parts of it.
Here’s a list of main changes and features which should be realized with 2.0:

• release test map for 2.0
• add much more detailed Doxygen comments to code (include examples etc.)
• add step-by-step tutorial “How to use ASL?” which is related to example map
• decrease number of structure initializers which has to be called manually (identified as “init”) and increase number of dynamic members
• decrease number of global options
• add new core functions for interface (sound, camera, cinematic filters) and strings (such as Trim…)
• add new core structures like AImageBar, ATextTagBar, AReverseIterator and some more container types
• add A_PAIR and A_SORTED_CONTAINER
• add interface ASerializable for all serializable structures (such as character system’s ones)
• add structure APlayerUIData which stores and restores player’s user interface data (required for in-game videos)
• function interfaces should become static members of structures if possible
• many ACharacter related structures (such as AInventory, AFight and ARevival) should be implemented unit-based and extended by those character system related structures
• add new implementation of structure AInventory which is extended by AEquipment and ARucksack
• improve GUI system by adding/improving structures AWindow, AStyle, ALayout etc. and using graphics from project “archives”
• add more trigger and trigger editor UI data (primarily for global functions and core types) to provide easier access
• add JassHelper option [forcemethodevaluate] support
• add structure AUnitStats based on ADamageRecorder which could be usable in strategy games and for various spells
• structure ATokenizer should get backwards functionality and extends AContainerInterface

If you have some more cool ideas just write an e-mail. All contributions are appreciated.

Another new feature of ASL is the foreach loop. Many programming languages do have native foreach support. C++ does not have native support but libraries like Boost and Qt do have preprocessors which generate them automatically for specific types of containers.
Since vJass allows you to define text macros this can be done with it, too. Surely it doesn’t look as nice as in C++ since you have to call text macros by the statement “//! runtextmacro” and you can not declare local variables anywhere but it’s a funny and nice feature, although:

local AIntegerList list = AIntegerList.createWithSize(10, 12)
local integer value
//! runtextmacro A_FOREACH("list")
debug call Print("Value " + I2S(aIterator.data())) // Use global iterator "aIterator".
call aIterator.setValue(GetRandomInt(0, 100))
//! runtextmacro A_FOREACH_END()

//! runtextmacro A_FOREACH_2("value", "list", "AIntegerListIterator")
debug call Print("Value " + I2S(value))
//! runtextmacro A_FOREACH_END()

Unfortunately there is a vJass bug when implementing an interface in size limited structs. Otherwise you probably could remove the iterator type argument.
Note that since “aIterator” is global you should not use “TriggerSleepAction” calls in foreach loops.
Maybe I will add a third version which takes an iterator as argument but usually you could write it commonly if you want to use your own iterator:

local AIntegerListIterator iterator = list.begin()
loop
exitwhen (not iterator.isValid())
debug call Print("Value " + I2S(iterator.data()))
call iterator.next()
endloop
iterator.destroy()

At the moment foreach loops can only be used on map and list containers. Vector container does not support iterators, yet.
I will release ASL version 1.2 next months I hope because there had been made lots of changes and fixes lately.

• Mpq: Main class which represents single archive.
• Hash: Should be read-only class and provides access to single hash table entry.
• Block: Also read-only class which provides access to single block table entry.
• MpqFile: Represents single file contained by an archive.
• Sector: Provides access to an MPQ file data sector. Usually this class should not be used by users.

Normally you just need to know the classes Mpq and MpqFile which provide all functions you need to add, rename, move or remove files from archives or to modify files and archives attributes.
MPQ archives do always contain hash and block table which provide entry lists for files.
Each file has exactly one hash table entry which allows user to search for files using their hash values and the hash table of the archive.
Additionally the file consists of blocks which again do consist of sectors.
Each sector can be compressed differently by using various compression methods (Huffman, Bzip2 etc.).
Some compression and decompression functions have been imported from the StormLib (e. g. PKWare and Wave) since it would be much and unnecessary work to write custom ones.
Some others (like inflate and deflate – Zlib) were implemented by myself using some documentation stuff.
All MPQ related compressing, decompression and hashing functions can be reached by including header file “” but should usually not be required by user.
There are various surrounding conditions to clarify when creating such a library. First of all I had design the classes and their methods based on the MPQ specification (which incorrectly uses int8 instead of int16 by the way).
At the moment you can only get constant access to MPQ files and writing file functionality is not implemented yet.
The variety of compression algorithm made me creating some kind of dependencies since I have to use external libraries for some of the compression algorithm.
These dependencies did also occur when I created the BLP module since it needs to compress and decompress JPEG images.
At the moment I work on changes from compile time linking support (to shared objects) to run time linking by using functions like dlopen.
This feature would prevent unnecessary recompiling when using other compile flags but also means much more work.
There’s a simple class now called LibraryLoader which I’ve added to solve this.
Another problem I’ve to consider is code licensing of externally and internally used code.
For instance Zlib and bzip2 do use open source licenses and has to be installed additionally to the wc3lib when using MPQ module but as I mentioned there’s also some code which is directly implemented in the wc3lib itself (took from StormLib and MPQ specification) which I’ll have to license separately.
The author of the MPQ specification, Justin Olbrantz, mentions that you’re allowed to distribute everything as long as stating the author which should not be a big problem for me.
By contrast, Ladislav Zezula author of StormLib does not specify any license and therefore owns copyright to it.
It would be nice to see StormLib with GPL or any similar license.
mpqlib uses GPLv2 license, MpqLib uses GPLv3 (but consider that it needs StormLib) and SFmpqapi is licensed in a similar way to the MPQ specification.
C++ does provide nice features (operator overloading, friends) to develop such API. For example you can use stream operators to add files to archives:

#include // Include MPQ module of wc3lib.

// Like fstreams, MPQ archives are being closed automatically when being deleted (at end of scope).
}

This little (completely useless) example shows you how to use stream operators and some functions (open and findFile). Of course there is already more functionality than this but I just wanted to show you that it’s not hard to use the library.
Exception handling improves (in my opinion) error handling and makes it easier for developers to check if everything was fine.
Internally Mpq and MpqFile classes do only read meta data (like hash, block and file sector table). Primary when user wants to read some file data (e. g. file data is being written into output stream as in the example above) it’s allocated. For this reason it would be hard to work with two instances of the same MPQ archive and adding or deleting some files (multithreading). I hope I will have left some time to add multithreading support one day but usually it should be enough without for most applications. Consider that MPQ archives do not save file paths in header, hash or block table. They’re always stored separately in the “(listfile)” file which is not required necessarily.
Further plans I’ve made are for the editor module of wc3lib which allow users some GUI support for Blizzards formats. Maybe I’m going to implement some formats like the MPQ one as KIO slaves.
This would allow KDE users to open and modify MPQ archives e. g. in Konqueror directly.
Contribution would be appreciated, so if you know Python or C++ (I would like to add Python bindings or to write some parts of wc3lib in Python since it’s easier to maintain) and want to help just contact me.

Link to C++ program source code

• Ambient
• Asl
• Creatures
• Interface
• Items
• Spells

The archive “Asl” won’t be uploaded since it does only contain some unfinished trigger data files for using ASL functions in trigger editor.
Most of texture and model files do have German names. Only the newer ones have English names because when I started this project I decided to give all files German names but later I thought it would be much better to make it available to people from all nations.
Each directory which contains at least one file which is not a directory itself should contain a file called “Credits.txt”.
Those credits files contain all or most of file authors and sources where I downloaded them.
Some of the files were especially created for my project “Die Macht des Feuers” but most of them were downloaded (sometimes renamed and customized) by me from websites like Wc3C.net, The Hive Workshop and \\XGM\\. Note that “Die Macht des Feuers” has its own additonal archive which contains stuff like game music, dialogue sounds and customized files like e. g. Terrain.slk and Water.slk. Besides you should consider how to use them as MPQ archives. At the moment I always create a completely new huge MPQ archive (or add the updated archive directories) since I’m not able to start Grimoire hacked Warcraft TFT and to load custom MPQ archives into game which would probably be the best way.
Primarily I was going to commit them all to my wc3sdk SVN repository (archives sub folder) but it’s unimaginable to upload all those files uncompressed (should have started with git :-/) with my current Internet connection speed.
I thank all people who created any of the files since without them I would be unable to make my modification “Die Macht des Feuers”.

Update (2010-07-26): This is a corresponding doodad file which can be used together with the Ambient archive.
It’s the same which is used for the project “Die Macht des Feuers” and contains 415 different doodads at the moment with default scale values fitting to the Warcraft 3 villager model scaled with value 1.20.