Post July 15th, 2009, 5:01 am

Plugins guide. Part 3: Creating, Compiling and Running

A basic guide to writing SC plugins (by BroodKiller)

Part 3. Creating, Compiling and Running


In order to compile the code that we've written into a real plugin, we will need a few things:
-General Plugin Template Project v2.0 (the full source, not the GUI)
-Microsoft Visual C++ 2008 Express Edition
-FireGraft for 1.15.1 or later or MPQDraft

Don't be scared that we will use the MS VC++ 2008 Express. You don't have to learn all of it, we will need just the very basic of its features to succesfully create some cool plugins. GPTP is a great starting point to writing plugins. It provides you with a library that allows you to access data in the game and header files that tell you what you can access. You can just take it, and start writing your custom code, which is a fantastic thing.

We start out by opening the GPT v2.0 solution file. Then, on the panel to the left choose Solution Explorer (should be at the bottom side), to browse through the files belonging to it. There are many different files listed in it, placed in different directories. Some contain information on the data structures (classes) used in the GPT, other hold version-dependent memory addresses and some other internal stuff. Fortunately, you don't have to use/know all of them, and here's a rundown of files that you'll have a chance and need to touch while plugin making:

definitions.h - in this file you can specify 3 things: The ID of your plugin, the version of the game it works with and whether we're working in the DEBUG or RELEASE mode. You will probably want to change the last option from DEBUG to RELEASE after you're finished with your plugin.
qdp.cpp - in this file you can specify the name of your plugin, as it will appear in MPQDraft and Firegraft plugin listing.
enumerations.h - this file contains the list of handy names for unit, tech, upgrade and order IDs. You may want to consult it every now and then, if you don't want to use the numerical values instead of the IDs
structures.h - this file contains the descriptions of some of the structures that you can access in the plugin code, including the IMAGE and SPRITE structures, as well as others.
unit.h - this is by far the most useful reference file in the GPT, because it contains the description of the UNIT structure, that holds a lot of various interesting properties. You get familiar with this file early on :)
game.h - this file is to contain our custom plugin code. It contains 3 ready-made functions: GameOn - that is executed at the beginning of the end. GameEnd, that is executed at the end; and nextFrame() that goes on throughout the entire game. It is the last function that we will spend probably most of the time with.

While there are files already in the template, there is no problem if you want to add to it later on some new ones, with your own custom code.

In order to compile your plugin, you press F5. If there are any errors, you will see nothing. The "Output" panel at the bottom of the screen will tell you what problems did it encounter in your code. It will say something along the lines of: "Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped". Above this info you will find listed the precise errors in the code. If you don't know where an error lies, right-click the line and choose "Go to Location", which will take you directly to the line in the code that is causing a problem, so you can fix it.
If all the code is correct, MSVC will come up with an 'error' that states: "Unable to start program "..." The system cannot find the file specified." If you see that message, don’t worry, it actually did compile everything correctly, it just is trying to run a file that doesn’t exist because of the compiler we are using. Now that you’ve compiled, open up the GPT directory with the solution and go to the folder “General Plugin Template Project v2.0” and look for the file "qdp.dll". This is our compiled plugin. Rename this file to whatever you want, but make sure it has the extension ".qdp". Now you're ready to run the plugin and see if your effects work properly.

Running the plugin with MPQDraft:

1). Open up MPQDraft.exe.
2). Select either option (Create Self-Executing MPQ or Load MPQ Patch)
3). Select Starcraft and hit next
4). Load your custom MPQ archive (optional) and hit next
5). Hit “Browse for Plugins”
6). Search for your plugin in the directory you renamed it in
7). Click Open
8). Make sure it is check marked.
9). Configure if needed.
10). Click finish

For use with FireGraft:

1). Open Firegraft.exe
2). Make a New archive or Open an old one
3). Go to the Plugins tab
4). Click Add
5). Search for your plugin in the directory you renamed it in
6). Click Open
7). Configure if needed.
8). Save or Save As…
9). Run the saved .exe


This would be all the info concerning successful preparation and compilation of the plugin code using GPT v2.0. I have used here notes on this subject made by AofST for his original plugin 'tutorial'. If anything is unclear or you would like more info to be included in this particular part of the guide, let me know.


-Uncle Broody
Clean...simple...devious. I like it.