Entity Classes

Object-oriented wrappers for FiveM's native entity handles, providing a type-safe and intuitive interface for game entity manipulation.

Overview

FiveM uses numeric handles to represent game entities. These classes wrap those handles with:

• Type-safe properties instead of procedural native calls
• Disposable pattern for automatic cleanup
• Null object pattern for safe entity references
• Inheritance hierarchy matching game entity types

Class Hierarchy

Design Principles

Null Object Pattern

Each class has a NULL constant for safe comparisons:

const entity = Entity.fromHandle(someHandle);

if (entity === Entity.NULL) {
  // Handle is invalid
}

if (entity.exists()) {
  // Entity exists in the game world
}

Disposable Integration

All classes implement IDisposable, enabling use with DisposableStore or TypeScript's using:

// With DisposableStore
const disposables = new DisposableStore();
disposables.add(Ped.create(model, coords, 0));
// Later: disposables.dispose() deletes all entities

// With 'using' declaration
using ped = Ped.create(model, coords, 0);
// Ped auto-deleted when scope exits

Property-Based Interface

Native calls are exposed as properties for intuitive access:

// Instead of: GetEntityCoords(handle, true)
const pos = entity.coords;

// Instead of: SetEntityCoords(handle, x, y, z, ...)
entity.coords = vec3(100, 200, 30);

Key Classes

Class	Purpose	Destructible
Entity	Base class for peds, vehicles, objects	Yes
Ped	NPCs with weapons, tasks, appearance	Yes
Vehicle	Vehicle entities	Yes
Player	Connected players	No
Camera	Scripted camera control	Yes
Blip	Map markers with sprites/colors	Yes

Usage Pattern

"use client";

import { Player, Ped, Blip, vec3 } from "@core/classes";
import { DisposableStore } from "@core/disposable";

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

  @ClientOnly
  initClientSide(): void {
    const player = Player.LOCAL;
    const ped = player.ped;
    
    // Create a marker at player position
    const blip = Blip.createWithCoords(ped.coords);
    blip.sprite = BlipSprite.Waypoint;
    this.disposables.add(blip);
  }

  @ClientOnly
  cleanupClientSide(): void {
    this.disposables.dispose();
  }
}

When to Use

• Use entity classes when you need to interact with game world entities
• Use Player.LOCAL to access the local player and their ped
• Use disposable stores to manage entity lifecycles in services
• Always check exists() before operating on entities that may have been deleted

note

Entity classes are client-only ("use client") and wrap FiveM native handles. See the Math Utilities API for similar Vector3 patterns used with entity coordinates.