====== Events ======

One of the main ways that Ashita allows addons to obtain various important data from the hook is through the method of events. Events are callback functions that are fired within an addons Lua state whenever the hook core handles something that warrants an addon to be notified. This can happen for things such as incoming or outgoing packets, chat commands entered by the user, etc.

The following events are currently valid within Ashita's core hook that are exposed to addons:
  * load
  * unload
  * command
  * incoming_packet
  * outgoing_packet
  * incoming_text
  * outgoing_text
  * prerender
  * render
  * timerpulse

----

==== Registering To Events ====

Addon developers can register to an event using one of two methods. The short-hand method, or the long-hand method. In most cases, the short-hand method will be ideal and recommended.

**Short-hand Method**
<sxh lua>
ashita.register_event('load', function()
    print('Load event fired!');
end);
</sxh>

**Long-hand Method**
<sxh lua>
function loadfunction()
    print('Load event fired!');
end

ashita.register_event('load', loadfunction);
</sxh>

----

===== Built-In Events =====

Below, you will find documentation for the built-in events that the Ashita addons library exposes to all addons. Please be aware of the returns and such of each event as incorrect returns can cause log spam of warnings/errors as well as potential client crashes! Be sure to test your addons thoroughly before having others use them!

----
==== Event: load =====

Called when the current addon is being loaded. (Also called when the addon is reloaded.)

<sxh lua>
ashita.register_event('load', function()
    print('Load event fired!');
end);
</sxh>

**Parameters** \\
    * None

**Returns** \\
    * None

----
==== Event: unload ====

Called when the current addon is being unloaded. (Also called when the addon is reloaded.)

<sxh lua>
ashita.register_event('unload', function()
    print('Unload event fired!');
end);
</sxh>

**Parameters** \\
    * None

**Returns** \\
    * None

----
==== Event: command =====

Called when a command has been entered in the game.

<sxh lua>
ashita.register_event('command', function(cmd, nType)
    print('Command event fired!');
    return false;
end);
</sxh>

**Parameters** \\
    * **cmd** - (string) The command that was entered.
    * **nType** - (number) The type of command that was entered.

**Returns** \\
    * **bool** - True if the addon handled the command, false otherwise to allow further addons to process the command.

----
==== Event: incoming_packet =====

Called when the game client is receiving an incoming packet.

<sxh lua>
ashita.register_event('incoming_packet', function(id, size, packet, packet_modified, blocked)
    print('Incoming packet event fired!');
    return false;
end);
</sxh>

**Parameters** \\
    * **id** - (number) The packet id being processed.
    * **size** - (number) The size of the packet being processed.
    * **packet** - (string) The raw packet data.
    * **packet_modified** - (string) The raw packet data that has been modified by other addons and plugins.
    * **blocked** - (bool) True if the packet has been blocked by another addon or plugin, false otherwise.

**Returns** \\
    * **bool** - True if the packet should be dropped/blocked, false otherwise.
    * or
    * **table** - A table containing new packet data that should be used to modify the packet.

----
==== Event: outgoing_packet =====

Called when the game client is sending an outgoing packet.

<sxh lua>
ashita.register_event('outgoing_packet', function(id, size, packet, packet_modified, blocked)
    print('Outgoing packet event fired!');
    return false;
end);
</sxh>

**Parameters** \\
    * **id** - (number) The packet id being processed.
    * **size** - (number) The size of the packet being processed.
    * **packet** - (string) The raw packet data.
    * **packet_modified** - (string) The raw packet data that has been modified by other addons and plugins.
    * **blocked** - (bool) True if the packet has been blocked by another addon or plugin, false otherwise.

**Returns** \\
    * **bool** - True if the packet should be dropped/blocked, false otherwise.
    * or
    * **table** - A table containing new packet data that should be used to modify the packet.

----
==== Event: incoming_text =====

Called when the game client is adding text to the chat log.

<sxh lua>
ashita.register_event('incoming_text', function(mode, message, modifiedmode, modifiedmessage, blocked)
    print('Incoming text event fired!');
    return false;
end);
</sxh>

**Parameters** \\
    * **mode** - (number) The chat mode of the message. (Controls the color of the overall message.)
    * **message** - (string) The message being added to the chat log.
    * **modifiedmode** - (number) The modified mode, if another addon or plugin has modified it.
    * **modifiedmessage** - (string) The modified message, if another addon or plugin has modified it.
    * **blocked** - (bool) True if the message has been blocked by another addon or plugin, false otherwise.

**Returns** \\
    * **bool** - True if the message should be blocked, false otherwise.
    * or
    * **number** - The modified message mode to use instead of the current one.
    * or
    * **string** - The modified message to use instead of the current one.
    * or
    * **string, number** - The modified message and mode to use instead of the current ones.

----
==== Event: outgoing_text =====

Called when the game client is sending text to the server.\\
//(This gets called when a command, chat, etc. is not handled by the client and is being sent to the server.)//

<sxh lua>
ashita.register_event('outgoing_text', function(mode, message, modifiedmode, modifiedmessage, blocked)
    print('Outgoing text event fired!');
    return false;
end);
</sxh>

**Parameters** \\
    * **mode** - (number) The chat mode of the message. (Controls the color of the overall message.)
    * **message** - (string) The message being added to the chat log.
    * **modifiedmode** - (number) The modified mode, if another addon or plugin has modified it.
    * **modifiedmessage** - (string) The modified message, if another addon or plugin has modified it.
    * **blocked** - (bool) True if the message has been blocked by another addon or plugin, false otherwise.

**Returns** \\
    * **bool** - True if the message should be blocked, false otherwise.
    * or
    * **number** - The modified message mode to use instead of the current one.
    * or
    * **string** - The modified message to use instead of the current one.
    * or
    * **string, number** - The modified message and mode to use instead of the current ones.

----
==== Event: prerender ====

Called when the client is about to start rendering. (Called just after D3D8 BeginScene.)

<sxh lua>
ashita.register_event('prerender', function()
    print('Prerender event fired!');
end);
</sxh>

**Parameters** \\
    * None

**Returns** \\
    * None

----
==== Event: render ====

Called when the client has finished its rendering and other tools can now render. (Called during D3D8 EndScene.)

<sxh lua>
ashita.register_event('render', function()
    print('Render event fired!');
end);
</sxh>

**Parameters** \\
    * None

**Returns** \\
    * None

----
==== Event: timerpulse ====

Called when the client is rendering the scene, used for Addons Lua timers library.\\
//(Addons should not register to this event themselves, it is used for the timers library.)//

<sxh lua>
ashita.register_event('timerpulse', function()
    print('Timer pulse event fired!');
end);
</sxh>

**Parameters** \\
    * None

**Returns** \\
    * None


----