Entities

The Entities module provides comprehensive entity detection and management utilities for FiveM resources with advanced filtering, caching, and performance optimization.

getNearby

Gets nearby entities of any type with comprehensive filtering options.

B2Lib.Entities.getNearby(coords, radius, entityType, options)

Parameters:

coords (vector3, optional): Coordinates to search from (default: player position)
radius (number, optional): Search radius in units (default: 50.0)
entityType (string, optional): Entity type filter ('all', 'vehicles', 'peds', 'objects')
options (table, optional): Additional filtering options
- excludePlayerVehicle (boolean): Exclude player's current vehicle
- onlyOccupied (boolean): Only vehicles with drivers
- onlyEmpty (boolean): Only empty vehicles
- playersOnly (boolean): Only player peds
- npcsOnly (boolean): Only NPC peds
- excludeDead (boolean): Exclude dead peds
- excludeInVehicle (boolean): Exclude peds in vehicles
- modelFilter (number): Specific model hash
- excludeFrozen (boolean): Exclude frozen objects
- onlyVisible (boolean): Only visible objects

Returns: table - Array of entity information sorted by distance

Example:

-- Get all nearby entities within 25 units
local entities = B2Lib.Entities.getNearby(GetEntityCoords(PlayerPedId()), 25.0, 'all')

-- Get only vehicles within 30 units, excluding player's vehicle
local vehicles = B2Lib.Entities.getNearby(coords, 30.0, 'vehicles', {
    excludePlayerVehicle = true,
    onlyEmpty = true
})

getNearbyVehicles

Gets nearby vehicles with detailed vehicle-specific information.

