Events

Events are used in order to establish communication between resources or scripts - for example, one resource communicating with another resource, or one server script file communicating with a client script file from the same resource.
The Armoury Framework recognizes functions annotated with the @EventListener() decorator and automatically marks them as event listeners.

The @EventListener() decorator accepts a configuration object with a few properties which define the functionality of our EventListener:

Property	Description	Default Value
eventName	Name of the event to listen to	Name of the function which the decorator has been added to
direction	Decides whether the EventListener listens to triggers from another script type (client/server) or not Values: SERVER_TO_SERVER - Only listens when defined inside a server script, and triggered from a server script SERVER_TO_CLIENT - Only listens when defined inside a server script, and triggered from a client script CLIENT_TO_SERVER - Only listens when defined inside a client script, and triggered from a server script CLIENT_TO_CLIENT - Only listens when defined inside a client script, and client from a server script	By default: listens for cross-script communication (server-to-client or client-to-server) * Can be omitted

Listening for events: Basic example

// server.controller.ts
@EventListener({ eventName: 'say-hello' })
public onSayHello(): void {
  console.log('Hello!');
}

Triggering events: Basic example

// client.controller.ts
TriggerServerEvent('say-hello');

Special cases

Sometimes you need to trigger an event from a client script and listen for it in another client script, or sometimes you might need to trigger an event from a server script and listen for it in another server script. In order to do this, you might need to specify the event direction and trigger the event accordingly.

Event Communication: Server to Client

When establishing event communication between a server script and a client script, the EventListener() does not necessarily need to specify an event direction - but you need to trigger the event accordingly:

// server.controller.ts
TriggerClientEvent('say-hello', 0);

// client.controller.ts
@EventListener({ eventName: 'say-hello' })
public onSayHello(): void {
  console.log('Hello!');
}

Event Communication: Client to Server

When establishing event communication between a client script and a server script, the EventListener() does not necessarily need to specify an event direction - but you need to trigger the event accordingly:

// client.controller.ts
TriggerServerEvent('say-hello');

// server.controller.ts
@EventListener({ eventName: 'say-hello' })
public onSayHello(): void {
  console.log('Hello!');
}

Event Communication: Server to Server

When establishing event communication between a server script and another server script, the EventListener() needs to specify an event direction and you need to trigger the event accordingly:

// server_1.controller.ts
emit('say-hello');

// server_2.controller.ts
@EventListener({ eventName: 'say-hello', direction: EVENT_DIRECTIONS.SERVER_TO_SERVER })
public onSayHello(): void {
  console.log('Hello!');
}

Event Communication: Client to Client

When establishing event communication between a client script and another client script, the EventListener() needs to specify an event direction and you need to trigger the event accordingly:

// client_1.controller.ts
emit('say-hello');

// client_2.controller.ts
@EventListener({ eventName: 'say-hello', direction: EVENT_DIRECTIONS.CLIENT_TO_CLIENT })
public onSayHello(): void {
  console.log('Hello!');
}

Event parameters

Sometimes you might need to send some specific data through the event. This goes very similarly to the original way you would it in plain Lua. Here’s an example:

// client.controller.ts
TriggerServerEvent('say-something', 'Hello!');

// server.controller.ts
@EventListener({ eventName: 'say-something' })
public onSaySomething(text: string): void {
  console.log(text); // Prints 'Hello!' inside the server console
}

Event source triggerer (How can I find the ID of the player who triggered this event?)

The ‘source’ is accessible just like in the original, plain Lua way. For example, in order to grab the ID of the player who has just triggered an event, you could do the following:

// client.controller.ts
TriggerServerEvent('say-hello');

// server.controller.ts
@EventListener({ eventName: 'say-hello' })
public onSaySomething(): void {
  console.log(`${GetPlayerName(source)} has just said Hello!`); // Prints 'Playername has just said Hello!' inside the server console
}