### Get Player by Server ID (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves a player object using their server source ID. This is a common starting point for server-side player interactions.

```lua
local player = Ox.GetPlayer(source)
```

--------------------------------

### Get All Player Groups (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves a table containing all groups the player is currently a member of, along with their respective grades.

```lua
-- Get all groups
local groups = player:getGroups()
-- Returns: { police = 3, ambulance = 1 }
```

--------------------------------

### Set and Get Player Metadata (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Manages custom metadata associated with a player's active character. The third parameter in `set` controls client replication.

```lua
-- Server-side: Set and get player metadata
local player = Ox.GetPlayer(source)

-- Set metadata (third parameter replicates to client)
player:set('job', 'police', true)
player:set('salary', 5000, false)

-- Get metadata
local job = player:get('job')
local salary = player:get('salary')
```

--------------------------------

### Player Metadata Management (Server-Side)

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for setting and getting custom metadata for a player's active character on the server.

```APIDOC
## Player Metadata and Data Management (Server-Side)

Players can store and retrieve custom metadata on their active character. Metadata can be replicated to the client for real-time updates.

### Set Metadata

Sets a metadata key-value pair for the player. The third parameter determines if the change should be replicated to the client.

- **Method**: `player:set(key, value, replicateToClient)`
  - **Parameters**:
    - `key` (string) - Required - The metadata key.
    - `value` (any) - Required - The value to set.
    - `replicateToClient` (boolean) - Required - Whether to replicate this change to the client.

### Get Metadata

Retrieves the value of a metadata key for the player.

- **Method**: `player:get(key)`
  - **Parameters**:
    - `key` (string) - Required - The metadata key.
  - **Returns**: `any` - The value associated with the key, or `nil` if not found.

### Built-in Metadata Fields

These are common metadata fields automatically managed or accessible:

- `name` (string) - Full name
- `firstName` (string)
- `lastName` (string)
- `gender` (string)
- `dateOfBirth` (string)
- `phoneNumber` (string)
- `activeGroup` (string) - The player's currently active group

### Example Usage (Lua)
```lua
local player = Ox.GetPlayer(source)

-- Set metadata (third parameter replicates to client)
player:set('job', 'police', true)
player:set('salary', 5000, false)

-- Get metadata
local job = player:get('job')
local salary = player:get('salary')

-- Access built-in metadata
local name = player:get('name')
local firstName = player:get('firstName')
local lastName = player:get('lastName')
local gender = player:get('gender')
local dob = player:get('dateOfBirth')
local phone = player:get('phoneNumber')
local activeGroup = player:get('activeGroup')
```
```

--------------------------------

### Group Management (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Create, delete, and manage groups (jobs, factions, gangs) with hierarchical grades and permissions. Includes getting groups by type, setting/removing permissions, and retrieving active players.

```lua
-- Get all groups by type
local jobs = Ox.GetGroupsByType('job')
local gangs = Ox.GetGroupsByType('gang')

-- Create a new group
Ox.CreateGroup({
    name = 'mechanic',
    label = 'Mechanic',
    type = 'job',
    colour = 3,
    hasAccount = true,  -- Create associated bank account
    grades = {
        { label = 'Trainee', accountRole = 'viewer' },
        { label = 'Mechanic', accountRole = 'contributor' },
        { label = 'Senior Mechanic', accountRole = 'contributor' },
        { label = 'Manager', accountRole = 'manager' },
        { label = 'Owner', accountRole = 'owner' }
    }
})

-- Delete a group
Ox.DeleteGroup('mechanic')

-- Set group permissions
Ox.SetGroupPermission('police', 3, 'arrest', 'allow')
Ox.SetGroupPermission('police', 1, 'patrol', 'allow')

-- Remove group permission
Ox.RemoveGroupPermission('police', 1, 'patrol')

-- Get active players in a group
local activeCops = Ox.GetGroupActivePlayers('police')
-- Returns array of player source IDs

-- Get active players by group type
local activeJobPlayers = Ox.GetGroupActivePlayersByType('job')
```

--------------------------------

### Get All Players or Filtered List (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves a list of all connected players or a subset based on specified criteria, such as group membership.

```lua
local allPlayers = Ox.GetPlayers()
local policePlayers = Ox.GetPlayers({ groups = 'police' })
```

--------------------------------

### Get Vehicle Instances and Data

Source: https://context7.com/communityox/ox_core/llms.txt

Server-side Lua functions to retrieve vehicle objects by their entity ID, VIN, network ID, or from a list of all vehicles, optionally filtered by owner or group. Also shows how to access various vehicle properties and data like coordinates, state, and stored status.

```lua
-- Get vehicle instances
local vehicleByEntity = Ox.GetVehicle(entityId)
local vehicleByVin = Ox.GetVehicle('1ADSU12345678')
local vehicleFromNet = Ox.GetVehicleFromNetId(netId)

-- Get all vehicles, optionally filtered
local allVehicles = Ox.GetVehicles()
local playerVehicles = Ox.GetVehicles({ owner = player.charId })
local policeVehicles = Ox.GetVehicles({ group = 'police' })

-- Access vehicle properties
print(vehicle.entity)   -- Entity handle
print(vehicle.netId)    -- Network ID
print(vehicle.plate)    -- License plate
print(vehicle.model)    -- Model name
print(vehicle.make)     -- Manufacturer
print(vehicle.vin)      -- Vehicle Identification Number
print(vehicle.id)       -- Database ID
print(vehicle.owner)    -- Owner charId
print(vehicle.group)    -- Group owner

-- Get vehicle data
local coords = vehicle:getCoords()
local state = vehicle:getState()
local stored = vehicle:getStored()
local properties = vehicle:getProperties()
```

