# Listeners
{ref}`Listeners` allows you to listen to certain events. You can either use the
built-in WaspLib listeners like {ref}`Chat Listener` or make your own.

It's important to keep in mind that {ref}`Listeners` only job is running your
listeners and balance them within the configured `Listeners.Interval`.
It's not meant to run any tasks when they trigger, that's up to the listener
itself and these should be quick tasks so other listeners don't get delayed.


- - -

(TListener)=
## TListener type
Simple record that represents a listener.

The bare minimum a listener has to have is a `function (): Boolean of object`.
This is what will be ran on a loop by {ref}`Listeners`.


- - -

(TListeners)=
## TListeners type
Type responsible for handling all your listeners.


- - -

### TListeners.Add
```pascal
procedure TListeners.Add(
  name: String; setup: procedure () of object;
  check: function (): Boolean of object
);
```
Add a {ref}`TListener` to {ref}`Listeners`.
`name` cannot be empty and only `setup` can optionally be `nil` if your listener
doesn't require any one time setup procedure.

The `check` function cannot be `nil` and is what {ref}`Listeners` will run on a
loop.
This function should be as fast as possible and if it triggers anything, it's
tasks should also be as fast as possible otherwise the whole `Listeners` loop
will be delayed.

You will be getting warning messages if your check functions under-perform for
what's expected.


- - -

### TListeners.Remove
```pascal
procedure TListeners.Remove(name: String);
```
Remove a {ref}`TListener` from {ref}`Listeners`.


- - -

### TListeners.Free
```pascal
procedure TListeners.Free();
```
Runs once on script termination assuming


- - -

### TListeners.Setup
```pascal
procedure TListeners.Setup();
```
Runs once and runs all of `Listeners.Listeners` `Setup` procedures.
It will also raise an exception if you run this before configuring
`Listeners.Interval`.


- - -

## Listeners.Start
```pascal
procedure TListeners.Start();
```
Starts `Listeners` in the current thread, which is not what you will usually
want as running this on the main thread you will be stuck on an infinite loop,
use {ref}`Listeners.StartInThread` instead which is what you will likely want.

Example:
```pascal
Listeners.Start();
```


- - -

## Listeners.StartInThread
```pascal
procedure TListeners.StartInThread(interval: Integer = 300);
```
Starts `Listeners` in a separate thread.

Below you have an example on how to use `Listeners` to keep a {ref}`Chat`
`History`:
```pascal
{$I WaspLib/osrs.simba}

var
  history: TChatMessageArray;

procedure ProcessChat(const msgs: TChatMessageArray);
var
  i, n: Integer;
begin
  for i := High(history) downto 0 do
    for n := High(msgs) downto 1 do
      if history[i].Equals(msgs[n], 0.85) then
        Break;
  for n to 7 do
    history += msgs[n];
end;

var
  updated: Boolean;
  messages: TChatMessageArray;

procedure OnMessage(const msgs: TChatMessageArray);
begin
  messages := msgs.Copy();
  updated := True;
end;

begin
  AddOnTerminate(@history.Print);
  ChatListener.OnMessage += @OnMessage;
  Listeners.Add('ChatListener', @ChatListener.Setup, @ChatListener.Check);
  Listeners.StartInThread(300);

  while True do
  begin
    WriteLn updated;
    if updated then
    begin
      ProcessChat(messages);
      updated := False;
    end;
    Sleep(4000);
  end;
end.
```


- - -

## Listeners variable
Global {ref}`TListeners` variable.


- - -

## StartListeners
```pascal
procedure StartListeners(interval: Integer = 200);
```
Starts {ref}`Listeners` with some of the built-in listeners:
- {ref}`LevelUpListener`

Example:
```pascal
{$I WaspLib/osrs.simba}

begin
  StartListeners(200);

  while True do
    Sleep(4000);
end.
```