Staredit Network > Forums > Modding Assistance > Topic: [GPTP] The Grand Topic
[GPTP] The Grand Topic
Feb 28 2016, 8:18 am
By: Corbo  

Feb 28 2016, 8:18 am Corbo Post #1

ALL PRAISE YOUR SUPREME LORD CORBO

GENERAL PLUG IN TEMPLATE PROJECT


TL;DR We make, discuss ideas, provide solutions and post our own plug in tutorials for the general plug in template project!

The Topic
So I have personally been doing a lot of GPTP stuff lately, I am far from a programmer, in fact, I have just been learning my way to understand a little bit of C++, this is by far my best attempt so far (out of like maybe tens of attempts in which I just simply loose interest...) and I just got the idea to make a tutorial/questions/documentation project out of whatever I am doing with the GPTP.

So, in this topic I will provide assistance (if I can) I'll post my own works that I have properly achieved and I'll be describing whatever I did to get them work and further readings on programming to better understand the concepts behind the plug ins.

The Goal
The idea is not only that I post my own works or turn them into tutorials of sorts, the idea is for everyone that has ever worked on a plug in for the GPTP to post their own, if they want to, of course, so that other people can become interested in such and gain knowledge through this topic.

The Format
If you are posting your own plug ins remember, please, that this is a topic aimed for absolute begginers that, like me, probably know next to nothing about programming. Since I have been in the position of "programing-knowledgenessless" I can testify that without any help making plug ins, even with the GPTP can be quite very much intimidating. So, while posting your own stuff you should try to be as simple and as descriptive as you possible can.

The Idea
idk man, I'm just very drunk atm and i've been thinking of this lately but this gave me the motivation to actually do it. A lot of the information in here could, and should be wrong. I like to be corrected and I'd enjoy people to contribute in and do so. I'll try to do my best to keep all the information correct, up to date and constantly improving it or complementing it. After all the topic is intended to help new modders to write their plugins as well. Starting to write plug ins is, in its very own way, writing C++ code and if you're not a programmer this can be quite intimidating, frustrating and simply difficult. The idea of this is that, hell, I am not a programmer either, if I can do it anyone can and should.

The Tutorials
Requirements - Installing Visual C++ & runtimes & Others
Your First Plugin

BroodKiller's Tutorials
These tutorials were made by BroodKiller. I am listing them here as reference of other material you might want to check out too. They're hosted at ModCrafters and their availability might be subject to modcrafters'.

Plugins Guide. Part 1: Writing the Code
Plugins Guide. Part 2: Using the Data
Plugins guide. Part 3: Creating, Compiling and Running

Post has been edited 6 time(s), last time on Apr 8 2016, 2:35 am by Roy.




Feb 28 2016, 8:19 am Corbo Post #2

ALL PRAISE YOUR SUPREME LORD CORBO

REQUIREMENTS

In order to properly make plug ins for Starcraft with the GPTP you will need to get a couple of things beforehand which are:
  • Visual Studio 2010 (For the 2010 GPTP version)
  • Working & latest copy of the GPTP
  • Firegraft v0.93
  • Some C++ Knowledge
  • List to increase along the way I write this

Most of these we'll cover in this tutorial, except for the "Some C++ Knowledge part" which you should do in your own time. I'll point out the sites and books I've been reading, though.


GETTING VISUAL STUDIO 2010
In order to sucesfully edit and create and... well, actually make a plug in with the GPTP you will need to install a version of Visual Studio 2010, which is what the version of the GPTP we're going to be using uses. It was originally written for VS 2008 but it was updated to use some C++ 11 features (Don't worry, I too don't know what this means) and code-readability was improved. Trying to compile the source with another version of Visual Studio will result in failure.
Additionally, there's is a 2008 version2008 version which has reportedly more functions and it is being updated and constantly improved by UndeadStar. We are going to be using the 2010 version for this tutorial and most of the things discussed here might actually not work there without some code editing (Since the 2008 and 2010 functions change in some way)

You can get Visual Studio 2010 easily by just googling, going to Microsoft or following this link: Visual Studio C++ 2010 Note that this link, most likely, and should get you to try to install a more up-to-date version of VS. Thing that you should not do because i have found that trying to compile the GPTP with another version other than 2010 results in errors. I personaly use Visual Studio C++ 2010 Express. Which you can get here: THIS IS A 3RD PARTY SITE, NOT MICROSOFT.

The program, like most, if not all, Visual Studios is completely free. You are most likely going to download a Trial for 30, 60 or 90 days which you can, and should, activate when it's done. (You need an original and verified windows OS actve in order to complete the verification process (They send you a key via e-mail)


