Skip to main content

Player Methods

xPlayer.triggerEvent​

Triggers a client event for the player.

xPlayer.triggerEvent(eventName, ...)
  • eventName: string name of the client event
  • ... : any

xPlayer.triggerSafeEvent​

Triggers a safe event for the player.

xPlayer.triggerSafeEvent(eventName, eventData, eventOptions)
  • eventName: string (name of the safe event)
  • eventData?: table (data to send through the safe event)
  • eventOptions?: CEventOptions (whether server, client, or both should be triggered - defaults to {server = false, client = true})

xPlayer.setCoords​

Sets the player's coordinates.

xPlayer.setCoords(coords)
  • coords: table or vector3 or vector4

xPlayer.getCoords​

Gets the player's coordinates.

xPlayer.getCoords(vector)
  • vector?: boolean (whether to return the player coords as vector4 or as table)
  • return? vector4 or table

xPlayer.kick​

Kicks the player out with an optional reason.

xPlayer.kick(reason)
  • reason?: string

xPlayer.setMoney​

Sets the player's money to the specified value.

xPlayer.setMoney(money)
  • money: number
  • return boolean (whether the action was successful or not)

xPlayer.getMoney​

Gets the player's money value.

xPlayer.getMoney()
  • return number

xPlayer.addMoney​

Adds the specified value to the player's money.

xPlayer.addMoney(money, reason)
  • money: number
  • reason?: string
  • return boolean (whether the action was successful or not)

xPlayer.removeMoney​

Removes the specified value from the player's money.

xPlayer.removeMoney(money, reason)
  • money: number
  • reason?: string
  • return boolean (whether the action was successful or not)

xPlayer.getIdentifier​

Gets the player's identifier.

xPlayer.getIdentifier()
  • return string

xPlayer.getLicense​

Gets the player's Rockstar license.

xPlayer.getLicense()
  • return string

xPlayer.hasGroup​

Checks if the player has the specified group.