--------------------------------

### Get Player Coordinates and State (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves the current world coordinates and state information for a player. The state object contains dynamic player attributes.

```lua
local coords = player:getCoords()
local state = player:getState()
```

--------------------------------

### Get Group by Type (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Fetches the player's grade in a group of a specific type, such as 'job' or 'gang'. Useful for systems that categorize groups.

```lua
-- Get group by type (e.g., 'job', 'gang')
local groupName, grade = player:getGroupByType('job')
```

--------------------------------

### Get Player from Filter Criteria (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Finds a single player object that matches specific filter conditions, such as first name. Returns nil if no player matches.

```lua
local targetPlayer = Ox.GetPlayerFromFilter({ firstName = 'John' })
```

--------------------------------

### Get Player by User or Character ID (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Fetches a player object using their unique userId (account ID) or charId (character ID). Useful when player identifiers are known through other means.

```lua
local playerByUserId = Ox.GetPlayerFromUserId(1)
local playerByCharId = Ox.GetPlayerFromCharId(100)
```

--------------------------------

### Manage Player Statuses

Source: https://context7.com/communityox/ox_core/llms.txt

Server-side Lua functions to set, get, and modify player status values like hunger, thirst, and stress. Values range from 0 to 100.

```lua
-- Server-side: Manage player statuses
local player = Ox.GetPlayer(source)

-- Set status value (0-100)
player:setStatus('hunger', 75)
player:setStatus('thirst', 100)

-- Get status value
local hunger = player:getStatus('hunger')

-- Get all statuses
local statuses = player:getStatuses()
-- Returns: { hunger = 75, thirst = 100, stress = 0 }

-- Add or remove from status
player:addStatus('hunger', 10)     -- Increase by 10
player:removeStatus('thirst', 5)   -- Decrease by 5
```

--------------------------------

### Get Player's Grade in a Group (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves the player's current grade within a specified group. Returns the grade as a number or nil if the player is not in the group.

```lua
-- Get player's grade in a group
local grade = player:getGroup('police')  -- Returns number or nil
```

--------------------------------

### Access Vehicle Data and Statistics

Source: https://context7.com/communityox/ox_core/llms.txt

Lua code to retrieve data for specific vehicle models, all vehicles, or top performance statistics by category. Use this to get information about vehicle attributes and performance.

```lua
-- Get data for a specific vehicle model
local vehicleData = Ox.GetVehicleData('adder')
--[[ 
Returns:
{
    name = 'adder',
    make = 'Truffade',
    class = 7,  -- VehicleClasses.SUPER
    type = 'automobile',
    category = 'land',
    seats = 2,
    doors = 2,
    price = 1000000,
    acceleration = 0.89,
    braking = 0.72,
    handling = 0.85,
    speed = 0.95,
    traction = 0.88
}
]]

-- Get all vehicle data
local allVehicles = Ox.GetVehicleData()

-- Get multiple specific vehicles
local vehicles = Ox.GetVehicleData({ 'adder', 'sultan', 'zentorno' })

-- Get top stats by category for comparison
local landStats = Ox.GetTopVehicleStats('land')
local airStats = Ox.GetTopVehicleStats('air')
local seaStats = Ox.GetTopVehicleStats('sea')

-- Get all top stats
local allTopStats = Ox.GetTopVehicleStats()

-- Generate unique VIN and plate
local vin = Ox.GenerateVehicleVin('adder')
local plate = Ox.GenerateVehiclePlate()
local customPlate = Ox.GenerateVehiclePlate('1AAA111')  -- Pattern
```

--------------------------------

### Manage Account Access and Invoices (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Check player permissions, manage character roles on accounts, convert personal accounts to shared, create invoices, and pay or delete invoices. Also includes deleting an account.

```lua
-- Check if player has permission on account
local canWithdraw = account:playerHasPermission(source, 'withdraw')
local canManage = account:playerHasPermission(source, 'manageAccount')

-- Get character's role on account
local role = account:getCharacterRole(player.charId)
-- Returns: 'viewer', 'contributor', 'manager', or 'owner'

-- Set character's role (for shared accounts)
account:setCharacterRole(player.charId, 'contributor')
account:setCharacterRole(player.charId, nil)  -- Remove access

-- Convert personal account to shared
account:setShared()

-- Create an invoice
local invoiceId = account:createInvoice({
    actorId = player.charId,      -- Who created the invoice
    toAccount = targetAccountId,   -- Account to be charged
    amount = 500,
    message = 'Vehicle repair',
    dueDate = '2024-12-31'
})

-- Pay or delete invoices
local success = Ox.PayAccountInvoice(invoiceId, player.charId)
local success = Ox.DeleteAccountInvoice(invoiceId)

-- Delete account
account:deleteAccount()
```

--------------------------------

### Client-Side Player API with TypeScript

Source: https://context7.com/communityox/ox_core/llms.txt

