# Entities

### getNearby

Gets nearby entities of any type with comprehensive filtering options.

```lua
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:**

```lua
-- 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.

```lua
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:**

```lua
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.

```lua
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:**

```lua
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.

```lua
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.

```lua
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:**

```lua
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.

```lua
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.

```lua
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.

```lua
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.

```lua
B2Lib.Entities.getEntityInfo(entity)
```

**Parameters:**

* `entity` (number): Entity handle

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

**Example:**

```lua
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.

```lua
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.

```lua
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).

```lua
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.

```lua
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.

```lua
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.

```lua
B2Lib.Entities.clearCache()
```

**Returns:** boolean - True if cache was cleared

### getStats

Gets entity system statistics.

```lua
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`:

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

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

#### Performance Issues

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

#### Outdated Entity Information

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

#### Memory Usage

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