gurp logo gurp docs
Main Website Status Discord

Documentation Draft

gurp Lua API Reference

This API page is seeded from your current runtime notes and is marked as provisional. Update signatures and behavior notes whenever the loader/runtime changes.

Getting Started

overviewdraft

Current best-known API layout for gurp Lua (subject to change).

This is a draft reference from runtime notes. Treat it as a structured base and update signatures as your loader/API changes.

How To Use This Docs Set

  • Use sidebar categories to open one module page at a time.
  • Use tags to quickly spot module type (overview, module, debug, etc.).
  • Use search to filter pages by function names and keywords.

Maintenance Checklist

  • Update changed signatures and return types first.
  • Add behavior notes for edge cases and reset behavior.
  • Keep one short runnable example per module.

Versioning

metacompat

Global namespace: gurp

Current version marker: gurp.api_version == 3

Cache API marker: gurp.has_cache_api == true

Quick tip: check api_version first in shared scripts so older loaders fail gracefully instead of hard erroring later.

Important Type Notes

typesbehavior

  • Roblox objects are passed as u64 addresses (Lua integer/number values).
  • Most SDK/memory functions return nil on invalid input/address.
  • gurp.wait() / gurp.sleep_ms() can throw "Lua environment reset".
  • gurp.game is a snapshot captured when script starts, not a live-updating table.
If something returns nil unexpectedly, first verify the object still exists before assuming the API is broken.

Top-Level gurp

apiruntime

Address & Runtime Accessors

FunctionReturns
gurp.get_base_address()u64
gurp.get_datamodel()u64
gurp.get_workspace()u64
gurp.get_camera()u64
gurp.get_localplayer()u64
gurp.get_offset(namespace, name)u64 | nil
In most scripts, these are read once at startup and occasionally refreshed after teleports or major state changes.

Timing, Input, and Helpers

FunctionReturns
gurp.wait(seconds 0..60)nil
gurp.sleep_ms(ms 0..60000)nil
gurp.time_ms()integer
gurp.is_key_down(vk)boolean
gurp.log(msg)nil
gurp.clamp(value, min, max)number

Top-Level Fields

gurp.api_version -> integer (3)
gurp.has_cache_api -> boolean (true)
gurp.memory -> table
gurp.sdk -> table
gurp.cache -> table
gurp.ui -> table
gurp.draw -> table
gurp.game -> table

gurp.memory

modulememory

Read Functions

gurp.memory.read_u64(address: u64) -> u64|nil
gurp.memory.read_u32(address: u64) -> integer|nil
gurp.memory.read_f32(address: u64) -> number|nil
gurp.memory.read_bool(address: u64) -> boolean|nil

Write Functions

gurp.memory.write_u64(address: u64, value: u64) -> boolean
gurp.memory.write_u32(address: u64, value: integer) -> boolean
gurp.memory.write_f32(address: u64, value: number) -> boolean
gurp.memory.write_bool(address: u64, value: boolean) -> boolean
Reads return nil on invalid addresses. Writes return false on invalid addresses.
Safe pattern: always read, validate, then write. Blind writes are the quickest way to crash loops.

gurp.sdk (Object Helpers)

moduleobjects

All object arguments are expected to be u64 addresses.
Naming helpers are usually the cheapest sanity check when debugging weird object paths.

Identity & Hierarchy

gurp.sdk.name(obj) -> string|nil
gurp.sdk.display_name(obj) -> string|nil
gurp.sdk.class_name(obj) -> string|nil
gurp.sdk.children(obj) -> table<integer, u64>
gurp.sdk.find_child(obj, child_name) -> u64|nil
gurp.sdk.find_child_of_class(obj, class_name) -> u64|nil
gurp.sdk.character(obj) -> u64|nil

Spatial & State

gurp.sdk.position(obj) -> {x,y,z}|nil
gurp.sdk.velocity(obj) -> {x,y,z}|nil
gurp.sdk.size(obj) -> {x,y,z}|nil
gurp.sdk.humanoid_state(obj) -> integer|nil
gurp.sdk.text(obj) -> string|nil

Physics & Camera

gurp.sdk.anchored(obj) -> boolean|nil
gurp.sdk.set_anchored(obj, value) -> boolean
gurp.sdk.set_can_collide(obj, value) -> boolean
gurp.sdk.field_of_view(camera_obj) -> number|nil
gurp.sdk.set_field_of_view(camera_obj, fov) -> boolean

CFrame & Rotation

gurp.sdk.cframe(obj) -> {r00..r22,x,y,z}|nil
gurp.sdk.rotation(obj) -> matrix3x3|nil
gurp.sdk.camera_rotation(obj) -> matrix3x3|nil
gurp.sdk.camera_position(obj) -> {x,y,z}|nil
gurp.sdk.set_rotation(obj, matrix3x3) -> boolean
gurp.sdk.set_camera_rotation(obj, matrix3x3) -> boolean

Value Accessors

