Revision as of 20:18, 2 May 2013

Often referred to as the HPM, the Hercules Plugin Manager is yet another Hercules Original

Building a plugin

While 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 2 guides below, one for windows and other for everything else (which should work on any *nix distro, as well as on OSX).

Windows

Building HPM Plugin for MSVC

All Others

Building HPM Plugin for gcc

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 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.

With the HPM you only need to code the events your plugin will use.

HPM Hooks

Support for Hooks will be enabled within the next HPM release.

HPM @commands

The HPM makes it very simple to provide @commands through plugins.
You define a new @command exactly as it'd normally be done in src/map/atcommand.c.
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;
}

After that you just have to link your new command, to do that you use the void plugin_init (void) event.

HPMi->addCommand("sample",ACMD_A(sample));

and voila, your plugin now adds the @sample command. A full usage of this is demonstrated in the HPM's sample src/plugins/sample.c

HPM Script Commands

The HPM makes it very simple to provide script commands through plugins.
You define a new script command exactly as it'd normally be done in src/map/script.c.
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;
}

After that you just have to link your new script command, to do that you use the void plugin_init (void) event.

HPMi->addScript("sample","i",BUILDIN_A(sample)); //note the 2nd param is this commands' arg-types (in this case, a number)

and voila, your plugin now adds the sample script command. A full usage of this is demonstrated in the HPM's sample src/plugins/sample.c

HPM Console Commands

The HPM makes it very simple to provide console commands through plugins.
You define a new console command exactly as it'd normally be done in src/common/console.c.
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 src/plugins/sample.c

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
}
struct battle_interface *battle;
void server_ready(void) {
	battle = GET_SYMBOL("battle");
	battle->check_target = &my_custom_check_target_function;
}

and voila, your plugin just overloaded the game server's battle_check_target function with your plugin's own, this is greatly handy to ensure your customs do not create conflicts when updating your Hercules Repository

Other Features

Is there something you'd like to do with your plugin that requires modifications to HPM's core? let we 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