Players API

Access cached player data with high performance.

Overview

The Players API provides access to cached player information. The cache is updated automatically in the background, making these functions very fast.

Player Object

All functions return player objects with this structure:

{
    address = 0x...,      -- Memory address (number)
    name = "PlayerName",  -- Player name (string)
    health = 100,         -- Current health (number)
    max_health = 100,     -- Maximum health (number)
    distance = 50.5,      -- Distance in studs (number)
    position = {          -- Position (table, may be nil)
        x = 0,
        y = 0,
        z = 0
    }
}

Functions

get_all()

Get all players in the game.

local players = kinetic.players.get_all()

Returns: table - Array of player objects

Example:

local players = kinetic.players.get_all()
print("Found " .. #players .. " players")

for i, player in ipairs(players) do
    print(i .. ". " .. player.name .. " - Health: " .. player.health)
end

---

get_local()

Get the local player (you).

local local_player = kinetic.players.get_local()

Returns: table or nil - Local player object

Example:

local local_player = kinetic.players.get_local()

if local_player then
    print("Your name: " .. local_player.name)
    print("Your health: " .. local_player.health .. "/" .. local_player.max_health)
    
    if local_player.position then
        print("Your position: " .. local_player.position.x .. ", " .. 
              local_player.position.y .. ", " .. local_player.position.z)
    end
end

---

get_closest()

Get the closest player to you.

local closest = kinetic.players.get_closest()

Returns: table or nil - Closest player object

Example:

local closest = kinetic.players.get_closest()

if closest then
    print("Closest player: " .. closest.name)
    print("Distance: " .. string.format("%.1f", closest.distance) .. " studs")
end

---

get_by_name()

Find a player by name.

local player = kinetic.players.get_by_name(name)

Parameters:

• name (string) - Player name to search for

Returns: table or nil - Player object if found

Example:

local player = kinetic.players.get_by_name("PlayerName")

if player then
    print("Found player!")
    print("Health: " .. player.health)
    print("Distance: " .. player.distance)
else
    print("Player not found")
end

---

filter_by_distance()

Get players within a certain distance.

local nearby = kinetic.players.filter_by_distance(max_distance)

Parameters:

• max_distance (number) - Maximum distance in studs

Returns: table - Array of player objects

Example:

-- Get players within 100 studs
local nearby = kinetic.players.filter_by_distance(100)

print("Players nearby: " .. #nearby)
for i, player in ipairs(nearby) do
    print(player.name .. " - " .. string.format("%.1f", player.distance) .. " studs")
end

---

filter_by_health()

Get players within a health range.

local filtered = kinetic.players.filter_by_health(min_health, max_health)

Parameters:

• min_health (number) - Minimum health

• max_health (number) - Maximum health

Returns: table - Array of player objects

Example:

-- Get low health players (0-50 HP)
local low_health = kinetic.players.filter_by_health(0, 50)

print("Low health players: " .. #low_health)
for i, player in ipairs(low_health) do
    print(player.name .. " - " .. player.health .. " HP")
end

-- Get full health players
local full_health = kinetic.players.filter_by_health(100, 100)

Complete Examples

Player List Display

kinetic.on_frame = function(delta_time)
    local players = kinetic.players.get_all()
    local y = 10
    
    kinetic.draw.text({10, y}, {255, 255, 0}, "Players (" .. #players .. ")")
    y = y + 20
    
    for i, player in ipairs(players) do
        -- Name and health
        local text = string.format("%d. %s [%.0f HP] %.0f studs", 
            i, player.name, player.health, player.distance)
        
        -- Color based on health
        local health_percent = player.health / player.max_health
        local color
        if health_percent > 0.7 then
            color = {0, 255, 0}  -- Green
        elseif health_percent > 0.3 then
            color = {255, 255, 0}  -- Yellow
        else
            color = {255, 0, 0}  -- Red
        end
        
        kinetic.draw.text({10, y}, color, text)
        y = y + 15
        
        -- Stop if too many players
        if i >= 10 then
            kinetic.draw.text({10, y}, {150, 150, 150}, "... and " .. (#players - 10) .. " more")
            break
        end
    end
end

Closest Player Tracker

kinetic.on_frame = function(delta_time)
    local closest = kinetic.players.get_closest()
    
    if not closest then
        kinetic.draw.text({10, 10}, {255, 255, 255}, "No players nearby")
        return
    end
    
    local y = 10
    
    -- Title
    kinetic.draw.text({10, y}, {255, 255, 0}, "Closest Player:")
    y = y + 20
    
    -- Name
    kinetic.draw.text({10, y}, {255, 255, 255}, "Name: " .. closest.name)
    y = y + 15
    
    -- Distance
    kinetic.draw.text({10, y}, {255, 255, 255}, 
        string.format("Distance: %.1f studs", closest.distance))
    y = y + 15
    
    -- Health
    kinetic.draw.text({10, y}, {255, 255, 255}, 
        string.format("Health: %.0f/%.0f", closest.health, closest.max_health))
    y = y + 15
    
    -- Health bar
    local health_percent = closest.health / closest.max_health
    kinetic.draw.progress_bar(
        {10, y}, 200, 20, health_percent,
        {50, 50, 50}, {0, 255, 0}
    )
end

Threat Detector

local threat_distance = 50  -- studs
local low_health_threshold = 30

kinetic.on_frame = function(delta_time)
    local local_player = kinetic.players.get_local()
    if not local_player then return end
    
    -- Check for nearby threats
    local nearby = kinetic.players.filter_by_distance(threat_distance)
    local threats = 0
    
    for _, player in ipairs(nearby) do
        if player.health > low_health_threshold then
            threats = threats + 1
        end
    end
    
    -- Display warning
    if threats > 0 then
        local color = threats >= 3 and {255, 0, 0} or {255, 255, 0}
        kinetic.draw.text({10, 10}, color, 
            "WARNING: " .. threats .. " threats nearby!")
    else
        kinetic.draw.text({10, 10}, {0, 255, 0}, "Area clear")
    end
end

Team Analyzer

kinetic.on_frame = function(delta_time)
    local players = kinetic.players.get_all()
    
    -- Count by health ranges
    local full_health = 0
    local damaged = 0
    local critical = 0
    
    for _, player in ipairs(players) do
        local health_percent = (player.health / player.max_health) * 100
        
        if health_percent >= 80 then
            full_health = full_health + 1
        elseif health_percent >= 30 then
            damaged = damaged + 1
        else
            critical = critical + 1
        end
    end
    
    -- Display stats
    local y = 10
    kinetic.draw.text({10, y}, {255, 255, 0}, "Team Status:")
    y = y + 20
    
    kinetic.draw.text({10, y}, {0, 255, 0}, "Full Health: " .. full_health)
    y = y + 15
    
    kinetic.draw.text({10, y}, {255, 255, 0}, "Damaged: " .. damaged)
    y = y + 15
    
    kinetic.draw.text({10, y}, {255, 0, 0}, "Critical: " .. critical)
end

Performance Notes

• Cached data - All functions use cached data, very fast

• Updated automatically - Cache updates ~10 times per second

• No memory reads - Direct access to cached values

• Safe to call frequently - Minimal performance impact

Tips

• Always check for nil - Players may not exist

local player = kinetic.players.get_local()
if player then
    -- Safe to use
end

• Check position exists - Not all players have position data

if player.position then
    local x = player.position.x
end

• Cache results - Don't call get_all() multiple times per frame

-- Good
local players = kinetic.players.get_all()
for i, player in ipairs(players) do
    -- Use player
end

-- Bad
for i = 1, kinetic.player_count() do
    local players = kinetic.players.get_all()  -- Called multiple times!
end

Next Steps

• Drawing API - Draw player information

• Camera API - Project player positions to screen

• Roblox API - Access detailed player data