Skip to main content

Entities

In GTA V, almost everything tangible in the world is an Entity. Whether it is Franklin walking down Vinewood Boulevard, a police cruiser chasing a suspect, or a wooden crate falling off a forklift, they all share a single common base class: GTA.Entity.

The entity hierarchy​

In ScriptHookVDotNet, the hierarchy looks like this:

                  +--------------+
                  |  GTA.Entity  |
                  +--------------+
                   /     |      \
                  /      |       \
        +----------+ +-----------+ +----------+
        | GTA.Ped  | |GTA.Vehicle| | GTA.Prop |
        +----------+ +-----------+ +----------+

Because Ped, Vehicle, and Prop inherit from Entity, they all share essential spatial and physical properties:

  • Position: The 3D location (Vector3).
  • Heading: The compass rotation angle (0 to 360 degrees).
  • Health: Current hit points.
  • IsDead / IsAlive: Quick state queries.
  • ForwardVector: The direction the entity is facing.

Handles: the engine's identity system​

When GTA V spawns a car or a pedestrian, it stores the object in an internal fixed-size memory pool and hands back an integer called a handle.

In your C# code:

Ped ped = Game.Player.Character;
int engineHandle = ped.Handle;

A handle is not the entity itself; it is like an index or a room key. When you tell SHVDN ped.Delete(), it passes that handle to an engine native that frees the slot in the memory pool.

Script-owned vs world-owned​

When your script spawns an entity, the game marks it as mission entity (script-owned). This means:

  • The game's ambient garbage collector will never delete it, even if you drive five miles away.
  • It will remain in memory until you delete it or the script unloads.

If you spawn fifty cars without deleting them, the vehicle pool fills up, and ambient traffic completely vanishes from the city.

Releasing entities to the world​

If you want an entity to naturally fade away when the player leaves the area (like a normal ambient pedestrian), release it:

// Tells the engine: I am done with this ped, let ambient despawn rules apply
ped.MarkAsNoLongerNeeded();

If you want it gone immediately:

// Instantly deletes the entity from memory and screen
ped.Delete();

In the next lesson, we see why checking entity validity is the number one defence against script crashes.