Demonstrates using the client-side Player API in TypeScript, including importing functions, accessing properties, and listening for data updates.

```typescript
// TypeScript client-side usage
import { GetPlayer } from '@communityox/ox_core/client';

const player = GetPlayer();

// Access player properties
console.log(player.userId);
console.log(player.charId);
console.log(player.stateId);

// Get cached data
const name = player.get('name');

// Listen for updates
player.on('activeGroup', (groupName: string) => {
  console.log('Active group changed to:', groupName);
});

// Get coordinates
const coords = player.getCoords();
```

--------------------------------

### Access Player Properties (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Demonstrates accessing core properties of a player object, including server ID, user ID, character ID, state ID, username, and license identifier.

```lua
print(player.source)      -- Server ID
print(player.userId)      -- Account ID
print(player.charId)      -- Character ID
print(player.stateId)     -- State ID (e.g., "AB1234")
print(player.username)    -- Username
print(player.identifier)  -- License identifier
```

--------------------------------

### Player and Vehicle Management (TypeScript)

Source: https://context7.com/communityox/ox_core/llms.txt

Manage player groups, create vehicles with properties, and interact with player accounts. Requires importing necessary functions from '@communityox/ox_core/server'.

```typescript
// TypeScript server-side usage
import { Ox, GetPlayer, GetPlayers, CreateVehicle, GetVehicle } from '@communityox/ox_core/server';

// Get player and manage groups
const player = GetPlayer(source);
await player.setGroup('police', 3);

const [groupName, grade] = player.getGroup(['police', 'ambulance']) || [];

// Create and manage vehicles
const vehicle = await CreateVehicle(
  {
    model: 'adder',
    owner: player.charId,
    properties: { colour1: [255, 0, 0] }
  },
  [0, 0, 72],
  90.0
);

vehicle.set('insured', true);
await vehicle.save();

// Account operations
const account = await player.getAccount();
if (account) {
  await account.addBalance({ amount: 1000, message: 'Bonus' });
  const balance = await account.get('balance');
}
```

--------------------------------

### Character Creation and Management

Source: https://context7.com/communityox/ox_core/llms.txt

Handles the creation, selection, and deletion of characters for players.

```APIDOC
## Character Creation and Management

### Description
Provides functionality to create, select, and delete characters associated with a player account.

### Methods
- `player:createCharacter(data)`: Creates a new character with the provided data.
  - `data` (table): Contains character details like `firstName`, `lastName`, `gender`, `date` (Unix timestamp).
- `player:setActiveCharacter(charId)`: Sets the specified character as the active one for the player.
- `player:deleteCharacter(charId)`: Deletes a character identified by `charId`.
- `player:logout(saveData)`: Logs out the current character, optionally saving data.

### Example Usage
```lua
-- Server-side: Character management (typically handled internally)
local player = Ox.GetPlayer(source)

-- Create a new character
local slotIndex = player:createCharacter({
    firstName = 'John',
    lastName = 'Doe',
    gender = 'male',
    date = 631152000000  -- Unix timestamp for date of birth
})

-- Set active character by charId
local character = player:setActiveCharacter(charId)

-- Delete a character
local success = player:deleteCharacter(charId)

-- Logout current character
player:logout(true)  -- true = save data
```
```

--------------------------------

### Ban System (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Ban and unban users from the server. Specify a reason and duration (in hours) for bans. Use nil for a permanent ban.

```lua
-- Ban a user
local success = Ox.BanUser(
    userId,         -- User ID to ban
    'Cheating',     -- Reason
    24              -- Hours (nil for permanent)
)

-- Unban a user
local success = Ox.UnbanUser(userId)
```

--------------------------------

### Player Group Management (Server-Side)

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for managing player group memberships, grades, and permissions on the server.

```APIDOC
## Player Group Management (Server-Side)

Players can belong to multiple groups with different grades. Groups represent jobs, factions, or organizations with hierarchical permissions.

### Set Player Group

Sets or updates a player's grade within a specific group. Setting the grade to 0 removes the player from the group.

- **Method**: `player:setGroup(groupName, grade)`
  - **Parameters**:
    - `groupName` (string) - Required - The name of the group.
    - `grade` (number) - Required - The grade level (0 to remove).

### Get Player Group Grade

Retrieves a player's grade in a specific group or checks multiple groups.

- **Method**: `player:getGroup(groupName)`
  - **Parameters**:
    - `groupName` (string) - Required - The name of the group.
  - **Returns**: `number` - The player's grade in the group, or `nil` if not a member.

- **Method**: `player:getGroup(groupNames)`
  - **Parameters**:
    - `groupNames` (table) - Required - A table of group names to check.
  - **Returns**: `string`, `number` - The name of the first group found and the player's grade, or `nil`, `nil`.

- **Method**: `player:getGroup(groupFilter)`
  - **Parameters**:
    - `groupFilter` (table) - Required - A table mapping group names to minimum required grades (e.g., `{ police = 2, ambulance = 1 }`).
  - **Returns**: `string`, `number` - The name of the highest-grade group matched and the player's grade, or `nil`, `nil`.

### Get All Player Groups

Retrieves all groups the player is a member of.

- **Method**: `player:getGroups()`
  - **Returns**: `table` - A table where keys are group names and values are grades (e.g., `{ police = 3, ambulance = 1 }`).

### Get Group by Type

Retrieves the player's highest grade in a group of a specific type (e.g., 'job', 'gang').

- **Method**: `player:getGroupByType(type)`
  - **Parameters**:
    - `type` (string) - Required - The type of group to search for.
  - **Returns**: `string`, `number` - The name of the group and the player's grade, or `nil`, `nil`.

### Set Active Group

Sets the player's active group, often used for duty status.

- **Method**: `player:setActiveGroup(groupName)`
  - **Parameters**:
    - `groupName` (string | nil) - Required - The name of the group to set as active, or `nil` to clear.

### Check Group Permissions

Checks if the player has a specific permission within a group.

- **Method**: `player:hasPermission(permissionString)`
  - **Parameters**:
    - `permissionString` (string) - Required - The permission string to check (e.g., `"group.police.arrest"`).
  - **Returns**: `boolean` - `true` if the player has the permission, `false` otherwise.

### Example Usage (Lua)
```lua
local player = Ox.GetPlayer(source)

