Player
CLIENT SIDE ONLY
A set of functions to manage and retrieve detailed player-related information. These functions are designed to be modular and framework-independent, enabling developers to access cardinal directions, street names, targeting, animation handling, and more.
Functions
get_cardinal_direction
Retrieve the cardinal direction the player is facing
Function
local function get_cardinal_direction(player)
local heading = GetEntityHeading(player)
local directions = {
'N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'
}
local index = math.floor(((heading + 22.5) % 360) / 45) + 1
return directions[index]
end
exports('get_cardinal_direction', get_cardinal_direction)
utils.player.get_cardinal_direction = get_cardinal_directionExample
--- Utils object
local direction = utils.player.get_cardinal_direction(PlayerPedId())
print("Player is facing:", direction)
--- Direct export
local direction = exports.boii_utils:get_cardinal_direction(PlayerPedId())get_street_name
Retrieves the street name and area the player is currently located.
Function
local function get_street_name(player)
local player_coords = GetEntityCoords(player)
local street_hash, _ = GetStreetNameAtCoord(player_coords.x, player_coords.y, player_coords.z)
local street_name = GetStreetNameFromHashKey(street_hash)
local area_name = GetLabelText(GetNameOfZone(player_coords.x, player_coords.y, player_coords.z))
if street_name and area_name then
return street_name .. ', ' .. area_name
elseif street_name then
return street_name
elseif area_name then
return area_name
else
return 'Unknown'
end
end
exports('get_street_name', get_street_name)
utils.player.get_street_name = get_street_nameExample
--- Utils object
local street_name = utils.player.get_street_name(PlayerPedId())
print("Player is on:", street_name)
--- Direct export
exports.boii_utils:get_street_name(PlayerPedId())get_region_name
Gets the region name where player is located.
Function
local function get_region(player)
local player_coords = GetEntityCoords(player)
return GetNameOfZone(player_coords.x, player_coords.y, player_coords.z)
end
exports('get_region', get_region)
utils.player.get_region = get_regionExample
local player = PlayerPedId()
local region_name = utils.player.get_region(player)
print("Player is in the region:", region_name)
get_player_details
Retrieve detailed information about the player.
Function
local function get_player_details(player)
local data = {}
data.server_id = GetPlayerServerId(player)
data.name = GetPlayerName(player)
data.max_stamina = GetPlayerMaxStamina(player)
data.stamina = GetPlayerStamina(player)
data.health = GetEntityHealth(player)
data.armor = GetPedArmour(player)
data.melee_damage_modifier = GetPlayerMeleeWeaponDamageModifier(player)
data.melee_defense_modifier = GetPlayerMeleeWeaponDefenseModifier(player)
data.vehicle_damage_modifier = GetPlayerVehicleDamageModifier(player)
data.vehicle_defense_modifier = GetPlayerVehicleDefenseModifier(player)
data.weapon_damage_modifier = GetPlayerWeaponDamageModifier(player)
data.weapon_defense_modifier = GetPlayerWeaponDefenseModifier(player)
local player_coords = GetEntityCoords(player)
data.coords = vector4(player_coords.x, player_coords.y, player_coords.z, GetEntityHeading(player))
data.model_hash = GetEntityModel(player)
return data
end
exports('get_player_details', get_player_details)
utils.player.get_player_details = get_player_detailsExample
--- Utils object
local details = utils.player.get_player_details(PlayerPedId())
print("Player details:", json.encode(details))
--- Direct export
local details = export.boii_utils:get_player_details(PlayerPedId())get_targeted_entity
Check if player is targeting an entity and retrieve its ID.
Function
local function get_target_entity(player)
local entity = 0
if IsPlayerFreeAiming(player) then
local success, target = GetEntityPlayerIsFreeAimingAt(player)
if success then
entity = target
end
end
return entity
end
exports('get_target_entity', get_target_entity)
utils.player.get_target_entity = get_target_entityExample
--- Utils object
local target = utils.player.get_target_entity(PlayerPedId())
if target > 0 then
print("Player is targeting entity ID:", target)
else
print("Player is not targeting any entity.")
end
--- Direct export
local target = exports.boii_utils:get_target_entity(PlayerPedId())get_distance_to_entity
Calculate distance between a player and a specified entity.
Function
local function get_distance_to_entity(player, entity)
local player_coords = GetEntityCoords(player)
local entity_coords = GetEntityCoords(entity)
return #(player_coords - entity_coords)
end
exports('get_distance_to_entity', get_distance_to_entity)
utils.player.get_distance_to_entity = get_distance_to_entityExample
--- Specify entity
local entity = --[[ some entity ID ]]
--- Utils object
local distance = utils.player.get_distance_to_entity(PlayerPedId(), entity)
print("Distance to entity:", distance)
--- Direct export
local distance = exports.boii_utils:get_distance_to_entity(PlayerPedId(), entity)play_animation
Runs an animation on the player with detailed customisation options.
Function
local function play_animation(player, options, callback)
if not player then print('player ped is missing') return end
if not options or not options.dict or not options.anim then print('Options or animation dictionary/animation name is missing') return end
utils.requests.anim(options.dict)
if options.freeze then
FreezeEntityPosition(player, true)
end
local duration = options.duration or 2000
local props = {}
if options.props then
for _, prop in ipairs(options.props) do
utils.requests.model(prop.model)
local prop_entity = CreateObject(GetHashKey(prop.model), GetEntityCoords(player), true, true, true)
AttachEntityToEntity(prop_entity, player, GetPedBoneIndex(player, prop.bone), prop.coords.x or 0.0, prop.coords.y or 0.0, prop.coords.z or 0.0, prop.rotation.x or 0.0, prop.rotation.y or 0.0, prop.rotation.z or 0.0, true, prop.use_soft or false, prop.collision or false, prop.is_ped or true, prop.rot_order or 1, prop.sync_rot or true)
props[#props + 1] = prop_entity
end
end
if options.continuous then
TaskPlayAnim(player, options.dict, options.anim, options.blend_in or 8.0, options.blend_out or -8.0, -1, options.flags or 49, options.playback or 0, options.lock_x or 0, options.lock_y or 0, options.lock_z or 0)
else
TaskPlayAnim(player, options.dict, options.anim, options.blend_in or 8.0, options.blend_out or -8.0, duration, options.flags or 49, options.playback or 0, options.lock_x or 0, options.lock_y or 0, options.lock_z or 0)
Wait(duration)
ClearPedTasks(player)
if options.freeze then
FreezeEntityPosition(player, false)
end
for _, prop_entity in ipairs(props) do
DeleteObject(prop_entity)
end
if callback then
callback()
end
end
end
exports('play_animation', play_animation)
utils.player.play_animation = play_animationExample
--- Utils object
utils.player.play_animation(player_ped, {
dict = 'missheistdockssetup1clipboard@base',
anim = 'base',
flags = 49,
duration = 5000,
freeze = true,
continuous = true,
props = {
{
model = 'prop_cs_burger_01',
bone = 57005,
coords = vector3(0.13, 0.05, 0.02),
rotation = vector3(-50.0, 16.0, 60.0),
soft_pin = false,
collision = false,
is_ped = true,
rot_order = 1,
sync_rot = true
},
{
model = 'ba_prop_club_water_bottle',
bone = 60309,
coords = vector3(0.0, 0.0, 0.05),
rotation = vector3(0.0, 0.0, 0.0),
soft_pin = false,
collision = false,
is_ped = true,
rot_order = 1,
sync_rot = true
}
}
}, function()
print('animation finished')
end)
--- Direct export
exports.boii_utils:play_animation(...)Last updated