Events

True Life provides type-safe wrappers around FiveM's native events with automatic cleanup via the disposable pattern.

Server Events

Available via @core/events/server:

"use server";

import { fivemEvents } from "@core/events/server";
import { DisposableStore } from "@core/disposable";

const disposables = new DisposableStore();

// Player joining (before fully connected)
disposables.add(
  fivemEvents.playerJoining.on((playerId) => {
    console.log(`Player ${playerId} joining`);
  })
);

// Player dropped (disconnected)
disposables.add(
  fivemEvents.playerDropped.on((playerId, reason) => {
    console.log(`Player ${playerId} dropped: ${reason}`);
  })
);

// Player connecting (with deferrals)
disposables.add(
  fivemEvents.playerConnecting.on((playerId, playerName, setKickReason, deferrals) => {
    deferrals.defer();
    // Async validation...
    deferrals.done();
  })
);

// Resource lifecycle
disposables.add(
  fivemEvents.onResourceStart.on((resourceName) => {
    if (resourceName === GetCurrentResourceName()) {
      console.log("Our resource started");
    }
  })
);

disposables.add(
  fivemEvents.onResourceStop.on((resourceName) => {
    if (resourceName === GetCurrentResourceName()) {
      console.log("Our resource stopping");
    }
  })
);

// Cleanup
disposables.dispose();

Available Server Events

Event	Parameters	Description
playerJoining	playerId: number	Player beginning to join
playerDropped	playerId: number, reason: string	Player disconnected
playerConnecting	playerId, name, setKickReason, deferrals	Connection with deferrals
onResourceStart	resourceName: string	Resource started
onResourceStop	resourceName: string	Resource stopping

Client Events

Available via @core/events/client:

"use client";

import { fivemClientEvents } from "@core/events/client";
import { DisposableStore } from "@core/disposable";

const disposables = new DisposableStore();

// Resource lifecycle on client
disposables.add(
  fivemClientEvents.onClientResourceStart.on((resourceName) => {
    if (resourceName === GetCurrentResourceName()) {
      console.log("Our resource started on client");
    }
  })
);

disposables.add(
  fivemClientEvents.onClientResourceStop.on((resourceName) => {
    console.log(`Resource ${resourceName} stopped`);
  })
);

// Game events
disposables.add(
  fivemClientEvents.gameEventTriggered.on((eventName, args) => {
    if (eventName === "CEventNetworkEntityDamage") {
      const [victim, attacker, ...rest] = args;
      console.log(`Entity ${victim} damaged by ${attacker}`);
    }
  })
);

// Entity lifecycle
disposables.add(
  fivemClientEvents.entityCreated.on((entity) => {
    console.log(`Entity ${entity} created`);
  })
);

disposables.add(
  fivemClientEvents.entityRemoved.on((entity) => {
    console.log(`Entity ${entity} removed`);
  })
);

// Ped changes
disposables.add(
  fivemClientEvents.playerPedChanged.on((newPed, oldPed) => {
    console.log(`Player ped changed from ${oldPed} to ${newPed}`);
  })
);

// Cleanup
disposables.dispose();

Available Client Events

Event	Parameters	Description
onClientResourceStart	resourceName: string	Resource started on client
onClientResourceStop	resourceName: string	Resource stopped on client
gameEventTriggered	name: string, args: unknown[]	Game event fired
populationPedCreating	x, y, z, model, overrideCalls	Ped spawning
playerPedChanged	newPed: number, oldPed: number	Player ped changed
playerSpawned	spawn: SpawnInfo	Player spawned
entityCreated	entity: number	Entity created
entityRemoved	entity: number	Entity removed

Creating Custom Events

Use createNativeEvent for custom event wrappers:

import { createNativeEvent } from "@core/events/helpers";

// Create a typed event wrapper
const myCustomEvent = createNativeEvent<[data: MyData]>("my:custom:event");

// Subscribe
const disposable = myCustomEvent.on((data) => {
  console.log("Received:", data);
});

// Emit (if needed)
myCustomEvent.emit({ value: 123 });

// Cleanup
disposable.dispose();

Event Registration Tracking

For debugging, the framework tracks all registered events:

import { getRegisteredEvents, debugPrintEvents } from "@core/events/tracker";

// Get all registered events
const events = getRegisteredEvents();

// Print debug info
debugPrintEvents();

Disposable Pattern

Events return IDisposable for automatic cleanup:

import { DisposableStore, toDisposable } from "@core/disposable";

export class MyService {
  private disposables = new DisposableStore();

  @ServerOnly
  initServerSide(): void {
    // Add event subscriptions
    this.disposables.add(
      fivemEvents.playerJoining.on(this.handlePlayerJoining)
    );
    
    // Add custom cleanup
    this.disposables.add(
      toDisposable(() => {
        clearInterval(this.timer);
      })
    );
  }

  @ServerOnly
  cleanupServerSide(): void {
    // Disposes all registered disposables
    this.disposables.dispose();
  }

  private handlePlayerJoining = (playerId: number) => {
    console.log(`Player ${playerId} joining`);
  };
}

Best Practices

1. Always clean up subscriptions - Use DisposableStore
2. Use typed events - Leverage TypeScript for safety
3. Check resource name - Prevent handling other resources' events
4. Handle errors - Wrap handlers in try/catch
5. Use arrow functions or bind - Preserve this context
6. Avoid event spam - Debounce frequent events if needed