# Understanding the Entity, Ped, and Vehicle Class Hierarchy in YimMenuV2

> Explore the YimMenuV2 Entity, Ped, and Vehicle class hierarchy. Learn how YimMenu Entity serves as the base for managing game object handles with type specific functionality.

- Repository: [YimMenu/YimMenuV2](https://github.com/YimMenu/YimMenuV2)
- Tags: internals
- Published: 2026-07-16

---

**YimMenuV2 implements a single inheritance hierarchy where `YimMenu::Entity` serves as the abstract base class for all game object handles, with concrete subclasses `Ped` and `Vehicle` extending it with type-specific functionality and Lua API bindings.**

Managing game objects in GTA V requires a robust abstraction over raw memory pointers and script handles. The YimMenuV2 codebase solves this through a clean **Entity/Ped/Vehicle class hierarchy** that unifies handle lifecycle management while exposing distinct APIs for pedestrians and automobiles. This design centralizes common operations like position updates and validity checks in the base class while isolating domain-specific logic in dedicated subclasses.

## The Base Entity Class

At the root of the hierarchy lies **`YimMenu::Entity`**, defined in [`src/game/gta/Entity.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Entity.hpp). This abstract base consolidates the raw object pointer and script handle, providing generic getters and setters for transform data, health values, and network synchronization status. By implementing the core Lua bindings for these shared operations here, the architecture eliminates redundant code across object types.

### Handle Storage and Validation

The Entity class maintains the internal mapping between the game's native script handle and the internal object pointer. It exposes methods such as `get_handle()` and `is_valid()` that subclasses inherit directly, ensuring consistent validation semantics whether you are working with a pedestrian or a vehicle.

## Concrete Subclass Implementations

Two primary subclasses extend Entity to provide type-specific scripting capabilities. Both are registered with the Lua runtime using `Metatable<Entity>::AddSubclass<T>()`, which automatically inherits the base Entity methods while allowing each type to register its own extensions.

### The Ped Class

Located in [`src/game/scripting/libraries/Ped.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Ped.cpp), the **Ped** class represents pedestrian entities including NPCs and player characters. It augments the base Entity interface with pedestrian-specific operations such as `give_weapon()`, `start_scenario()`, and `get_vehicle()`. The class also manages ragdoll physics states and group formations, exposing these through dedicated Lua methods that wrap the underlying native function calls.

### The Vehicle Class

The **Vehicle** subclass, implemented in [`src/game/scripting/libraries/Vehicle.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Vehicle.cpp), handles automobiles, aircraft, and watercraft. Beyond inherited position and rotation controls, it provides specialized methods including `fix()` for instant repairs, `get_speed()` for momentum queries, and `set_plate_text()` for cosmetic customization. These methods interface directly with the game's vehicle handling data, offering script-level access to otherwise internal simulation state.

## Lua Integration and Method Registration

The hierarchy leverages template-based registration to expose C++ methods to Lua scripts. When `Metatable<Entity>::AddSubclass<YimMenu::Ped>()` is invoked, it clones the Entity method table into the Ped metatable before appending pedestrian-specific entries. This ensures that both `ped:set_position()` (inherited) and `ped:give_weapon()` (specific) resolve correctly, maintaining a unified scripting interface while preventing cross-contamination of incompatible entity types.

## Practical Usage Examples

The following Lua examples demonstrate how the hierarchy translates into scripting workflows. Notice how Vehicle and Ped objects both support generic Entity methods while exposing their own specialized APIs.

```lua
-- Spawn and configure a vehicle
local modelHash = game.get_hash_key("adder")
local spawnPos = vector3(0, 0, 72)
local car = Vehicle.create(modelHash, spawnPos)

-- Vehicle-specific methods
car:set_plate_text("YIMMENU")
print("Current speed:", car:get_speed())
car:fix()  -- Instant repair

-- Generic Entity methods work on vehicles too
car:set_position(vector3(100, 100, 50))

```

```lua
-- Spawn and control a pedestrian
local pedModel = game.get_hash_key("a_m_m_business_01")
local ped = Ped.create(pedModel, spawnPos)

-- Ped-specific actions
ped:give_weapon(game.get_hash_key("weapon_pistol"))
ped:start_scenario("WORLD_HUMAN_GUARD_STAND")

-- Inherited Entity validation
if ped:is_valid() then
    print("Ped handle:", ped:get_handle())
end

```

## Summary

- **Entity base class**: Defined in [`src/game/gta/Entity.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Entity.hpp), manages raw pointers, script handles, and generic transformations for all game objects.
- **Single inheritance**: Both `Ped` and `Vehicle` inherit directly from `YimMenu::Entity`, utilizing `Metatable<Entity>::AddSubclass<T>()` for Lua registration.
- **Ped specialization**: Located in [`src/game/scripting/libraries/Ped.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Ped.cpp), adds weapon management, scenario execution, and ragdoll control.
- **Vehicle specialization**: Located in [`src/game/scripting/libraries/Vehicle.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Vehicle.cpp), adds repair functions, speed queries, and license plate customization.
- **Unified API**: Subclasses automatically inherit common Entity methods while exposing type-specific extensions, creating a consistent scripting interface across all handle-based objects.

## Frequently Asked Questions

### Does Object or Prop inherit from Entity in YimMenuV2?

The analysis confirms that `Ped` and `Vehicle` are the primary concrete subclasses of `Entity` documented in the scripting libraries. While the base `Entity` class is designed to support any handle-based game object, the current implementation in [`src/game/gta/Entity.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Entity.hpp) serves as the foundation for these specific types, with other object categories potentially following the same inheritance pattern.

### How do I check if a Vehicle handle is still valid before calling methods?

Call the inherited `is_valid()` method available on all Entity subclasses. This method, defined in the base class and accessible to both `Ped` and `Vehicle` instances, verifies that the underlying game pointer remains active and the script handle has not been invalidated by the game's object cleanup systems.

### Can I cast a Ped to a Vehicle if the pedestrian is driving?

While the `Ped` class provides `get_vehicle()` to retrieve the current automobile a pedestrian occupies, the types remain distinct in the hierarchy. The function returns a `Vehicle` handle rather than performing a type cast, maintaining type safety and preventing invalid operations on pedestrians who are not inside automobiles.

### Where are the Lua bindings for Entity methods registered?

The base Entity bindings are established within the class definition in [`src/game/gta/Entity.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Entity.hpp), while subclass-specific registrations occur in their respective library files—[`src/game/scripting/libraries/Ped.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Ped.cpp) for pedestrians and [`src/game/scripting/libraries/Vehicle.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Vehicle.cpp) for vehicles. This separation keeps the core handle logic decoupled from scripting surface area.