B2Lib.Entities.getNearbyVehicles(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Vehicle-specific filtering options

Returns: table - Array of vehicle information sorted by distance

entity (number): Vehicle handle
type (string): Entity type
coords (vector3): Vehicle coordinates
distance (number): Distance from search point
model (number): Model hash
modelName (string): Display name
plate (string): License plate
heading (number): Vehicle heading
health (number): Current health
maxHealth (number): Maximum health
locked (boolean): Door lock status
engineRunning (boolean): Engine state
driver (number): Driver ped handle (0 if empty)
passengers (number): Number of passengers
class (number): Vehicle class
velocity (vector3): Current velocity

Example:

local vehicles = B2Lib.Entities.getNearbyVehicles(coords, 50.0, {
    excludePlayerVehicle = true
})

for _, vehicle in ipairs(vehicles) do
    if not vehicle.locked and vehicle.driver == 0 then
        print(string.format("Found unlocked %s at %.1fm", vehicle.modelName, vehicle.distance))
    end
end

getNearbyPeds

Gets nearby peds with detailed ped-specific information.

B2Lib.Entities.getNearbyPeds(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Ped-specific filtering options

Returns: table - Array of ped information sorted by distance

entity (number): Ped handle
type (string): Entity type
coords (vector3): Ped coordinates
distance (number): Distance from search point
model (number): Model hash
heading (number): Ped heading
health (number): Current health
maxHealth (number): Maximum health
isPlayer (boolean): Is this a player ped
isDead (boolean): Is ped dead
isInVehicle (boolean): Is ped in a vehicle
weapon (number): Current weapon hash
velocity (vector3): Current velocity
isAiming (boolean): Is ped aiming
isShooting (boolean): Is ped shooting
serverId (number): Server ID (players only)
playerName (string): Player name (players only)

Example:

local nearbyPlayers = B2Lib.Entities.getNearbyPeds(coords, 10.0, {
    playersOnly = true,
    excludeDead = true
})

for _, player in ipairs(nearbyPlayers) do
    print(string.format("Player %s (ID: %d) is %.1fm away", 
        player.playerName, player.serverId, player.distance))
end

getNearbyObjects

Gets nearby objects with detailed object-specific information.

B2Lib.Entities.getNearbyObjects(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Object-specific filtering options

Returns: table - Array of object information sorted by distance

entity (number): Object handle
type (string): Entity type
coords (vector3): Object coordinates
distance (number): Distance from search point
model (number): Model hash
heading (number): Object heading
isFrozen (boolean): Is object frozen
isVisible (boolean): Is object visible
hasPhysics (boolean): Has physics enabled
isAttached (boolean): Is attached to another entity
velocity (vector3): Current velocity

getClosest

Gets the closest entity of a specific type.

B2Lib.Entities.getClosest(coords, entityType, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
entityType (string): Entity type ('vehicle', 'ped', 'object')
radius (number, optional): Search radius in units
options (table, optional): Filtering options

Returns: table|nil - Closest entity information or nil if none found

Example:

local closestVehicle = B2Lib.Entities.getClosest(coords, 'vehicle', 10.0)
if closestVehicle then
    print("Closest vehicle:", closestVehicle.modelName)
end

getClosestVehicle

Gets the closest vehicle to specified coordinates.

B2Lib.Entities.getClosestVehicle(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Vehicle filtering options

Returns: table|nil - Closest vehicle information or nil if none found

getClosestPed

Gets the closest ped to specified coordinates.

B2Lib.Entities.getClosestPed(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Ped filtering options

Returns: table|nil - Closest ped information or nil if none found

getClosestObject

Gets the closest object to specified coordinates.

B2Lib.Entities.getClosestObject(coords, radius, options)

Parameters:

coords (vector3, optional): Coordinates to search from
radius (number, optional): Search radius in units
options (table, optional): Object filtering options

Returns: table|nil - Closest object information or nil if none found

getEntityInfo

Gets detailed information about a specific entity.

B2Lib.Entities.getEntityInfo(entity)

Parameters:

entity (number): Entity handle

Returns: table|nil - Entity information or nil if invalid

Example:

local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)
if vehicle ~= 0 then
    local info = B2Lib.Entities.getEntityInfo(vehicle)
    print("Vehicle model:", info.modelName)
    print("Plate:", info.plate)
end

isEntityValid

Checks if an entity handle is valid and exists.

B2Lib.Entities.isEntityValid(entity)

Parameters:

entity (number): Entity handle to check

Returns: boolean - True if entity is valid, false otherwise

getEntityDistance

Gets the distance between two entities or an entity and coordinates.

B2Lib.Entities.getEntityDistance(entity1, entity2OrCoords)

Parameters:

entity1 (number): First entity handle
entity2OrCoords (number|vector3): Second entity handle or coordinates

Returns: number - Distance between entities/coordinates

getEntitiesInArea

Gets all entities within a specified area (box or sphere).

B2Lib.Entities.getEntitiesInArea(coords, size, shape, entityType)

Parameters:

coords (vector3): Center coordinates
size (number|vector3): Radius for sphere or dimensions for box
shape (string, optional): 'sphere' or 'box' (default: 'sphere')
entityType (string, optional): Entity type filter

Returns: table - Array of entities in the area

filterEntities

Filters an array of entities based on specified criteria.

B2Lib.Entities.filterEntities(entities, filterOptions)

Parameters:

entities (table): Array of entity information
filterOptions (table): Filtering criteria

Returns: table - Filtered array of entities

sortEntitiesByDistance

Sorts entities by distance from specified coordinates.

B2Lib.Entities.sortEntitiesByDistance(entities, coords)

Parameters:

entities (table): Array of entity information
coords (vector3): Reference coordinates

Returns: table - Sorted array of entities

clearCache

Clears the entity information cache.

B2Lib.Entities.clearCache()

Returns: boolean - True if cache was cleared

getStats

Gets entity system statistics.

B2Lib.Entities.getStats()

Returns: table - Statistics about entity operations

cacheSize (number): Current cache size
cacheHits (number): Cache hit count
cacheMisses (number): Cache miss count
totalQueries (number): Total entity queries
averageQueryTime (number): Average query time in ms

Configuration

Configure the entities system in config.lua:

Config.Entities = {
    defaultRadius = 50.0,       -- Default search radius
    maxCacheSize = 500,         -- Maximum cache entries
    cacheTimeout = 5000,        -- Cache timeout in milliseconds
    enableCache = true,         -- Enable entity caching
    enableStats = true,         -- Enable statistics tracking
    debugMode = false           -- Enable debug logging
}

Troubleshooting

No Entities Found

Check that the search radius is appropriate
Verify coordinates are valid
Ensure entity type filter is correct
Check if entities exist in the area

Performance Issues

Reduce search radius for better performance
Use specific entity type filters instead of 'all'
Enable caching to reduce repeated queries
Use filtering options to limit results

Outdated Entity Information

Clear cache with clearCache() if needed
Reduce cache timeout for more frequent updates
Check if entities have been deleted or moved
Verify entity handles are still valid

Memory Usage

Reduce maxCacheSize in configuration
Clear cache periodically in long-running scripts
Use specific queries instead of broad searches
Monitor cache statistics with getStats()

PreviousAnimations NextMarkers

Last updated 1 month ago