
Mo'PaQ 2000
The official client of Andrey Lelikovs MPQ API Library DLL
By Quantam

User's Manual	Last Modified: 11/30/2000

Table of Contents
1.	Version History

2.	Introduction
2.1	Whats an MPQ?
2.2	Whats Storm?
2.3	Whats the MPQ API Library DLL?
2.4	Whats MoPaQ 2000?
2.5	For More Information about MoPaQs - Inside MoPaQ

3.	Getting Started
3.1	System Requirements
3.2	Setting Up MoPaQ 2000
3.3	For the Impatient

4.	Using MoPaQ 2000
4.1	Overview of Functionality
4.2	The Command-Line Interface
4.3	Adding Files - the A Command
4.4	Extracting Files - the E Command
4.5	Renaming Files - the R Command
4.6	Moving Files - the M Command
4.7	Deleting Files - the D Command
4.8	Flushing Out an Archive - the F Command
4.9	Listing the Files in an Archive - the L Command
4.10	Running Scripts - the S Command

5.	Writing Scripts
5.1	Overview of Scripts
5.2	Differences Between the Command Line and Scripts
5.3	Opening Archives - the O Commands
5.4	Closing Archives - the C Commands
5.5	Pausing Scripts - the P Command
5.6	Script Comments - the Semicolon ;

6.	Technical Support
6.1	Is It a Bug?
6.2	Tech. Support Checklist
6.3	Getting the Latest Version of MoPaQ 2000
6.4	Getting the MPQ API Library DLL

7.	Credits

8.	Coming In Future Versions

9.	Legal Stuff


1.	Version History
Build 2210 (v2.0 release)
Added the WAV compression (/wav) option to the add command
Added the rename file (r) command
Added the move files (m) command
Added flush archive (f) command
Turbocharged the list command with a whole bunch of new functionality
Awesome new error-handing tells you exactly what went wrong (most of the time, anyway)
Bugfixes lots of em
Now REQUIRES Starcraft/Brood War 1.07 and wont work with anything less
	
	Version 2.0 Preview 2 (not publicly released)
Added wildcard (*/?) filtering to the list function
Added the listfile (/lf) option for writing listfiles rather than reports
Added the recurse through subdirectories (/r) option to the add, extract, and delete commands
Compressed internal listfiles
Enhanced the error checking and messages
Optimized code
	
	Version 2.0 Preview 1 (not publicly released)
Added wildcard support to the d command (delete file)
Allowed the l command to write the output to a file
Redid the core of MoPaQ 2000 for noticeably better performance and efficiency
Redid the command parsing engine for more flexibility and ease of use
Added the MiniHelp (h command) which almost makes this file obsolete
Moved the handling of listfiles internally
	
	Version 1.10
Added the d command (delete file)
Added the p command (pause) to scripts
Added the ability to use wildcards for extracting files
	
	Version 1.02
Fixed a mistake of mine that switched the x and e commands in scripts. 
Fixed several small potential bugs (and probably added a lot more). 
Wrote a more powerful and flexible implementation for the List Files command. 
Added more robust error handling.

2.	Introduction
2.1	Whats an MPQ?
MPQ, or MoPaQ, is a proprietary archive format created by Mike O'Brien, the man hailed as Blizzard's multiplayer engine genius, back in 1996 as a general-purpose archive for use with Diablo, and named narcissistically for its creator - "Mike O'brien PaCK"; the copyrights to it, however, are held by Havas Interactive, Blizzard's parent company, and it may continue to be used now that Mike O'Brien has left Blizzard. MPQs apparently excelled in their role in Diablo, because Havas has turned back to them time and time again for Starcraft, Warcraft 2: BNE, Diablo 2, Lords of Magic (by Sierra, another company owned by Havas), and possibly others that I'm not aware of.
 An archive is a file that contains other files inside it, usually in a compressed state. Havas uses MPQs to hold all sorts of things ranging from files that are copied to the hard drive to game data. It is the game data that is particularly useful. Those MPQs contain everything including graphics, sounds, animations, levels, strings, numeric data, and storyline information.