-- Set player's grade in a group (0 removes them)
player:setGroup('police', 3)  -- Set to grade 3
player:setGroup('police', 0)  -- Remove from group

-- Get player's grade in a group
local grade = player:getGroup('police')  -- Returns number or nil

-- Check multiple groups at once
local groupName, grade = player:getGroup({ 'police', 'ambulance' })

-- Check with minimum grade requirement
local groupName, grade = player:getGroup({ police = 2, ambulance = 1 })

-- Get all groups
local groups = player:getGroups()
-- Returns: { police = 3, ambulance = 1 }

-- Get group by type (e.g., 'job', 'gang')
local groupName, grade = player:getGroupByType('job')

-- Set active group (for duty status)
player:setActiveGroup('police')
player:setActiveGroup(nil)  -- Clear active group

-- Check group permissions
local hasPermission = player:hasPermission('group.police.arrest')
```
```

--------------------------------

### Client-Side Player Data Access (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Accesses the local player's data on the client-side. Data is automatically cached and updated. Requires `Ox.GetPlayer()` without arguments.

```lua
-- Get the local player instance
local player = Ox.GetPlayer()

-- Access player data
print(player.userId)
print(player.charId)
print(player.stateId)
print(player.state)  -- LocalPlayer.state

-- Get cached data with automatic updates
local name = player:get('name')
local activeGroup = player:get('activeGroup')

-- Listen for data changes
player:on('activeGroup', function(groupName)
    print('Active group changed to:', groupName)
end)

-- Get player coordinates
local coords = player:getCoords()
```

--------------------------------

### Client-Side Player API

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for accessing the local player's data and state on the client.

```APIDOC
## Client-Side Player API

The client-side Player API provides access to the local player's data with automatic caching and event-driven updates.

### Get Local Player

Retrieves the local player instance.

- **Method**: `Ox.GetPlayer()`
  - **Returns**: `Player` object

### Player Data Access

Access properties and cached data of the local player.

- `player.userId` (number) - Account ID
- `player.charId` (number) - Character ID
- `player.stateId` (string) - State ID
- `player.state` (table) - LocalPlayer.state object

- **Method**: `player:get(key)`
  - **Parameters**:
    - `key` (string) - Required - The metadata key to retrieve.
  - **Returns**: `any` - The cached value of the metadata key.

### Event Handling

Listen for changes in player metadata.

- **Method**: `player:on(key, callback)`
  - **Parameters**:
    - `key` (string) - Required - The metadata key to listen for changes on.
    - `callback` (function) - Required - Function to execute when the key's value changes. Receives the new value as an argument.

### Get Coordinates

Get the local player's current coordinates.

- **Method**: `player:getCoords()`
  - **Returns**: `table` - Player's coordinates `{ x, y, z }`.

### Example Usage (Lua)
```lua
-- Get the local player instance
local player = Ox.GetPlayer()

-- Access player data
print(player.userId)
print(player.charId)
print(player.stateId)
print(player.state)  -- LocalPlayer.state

-- Get cached data with automatic updates
local name = player:get('name')
local activeGroup = player:get('activeGroup')

-- Listen for data changes
player:on('activeGroup', function(groupName)
    print('Active group changed to:', groupName)
end)

-- Get player coordinates
local coords = player:getCoords()
```

### Example Usage (TypeScript)
```typescript
import { GetPlayer } from '@communityox/ox_core/client';

const player = GetPlayer();

// Access player properties
console.log(player.userId);
console.log(player.charId);
console.log(player.stateId);

// Get cached data
const name = player.get('name');

// Listen for updates
player.on('activeGroup', (groupName: string) => {
  console.log('Active group changed to:', groupName);
});

// Get coordinates
const coords = player.getCoords();
```
```

--------------------------------

### Check Group Permissions (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Verifies if a player has a specific permission associated with a group, such as 'group.police.arrest'.

```lua
-- Check group permissions
local hasPermission = player:hasPermission('group.police.arrest')
```

--------------------------------

### Access Built-in Player Metadata (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Retrieves standard player metadata fields that are commonly used, such as name, date of birth, and phone number.

```lua
-- Built-in metadata includes:
local name = player:get('name')           -- Full name
local firstName = player:get('firstName')
local lastName = player:get('lastName')
local gender = player:get('gender')
local dob = player:get('dateOfBirth')
local phone = player:get('phoneNumber')
local activeGroup = player:get('activeGroup')
```

