====== Creating Plugins ======

<WRAP important>
Before you start making plugins, be sure to read this documentation to understand what is required of your plugin in order for it to work properly.\\
Failure to follow what this doc says can cause your plugin to fail to load, or not work at all!
</WRAP>

-----

==== Creating Your Plugin ====

Plugins can be found inside the \Ashita\Plugins\ folder. Inside here you will find the various .dll files which are plugins. Each plugin should consist of at least 1 .dll file.

Plugins must be uniquely named and compiled against the latest Ashita SDK (known as the ADK) in order for it to be properly loaded.

Failure to compile against the latest ADK will result in your plugin being rejected from loading.

Plugins should consist of a single word name or compressed into a word without spaces or special characters. Users should be able to load them with ease so names with spaces, special characters, etc are not recommended at all.

-----

==== Example Plugin Source Code ====

To get started, you can find an example plugin here:
http://delvl.ffevo.net/atom0s/ExamplePlugin

This repository contains a fully implemented example plugin demonstrating and explaining how to use each part of the main plugin base  class. 


-----

==== Required Plugin Exports ====

In order for Ashita to interact with a plugin, there must be a few functions exported from a plugin. Those functions are:
  * GetInterfaceVersion
  * CreatePluginData
  * CreatePlugin

The exports have the following purpose:

**GetInterfaceVersion**
<code cpp>__declspec(dllexport) double __stdcall GetInterfaceVersion(void);</code>
Exported function used to get the interface version the plugin was compiled with.
  * **Returns:** (double) The plugin ADK version the plugin was compiled with.

**CreatePluginData**
<code cpp>__declspec(dllexport) void __stdcall CreatePluginData(PluginData* lpBuffer);</code>
Exported function used to obtain general information of the plugin.
  * **lpBuffer:** (PluginData*) Pointer to a PluginData structure holding information about the plugin.

**CreatePlugin**
<code cpp>__declspec(dllexport) IPlugin* __stdcall CreatePlugin(char* pszReserved);</code>
  * **pszReserved:** (char*) Currently unused parameter.
  * **Returns:** (IPlugin*) An instance of the plugins main class.
Exported function used to create an instance of the plugins main class. (This main class must inherit the IPlugin structure.)

-----

==== PluginBase Implementation ====

The PluginBase structure is a base class that Plugins must inherit and expose via the CreatePlugin function. PluginBase implements the IPlugin interface so you do not need to worry about casting back to the original interface.

Plugins are required to implement at least the **Initialize** method in order to load properly. The other functions that can be overridden are not required for a plugin to function properly.

Here is a quick run down of what each function is used for:

  * **Initialize:** First called when a plugin is being loaded. Allows the plugin to prepare itself. Passes the main IAshitaCore object to the plugin to allow the plugin to interact with Ashita.
  * **Release:** Called when the plugin is being released, allowing the plugin to cleanup any resources.
  * **HandleCommand:** Called when an unhandled command has been sent in game. This allows plugins to attempt to handle the command before it is considered an invalid command.
  * **HandleNewChatLine:** Called when a new incoming line of chat is being added to the chat log.
  * **HandleIncomingPacket:** Called when an incoming packet is sent from the server to the client.
  * **HandleOutgoingPacket:** Called when an outgoing packet is sent from the client to the server.
  * **Direct3DInitialize:** Called when the plugin is being initialized for Direct3D access. Allows the plugin to prepare Direct3D resources. Passes the current IDirect3DDevice8 pointer to the plugin.
  * **Direct3DRelease:** Called when the plugin is being unloaded. Allows the plugin to release any Direct3D resources it may have created.
  * **Direct3DPreRender:** Called when Ashita is about to begin rendering. (Called during BeginScene hook.)
  * **Direct3DRender:** Called when Ashita is rendering its objects. (Called during EndScene hook.)