xPlayer.hasGroup(groupName, groupGrade)
  • groupName: string
  • groupGrade?: number
  • return boolean
  • return? number (returns the player's group grade if exists in case groupGrade is omitted)

xPlayer.addGroup​

Adds the specified group to the player's groups

xPlayer.addGroup(groupName, groupGrade)
  • groupName: string
  • groupGrade: number
  • return boolean (whether the action was successful or not)

xPlayer.removeGroup​

Removes the specified group from the player's groups.

xPlayer.removeGroup(groupName)
  • groupName: string
  • return boolean (whether the action was successful or not)

xPlayer.getGroups​

Gets all of the player's groups.

xPlayer.getGroups()
  • return table<string, number>

xPlayer.setGroup​

Sets the player's permission/user/admin group.

xPlayer.setGroup(newGroup)
  • newGroup: string
  • return boolean (whether the action was successful or not)

xPlayer.getGroup​

Gets the player's permission/user/admin group.

xPlayer.getGroup()
  • return string

xPlayer.set​

Sets the specified value to the key variable for the player.

xPlayer.set(key, value)
  • key: string
  • value: any

xPlayer.get​

Gets the value of the specified key variable from the player, returning the entire table if key is omitted.

xPlayer.get(key)
  • key?: string
  • return any

xPlayer.getAccounts​

Gets all of the player's accounts.

xPlayer.getAccounts(minimal)
  • minimal?: boolean
  • return table

xPlayer.getAccount​

Gets the specified account's data of the player.

xPlayer.getAccount(accountName)
  • accountName?: string
  • return? table

xPlayer.getInventory​

Gets all of the player's inventory data.

xPlayer.getInventory(minimal)
  • minimal?: boolean
  • return table

xPlayer.getLoadout​

Gets all of the player's loadout data.

xPlayer.getLoadout(minimal)
  • minimal?: boolean
  • return table

xPlayer.getName​

Gets the player's name.

xPlayer.getName()
  • return string

xPlayer.setName​

Sets the player's name.

xPlayer.setName(newName)
  • newName: string

xPlayer.setAccountMoney​

Sets money for the specified account of the player.

xPlayer.setAccountMoney(accountName, money, reason)
  • accountName: string
  • money: number
  • reason?: string
  • return boolean (whether the action was successful or not)

xPlayer.addAccountMoney​

Adds money to the specified account of the player.

xPlayer.addAccountMoney(accountName, money, reason)
  • accountName: string
  • money: number
  • reason?: string
  • return boolean (whether the action was successful or not)

xPlayer.removeAccountMoney​

Removes money from the specified account of the player.

xPlayer.removeAccountMoney(accountName, money, reason)
  • accountName: string
  • money: number
  • reason?: string
  • return boolean (whether the action was successful or not)

xPlayer.getInventoryItem​

Gets the specified item data from the player's inventory.

xPlayer.getInventoryItem(itemName)
  • itemName: string
  • return? table

xPlayer.addInventoryItem​

Adds the specified item to the player's inventory.

xPlayer.addInventoryItem(itemName, itemCount)
  • itemName: string
  • itemCount?: number (defaults to 1 if omitted)
  • return boolean (whether the action was successful or not)

xPlayer.removeInventoryItem​

Removes the specified item from the player's inventory.

xPlayer.removeInventoryItem(itemName, itemCount)
  • itemName: string
  • itemCount?: number (defaults to 1 if omitted)
  • return boolean (whether the action was successful or not)

xPlayer.setInventoryItem​

Set the specified item count in the player's inventory.

xPlayer.setInventoryItem(itemName, itemCount)
  • itemName: string
  • itemCount: number
  • return boolean (whether the action was successful or not)

xPlayer.getWeight​

Gets the player's inventory weight.

xPlayer.getWeight()
  • return number

xPlayer.getMaxWeight​

Gets the player's maximum inventory weight.

xPlayer.getMaxWeight()
  • return number

xPlayer.setMaxWeight​

Sets the player's maximum inventory weight.

xPlayer.setMaxWeight(newWeight)
  • newWeight: number

xPlayer.canCarryItem​

Checks if the player does have enough space in inventory to carry the specified item count(s).

xPlayer.canCarryItem(itemName, itemCount)
  • itemName: string
  • itemCount: number
  • return boolean

xPlayer.canSwapItem​

Checks if 2 items with the specified counts can be swapped in the player's inventory based on max inventory weight.

xPlayer.canSwapItem(firstItem, firstItemCount, testItem, testItemCount)
  • firstItem: string
  • firstItemCount: number
  • testItem: string
  • testItemCount: number
  • return boolean

xPlayer.getJob​

Gets the player's job object.

xPlayer.getJob()
  • return table

xPlayer.setJob​

Sets job for the player.

xPlayer.setJob(job, grade, duty)
  • job: string
  • grade: number
  • duty?: boolean (if omitted, it will use the job's default duty state)
  • return boolean (whether the action was successful or not)

xPlayer.getDuty​

Gets the player's job duty state.

xPlayer.getDuty()
  • return boolean

xPlayer.setDuty​

Sets the player's job duty state.

xPlayer.setDuty(duty)
  • duty: boolean
  • return boolean (whether the action was successful or not)

xPlayer.addWeapon​

Adds a weapon with the specified ammo to the player's loadout.

xPlayer.addWeapon(weaponName, ammo)
  • weaponName: string
  • ammo: number
  • return boolean (whether the action was successful or not)

xPlayer.removeWeapon​

Removes the specified weapon from the player's loadout.

xPlayer.removeWeapon(weaponName)
  • weaponName: string
  • return boolean (whether the action was successful or not)

xPlayer.addWeaponComponent​

Adds a specific component to the player's weapon.

xPlayer.addWeaponComponent(weaponName, weaponComponent)
  • weaponName: string
  • weaponComponent: string
  • return boolean (whether the action was successful or not)

xPlayer.removeWeaponComponent​

Removes the specified weapon component from the player's loadout.

xPlayer.removeWeaponComponent(weaponName, weaponComponent)
  • weaponName: string
  • weaponComponent: string
  • return boolean (whether the action was successful or not)

xPlayer.updateWeaponAmmo​

Sets ammo of the player's specified weapon.

xPlayer.updateWeaponAmmo(weaponName, ammoCount)
  • weaponName: string
  • ammoCount: number
  • return boolean (whether the action was successful or not)

xPlayer.addWeaponAmmo​

Adds ammo to the player's specified weapon.

xPlayer.addWeaponAmmo(weaponName, ammoCount)
  • weaponName: string
  • ammoCount: number
  • return boolean (whether the action was successful or not)

xPlayer.removeWeaponAmmo​

Removes ammo from the player's specified weapon.

xPlayer.removeWeaponAmmo(weaponName, ammoCount)
  • weaponName: string
  • ammoCount: number
  • return boolean (whether the action was successful or not)

xPlayer.setWeaponTint​

Sets tint of the player's specified weapon.

xPlayer.setWeaponTint(weaponName, weaponTintIndex)
  • weaponName: string
  • weaponTintIndex: number
  • return boolean (whether the action was successful or not)

xPlayer.getWeaponTint​

Gets the tint index of the player's specified weapon.

xPlayer.getWeaponTint(weaponName)
  • weaponName: string
  • return boolean (whether the action was successful or not)

xPlayer.hasWeaponComponent​

Checks if player has the specified component for the weapon.

xPlayer.hasWeaponComponent(weaponName, weaponComponent)
  • weaponName: string
  • weaponComponent: string
  • return boolean (whether the action was successful or not)

xPlayer.hasWeapon​

Checks if the specified weapon can be found in the player's loadout.

xPlayer.hasWeapon(weaponName)
  • weaponName: string
  • return boolean (whether the action was successful or not)

xPlayer.hasItem​

Checks if the specified item can be found in the player's inventory.

xPlayer.hasItem(itemName)
  • itemName: string
  • return boolean
  • return? number (returns nil if first return data is false)

xPlayer.getWeapon​

Gets the specified weapon data from player's loadout if it exists.

xPlayer.getWeapon(itemName)
  • weaponName: string
  • return false or number
  • return? table (returns nil if first return data is false)

xPlayer.showNotification​

Shows a notification to the player.

xPlayer.showNotification(message, type, duration, extra)
  • message: string or table (if table is passed, the first index reflects the message title and the second index reflects the message description)
  • type?: "inform" or "error" or "success" or "warning" (defaults to "inform" if no value is provided)
  • duration?: number (defaults to 3000 if no value is provided)
  • extra?: table (extra properties related to ox_lib notify can be found here)

xPlayer.showHelpNotification​

Shows a help-type notification to the player.

xPlayer.showHelpNotification(message, thisFrame, beep, duration)
  • message: string
  • thisFrame: boolean
  • beep: boolean
  • duration: number

xPlayer.getMetadata​

Gets the player's specified metadata. Returns all metadatas if the key/index is omitted.

xPlayer.getMetadata(index, subIndex)
  • index?: string
  • subIndex?: string or table
  • return? string or table or nil

xPlayer.setMetadata​

Sets value of the specified metadata key/index of the player's.

xPlayer.setMetadata(index, value, subValue)
  • index: string
  • value?: string or number or table
  • subValue?: any
  • return boolean (whether the action was successful or not)

xPlayer.getInScopePlayers​

Gets a table including all instances of players ids that are in-scope/in-range with the current player.

xPlayer.getInScopePlayers(includeSelf)
  • includeSelf?: boolean (include the current player within the return data or not - defaults to false)
  • return? table<number, playerId> or nil

xPlayer.isInPlayerScope​

Checks if the current player is inside the scope/range of the target player id.

xPlayer.isInPlayerScope(targetId)
  • targetId?: number
  • return? boolean

xPlayer.isPlayerInScope​

Checks if the target player id is inside the scope/range of the current player.

xPlayer.isPlayerInScope(targetId)
  • targetId?: number
  • return? boolean

xPlayer.triggerScopedEvent​

Triggers a client event for all players that are in-scope/in-range with the current player.

xPlayer.triggerScopedEvent(eventName, includeSelf, ...)
  • eventName: string (name of the client event)
  • includeSelf?: boolean (trigger the event for the current player - defaults to false)
  • ... : any

xPlayer.triggerSafeScopedEvent​

Triggers a safe event for all players that are in-scope/in-range with the current player.

xPlayer.triggerSafeScopedEvent(eventName, includeSelf, eventData, eventOptions)
  • eventName: string (name of the safe event)
  • includeSelf?: boolean (trigger the event for the current player as well or not - defaults to false)
  • eventData?: table (data to send through the safe event)
  • eventOptions?: table:CEventOptions (data to define whether server, client, or both should be triggered - defaults to { server = false, client = true })

xPlayer.getRoutingBucket​

Gets the routing bucket id that the player is inside.

xPlayer.getRoutingBucket()
  • return number

xPlayer.setRoutingBucket​

Adds the player to the specified routing bucket id.

xPlayer.setRoutingBucket(bucketId)
  • bucketId: number
  • return boolean (whether the action was successful or not)

xPlayer.setField​

Sets the value of the specified field for the xPlayer object. If a field with the same name already exist, its value will be overrided.

xPlayer.setField(fieldName, value)
  • fieldName: string
  • value: number or string or boolean or table
  • return boolean (whether the field registration was successful or not)

xPlayer.setMethod​

Adds a new method/function to the current xPlayer object. If a method with the same name already exist, it will be overrided.

xPlayer.setMethod(fnName, fn)
  • fnName: string
  • fn: function
  • return boolean (whether the method registration was successful or not)
info

Example using xPlayer.setMethod function​

local xPlayer = ESX.GetPlayerFromId(1)

-- registering a new method called "customCheck"
xPlayer.setMethod("customCheck", function(self)
    return function(firstParameter)
        print(("This is xPlayer(%s)'s 'customCheck' method being triggered"):format(self.source))
        print(("The parameter passed in the 'customCheck' method is '%s'"):format(firstParameter))
    end
end)

-- reloading the xPlayer object after new method is registered
xPlayer = ESX.GetPlayerFromId(xPlayer.source)

-- calling the new registered method
xPlayer.customCheck("hello from customCheck")

p.s. In this way of registering a new method, only xPlayer object of player(1) will have the customCheck method registered for it!

could be useful in scenarios when your server has multiple gamemodes/lobbies setup and you don't want to populate all player objects with the new method.