--------------------------------

### Server-Side Player API

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for retrieving and managing player data on the server.

```APIDOC
## Server-Side Player API

The Player API provides methods to retrieve, manage, and interact with connected players and their characters. Players are identified by their server source ID, userId (account), or charId (character).

### Get Player

Retrieves a player instance based on various identifiers.

- **Method**: `Ox.GetPlayer(source)`
  - **Parameters**:
    - `source` (number) - Required - The server source ID of the player.
  - **Returns**: `Player` object or `nil`

- **Method**: `Ox.GetPlayerFromUserId(userId)`
  - **Parameters**:
    - `userId` (number) - Required - The user ID of the player.
  - **Returns**: `Player` object or `nil`

- **Method**: `Ox.GetPlayerFromCharId(charId)`
  - **Parameters**:
    - `charId` (number) - Required - The character ID of the player.
  - **Returns**: `Player` object or `nil`

### Get All Players

Retrieves a list of all connected players, with optional filtering.

- **Method**: `Ox.GetPlayers(filter?)`
  - **Parameters**:
    - `filter` (table, optional) - Criteria to filter players (e.g., `{ groups = 'police' }`).
  - **Returns**: `table` - A table of `Player` objects.

### Get Player From Filter

Retrieves a single player matching specific filter criteria.

- **Method**: `Ox.GetPlayerFromFilter(filter)`
  - **Parameters**:
    - `filter` (table) - Criteria to filter players (e.g., `{ firstName = 'John' }`).
  - **Returns**: `Player` object or `nil`

### Player Properties

Access properties of a `Player` object.

- `player.source` (number) - Server ID
- `player.userId` (number) - Account ID
- `player.charId` (number) - Character ID
- `player.stateId` (string) - State ID (e.g., "AB1234")
- `player.username` (string) - Username
- `player.identifier` (string) - License identifier

### Player State and Coordinates

Get the player's current coordinates and state.

- **Method**: `player:getCoords()`
  - **Returns**: `table` - Player's coordinates `{ x, y, z }`.

- **Method**: `player:getState()`
  - **Returns**: `table` - Player's current state data.

### Example Usage (Lua)
```lua
-- Get a player by their server ID
local player = Ox.GetPlayer(source)

-- Get player by userId or charId
local playerByUserId = Ox.GetPlayerFromUserId(1)
local playerByCharId = Ox.GetPlayerFromCharId(100)

-- Get all players, optionally filtered
local allPlayers = Ox.GetPlayers()
local policePlayers = Ox.GetPlayers({ groups = 'police' })

-- Get a single player matching filter criteria
local targetPlayer = Ox.GetPlayerFromFilter({ firstName = 'John' })

-- Access player properties
print(player.source)
print(player.userId)
print(player.charId)
print(player.stateId)
print(player.username)
print(player.identifier)

-- Get player coordinates and state
local coords = player:getCoords()
local state = player:getState()
```
```

--------------------------------

### Create and Spawn Vehicles

Source: https://context7.com/communityox/ox_core/llms.txt

Server-side Lua functions to create vehicles, either spawning them directly into the world with specified properties and location, or creating them as stored entities without immediate spawning. Supports spawning stored vehicles by database ID or VIN.

```lua
-- Create a new vehicle (spawned in world)
local vehicle = Ox.CreateVehicle({
    model = 'adder',
    owner = player.charId,  -- Optional: character owner
    group = 'police',       -- Optional: group owner
    stored = nil,           -- Optional: storage location
    properties = {          -- Optional: vehicle properties
        colour1 = { 0, 0, 0 },
        colour2 = { 255, 255, 255 }
    }
}, vector3(0, 0, 0), 90.0)  -- coords, heading

-- Create vehicle without spawning (stored)
local storedVehicle = Ox.CreateVehicle({
    model = 'sultan',
    owner = player.charId,
    stored = 'garage_legion'
})

-- Spawn a stored vehicle from database
local vehicle = Ox.SpawnVehicle(vehicleDbId, vector3(0, 0, 0), 90.0)
-- Or by VIN
local vehicle = Ox.SpawnVehicle('1ADSU12345678', vector3(0, 0, 0), 90.0)
```

--------------------------------

### Server-Side Vehicle API

Source: https://context7.com/communityox/ox_core/llms.txt

Offers comprehensive vehicle management, including creation, spawning, ownership, and metadata storage.