2.2	Whats Storm?
Blizzard uses a shared library called Storm (Storm.dll on PCs, Storm.bin on Macs) in all their modern games to store important functions like MPQ reading, Battle.net, and even some graphics routines. Like all shared libraries, Storm makes its functions available to any program that wants to use them, which is not very good for security. It is for this reason that Storm only contains MPQ reading functions. The MPQ writing functions are Blizzard's prized possessions, and they're not going to let just anyone use them.

2.3	Whats the MPQ API Library DLL?
Although Storm provides public functions for reading MoPaQs, for security reasons it does not contain any functions to edit MoPaQs. However, StarEdit does, since SCMs/SCXs are really MoPaQs. Unfortunately, these functions are under tight lock and key, so all but the most knowledgeable (and persistent) hackers will be unable to use them. Unfortunately for Blizzard, there does exist one such hacker, named Andrey Lelikov (aka Lelik). He has found a way to access these precious functions, and has encapsulated this complex process in LMPQAPI.DLL (Leliks MPQ API Library DLL), which automatically cracks open StarEdit to reveal these functions to any programmer.

2.4	Whats MoPaQ 2000?
Ive been with Lelik for a while now; since before he made his LMPQAPI.DLL. Back then, he had made a program called MPQ Archiver, the ancestor of MoPaQ 2000. The source of this program was not public, but by some strange twist of fate, Lelik sent me the source in response to an e-mail I sent him (the e-mail didnt ask for the source). The code fascinated me. He had done many things I didnt even know you could do. I sat at my computer for 2 days straight, trying to figure out what his amazing code was doing (making ample use of my Win32 API help files, to be sure). Eventually, I figured it all out. Thats when the real fun began. I asked Lelik for permission, and, after getting it, went about redoing most of MPQ. You see, even though Lelik ingeniously designed the kernel, his user interface left much to be desired. So, that was the part I worked on. I added many new features, ease of use, and a LOT of speed; and MoPaQ 2000 is the result.

