gurp Lua API Reference

Print your position every second

local function root_part()
  local lp = gurp.get_localplayer()
  if lp == 0 then return nil end
  local character = gurp.sdk.character(lp)
  if not character or character == 0 then return nil end
  local hrp = gurp.sdk.find_child(character, "HumanoidRootPart")
  if not hrp or hrp == 0 then return nil end
  return hrp
end

while true do
  local hrp = root_part()
  if hrp then
    local p = gurp.sdk.position(hrp)
    print(("you are at %.1f, %.1f, %.1f"):format(p.x, p.y, p.z))
  end
  gurp.wait(1)
end

Draw a label above your head

local function valid(x) return x and x ~= 0 end

while true do
  gurp.draw.clear()                      -- start this frame's drawing from scratch
  local character = gurp.sdk.character(gurp.get_localplayer())
  local head = valid(character) and gurp.sdk.find_child(character, "Head")
  if valid(head) then
    local p = gurp.sdk.position(head)
    local s = gurp.draw.world_to_screen(p.x, p.y + 2, p.z)
    if s then
      gurp.draw.text(s.x, s.y, "me", 0.6, 0.9, 0.4, 1, true, 16)
    end
  end
  gurp.wait(0)                           -- shows the frame, lets gurp breathe
end

Limits

Shapes used across the API

Game objects

Timing

Input & screen

Misc

Example: hold a key

local VK_E = 0x45
while true do
  if gurp.is_key_down(VK_E) then
    gurp.log("E is held at " .. gurp.time_ms())
  end
  gurp.wait(0.1)
end

Files

HTTP

Example: save settings as JSON

local Http = game:GetService("HttpService")   -- from the Roblox-style layer
local path = "myscript/settings.json"

local settings = { fov = 90, enabled = true }
if gurp.fs_exists(path) then
  settings = Http:JSONDecode(gurp.fs_read(path)) or settings
end
settings.fov = settings.fov + 1
gurp.fs_write(path, Http:JSONEncode(settings))

local ok, body = pcall(gurp.http_get, "https://example.com/version.txt")
if ok then print("latest version: " .. body) else warn(body) end

gurp fields

gurp.game

Example: read your health with an offset

local lp = gurp.get_localplayer()
local character = gurp.sdk.character(lp)
local humanoid = character and character ~= 0 and gurp.sdk.find_child_of_class(character, "Humanoid") or 0
local health_off = gurp.get_offset("Humanoid", "Health")
if humanoid ~= 0 and health_off then
  local hp = gurp.memory.read_f32(humanoid + health_off)
  print("health: " .. tostring(hp))
end

Identity & hierarchy

Parts & physics

Camera

Humanoids & GUI objects

Value objects (IntValue, BoolValue, ObjectValue...)

Example: list everyone in the server

local players = gurp.sdk.players_service()
for _, plr in ipairs(gurp.sdk.children(players or 0)) do
  if gurp.sdk.class_name(plr) == "Player" then
    print(gurp.sdk.name(plr) .. " (" .. gurp.sdk.display_name(plr) .. ")")
  end
end

Reading

Writing

Example: feed NPCs from a folder

local folder = gurp.sdk.find_child(gurp.get_workspace(), "NPCs")
while true do
  for i, model in ipairs(gurp.sdk.children(folder)) do
    local id = 1000000 + i                     -- any stable id you choose
    gurp.cache.add_player(model, id, gurp.sdk.name(model), "", 0)
    for _, part in ipairs({ "Head", "HumanoidRootPart" }) do
      gurp.cache.set_player_part(id, model, part, gurp.sdk.find_child(model, part))
    end
  end
  gurp.wait(1)
end

Windows

Elements

Reading and setting values

Example

gurp.ui.window("main", "My Script", 120, 120, 320, 200)
while true do
  local enabled = gurp.ui.checkbox("main", "enabled", "Enabled", true)
  local fov = gurp.ui.slider_float("main", "fov", "Field of view", 70, 120, 90, 1)
  gurp.ui.layout("main", false, 0.5)
  local r, g, b = gurp.ui.color("main", "tint", "Tint", 0.6, 0.9, 0.4)
  if gurp.ui.button("main", "reset", "Reset FOV") then
    gurp.ui.set_float("main", "fov", 90)
  end
  if enabled then
    gurp.sdk.set_field_of_view(gurp.get_camera(), fov)
  end
  gurp.wait(0)
end

Example: crosshair that follows the mouse

while true do
  gurp.draw.clear()
  local mx, my = gurp.mouse_pos()
  gurp.draw.circle(mx, my, 10, 1.5, 32, 0.6, 0.9, 0.4, 1)
  gurp.draw.line(mx - 15, my, mx + 15, my, 1, 1, 1, 1, 0.8)
  gurp.draw.line(mx, my - 15, mx, my + 15, 1, 1, 1, 1, 0.8)
  gurp.draw.rect(mx + 14, my + 14, 60, 18, 0, 0, 0, 0.6, 4)
  gurp.draw.text(mx + 44, my + 15, "aim", 1, 1, 1, 1, true, 13)
  gurp.wait(0)