```APIDOC
## Server-Side Vehicle API

### Description
The Vehicle API provides comprehensive vehicle management, including creation, spawning, ownership, and metadata storage.

### Methods
- `Ox.CreateVehicle(data, coords, heading)`: Creates a new vehicle in the world or stores it.
  - `data` (table): Vehicle configuration (`model`, `owner`, `group`, `stored`, `properties`).
  - `coords` (vector3): Spawn coordinates.
  - `heading` (number): Spawn heading.
- `Ox.CreateVehicle(data)`: Creates a vehicle and stores it without spawning.
- `Ox.SpawnVehicle(vehicleDbId, coords, heading)`: Spawns a stored vehicle from the database.
- `Ox.SpawnVehicle(vin, coords, heading)`: Spawns a stored vehicle by its VIN.
- `Ox.GetVehicle(entityId)`: Retrieves a vehicle instance by its entity ID.
- `Ox.GetVehicle(vin)`: Retrieves a vehicle instance by its VIN.
- `Ox.GetVehicleFromNetId(netId)`: Retrieves a vehicle instance by its network ID.
- `Ox.GetVehicles(filter)`: Retrieves all vehicles, optionally filtered by owner or group.

### Vehicle Properties
- `entity`: Entity handle.
- `netId`: Network ID.
- `plate`: License plate.
- `model`: Model name.
- `make`: Manufacturer.
- `vin`: Vehicle Identification Number.
- `id`: Database ID.
- `owner`: Owner character ID.
- `group`: Group owner.

### Vehicle Methods
- `vehicle:getCoords()`: Gets the vehicle's coordinates.
- `vehicle:getState()`: Gets the vehicle's current state.
- `vehicle:getStored()`: Gets the storage location of the vehicle.
- `vehicle:getProperties()`: Gets the vehicle's properties.

### Example Usage
```lua
-- Create a new vehicle (spawned in world)
local vehicle = Ox.CreateVehicle({
    model = 'adder',
    owner = player.charId,  -- Optional: character owner
    group = 'police',       -- Optional: group owner
    stored = nil,           -- Optional: storage location
    properties = {          -- Optional: vehicle properties
        colour1 = { 0, 0, 0 },
        colour2 = { 255, 255, 255 }
    }
}, vector3(0, 0, 0), 90.0)  -- coords, heading

-- Create vehicle without spawning (stored)
local storedVehicle = Ox.CreateVehicle({
    model = 'sultan',
    owner = player.charId,
    stored = 'garage_legion'
})

-- Spawn a stored vehicle from database
local vehicle = Ox.SpawnVehicle(vehicleDbId, vector3(0, 0, 0), 90.0)
-- Or by VIN
local vehicle = Ox.SpawnVehicle('1ADSU12345678', vector3(0, 0, 0), 90.0)

-- Get vehicle instances
local vehicleByEntity = Ox.GetVehicle(entityId)
local vehicleByVin = Ox.GetVehicle('1ADSU12345678')
local vehicleFromNet = Ox.GetVehicleFromNetId(netId)

-- Get all vehicles, optionally filtered
local allVehicles = Ox.GetVehicles()
local playerVehicles = Ox.GetVehicles({ owner = player.charId })
local policeVehicles = Ox.GetVehicles({ group = 'police' })

-- Access vehicle properties
print(vehicle.entity)   -- Entity handle
print(vehicle.netId)    -- Network ID
print(vehicle.plate)    -- License plate
print(vehicle.model)    -- Model name
print(vehicle.make)     -- Manufacturer
print(vehicle.vin)      -- Vehicle Identification Number
print(vehicle.id)       -- Database ID
print(vehicle.owner)    -- Owner charId
print(vehicle.group)    -- Group owner

-- Get vehicle data
local coords = vehicle:getCoords()
local state = vehicle:getState()
local stored = vehicle:getStored()
local properties = vehicle:getProperties()
```
```

--------------------------------

### Saving and Batch Operations (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Save all players and vehicles to the database. Can optionally save vehicles from a specific resource or include a message when saving all players (e.g., for server restarts).

```lua
-- Save all players to database
Ox.SaveAllPlayers()

-- Save and kick all players (for restart)
Ox.SaveAllPlayers('Server restarting...')

-- Save all vehicles to database
Ox.SaveAllVehicles()

-- Save vehicles from specific resource
Ox.SaveAllVehicles('myresource')
```

--------------------------------

### Manage Player Licenses

Source: https://context7.com/communityox/ox_core/llms.txt

Server-side Lua functions for adding, retrieving, updating, and removing player licenses such as driver's or weapon permits. License data can include issue timestamps and suspension details.

```lua
-- Server-side: Manage player licenses
local player = Ox.GetPlayer(source)

-- Add a license
local success = player:addLicense('driver')
local success = player:addLicense('weapon')

-- Get a specific license
local license = player:getLicense('driver')
-- Returns: { issued = 1699999999999 }

-- Get all licenses
local licenses = player:getLicenses()

-- Update license data (e.g., add points, suspension)
player:updateLicense('driver', 'points', 3)
player:updateLicense('driver', 'suspended', { os.time(), os.time() + 86400 })

-- Remove a license
player:removeLicense('driver')
```

--------------------------------

### Player License System

Source: https://context7.com/communityox/ox_core/llms.txt

Manages character licenses such as driver's licenses, weapon permits, etc.

```APIDOC
## Player License System

### Description
Manages character licenses, including driver's licenses, weapon permits, and other credentials.

### Methods
- `player:addLicense(licenseType)`: Adds a license of the specified type to the player.
- `player:getLicense(licenseType)`: Retrieves data for a specific license.
- `player:getLicenses()`: Retrieves all licenses associated with the player.
- `player:updateLicense(licenseType, key, value)`: Updates specific data for a license (e.g., points, suspension).
- `player:removeLicense(licenseType)`: Removes a license of the specified type from the player.

### Example Usage
```lua
-- Server-side: Manage player licenses
local player = Ox.GetPlayer(source)

-- Add a license
local success = player:addLicense('driver')
local success = player:addLicense('weapon')

