Building HPM Plugin for MSVC
After you've either built your own plugin or downloaded a plugin from the forums, you need to configure your build to include the plugin as a sub project.
There are 2 guides on how to prepare your Microsoft Visual Studio C++ (MSVC) environment for a new HPM plugin.
You can choose to follow either one.
You need the following:
Microsoft Visual Studio IDE - This IDE will be used to build your main build solution (your Hercules server), and to include your plugins as new sub projects.
As of December 2018, the IDE version I used for updating this guide uses Microsoft Visual Studio Community 2017, Version 15.2. This property can be viewed when you open the IDE and go to Help > About Microsoft Visual Studio.
Notepad++ - A convenient improvement to the standard notepad editor. This will be used when editing .conf files or .c. Unlike more complicated text editors (Sublime Text 3, Visual Code), Notepad++ is much much simpler and would be less confusing for new programmers.
For this tutorial on how to build your HPM plugin, we will use YourProject as the name of the plugin. This means that it is contained in a file called YourProject.c. Plugins can be downloaded from the Hercules Board, Plugin Releases.
In May 2018, User Kiriez introduced the VS Plugin Creator, which automates steps 1 to 13 of the New Method described below. I suggest you try this first to see if it works. Give feedback on the tool (whether it works or not, errors you might encounter) on the thread itself.
If his tool didn't work, try using the Plugin Automator for Windows by User fourxhackd, which automates steps 1 to 10 of the New Method.
Using the tools will make sure you don't make simple typo-related mistakes, or placing the files in the wrong folder. Doing it manually, as described in the New Method, will show you exactly what the tools do.
This new method is recommended. There are two parts to the new method: integrating the plugin into your project's build solution and adding your plugin to the configuration files.
It uses the software Visual Studio IDE Community 2017 and would most likely be the software that you can access and download as of this date.
This method was imported from the Wiki data in 2016, and was updated as of December 2018.
Download the YourProject.c from the Hercules Board, Plugin Releases or build it yourself.
Copy or move the YourProject.c file into your /src/plugins/ folder.
Depending on which Visual Studio C project version (.vcproj) you are using, navigate to the appropriate folder.
For example, if you are using Microsoft Visual Studio IDE (Community 2017), navigate to the directory \vcproj-15\. We use 15 because that is the latest build type available (better to use 15 instead of using the older build solutions).
Select plugin-sample.vcxproj, copy the file, and paste it on the same directory. This will produce a copy of the file with filename plugin-sample - Copy.vcxproj.
Rename plugin-sample - Copy.vcxproj into YourProject.vcxproj
While renaming, Highlight the word YourProject and Copy it by Ctrl+C
Right click on YourProject.vcxproj, select Edit with Notepad++ or Microsoft Notepad.
Find the following line:
<ProjectName>plugin-sample</ProjectName>
Replace plugin-sample with YourProject. Make sure that you copy this correctly and not make typos.
To avoid typos, you can use CTRL+C to copy the name of the plugin and CTRL+V to paste the name of the plugin without making mistakes.
Find the following line:
<TargetName Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">sample</TargetName>
Replace sample to YourProject.
<TargetName Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">YourProject</TargetName>
Find the following line:
<ClCompile Include="..\src\plugins\sample.c" />
Replace sample to YourProject.
Save the file by pressing CTRL+S.
From your the main folder of your server, open the appropriate Visual Studio solution file Hercules-N.sln using your IDE. In this example, we used Hercules-15.sln because we are using Microsoft Visual Studio (Community 2017).
On the Solution Explorer tab, right click Hercules-15, select Add > Existing Project...
Select YourProject.vcxproj in the \vcproj-15\ folder.
Right click `Solution 'Hercules-15' and select Build Solution.
This will now re-build your Hercules server while also integrating your plugin. This patches up the source code as necessary and includes the code into the appropriate .c files without you having to go to the individual files.
Finally, we will open the file /conf/plugins.conf and include the name of our new plugin into the list.
plugins_list: [
/* Enable HPMHooking when plugins in use rely on Hooking */
//"HPMHooking",
//"db2sql",
//"sample",
//"other",
"YourProject"
]
{{Quote|text=This guide used Microsoft Visual Studio C++ (MSVC) 2008 as an IDE. This guide was tested using that IDE as well. It was also tested using Microsoft Visual Studio C++ 2010.|sign=Ind}}
Go to 'src/plugins/' folder, create a new '.c' file, e.g. 'dance.c' (this name will be used throughout this guide) File:step1.JPG
Open dance.c and paste this code
#include "common/hercules.h" // Should always be the first Hercules file included! (if you don't make it first, you won't be able to use interfaces)
#include <stdio.h>
#include <string.h>
#include "common/HPMi.h"
#include "map/script.h"
#include "map/pc.h"
#include "common/HPMDataCheck.h" // should always be the last file included! (if you don't make it last, it'll intentionally break compile time)
HPExport struct hplugin_info pinfo = {
"dance", // Plugin name
SERVER_TYPE_MAP,// Which server types this plugin works with?
"0.2", // Plugin version
HPM_VERSION, // HPM Version (don't change, macro is automatically updated)
};
ACMD(dance) {
if (!message || !*message) {
clif->message(fd, "usage: @dance 1-9");
return -1;
}
if ( atoi(message) == 1 ) {
clif->specialeffect(&sd->bl, 413, ALL_CLIENT);
} else if ( atoi(message) == 2 ) {
clif->specialeffect(&sd->bl, 414, ALL_CLIENT);
} else if ( atoi(message) == 3 ) {
clif->specialeffect(&sd->bl, 415, ALL_CLIENT);
} else if ( atoi(message) == 4 ) {
clif->specialeffect(&sd->bl, 426, ALL_CLIENT);
} else if ( atoi(message) == 5 ) {
clif->specialeffect(&sd->bl, 458, ALL_CLIENT);
} else if ( atoi(message) == 6 ) {
clif->specialeffect(&sd->bl, 466, ALL_CLIENT);
} else if ( atoi(message) == 7 ) {
clif->specialeffect(&sd->bl, 501, ALL_CLIENT);
} else if ( atoi(message) == 8 ) {
clif->specialeffect(&sd->bl, 540, ALL_CLIENT);
} else if ( atoi(message) == 9 ) {
clif->specialeffect(&sd->bl, 550, ALL_CLIENT);
} else {
clif->message(fd, "usage: @dance 1-9");
}
return true;
}
/* Server Startup */
HPExport void plugin_init (void) {
addAtcommand("dance",dance);
}Open your MSVC project (e.g. '''Hercules-10.sln'') File:step2.JPG
Go to the '''Solution Explorer''' File:step3.JPG
Right click the Hercules project (first item in '''Solution Explorer'''), and click '''Add->New Project''' File:step4.JPG
Select '''General''', and pick '''Empty Project'''. File:step5.JPG
Enter the name of your plugin in the '''Name''' field, and click OK.
In the solution explorer it'll display the new project. File:step6.JPG
Right click the new project, and open '''Add->Existing Item''' File:step7.JPG
Browse to '''src/plugins/''' and select the '''dance.c''' file, and hit OK. File:step8.JPG
It will place the '''dance.c''' file under the '''Source Files''' folder, drag it to the project you created and drop it (in a manner it be placed out of the source files folder.) File:step9.JPG (It should look like the image below) File:step10.JPG
With the '''dance.c''' out of the folders, delete the 3 of them (select the 3, hit delete, hit ok) File:step11.JPG (It should look like the image below) File:step12.JPG
Right click the project you created, open '''Properties''' File:step13.JPG
Under '''Configuration Properties''' click '''General''', change '''Output Directory''' to '''..\plugins''', '''Intermediate Directory''' to '''$(ProjectName)$(ConfigurationName)''' and '''Configuration Type''' to '''Dynamic Library (.dll)''' File:step14.JPG
Under '''Configuration Properties''' click '''C/C++''' and open '''General''', change '''Additional Include Directories''' to '''..\src;..\3rdparty;..\3rdparty\msinttypes\include;%(AdditionalIncludeDirectories)''' File:step15.JPG
Under '''Configuration Properties''' click '''Linker''' and open '''General''', change '''Output File''' to '''$(OutDir)$(ProjectName).dll''' File:step16.JPG
Under '''Configuration Properties''' click '''C/C++''' and open '''Preprocessor''', change '''Preprocessor Definitions''' to '''_WINDLL;PCRE_SUPPORT;%(PreprocessorDefinitions)''' File:step17.jpg
Under '''Configuration Properties''' click '''C/C++''' and open '''Advanced''', on '''Disable Specific Warnings''' add '''4996;%(DisableSpecificWarnings)'''
This step can prevent errors like ''sscanf'' or ''sprintf'' that only happen with Microsoft compiler.
File:step18.png
Add your code to the '''dance.c''' file, and then right-click the project you created, and select '''Build'''
Add it to ''' /conf/plugins.conf'''
plugins_list: [ /* Enable HPMHooking when plugins in use rely on Hooking */ //"HPMHooking", //"db2sql", //"sample", //"other", "dance", // loads dance plugin ]
- This guide is probably the worst I've ever written, if you can do better please hit the 'Edit' button, will be most welcome. - Ind
- I used MSVC 2008 when testing this guide.
- Sorry for editing this page, I added step by step images for other people to follow so they can easily follow one of the best feature Hercules have, the HPM. - Thanna
- The tutorial is tested on MSVC 2010.
- Another method idea by hemagx, sorry for publish it first - AnnieRuru.