YOUR FIRST PLUGIN
STARTING UPLike so with most programming tutorials on C++ your very first plug in should be one that outputs the text "Hello, World!". The GPTP has its very own way of doing this which we'll soon find out but first we need to get some things in order.
If you open up your downloaded copy of the GPTP (The one we downloaded back at the very first tutorial) you'll find yourself in a picture like this:
Of all these folders, my personal copy is the one labelled "Corbo", most obviously, others might be different plugins/branches/copies from other people, remember that the way the github site works is that everyone can have a copy and contribute with their own copy, but it keeps the original. The original copy is the one labeled GPTP. I suggest making a copy of this folder for your edits. This way you'll always have the original source to go back to as a back up in case you
terribly mess something up, which is something that just happens.
If you open up the GPTP folder you'll find yourself with more folders and one labeled "src" which contains these files:
The file named "GPTP.vcxproj" is the project file. Opening this will open the whole project for edition. You could also edit the files individually by going into the "/hooks/" sub-folder but you'll eventually need to compile your code. It's better to just edit the whole project by opening the actual project file, GPTP.vcxproj.
When you open the project file, after a little while of Visual Studio 2010 firing up and loading itself and all the project's files you'll end up with a picture like this:
WORKING WITH VISUAL STUDIO 2010There's quite a few things going on in here so I'll try to explain some of them.
1. Is your standard options for most softwares, with a twist. You have the basics, save, save as, new, open, etc. And then you have a few settings specific for VS2010. The "Start Debugging" button, next to it there a "Solutions Configuration" drop down. The one that matters for us the most, at the moment, is the drop down which you might have it set up as "Debug", That's alright, but if we compiled our code the output plugin will be a bit large as compared to if you select the option "Release" from that drop down. Just set the drop down to Release and that's done.
2. This is the "Solution Explorer" in this box you'll find all the project files related to the GPTP. All the source files are listed here, along with all other files that the whole project uses in order to compile. This could be either Starcraft Library Files written by other people that the GPTP uses, or GPTP project files or even C++ standard library files. Remember, this is basically programming so all the rules apply and most programs need standard library files to function. You can double click the files listed in this box so you can see and edit the code in box #3.
3. This is the main screen, where all the code for a file will show up and where we will write our very own plug ins! You will notice that I have the "game_hooks.cpp" file opened in said screenshot. If you opened more than 1 file they will appear tabbed in the upper ribbon of this box. You see that there's a lot going on with the code, lots of functions, lots of stuff that doesn't quite make sense. But we can simplify this! Don't worry!
4. This is the output box, this is usually used for debbuging, when you compile your code it will process it and output the results here. If the program succeeds in compiling it will say so here. If there are any errors it will also complain in here. We'll get in to this later on.
YOUR FIRST PLUGINIf you can see the code written in "game_hooks.cpp" you'll see that it has lots of lines, they probably won't fit your screen and overall seem very complex and intimidating. But really these are just three little functions that Starcraft calls in every game.
To simplify our view you can click the little "-" and "+" symbols in the far left of the box containing the written code.
We now realise that these are just three functions defined as:
bool nextFrame(){...}
bool gameOn(){...}
bool gameEnd(){...}
The one that matters the most of all is the
boolean function nextFrame(). You can see that Visual Studio has a green text saying "/// This hook is called every frame; most of your plugin's logic goes here." Green text are comments and the compiler will ignore them, they're there so you can understand some functions and they were written in by the programmer so guys like you and me can actually understand what's going on.
If you expand back the functions you'll find these lines:
//This block is executed once every game.
if (*elapsedTimeFrames == 0) {
//Write your code here
scbw::printText(PLUGIN_NAME ": Hello, world!");
}
//Loop through all visible units in the game.
for (CUnit *unit = *firstVisibleUnit; unit; unit = unit->link.next) {
//Write your code here
}
basically nextFrame() is called EVERY frame in the game, if there's anything changing in the game it's going to call back to this function. That means that we can write our code here and it will most definitely have effects in the game at some point. You'll also see that there's a line that contains the words "Hello, world!" That seems an awful lot like what we're trying to do, make Starcraft output "Hello, World!" and you know what, it IS exactly what we're trying to do.
OUTPUT TEXT TO STARCRAFTThe function for outputting text to starcraft is:
void printText(const char* text, u32 color)
You can call it at anytime, it's particulary useful to debug things, which we'll get to later. You can see that this function is type void and takes two parameters. A char and an u32 to define the color. This function is prefixed with scbw::, if you noticed. This is because it exists in a namespace called "scbw" in the "api.cpp" source file. There are also many other functions in the scbw namespace that we'll get to later and you can access them all.
Note that the reason you can add them is because the "game_hooks.cpp" source file includes the "api.cpp" in its header.
#include "game_hooks.h"
#include <graphics/graphics.h>
#include <SCBW/api.h>
#include <SCBW/scbwdata.h>
#include <SCBW/ExtendSightLimit.h>
#include "psi_field.h"
#include <cstdio>
It doesn't directly include api.cpp but it does include "api.h" which in turn calls to "api.cpp" which is why you can access all of the functions in api.cpp in "game_hooks.cpp". Confusing? Sure. But if you think about it it's only logical. It's like if you climbed a tree to grab some apples. If you choose to go to the rightmost branch, you'll be able to grab all the apples in that branch, but not the ones on the left. (Yay for poor analogies)
YOUR FIRST PLUGINAt this point you have written absolutely nothing of code but we'll make our first plug in anyway!
You're at a point that the GPTP already will output the "Hello, World!" we want to output. So let's just compile the program and implement it!
Press F7 to "build a solution". Or go to Debug->Build Solution. Visual Studio C++ 2010 will do its thing and compile all the code, all the source files, all the libraries, everything and output several files, in between which will be the one we one, a file with the extention ".qdp"
You will know that Visual Studio C++ 2010 is done because you'll see these lines in the output:
1> Creating library D:\whateveryoursubfoldersare\general-plugin-template-project\GGPTP\src\Release\GPTP.lib and object D:\whateveryoursubfoldersare\general-plugin-template-project\GGPTP\src\Release\GPTP.exp
1> Generating code
1> Finished generating code
1> GPTP.vcxproj -> D:\BACK UP SORTED\SC\MODDING\general-plugin-template-project\GGPTP\src\Release\GPTP.qdp
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
Build: 1 succeeded means we just made our very own first plug in and is ready to be implemented! Since we have made absolutely no changes this was very easy. Trust me that when we get to actually writing code this will fail many times.
But for now go to the GPTP source folder and you'll see that a folder labeled "Release" has been created or "Debug" if you didn't change the dropdown option back at the beggining of this tutorial.
You'll find several files in this folder along with the actual real .qdp file we want:
And that was it! All we need to do now is implement the plug in for which we will use Firegraft!
IMPLEMENTING YOUR FIRST PLUGINOpen up firegraft and create a new file:
The process of adding a new plug in is very easy and straight forward. Just go to the "Plugins" tab and click "Add" at this point you'll get a pop up box and you should locate your .qdp file that we just compiled and add it to firegraft. When done it should show up listed and at this point you're ready to save the firegraft project as a .exe so we can test it out.
THE RESULT
You will notice that it outputted more than just "Hello, World!" We'll get to that later on as I am going to pause writing this tutorial for the day.
Post has been edited 2 time(s), last time on Apr 8 2016, 2:34 am by Roy.
fuck you all
*strange cult noises in the background*