-- Get a specific license
local license = player:getLicense('driver')
-- Returns: { issued = 1699999999999 }

-- Get all licenses
local licenses = player:getLicenses()

-- Update license data (e.g., add points, suspension)
player:updateLicense('driver', 'points', 3)
player:updateLicense('driver', 'suspended', { os.time(), os.time() + 86400 })

-- Remove a license
player:removeLicense('driver')
```
```

--------------------------------

### Check Multiple Groups or Minimum Grade (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Checks the player's status in multiple groups simultaneously or verifies if they meet a minimum grade requirement across specified groups.

```lua
-- Check multiple groups at once
local groupName, grade = player:getGroup({ 'police', 'ambulance' })

-- Check with minimum grade requirement
local groupName, grade = player:getGroup({ police = 2, ambulance = 1 })
```

--------------------------------

### Manage Character and Group Bank Accounts

Source: https://context7.com/communityox/ox_core/llms.txt

Lua code for retrieving, creating, and accessing metadata for character and group bank accounts. Use this to manage financial entities within the game.

```lua
-- Get accounts
local characterAccount = Ox.GetCharacterAccount(player.charId)
local groupAccount = Ox.GetGroupAccount('police')
local accountById = Ox.GetAccount(accountId)

-- Create a new account
local newAccount = Ox.CreateAccount(player.charId, 'Savings Account')
-- Or for a group
local groupAccount = Ox.CreateAccount('police', 'Police Fund')

-- Get account metadata
local balance = characterAccount:get('balance')
local label = characterAccount:get('label')
local accountType = characterAccount:get('type')  -- 'personal', 'shared', 'group'
local isDefault = characterAccount:get('isDefault')

-- Get multiple values at once
local data = characterAccount:get({ 'balance', 'label', 'type' })
```

--------------------------------

### Character Creation and Management

Source: https://context7.com/communityox/ox_core/llms.txt

Server-side Lua functions for creating new characters with specified details, setting the active character using their ID, and deleting characters. Includes a function to log out the current character, with an option to save data.

```lua
-- Server-side: Character management (typically handled internally)
local player = Ox.GetPlayer(source)

-- Create a new character
local slotIndex = player:createCharacter({
    firstName = 'John',
    lastName = 'Doe',
    gender = 'male',
    date = 631152000000  -- Unix timestamp for date of birth
})

-- Set active character by charId
local character = player:setActiveCharacter(charId)

-- Delete a character
local success = player:deleteCharacter(charId)

-- Logout current character
player:logout(true)  -- true = save data
```

--------------------------------

### Perform Account Transactions

Source: https://context7.com/communityox/ox_core/llms.txt

Lua code for managing account transactions including adding/removing funds, transferring between accounts, and player deposits/withdrawals. Use this to handle all financial movements.

```lua
-- Add funds to account
local success = account:addBalance({
    amount = 5000,
    message = 'Salary payment'
})

-- Remove funds from account
local success = account:removeBalance({
    amount = 1000,
    message = 'Purchase',
    overdraw = false  -- Prevent negative balance
})

-- Transfer between accounts
local success = account:transferBalance({
    toId = targetAccountId,
    amount = 2500,
    message = 'Transfer to savings',
    note = 'Monthly savings',
    overdraw = false,
    actorId = player.charId  -- Who initiated the transfer
})

-- Player deposit (from cash to account)
local success = account:depositMoney(
    source,     -- Player source
    1000,       -- Amount
    'Deposit',  -- Message
    'ATM'       -- Note
)

-- Player withdrawal (from account to cash)
local success = account:withdrawMoney(
    source,
    500,
    'Withdrawal',
    'ATM'
)
```

--------------------------------

### Vehicle Modification and Persistence

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for modifying vehicle properties, ownership, and saving changes to the database.

```APIDOC
## Vehicle Modification and Persistence

Modify vehicle properties, ownership, and persist changes to the database.

### Server-side: Modify vehicle

Use `Ox.GetVehicle(entityId)` to retrieve a vehicle object.

#### Set Vehicle Metadata
- `vehicle:set('key', value)`: Sets a metadata key-value pair for the vehicle.
- Example: `vehicle:set('insurance', true)`

#### Get Vehicle Metadata
- `vehicle:get('key')`: Retrieves the value for a given metadata key.
- Example: `local insured = vehicle:get('insurance')`

#### Change Ownership
- `vehicle:setOwner(player.charId)`: Transfers ownership to a player.
- `vehicle:setOwner(nil)`: Removes ownership.

#### Change Group Ownership
- `vehicle:setGroup('groupName')`: Assigns the vehicle to a group.
- `vehicle:setGroup(nil)`: Removes group ownership.

#### Change Plate
- `vehicle:setPlate('PLATE')`: Sets a custom license plate.

#### Set Storage Location
- `vehicle:setStored('garageName')`: Marks the vehicle as stored in a specific garage.
- `vehicle:setStored('garageName', true)`: Stores the vehicle and despawns it.

#### Apply Vehicle Properties
- `vehicle:setProperties(propertiesTable, immediate)`: Applies modifications like colors and engine parts.
  - `propertiesTable`: A table containing properties like `colour1`, `modEngine`, etc.
  - `immediate` (boolean): If true, applies changes immediately.

#### Save Vehicle
- `vehicle:save()`: Saves the current state of the vehicle to the database.

#### Respawn Vehicle
- `vehicle:respawn(coordinates, heading)`: Respawns the vehicle at a specified location and heading.

#### Despawn Vehicle
- `vehicle:despawn(saveBefore)`: Despawns the vehicle. If `saveBefore` is true, it saves before despawning.

#### Delete Vehicle
- `vehicle:delete()`: Permanently removes the vehicle from the database.
```

