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

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. 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, 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, 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.

-- 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))

-- 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, 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, adds weapon management, scenario execution, and ragdoll control.
• Vehicle specialization: Located in 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 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, while subclass-specific registrations occur in their respective library files—src/game/scripting/libraries/Ped.cpp for pedestrians and src/game/scripting/libraries/Vehicle.cpp for vehicles. This separation keeps the core handle logic decoupled from scripting surface area.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}