end

Color3

Vector2

Enum.KeyCode

Each entry is { Name = "E", Value = 0x45 }, where Value is the Windows key code (usable with gurp.is_key_down). Available names:

• Letters A–Z, Number0–Number9, Keypad0–Keypad9, KeypadDot, F1–F12
• LeftShift, RightShift, LeftControl, RightControl, LeftAlt, RightAlt
• Space, Return/Enter/KeypadEnter, Escape, Backspace, Tab, Slash, Period, Minus, Equals
• Left, Right, Up, Down, Insert, Delete, Home, End

Example

local RunService = game:GetService("RunService")
local UIS = game:GetService("UserInputService")
local label = Drawing.new("Text")
label.Size = 16
label.Color = Color3.fromRGB(150, 220, 100)

local conn
conn = RunService.RenderStepped:Connect(function()
  local m = UIS:GetMouseLocation()
  label.Position = m + Vector2.new(12, 12)
  label.Text = UIS:IsKeyDown(Enum.KeyCode.LeftShift) and "shift!" or "hold shift"
  if UIS:IsKeyDown("End") then
    label:Remove()
    conn:Disconnect()
  end
end)

Drawing.new(class)

Classes "Square", "Text" and "Circle" are drawn; other class names make an object that doesn't draw. Objects are drawn every frame while a RunService callback is connected.

obj:Remove() deletes one object; Drawing.clear() deletes them all.

DrawingImmediate

One-frame shapes; call them inside a RunService callback.

DrawingImmediate.FilledRectangle(pos, size, color, opacity)
DrawingImmediate.FilledCircle(pos, radius, color, opacity)
DrawingImmediate.Line(from, to, color, opacity, thickness)

task

Files (same sandbox folder as gurp.fs_*)

Input

Language helpers

Stopping cleanly

A reset raises "Lua environment reset" from gurp.wait. If you need to clean up first, wrap the loop:

local ok, err = pcall(function()
  while true do
    -- work
    gurp.wait(0)
  end
end)
gurp.set_desync(false)          -- example clean-up
if not ok and not tostring(err):find("environment reset") then error(err) end

Name tags with health and distance

local health_off = gurp.get_offset("Humanoid", "Health")
local max_health_off = gurp.get_offset("Humanoid", "MaxHealth")

local function valid(x) return x and x ~= 0 end

while true do
  gurp.draw.clear()
  local me = gurp.get_localplayer()
  local cam = gurp.sdk.camera_position(gurp.get_camera())
  for _, plr in ipairs(gurp.sdk.children(gurp.sdk.players_service() or 0)) do
    local character = plr ~= me and gurp.sdk.character(plr)
    local head = valid(character) and gurp.sdk.find_child(character, "Head")
    local hum = valid(character) and gurp.sdk.find_child_of_class(character, "Humanoid")
    if valid(head) and valid(hum) and cam then
      local p = gurp.sdk.position(head)
      local s = gurp.draw.world_to_screen(p.x, p.y + 1.5, p.z)
      if s then
        local hp = gurp.memory.read_f32(hum + health_off) or 0
        local max = gurp.memory.read_f32(hum + max_health_off) or 100
        local dist = math.sqrt((p.x - cam.x)^2 + (p.y - cam.y)^2 + (p.z - cam.z)^2)
        local t = math.clamp(hp / math.max(max, 1), 0, 1)
        gurp.draw.text(s.x, s.y, ("%s  %dm"):format(gurp.sdk.display_name(plr), math.floor(dist)), 1, 1, 1, 1, true, 14)
        gurp.draw.rect(s.x - 20, s.y + 16, 40, 3, 0, 0, 0, 0.7)
        gurp.draw.rect(s.x - 20, s.y + 16, 40 * t, 3, 1 - t, t, 0.2, 1)
      end
    end
  end
  gurp.wait(0)
end

1. Find out what's there

for _, a in ipairs(gurp.sdk.attribute_values(obj, 128) or {}) do
  print(a.name, "f64=" .. a.f64, "f32=" .. a.f32, "u32=" .. a.u32, "bool=" .. tostring(a.bool))
end

Roblox number attributes are usually doubles, so read f64 for numbers and bool for booleans.

2. Read

local ammo = gurp.sdk.attribute_f32(gun, "Ammo", 0)     -- fallback if missing
local auto = gurp.sdk.attribute_bool(gun, "Automatic", false)

3. Write with an exact name

-- 4th argument false = exact match. The default (true) also matches "MaxAmmo".
if not gurp.sdk.attribute_set_f32(gun, "Ammo", 30, false) then
  warn("Ammo attribute not found")
end

4. Case-insensitive fallback

local function set_attr(obj, name, value)
  if gurp.sdk.attribute_set_f32(obj, name, value, false) then return true end
  for _, a in ipairs(gurp.sdk.attribute_values(obj, 256) or {}) do
    if a.name:lower() == name:lower() then
      return gurp.sdk.attribute_set_f32(obj, a.name, value, false)
    end
  end
  return false
end