# Entity API The entity API provides access to cached player data. Player objects are snapshots updated each frame. Properties marked as **live** perform a memory read on every access. All others are read from the frame cache. > All examples use `snake_case`. Every function is also accessible in `camelCase` and `PascalCase` — the engine accepts all three. Pick one and stay consistent in your scripts. *** ### entity.get\_players ```lua local players = entity.get_players() ``` Returns a table of all valid player objects currently in the game. Includes both Players service characters and workspace entities (NPCs, bots). *** ### entity.get\_local\_player ```lua local me = entity.get_local_player() ``` Returns the local player object, or nil if not available. *** ### entity.get\_player\_count ```lua local count = entity.get_player_count() ``` Returns the number of valid players in the cache. *** ### Player Object #### Cached Properties Read from the frame snapshot, no memory cost. | Property | Type | Description | | --------------------- | ------ | ------------------------------------------ | | `name` | string | Player username | | `display_name` | string | Display name | | `user_id` | number | Roblox user ID (0 for NPCs) | | `team` | string | Team name | | `has_team` | bool | Whether the player is on a team | | `tool_name` | string | Name of equipped tool | | `is_local` | bool | True if this is the local player | | `is_valid` | bool | True if the player data is valid | | `is_workspace_entity` | bool | True if found via workspace scan (NPC/bot) | | `rig_type` | string | "R15", "R6", or "Unknown" | #### Live Properties Each access performs a memory read. These reflect the current game state. | Property | Type | Description | | ----------------- | ------- | ----------------------------------- | | `health` | number | Current health | | `max_health` | number | Maximum health | | `is_alive` | bool | True if health > 0 | | `is_dead` | bool | True if health <= 0 | | `position` | Vector3 | Root part world position | | `velocity` | Vector3 | Root part linear velocity | | `head_position` | Vector3 | Head world position | | `look_vector` | Vector3 | Head forward direction | | `move_direction` | Vector3 | Humanoid move direction | | `camera_offset` | Vector3 | Humanoid camera offset | | `walk_speed` | number | Current walk speed | | `jump_power` | number | Current jump power | | `jump_height` | number | Current jump height | | `hip_height` | number | Hip height | | `max_slope_angle` | number | Maximum walkable slope angle | | `state` | number | Humanoid state enum value | | `state_name` | string | Humanoid state as a readable string | | `sit` | bool | True if seated | | `is_jumping` | bool | True if jump is active | | `platform_stand` | bool | Platform standing state | | `auto_rotate` | bool | Auto rotate enabled | | `is_walking` | bool | True if currently walking | | `floor_material` | number | Material enum of the floor | #### Instance References These return game API instance objects for interop with the `game` API. | Property | Type | Description | | ----------- | -------- | --------------------- | | `character` | Instance | Character model | | `humanoid` | Instance | Humanoid instance | | `player` | Instance | Player service object | #### Writable Properties Player objects support direct property writes through assignment. These write to game memory immediately. **Humanoid writes** (require humanoid): | Property | Type | Description | | ------------------------ | ------- | ---------------------------- | | `health` | number | Set health | | `max_health` | number | Set max health | | `walk_speed` | number | Set walk speed | | `jump_power` | number | Set jump power | | `jump_height` | number | Set jump height | | `hip_height` | number | Set hip height | | `max_slope_angle` | number | Set max slope angle | | `state` | number | Set humanoid state enum | | `sit` | bool | Set seated state | | `jump` | bool | Trigger/cancel jump | | `platform_stand` | bool | Set platform standing | | `auto_rotate` | bool | Set auto rotate | | `auto_jump_enabled` | bool | Set auto jump | | `use_jump_power` | bool | Toggle jump power vs height | | `requires_neck` | bool | Set requires neck joint | | `break_joints_on_death` | bool | Set break joints on death | | `evaluate_state_machine` | bool | Enable/disable state machine | | `camera_offset` | Vector3 | Set humanoid camera offset | | `walkspeed_check` | number | Anti-cheat walkspeed mirror | **Primitive writes** (require root\_primitive): | Property | Type | Description | | ------------------ | ------- | -------------------- | | `position` | Vector3 | Set root position | | `velocity` | Vector3 | Set linear velocity | | `angular_velocity` | Vector3 | Set angular velocity | | `anchored` | bool | Set anchored flag | | `can_collide` | bool | Set collision flag | | `can_query` | bool | Set query flag | | `can_touch` | bool | Set touch flag | *** ### Player Methods #### :get\_bone\_screen(bone\_name) ```lua local sx, sy, visible = p:get_bone_screen(bone_name) ``` Returns the screen position of a named bone and a boolean indicating whether it is on screen. ```lua local sx, sy, visible = p:get_bone_screen("Head") if visible then draw.circle_filled(sx, sy, 4, {1, 1, 0, 1}) end ``` Supported R6 bones: `Head`, `Torso`, `Left Arm`, `Right Arm`, `Left Leg`, `Right Leg`, `HumanoidRootPart` Supported R15 bones: `Head`, `UpperTorso`, `LowerTorso`, `LeftUpperArm`, `LeftLowerArm`, `LeftHand`, `RightUpperArm`, `RightLowerArm`, `RightHand`, `LeftUpperLeg`, `LeftLowerLeg`, `LeftFoot`, `RightUpperLeg`, `RightLowerLeg`, `RightFoot`, `HumanoidRootPart` *** #### :get\_bones\_screen() ```lua local bones = p:get_bones_screen() ``` Returns a table of all valid bones projected to screen space. Keys are bone name strings, values are `{x, y}` tables. ```lua local bones = p:get_bones_screen() if bones["Head"] and bones["UpperTorso"] then draw.line( bones["Head"][1], bones["Head"][2], bones["UpperTorso"][1], bones["UpperTorso"][2], {1, 1, 1, 1} ) end ``` *** #### :get\_bounds() ```lua local b = p:get_bounds() ``` Returns a bounding box table with fields `x`, `y`, `w`, `h`, and `valid`. ```lua local b = p:get_bounds() if b.valid then draw.box(b.x, b.y, b.w, b.h, {1, 1, 1, 1}) end ``` *** #### :distance\_to(point) ```lua local dist = p:distance_to(point) local dist = p:distance_to() -- defaults to camera position ``` Returns the distance from the player's root position to a point. If no argument is given, returns distance to the camera. ```lua local me = entity.get_local_player() for _, p in ipairs(entity.get_players()) do if not p.is_local then local dist = p:distance_to(me.position) print(p.name .. " is " .. math.floor(dist) .. " studs away") end end ``` *** ### Humanoid States The `state` property returns a numeric enum. Use `state_name` for a readable string. | Value | Name | Description | | ----- | ----------------- | -------------------------- | | 0 | FallingDown | Tripped/falling down | | 1 | Ragdoll | Ragdolled | | 2 | GettingUp | Recovering from fall | | 3 | Jumping | Jumping upward | | 4 | Swimming | In water | | 5 | Freefall | Falling through air | | 6 | Flying | Flying | | 7 | Landed | Just landed | | 8 | Running | Running/walking (default) | | 10 | RunningNoPhysics | Server-controlled running | | 11 | StrafingNoPhysics | Server-controlled strafing | | 12 | Climbing | Climbing a ladder/truss | | 13 | Seated | Sitting in a seat | | 14 | PlatformStanding | Standing on a platform | | 15 | Dead | Dead | | 16 | Physics | Physics-controlled | | 18 | None | No state / disabled | *** ### Examples #### Full ESP loop ```lua function on_frame() local players = entity.get_players() for _, p in ipairs(players) do if p.is_local or not p.is_alive then goto continue end local b = p:get_bounds() if not b.valid then goto continue end draw.box(b.x, b.y, b.w, b.h, {1, 1, 1, 1}) draw.health_bar(b.x - 5, b.y, b.h, p.health, p.max_health) local tw, th = draw.get_text_size(p.name, 14) draw.text(b.x + b.w / 2 - tw / 2, b.y - th - 2, p.name, {1, 1, 1, 1}) local hx, hy, hv = p:get_bone_screen("Head") if hv then draw.circle_filled(hx, hy, 3, {1, 1, 0, 1}) end ::continue:: end end ``` #### State display ```lua function on_frame() local players = entity.get_players() for _, p in ipairs(players) do if p.is_local or not p.is_alive then goto continue end local sx, sy, vis = p:get_bone_screen("Head") if vis then local state = p.state_name if state ~= "Running" then local tw, th = draw.get_text_size(state, 12) draw.text(sx - tw / 2, sy - 30, state, {1, 0.8, 0.2, 1}) end end ::continue:: end end ``` #### Speed modification ```lua local me = entity.get_local_player() if me then me.walk_speed = 50 me.jump_power = 100 print("Speed: " .. me.walk_speed) print("Jump: " .. me.jump_power) end ``` #### Force state ```lua local me = entity.get_local_player() if me then me.state = 6 -- set to Flying print("State: " .. me.state_name) end ``` #### Disable collision on all nearby players ```lua function on_frame() local me = entity.get_local_player() if not me then return end for _, p in ipairs(entity.get_players()) do if not p.is_local and p:distance_to(me.position) < 20 then p.can_collide = false end end end ``` #### Skeleton rendering ```lua local connections_r15 = { {"Head", "UpperTorso"}, {"UpperTorso", "LowerTorso"}, {"UpperTorso", "LeftUpperArm"}, {"LeftUpperArm", "LeftLowerArm"}, {"LeftLowerArm", "LeftHand"}, {"UpperTorso", "RightUpperArm"}, {"RightUpperArm", "RightLowerArm"}, {"RightLowerArm", "RightHand"}, {"LowerTorso", "LeftUpperLeg"}, {"LeftUpperLeg", "LeftLowerLeg"}, {"LeftLowerLeg", "LeftFoot"}, {"LowerTorso", "RightUpperLeg"}, {"RightUpperLeg", "RightLowerLeg"}, {"RightLowerLeg", "RightFoot"}, } function on_frame() local players = entity.get_players() for _, p in ipairs(players) do if p.is_local or not p.is_alive then goto continue end if p.rig_type ~= "R15" then goto continue end local bones = p:get_bones_screen() for _, conn in ipairs(connections_r15) do local a = bones[conn[1]] local b = bones[conn[2]] if a and b then draw.line(a[1], a[2], b[1], b[2], {1, 1, 1, 0.8}) end end ::continue:: end end ``` *** ### API Reference | Function | Returns | Description | | ------------------------------ | ------------- | -------------------------------- | | `entity.get_players()` | table | All cached player objects | | `entity.get_local_player()` | player/nil | Local player object | | `entity.get_player_count()` | number | Player count | | `player:get_bone_screen(name)` | x, y, visible | Screen position of a bone | | `player:get_bones_screen()` | table | All bones as screen positions | | `player:get_bounds()` | table | Bounding box {x, y, w, h, valid} | | `player:distance_to(vec3?)` | number | Distance to point or camera | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://project-vector-1.gitbook.io/vector-lua-engine/api/entity-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.