====== 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
    * newchat
    * incoming_packet
    * outgoing_packet
    * prerender
    * render
    * timer_pulse

----

==== Registering To Events ====

Addon developers can register to an event using one of two methods. The short-hand method, or the long-hand method. 

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

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

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

----

==== load Event =====

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

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

**Parameters** \\
    * None

**Returns** \\
    * None

----

==== unload Event ====

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

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

**Parameters** \\
    * None

**Returns** \\
    * None

----

==== command Event ====

Called when a command has been entered in the game.

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

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

----

==== newchat Event ====

Called when the game client has begun to add a new line of text to the chat box.

<code lua>
ashita.register_event('newchat', function(mode, chat)
    print('New Chat event fired!');
end);
</code>

**Parameters** \\
    * **mode** - (number) The chat mode of the new line. (Determines the color of the line.)
    * **chat** - (string) The chat string being added.

**Returns** \\
    * **bool** - True if the addon blocked the new chat line, false otherwise.
    * **bool**, **string** - Boolean to block the chat line, string to overwrite the chat line with something else.

----

==== incoming_packet Event ====

Called when the client is receiving an incoming packet.

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

**Parameters** \\
    * **id** - (number) The packet id being processed.
    * **size** - (number) The size of the packet being processed.
    * **packet** - (string) The raw packet data.

**Returns** \\
    * **bool** - True if the packet should be dropped/blocked, false otherwise.

----

==== outgoing_packet Event ====

Called when the client is sending an outgoing packet.

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

**Parameters** \\
    * **id** - (number) The packet id being processed.
    * **size** - (number) The size of the packet being processed.
    * **packet** - (string) The raw packet data.

**Returns** \\
    * **bool** - True if the packet should be dropped/blocked, false otherwise.

----

==== prerender Event ====

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

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

**Parameters** \\
    * None

**Returns** \\
    * None

----

==== render Event ====

Called when the client has finished its rendering and other tools can now render. 

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

**Parameters** \\
    * None

**Returns** \\
    * None

----

==== timer_pulse Event ====

Called when the client is rendering its scene.

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

**Parameters** \\
    * None

**Returns** \\
    * None