2.5	For More Information about MoPaQs - Inside MoPaQ
Clearly, with MoPaQs being used in Diablo, Diablo 2, Starcraft, and others, the customization power is tremendous. So, I decided to share my considerable knowledge I gained about MoPaQ, and, after writing MoPaQ 2000, to write Inside MoPaQ (at <http://www.campaigncreations.com/starcraft/inside_mopaq/>), which has since become the definitive, all-in-one source of information about MPQs, Storm, StarEdit, and the MPQ API Library.

3.	Getting Started
3.1	System Requirements
MoPaQ 2000 is a modest program, without expensive tastes. However, there are a couple basic requirements for it to run.
1.	A PC with Windows 98 of 2000, or Windows 95 or NT 4.0 with Internet Explorer 4.0
2.	Starcraft/Brood War must be properly installed and patched to version 1.07 on the computer OR the StarEdit.exe and Storm.dll files from a Starcraft/Brood War 1.07 installation must be in the same directory as MoPaQ 2000

3.2	Setting Up MoPaQ 2000
MoPaQ 2000 is very easy to set up. All you have to do is extract the mpq2k.exe, lmpqapi.dll and listfile.dat files into a single directory on the hard drive (you can even put them in your Starcraft directory, although this isnt recommended). If you do not own Starcraft or Brood War, you must obtain the StarEdit.exe and Storm.dll files from a friend (I cant distribute them for legal reasons) and place them in the same directory as mpq2k.exe.  From there, you should be checked up and good to go.

3.3	For the Impatient
Those of you who are too lazy to be convinced to read the rather lengthy following section on using MoPaQ 2000 may simply type

MPQ2K

at the command-line to get a brief summary of MoPaQ 2000s functionality, and then take your chances at figuring out what to do on your own.


4.	Using MoPaQ 2000
4.1	Overview of Functionality
MoPaQ 2000 (from here on well call it MPQ2K for short) is a full featured, easy to use MoPaQ editor. It allows you to add new files, overwrite existing ones, extract files, rename files, delete files, compact an MPQ, and list the files in it. 

4.2	The Command-Line Interface
MPQ2K is a command line utility. It must be run from Windows 9xs MS-DOS Prompt or NTs Command Prompt (both in the Start Menu->Programs->Accessories menu). The general format for running MPQ2K is something like this:

MPQ2K <Command> <MPQFile> [SourceFile] [DestinationFile]

Parameters in <> are required, ones in [] are optional for some commands. For the exact syntax and use of individual commands, see sections 4.3-4.10; but first, some preliminary information about the command-line interface.
Commands and parameters are not case sensitive. The MPQ and filenames can be either short filenames such as blah.txt or squish~1.txt or long filenames such as squishy fat.txt. But, if the filename is a long filename or has spaces or other strange characters, you MUST enclose the entire filename in quotes (either   or  ). Additionally, the quotes must be paired. For illustration, the following examples will work:

this file.txt
that file.txt
this.file-that.file.txt

But the following examples will NOT work:

bad file.txt
not.this-file.txt
dont try this
vice versa
or this for that matter

Another important part of command-line syntax is the wildcard. Wildcard characters (* and ?) are used by many command-line programs to represent multiple files. MPQ2K uses them for all commands except those noted otherwise in this manual. Wildcards represent one or more unknown characters. The ? wildcard stands for a single unknown character, while * wildcards stand for any number of unknown characters. The following:
 
*.txt

would include such files as flub.txt, shootme.txt, and deadcat.txt, given, of course, that those files exist in the current directory. Or, the following:

*ub.t?t

would include the files flub.txt, blub.txt, dub.txt, and nub.tnt. And finally, the following example:

??ub.t?t

would only include flub.txt and blub.txt.
Lastly is the concept of recursion. For most of MPQ2Ks commands (those that do not mention otherwise), there is a /r (recurse) option. This option can only work when wildcards are used, and specifies that all files in subdirectories should be included in the operation. For example, the following would include all files of *.txt in the current directory:

*.txt

But the following example would include all files of *.txt in the current directory and all of its subdirectories:

*.txt /r

4.3	Adding Files - the A Command
Probably the most useful of all the commands of MPQ2K is the add files command. As I said earlier, the files in a MoPaQ can be either compressed or uncompressed. What this means is that you can have some files in an archive that are compressed, while others not. You can decide which files are which; however, there are some file types that MUST NOT be compressed in a MoPaQ. So far, the only type I know of is Smacker animations (.SMK). If these are compressed in a MoPaQ, Starcraft will crash when it tries to read them. For this reason, there you can choose to add the files as either compressed or uncompressed. The syntax for adding files is:

MPQ2K a <MPQFile> <SourceFile> [DestinationFile] [/c] [/wav] [/r]

Parameters in <> are required, ones in [] are optional. MPQFile is the MoPaQ to add the file(s) to. SourceFile is the file(s) to add to the MoPaQ. If there is only a single file being added (no wildcards are used), DestinationFile is the name that the file will be stored as in the MoPaQ. But, if there are multiple files to add (wildcards are used), DestinationFile is the directory to put the files in. /c tells MPQ2K to compress the file(s). /wav tells MPQ2K to add the file with WAV compression, which is recommended for .WAV files (if both /c and /wav are used, /c will be ignored and /wav used). /r tells MPQ2K to recurse through subdirectories when searching for files to add. If no DestinationFile is given, the file will be added with the same name as SourceFile. For example, the following would add the file blah.txt to the MoPaQ whocares.mpq as dumbfile.txt:

MPQ2K a whocares.mpq blah.txt dumbfile.txt

You could also do this to add the file blah.txt as just plain blah.txt:

MPQ2K a whocares.mpq blah.txt

Wildcards may be used for adding files. But remember that the DestinationFile parameter changes. Thus, the following example would add the file flub.txt as temp\*.txt\flub.txt, not temp\flub.txt as it is meant to:

MPQ2K a *.txt temp\*.txt

Dont do this. Do it this way instead:

MPQ2K a *.txt temp

4.4	Extracting Files - the E Command
As well as the ability to put files into MoPaQs, MPQ2K also has the ability to get them out. That is where the extract command comes in. The general syntax for the extract command is:
MPQ2K e <MPQFile> <SourceFile> [DestinationDirectory] [/fp] [/r]

The parameters in <> are required, ones in [] are optional. SourceFile is the FULL name of the file(s) to be extracted from the MoPaQ, and DestinationDirectory is the directory in which to put the extracted file(s). If DestinationDirectory is absent, the file will be placed in the current directory. The /r parameter tells MPQ2K to recurse through subdirectories when searching for files to extract. The /fp parameter specifies that MPQ2K should extract the files with the full path. Consider these two lines:

MPQ2K e this.mpq flub\temp.txt

and

MPQ2K e this.mpq flub\temp.txt /fp

The first would extract the file flub\temp.txt as temp.txt in the current directory. The second would extract the file as temp.txt in the flub directory. Big difference.
NOTE: The /r parameter ONLY works in combination with the /fp parameter.

4.5	Renaming Files - the R Command
On occasion it may be necessary to rename a file in a MoPaQ. Thats what the rename command is for, the syntax of which is: 

MPQ2K r <MPQFile> <OldFileName> <NewFileName> 

All parameters are required. OldFileName is the full filename of the file to be renamed, and NewFileName is the new name for the file. Wildcards may not by used with the rename command.

4.6	Moving Files - the M Command
Complimenting the rename command is the move command. While the rename command only renames a single file in a MoPaQ, the move command moves one or more files from one virtual directory (technically MoPaQs dont have directories like hard drives do) to another virtual directory. The syntax is as shown: 

MPQ2K m <MPQFile> <SourceFile> <DestinationDirectory> [/r]

The parameters in <> are required, ones in [] are optional. SourceFile is the file(s) to be moved (wildcards allowed), DestinationDirectory is the virtual directory the file(s) to be moved will be placed in, and /r is the usual recurse switch.

4.7	Deleting Files - the D Command
One of the other useful commands in MPQ2Ks arsenal is the delete file command. The general syntax for which is:

MPQ2K d <MPQFile> <FileToDelete> [/r]

The parameters in <> are required, ones in [] are optional. FileToDelete is just that, the file(s) to delete; and, as usual, /r tells MPQ2K to recurse through subdirectories.
The first time you use the delete command, you might be rather surprised to find that a deleted file rarely takes up less space in a MoPaQ than a file that hasnt been deleted! This is due to the fact that the delete command only marks a file as deleted; it doesnt actually remove the file from the archive (to preempt the next question, no, you cant undelete a deleted file). To actually remove the file from the MoPaQ, you must use the flush command.

4.8	Flushing Out an Archive - the F Command
As mentioned above, the delete command does not actually remove a file, rather it only marks a file as deleted. Obviously, there must be some way to remove files from an archive, or else the delete command would be utterly useless. As a matter of fact, there is a way, and that is the flush command, using the following general syntax:

MPQ2K f <MPQFile>

 All parameters are optional. MPQFile is the file to flush.
The flush command searches through a MoPaQ and purges the space deleted files occupy, shrinking the MoPaQs size if there are any deleted files in it.

4.9	Listing the Files in an Archive - the L Command
Often, it is necessary to view all the files in a MoPaQ. To do this, you must use the list files command, as shown here:

MPQ2K l <MPQFile> [Filter] [Out_File] [/lf] [/p]
 
The parameters in <> are required, ones in [] are optional. This will list all the files in the MoPaQ to the screen. The [Filter] parameter is a wildcard filter that specifies what files to display. The [Out_File] parameter tells MPQ2K to write the listing to a file, rather than to the screen. When the /lf parameter is used with [Out_File], it tells MPQ2K to generate a listfile (with only each files name, useable as a listfile for MPQView or another MoPaQ utility), rather than a report file (which contains the name, size, and other information), like normal. And the /p parameter makes MPQ2K pause with each screen of files listed, and wait for a keypress.
NOTE: The list command will display files matching the filter spec in ALL subdirectories just as if the /r option for other commands had been used.

4.10	Running Scripts - the S Command
Perhaps the biggest reason that MPQ2K is superior to its predecessors is its scripting ability. MPQ2K allows you to run many commands much quicker and easier through scripts. The writing of scripts will be discussed in detail in section four. But here is how you run a script once it is written:

MPQ2K s <ScriptFile>

NOTE: You may not run multiple scripts using wildcards.

5.	Writing Scripts
5.1	Overview of Scripts
A script is basically a file that contains a lot of command lines for MPQ2K to process. This allows you to compile one or more entire MoPaQs in a single execution of MPQ2K. This allows for much faster execution, as well as avoiding some of the quirks that occur when a MoPaQ is changed after it is created.

5.2	Differences Between the Command Line and Scripts
For simplicitys sake, the command-line and script-line syntax are almost identical. There are a couple major points of difference, though.

1.	MoPaQs must be explicitly opened and closed in scripts. See section 5.3-5.4 for info on this.
2.	Because of this, you dont need to specify which MoPaQ you are working with on every single line, as you did on the command-line. For example, the following line is perfectly correct. It would add this.txt to the current archive as that.txt. The current archive is the one you have already opened.

a this.txt that.txt /c

5.3	Opening Archives - the O Command
The very first thing you must do in scripts is to open the MoPaQ you want to work with. The general syntax for the open archive command is:

o <MPQFile> [FileLimit]

Parameters in <> are required, ones in [] are optional. MPQFile is the file to open. FileLimit only takes affect when the archive is being created from scratch. It is the maximum number of files that this archive can hold, and is 1024 by default. If the MoPaQ already exists, FileLimit will have no effect, but no warning will be indicated. The FileLimit parameter has a minimum value of 16, and a maximum value of 262144.
NOTE: Each file that a MoPaQ can hold (the FileLimit) takes up 16 bytes in the MoPaQ, regardless of whether or not it is used. This can add up. For example, an empty MoPaQ with a file limit of 262144 would be 4 MB large!

5.4	Closing Archives - the C Command
Just like you must open a MoPaQ before using it, you must close the files after using them. Is it very simple to use the close command, as shown on the following line:

c

Thats all there is to it.

5.5	Pausing Scripts - the P Command
Occasionally, a script will behave different than you expected it to. And if the script is halfway large, it may scroll by too fast to see what went wrong. The solution to this common problem is the pause script command. The pause command is simple in function and usage, as shown here:

p

When this command is executed, the following message will appear, and MPQ2K will pause until you hit a key on the keyboard.

Pause - Press any key to continue...

5.6	Script Comments - the Semicolon ;
On some occasions you may want to put comments in a script file for one reason or another. To do this, simply put a semicolon(;) as the first character on a line, and the line will be ignored, and no error will be signaled.

6.	Technical Support
6.1	Is It a Bug?
There are several known issues with MoPaQ 2000. Some are bugs, some arent. I will try to summarize all known issues and their solutions here.

Symptom: When I double-click the mpq2k.exe file, a black window pops up for about half a second, and then disappears!
Problem: You havent read the manual.
Solution: Read section 4.2 of this manual.

Symptom: I can add around 1000 files to a MoPaQ, but then I cant add any more!
Problem: As part of the format, MoPaQs have a built in limit on how many files they can store. This number is designated when the MoPaQ is created for the first time. This number is, by default, 1024.
Solution: Write a script to compile your MoPaQ. Count the total number of files you want to put in the MoPaQ, then set the number of files on the line to create the MoPaQ (read section 5.3). This MUST be done when the MoPaQ is first created. If the MoPaQ already exists, delete it. For example, the following line create the archive whatever.mpq and set the file limit to 2000.

O whatever.mpq 2000

Symptom: I add a 20 MB .WAV file to a MoPaQ using /c, but the MoPaQs size increases almost 20 MB. Wheres the compression?
Problem: Due to the nature of WAV file, they cannot be reasonably compressed with MPQ2Ks standard compression (about 5% compression with /c, on average).
Solution: Add the file with /wav instead of /c. That will turn on MPQ2Ks special WAV compression and compress the file an average of 66%.

Symptom: I have this tiny archive with like 2k or stuff in it, but its like 20k large? Wheres the size coming from?
Problem: Each file that a MoPaQ CAN contain (not DOES contain) gets one header entry of 16 bytes long. When you get into the thousands of files, those 16 bytes can add up.
Solution: Try decreasing the number of files your archive can hold. See question above. 

Symptom: Ive added some Smackers (SMKs) to my MoPaQ, but Starcraft crashes every time it tries to view them.
Problem: Smackers MUST NOT be compressed in an archive.
Solution: Do not specify the /c (compress) option when adding the Smackers.

6.2	Technical Support Checklist
PLEASE dont go reporting to me every time something unexpected happens! If you do, I will simply squelch you. But, if you do have a problem, go through this checklist. 

1.	Try looking through the FAQ in section 6.1. Most common problems and their solutions can be found by looking at the FAQ above.
2.	Try looking through the whole manual. The solution to most problems not in the FAQ is in here somewhere. Read the WHOLE manual first. If you report something to me that the solution is in this manual, I wont be very happy about it, and you may or may not get a response.
3.	Try getting the latest version of MPQ2K and LMPQAPI. See sections 6.3 and 6.4.
4.	Make sure the problem can be reproduced. Is it just a fluke? Try doing the same thing again. If the problem occurs exactly the same way more than once and it isnt in the manual, it may possibly be a worthwhile error to report.
5.	Finally, lastly, and leastly, try contacting me. I can be reached at <quantam@campaigncreations.com> or at ICQ #10078230 (ICQ is preferred).

6.3	Getting the Latest Version of MoPaQ 2000
For the most up-to-date version of MoPaQ 2000, go to the official MoPaQ 2000 web site at <www.campaigncreations.com/starcraft/mpq2k/>

6.4	Getting the MPQ API Library DLL
You can acquire the MPQ API Library DLL and documentation (for your own programs) at Leliks site at <http://www.chat.ru/~lelmpq/>.

7.	Credits
This program (excluding the LMPQAPI.DLL) was written totally and completely by me, Justin Olbrantz(Quantam). I may be contacted at <quantam@campaigncreations.com>.
The MPQ API Library DLL (LMPQAPI.DLL) was written mostly by my amazing friend Andrey Lelikov, who may be contacted at <lelik@prologue.rustel-net.ru>. Parts were written by myself.

8.	Coming In Future Versions
GUI?
Fixes to any bugs I can find
Got any other ideas? Mail me!

9.	Legal Stuff
This program is freeware, you can do anything you want with it, but IT IS DISTRIBUTED "AS IS".  NO WARRANTY OF ANY KIND IS EXPRESSED OR IMPLIED. YOU USE IT AT YOUR OWN RISK. THE AUTHOR WILL NOT BE LIABLE FOR DATA LOSS, DAMAGES, LOSS OF PROFITS, OR ANY OTHER KIND OF LOSS WHILE USING OR MISUSING THIS SOFTWARE.