The Hercules Plugin Manager, often referred to as the [[HPM]], is yet another [[Hercules Original]].
Building a plugin¶
What does building a plugin mean?¶
To build a plugin is the same as to compile a plugin. This means that you want to use an existing plugin (that you may have downloaded from the Plugin Releases forum) in a server.
Where do I start?¶
The C code for the plugin normally won't have discrepancies. In order to compile the plugin, certain criteria must be met depending on your Operating System.
There are two (2) guides below: One for Windows and the other for everything else which should work on any *nix distro, as well as on OSX.
I use a Windows Machine, what guide should I follow?¶
I use a *nix based system (Linux or OSX), what guide should I follow?¶
Creating a plugin¶
What does creating a plugin mean?¶
Creating a plugin means to develop/design your custom source code edits that introduces new systems into RO. For example, the people who release plugins in the Plugin Releases forum created plugins. People who use the plugins that they made should follow the building a plugin guide shown above.
This is usually what more advanced users do, so if you're not sure if you're creating a plugin or not, you most likely aren't creating a plugin.
After following the building a plugin guide, all thats left is for your plugin's code to be made, the following will guide you through the basics of how a HPM plugin works.
HPM Events¶
Events are functions in a plugin that are triggered by the Hercules
Plugin Mananger when they meet certain criteria.
- void server_preinit(void)
- Triggered when the server starts loading plugins, useful to parse battle_config
- void plugin_init(void)
- Triggered when the server starts
- void plugin_final(void)
- Triggered when the server starts to shut itself down
- void server_ready(void)
- Triggered after the server is done starting, and is online.
- void server_post_final(void)
- Triggered after the server's main shutdown procedures are complete, core functionality such as memory manager, timer, and sockets are still available at this point.
With the HPM you only need to code the events your plugin will use.
HPM Hooks¶
In Hercules, hooking is a simple operation, it is possible to hook an infinite number of times to the over 2k hookable functions (all the interfaced ones, accounting for over 99% of map server)
HPExport void plugin_init(void)
{
addHookPre(pc, dropitem, my_pc_dropitem_preHook); /* int my_pc_dropitem_preHook(struct map_session_data **sd, int *n, int *amount) */
addHookPost(pc, dropitem, my_pc_dropitem_postHook); /* int my_pc_dropitem_postHook(int retVal, struct map_session_data *sd, int n, int amount) */
}
Hooks receive all function params as pointers, whereas the original may be
the one for the prehook shall be
which allows for hooks to modify any and all data as it pleases.
postHooks receive one additional param, which accounts for the result of the original function,
In this case it'd allow for the postHook to react properly to what the original returned, in this case (for pc_dropitem) 0 (failure) or 1 (success)
A full usage of this is demonstrated in the HPM's sample
HPM @commands¶
The HPM makes it very simple to provide @commands through plugins.
You define a new atcommand exactly as it'd normally be done in
Example:
ACMD(sample) { //@sample command - 5 params: const int fd, struct map_session_data* sd, const char* command, const char* message, struct AtCommandInfo *info
clif->message(fd, "You used the @sample command!");
ShowDebug("I'm being run! message -> '%s' by '%s'\n", message, sd->status.name);
return true;
}
void plugin_init (void) event.
and voila, your plugin now adds the @sample command.
A full usage of this is demonstrated in the HPM's sample
As of 778facb21f, atcommands loaded via plugins will overwrite default/original commands with the same name.
HPM Script Commands¶
The HPM makes it very simple to provide through plugins.
You define a new script command exactly as it'd normally be done in
Example:
BUILDIN(sample) { //script command 'sample(num);' - 1 param: struct script_state* st
int arg = script_getnum(st, 2);
ShowInfo("I'm being run! arg -> '%d'\n", arg);
return true;
}
void plugin_init (void) event.
addScriptCommand("sample", "i", sample); //note the 2nd param is this commands' arg-types (in this case, a number)`
A full usage of this is demonstrated in the HPM's sample
HPM Console Commands¶
The HPM makes it very simple to provide through plugins.
You define a new console command exactly as it'd normally be done in
Example:
CPCMD(sample) {//console command 'sample' - 1 param: char *line
ShowInfo("I'm being run! arg -> '%s'\n", line?line:"NONE");
}
After that you just have to link your new script command, to do that you use the void plugin_init (void) event.
addCPCommand("this:is:a:sample",CPCMD_A(sample)); // note the first param is the path to this command, in this case it translates to 'this is a sample' and everything afterwards is the commands' params
and voila, your plugin now adds the sample console command.
A full usage of this is demonstrated in the HPM's sample
HPM Custom Packets¶
The HPM makes it possible for a plugin to add or override packets within all 3 servers
Example:
/* sample packet implementation */
/* cmd 0xf3 - it is a client-server existent id, for clif_parse_GlobalMessage */
/* in this sample we do nothing and simply redirect */
void sample_packet0f3(int fd) {
struct map_session_data *sd = session[fd]->session_data;
if (sd == NULL) return; /* socket didn't fully log-in? this packet shouldn't do anything then! */
ShowInfo("sample_packet0f3: Hello World! received 0xf3 for '%s', redirecting!\n", sd->status.name);
clif->pGlobalMessage(fd, sd);`
}
void plugin_init(void) {
addPacket(0xf3, -1, sample_packet0f3, hpClif_Parse);
}
and voila, your plugin just changed the map server's 0xf3 packet to pass by sample_packet0f3 prior to being sent to clif_parse_GlobalMessage
A full usage of this is demonstrated in the HPM's sample
HPM Custom Data Structs¶
The HPM makes it possible for a plugin to create and append structs to existent data, this feature is currently supported on player units (map_session_data) and network pipes (socket_data)
Example:
/* can be of any size, using any data types */
struct sample_data_struct {
struct point lastMSGPosition;
unsigned int someNumber;
};
/* appends/reads sample_data_struct in a network session data entry (socket_data) */
void some_function_receiving_a_socket_fd(int fd) {
struct sample_data_struct *data;
if (!(data = HPMi->getFromSession(session[fd], HPMi->pid, 0))) {
CREATE(data,struct sample_data_struct,1);
data->lastMSGPosition.map = 1;
data->lastMSGPosition.x = 150;
data->lastMSGPosition.y = 150;
data->someNumber = rand()%777;
ShowInfo("Created Appended session[] data, %d %d %d %d\n", data->lastMSGPosition.map, data->lastMSGPosition.x, data->lastMSGPosition.y, data->someNumber);
HPMi->addToSession(session[fd], data, HPMi->pid , 0, true);
} else {
ShowInfo("Existent Appended session[] data, %d %d %d %d\n", data->lastMSGPosition.map, data->lastMSGPosition.x, data->lastMSGPosition.y, data->someNumber);
if (rand()%4 == 2) {
ShowInfo("Removing Appended session[] data\n");
HPMi->removeFromSession(session[fd], HPMi->pid, 0);
}
}
}
and voila, your plugin becomes capable of appending and handling your custom struct data
A full usage of this is demonstrated in the HPM's sample
HPM Function Overloading¶
Thanks to Hercules Renewal Phase One, you're capable of overloading all functions covered by the Hercules Renewal Phase One interfaces, with your plugin.
Example:
int my_custom_check_target_function(struct block_list *src, struct block_list *target, int flag) {
//<...> code
}
void server_ready(void) {
battle->check_target = &my_custom_check_target_function;
}
Other Features¶
Is there something you'd like to do with your plugin that requires modifications to HPM's core? let us know, and we'll do our best to make it happen.
Post your suggestions here
Support¶
Need help writing your plugin? post your question on our support forum