--------------------------------

### Player Status System

Source: https://context7.com/communityox/ox_core/llms.txt

Manages player conditions like hunger, thirst, and stress with automatic decay.

```APIDOC
## Player Status System

### Description
Manages player conditions such as hunger, thirst, and stress, with automatic decay.

### Methods
- `player:setStatus(statusName, value)`: Sets the value of a player status (0-100).
- `player:getStatus(statusName)`: Retrieves the current value of a player status.
- `player:getStatuses()`: Retrieves all player statuses.
- `player:addStatus(statusName, amount)`: Increases a player status by a specified amount.
- `player:removeStatus(statusName, amount)`: Decreases a player status by a specified amount.

### Example Usage
```lua
-- Server-side: Manage player statuses
local player = Ox.GetPlayer(source)

-- Set status value (0-100)
player:setStatus('hunger', 75)
player:setStatus('thirst', 100)

-- Get status value
local hunger = player:getStatus('hunger')

-- Get all statuses
local statuses = player:getStatuses()
-- Returns: { hunger = 75, thirst = 100, stress = 0 }

-- Add or remove from status
player:addStatus('hunger', 10)     -- Increase by 10
player:removeStatus('thirst', 5)   -- Decrease by 5
```
```

--------------------------------

### Set Player Grade in Group (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Assigns or removes a player from a specific group by setting their grade. A grade of 0 effectively removes the player from the group.

```lua
-- Server-side: Manage player groups
local player = Ox.GetPlayer(source)

-- Set player's grade in a group (0 removes them)
player:setGroup('police', 3)  -- Set to grade 3
player:setGroup('police', 0)  -- Remove from group
```

--------------------------------

### Account System (Banking)

Source: https://context7.com/communityox/ox_core/llms.txt

Manages character and group bank accounts, including transactions and metadata retrieval.

```APIDOC
## Account System (Banking)

The Account API manages character and group bank accounts with support for transactions, invoices, and role-based access.

### Get Accounts
- `Ox.GetCharacterAccount(charId)`: Retrieves a character's primary account.
- `Ox.GetGroupAccount(groupName)`: Retrieves a group's primary account.
- `Ox.GetAccount(accountId)`: Retrieves an account by its unique ID.

### Create Account
- `Ox.CreateAccount(charId, 'Account Label')`: Creates a new personal account for a character.
- `Ox.CreateAccount('groupName', 'Account Label')`: Creates a new group account.

### Get Account Metadata
- `account:get('key')`: Retrieves a specific metadata field from the account.
  - Supported keys: `balance`, `label`, `type` ('personal', 'shared', 'group'), `isDefault`.
- `account:get({key1, key2, ...})`: Retrieves multiple metadata fields at once.

**Example:**
```lua
local characterAccount = Ox.GetCharacterAccount(player.charId)
local balance = characterAccount:get('balance')
local data = characterAccount:get({ 'balance', 'label', 'type' })
```
```

--------------------------------

### Vehicle Data and Statistics

Source: https://context7.com/communityox/ox_core/llms.txt

APIs for accessing vehicle data definitions and performance statistics.

```APIDOC
## Vehicle Data and Statistics

Access vehicle data definitions and performance statistics.

### Get Vehicle Data
- `Ox.GetVehicleData(modelName)`: Retrieves data for a specific vehicle model (e.g., 'adder').
- `Ox.GetVehicleData()`: Retrieves data for all vehicle models.
- `Ox.GetVehicleData({model1, model2, ...})`: Retrieves data for a list of specified vehicle models.

**Returned Data Structure Example:**
```json
{
    "name": "adder",
    "make": "Truffade",
    "class": 7,  // VehicleClasses.SUPER
    "type": "automobile",
    "category": "land",
    "seats": 2,
    "doors": 2,
    "price": 1000000,
    "acceleration": 0.89,
    "braking": 0.72,
    "handling": 0.85,
    "speed": 0.95,
    "traction": 0.88
}
```

### Get Top Vehicle Stats
- `Ox.GetTopVehicleStats(category)`: Retrieves top performance statistics for a given category ('land', 'air', 'sea').
- `Ox.GetTopVehicleStats()`: Retrieves top performance statistics for all categories.

### Generate Vehicle Identifiers
- `Ox.GenerateVehicleVin(modelName)`: Generates a unique Vehicle Identification Number (VIN) for a given model.
- `Ox.GenerateVehiclePlate()`: Generates a random unique license plate.
- `Ox.GenerateVehiclePlate('PATTERN')`: Generates a license plate matching a specific pattern (e.g., '1AAA111').
```

--------------------------------

### Set Active Group (Lua)

Source: https://context7.com/communityox/ox_core/llms.txt

Designates a player's active group, often used to indicate their current job or duty status. Can be cleared by setting to nil.

```lua
-- Set active group (for duty status)
player:setActiveGroup('police')
player:setActiveGroup(nil)  -- Clear active group
```