gurp.sdk.value_u64(obj) -> u64|nil
gurp.sdk.value_u32(obj) -> integer|nil
gurp.sdk.value_f32(obj) -> number|nil
gurp.sdk.value_bool(obj) -> boolean|nil
gurp.sdk.set_value_u64(obj, v) -> boolean
gurp.sdk.set_value_u32(obj, v) -> boolean
gurp.sdk.set_value_f32(obj, v) -> boolean
gurp.sdk.set_value_bool(obj, v) -> boolean

Misc Helpers

gurp.sdk.primitive(obj) -> u64|nil
gurp.sdk.primitive_flags(obj) -> u64|nil
gurp.sdk.attribute_instance(obj) -> u64|nil
gurp.sdk.background_color3(obj) -> {x,y,z}|nil
gurp.sdk.players_service() -> u64|nil
For performance, cache frequently used objects locally instead of walking children every frame.

gurp.cache (Custom Player Feed)

modulecache

Lifecycle

gurp.cache.add_player(
  address:u64,
  userid:u64,
  name:string,
  display_name:string,
  team_address:u64,
  health:number=100.0,
  max_health:number=100.0
) -> boolean

gurp.cache.remove_player(userid:u64, address:u64) -> boolean
gurp.cache.clear_players() -> boolean
gurp.cache.players_count() -> integer

Per-Player Updates

gurp.cache.set_player_part(userid:u64, address:u64, part_name:string, part_address:u64) -> boolean
gurp.cache.set_player_humanoid(userid:u64, address:u64, humanoid_address:u64) -> boolean
gurp.cache.set_player_health(userid:u64, address:u64, health:number, max_health:number) -> boolean
Keep userid + address pairs consistent. Most cache desync bugs come from mixing one and not the other.

gurp.ui (Lua UI Builder)

moduleui

Element Creation

gurp.ui.window(window_id, title, x=100, y=100, width=300, height=180) -> boolean
gurp.ui.text(window_id, element_id, text) -> boolean
gurp.ui.button(window_id, element_id, label) -> boolean
gurp.ui.checkbox(window_id, element_id, label, default=false) -> boolean
gurp.ui.slider_float(window_id, element_id, label, min=0, max=1, default=min) -> number

State Access & Window Controls

gurp.ui.get_bool(window_id, element_id) -> boolean
gurp.ui.set_bool(window_id, element_id, value:boolean) -> boolean
gurp.ui.get_float(window_id, element_id) -> number
gurp.ui.set_float(window_id, element_id, value:number) -> boolean

gurp.ui.remove_window(window_id) -> boolean
gurp.ui.clear() -> boolean

gurp.ui.set_interactive(enabled:boolean) -> boolean
gurp.ui.get_interactive() -> boolean

gurp.ui.set_draggable(window_id, enabled:boolean) -> boolean
gurp.ui.get_draggable(window_id) -> boolean
  • window_id + element_id act as retained state keys.
  • Button returns true once per click cycle (latched behavior).
Keep IDs stable between script updates; changing IDs resets saved UI state and confuses users.

gurp.draw (Overlay Drawlist API)

modulerender

Primitives

gurp.draw.clear() -> boolean
gurp.draw.text(
  x:number, y:number, text:string,
  r:number=1, g:number=1, b:number=1, a:number=1,
  centered:boolean=false
) -> boolean

gurp.draw.line(
  x1:number, y1:number, x2:number, y2:number,
  thickness:number=1,
  r:number=1, g:number=1, b:number=1, a:number=1
) -> boolean

gurp.draw.circle(
  x:number, y:number,
  radius:number,
  thickness:number=1,
  segments:integer=0,
  r:number=1, g:number=1, b:number=1, a:number=1
) -> boolean

gurp.draw.circle_filled(
  x:number, y:number,
  radius:number,
  segments:integer=0,
  r:number=1, g:number=1, b:number=1, a:number=1
) -> boolean

Projection Helper

gurp.draw.world_to_screen(x:number, y:number, z:number)
  -> {x:number, y:number} | nil
Typical render loop calls gurp.draw.clear() each tick before redraw. Resetting the Lua environment clears draw commands.
If text/lines look offset, verify your world_to_screen output before tweaking draw coordinates manually.

gurp.game Snapshot Table

statesnapshot

gurp.game.is_in_game    -> boolean
gurp.game.base_address  -> u64
gurp.game.datamodel     -> u64
gurp.game.workspace     -> u64
gurp.game.camera        -> u64
gurp.game.localplayer   -> u64
This table is a startup snapshot. If you need fresh values mid-session, call top-level getters again.

Example Introspection Snippet

debugtools

for k,v in pairs(gurp) do
  gurp.log(("gurp.%s -> %s"):format(k, type(v)))
end

for k,v in pairs(gurp.draw) do
  gurp.log(("gurp.draw.%s -> %s"):format(k, type(v)))
end
This is useful after updates to quickly confirm which modules actually loaded in the current environment.

Changelog

updateshistory

v0.2.0 (Runtime API Draft Import)

Imported current runtime API reference for gurp, memory, sdk, cache, ui, draw, and game.