GETTING THE GENERAL PLUG IN TEMPLATE PROJECT
Easy. https://github.com/SCMapsAndMods/general-plugin-template-project

In order to get the GPTP's 2010 version you'll have to download so from its git copy. You can either create an account in github or you can just go to the page listed above and get it via the "Download ZIP" button.




If you do choose to create a new account and register to github, you might want to clone the whole project to your desktop using the github application. I'll make sure to write a short process on how this is done but having downloaded the ZIP package for now is ideal and enough.


GETTING FIREGRAFT v0.93
Easier. http://www.staredit.net/sc1db/file/2258/


CONCLUSION
Basically, at this point you should have these:
  • Visual Studio 2010 installed on your PC
  • A Folder which should contain what you downloaded in github that's supposedly GPTP. This folder should also contain multiple folders that we'll get to later on.
  • A working version of Firegraft for 1.16.1 so that you can embed your plug ins into an .exe (Alternatively you could have just downloaded MPQDraft)


Post has been edited 9 time(s), last time on Apr 8 2016, 2:35 am by Roy.




Feb 28 2016, 4:45 pm KYSXD Post #3



Maybe you could read the tutorial made by BroodKiller:

Plugins Guide. Part 1: Writing the Code

Plugins Guide. Part 2: Using the Data

Plugins guide. Part 3: Creating, Compiling and Running

Also, in Modcrafters page there are few examples you could read.

In the GPTP wiki there is also a list about important things you should know when working with GPTP, like How GPTP works.



None.

Feb 28 2016, 6:36 pm Corbo Post #4

ALL PRAISE YOUR SUPREME LORD CORBO

Thanks, I'll keep in mind those and create this topic accordingly, I have read some of those tutorials too. Not all, though.
Also, the GPTP wiki is compeletely helpless, the wiki was created for the 2008 version (I assume) so when trying to learn with only that wiki you'll eventually get lost because some functions have been renamed or relocated, unless you manage to get a 2008 version (which you cannot in the git site...)

Post has been edited 2 time(s), last time on Apr 8 2016, 2:35 am by Roy.




Feb 28 2016, 7:02 pm KYSXD Post #5



The lastest GPTP version i know is the UndeadStar's GPTP 2008 version. It has more functions than the last GPTP 2010 version. And BoomerangAide is updating it very often:

You can check Here.

Edit: (the last update today (28/02/2016) is in the Update 3 branch)

Quote
Note from BoomerangAide:

-If there are several Update-X branches, the most stable is the one with the lowest value, the less tested (but probably with more experimental features) is the one with the highest value.




None.

Feb 28 2016, 9:01 pm Corbo Post #6

ALL PRAISE YOUR SUPREME LORD CORBO

YOUR FIRST PLUGIN



STARTING UP
Like 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 2010

There'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 PLUGIN
If 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:
Code
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:

Code
            //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 STARCRAFT
The function for outputting text to starcraft is:
Code
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.
game_hooks.cpp 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 PLUGIN
At 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:
Code
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 PLUGIN
Open 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.




Mar 5 2016, 7:10 am iCCup.xboi209 Post #7



It's a pity that GPTP isn't updated to fully utilize more C++11 features, VS2010 is sooooo old.




Options
  Back to forum
Please log in to reply to this topic or to report it.
Members in this topic: None.
[05:27 pm]
Pr0nogo -- TiKels
TiKels shouted: Lemme know what you think
the gay autotune really turned me off but it was informative
[05:07 pm]
LoveLess -- That was what I said to myself at first too though.
[05:06 pm]
LoveLess -- Ahli
Ahli shouted: Clearly, men already died because they are the warriors and protectors. Else, maybe more women were send to that galaxy because they need to populate it.
Yeah but... I dunno, 50/50?
[04:57 pm]
Apos -- He is talking so fast, yet everything seems to make sense.
[03:41 pm]
TiKels -- Lemme know what you think
[03:41 pm]
TiKels -- I'm a year late on this meme but damn its hot
[02:47 pm]
Ahli -- Clearly, men already died because they are the warriors and protectors. Else, maybe more women were send to that galaxy because they need to populate it.
[02:40 pm]
LoveLess -- Maybe the whole SJW influence shit people have been talking about has some merit.
[02:39 pm]
LoveLess -- So been playing Mass Effect Andromeda for a while now and started to notice it felt like a clamfest... So I started counting, 25 men to 42 women after I started.
Please log in to shout.


Members Online: Roy, millinern87