entity

Query and filter players/characters in the current place, tune visibility (line-of-sight) checks, register custom (non-Roblox-Player) entities, and enumerate BaseParts across all tracked characters.

Queries

entity.GetPlayers

entity.GetPlayers(onlyEnemies: boolean?) -> { Player }

Returns an array of Player handles for every cached player except the LocalPlayer, optionally restricted to enemies.

for _, p in entity.GetPlayers() do print(p) end

entity.GetLocalPlayer

entity.GetLocalPlayer() -> Player | nil

Returns a Player handle for the local player, or nil if it could not be resolved.

local me = entity.GetLocalPlayer()

entity.GetClosestPlayer

entity.GetClosestPlayer(screenPos: Vector2, maxRadius: number?, filter: table?) -> Player | nil

Returns the player whose Head (or HRP fallback) projects closest on screen to screenPos within maxRadius, subject to an optional filter table.

local target = entity.GetClosestPlayer(Vector2.new(960, 540), 200)

entity.GetClosestToCursor

entity.GetClosestToCursor(maxRadiusOrFilter: (number | table)?, filter: table?) -> Player | nil

Returns the player closest to the current mouse cursor position, subject to an optional radius and filter table (if the first argument is a table it is treated as the filter with unlimited radius).

local target = entity.GetClosestToCursor({ onlyEnemies = true })

entity.GetOccluders

entity.GetOccluders(origin: Vector3?, radius: number?) -> { { h: MeshHandle, kind: number } }

Returns the occluder grid’s current geometry per tracked part as mesh handles with a kind code (Enum.PartType 0-4, or 5 for Union/MeshPart), optionally limited to parts near origin within radius.

local occ = entity.GetOccluders()

entity.GetParts

entity.GetParts() -> { Part }

Returns a Part handle for every BasePart across all tracked entities’ characters (players and custom models).

for _, part in entity.GetParts() do print(part:GetPartPosition()) end

entity.GetPartsCount

entity.GetPartsCount() -> number

Returns the count of BaseParts across all tracked entities’ characters.

local n = entity.GetPartsCount()

Visibility & models

entity.SetVisibilityFilter

entity.SetVisibilityFilter(opts: table) -> ()

Tunes which Workspace parts count as occluders for visibility checks (minSize, maxTransparency, requireCanCollide, maxScan, maxOccluders, rebuildPeriod, fastInterval, discoveryInterval, nearRadius); fields omitted from opts keep their current value.

entity.SetVisibilityFilter({ minSize = 1.0, requireCanCollide = true })

entity.SetVisibilityBone

entity.SetVisibilityBone(name: string) -> ()

Sets the character bone used as the target point for IsVisible-style checks, default Head, alias-resolved per rig by the bone cache.

entity.SetVisibilityBone("UpperTorso")

entity.SetVisibilityMode

entity.SetVisibilityMode(mode: "bone" | "any") -> ()

Selects whether visibility passes only when the single SetVisibilityBone target has line of sight (“bone”) or when any body point does (“any”, the default); errors on any other string.

entity.SetVisibilityMode("bone")

entity.GetVisibilityStats

entity.GetVisibilityStats() -> { registrySize: number, evictions: number, discoveryWalked: number, containerCount: number }

Returns counters describing the occluder registry state: current size, cumulative evictions, container count, and the most recent discovery-tick walked-node count.

local stats = entity.GetVisibilityStats()

entity.AddModel

entity.AddModel(key: string, data: table) -> ()

Registers (or replaces) a custom entity under key from a data table requiring a Character Instance field, with optional PrimaryPart, Name, Team, Health, and MaxHealth fields.

entity.AddModel("dummy1", { Character = model, Name = "Dummy", Health = 100, MaxHealth = 100 })

entity.EditModel

entity.EditModel(key: string, data: table) -> ()

Merges the provided fields into an existing custom-entity registration, preserving unspecified fields; a no-op if key is absent.

entity.EditModel("dummy1", { Health = 50 })

entity.RemoveModel

entity.RemoveModel(key: string) -> boolean

Removes a custom-entity registration and returns whether it existed.

local removed = entity.RemoveModel("dummy1")

entity.ClearModels

entity.ClearModels() -> ()

Drops all custom-entity registrations.

entity.ClearModels()

Player properties

Player.Name

Player.Name -> string

The player’s username.

print(p.Name)

Player.DisplayName

Player.DisplayName -> string

The player’s display name.

print(p.DisplayName)

Player.UserId

Player.UserId -> number

The player’s numeric user ID.

print(p.UserId)

Player.Team

Player.Team -> string

The name of the player’s team.

print(p.Team)

Player.IsEnemy

Player.IsEnemy -> boolean

True if the player is on an opposing team to the local player.

if p.IsEnemy then end

Player.IsLocal

Player.IsLocal -> boolean

True if this handle refers to the local player.

if p.IsLocal then end

Player.IsCustom

Player.IsCustom -> boolean

True if this is a custom entity registered via entity.AddModel rather than a real Roblox player.

if p.IsCustom then end

Player.IsR15

Player.IsR15 -> boolean

True if the player’s character rig is R15; false means R6.

if p.IsR15 then end

Player.Health

Player.Health -> number

The player’s current Humanoid health.

print(p.Health)

Player.MaxHealth

Player.MaxHealth -> number

The player’s Humanoid MaxHealth.

print(p.MaxHealth)

Player.IsAlive

Player.IsAlive -> boolean

True if the player’s Humanoid is currently alive.

if p.IsAlive then end

Player.Position

Player.Position -> Vector3

The world position of the player’s HumanoidRootPart.

print(p.Position)

Player.Velocity

Player.Velocity -> Vector3

The player’s derived world velocity, computed from position deltas across frames since the engine exposes none directly.

print(p.Velocity)

Player.Character

Player.Character -> Instance?

The player’s character model Instance, or nil if the player has no character.

local char = p.Character

Player.TeamColor

Player.TeamColor -> Color3

The color associated with the player’s team.

print(p.TeamColor)

Player.BoundingBox

Player.BoundingBox -> {x: number, y: number, w: number, h: number}

The player’s on-screen bounding box as a table of x, y, w, h fields.

local box = p.BoundingBox; print(box.x, box.y, box.w, box.h)

Player.IsVisible

Player.IsVisible -> boolean

True if the player currently has clear line of sight per the configured visibility mode, memoized across frames.

if p.IsVisible then end

Player.Visibility

Player.Visibility -> number

Tri-state line of sight: 1 clear, 2 behind an opaque occluder, 3 behind glass only.

if p.Visibility == 3 then end

Player methods

Player:GetDistanceFromLocal

Player:GetDistanceFromLocal() -> number

Returns the studs distance between this player and the local player, or -1 if the local player is unavailable.

local d = p:GetDistanceFromLocal()

Player:GetBonePosition

Player:GetBonePosition(name: string) -> Vector3?

Returns the world position of a named bone/body part, or nil if it cannot be resolved.

local pos = p:GetBonePosition("Head")

Player:GetBoneSize

Player:GetBoneSize(name: string) -> Vector3?

Returns the size of a named bone/body part, or nil if it cannot be resolved.

local sz = p:GetBoneSize("Head")

Player:GetBoneRotation

Player:GetBoneRotation(name: string) -> {number, [9]}?

Returns the row-major 3x3 rotation matrix of a named bone as a 9-element array, or nil if it cannot be resolved.

local rot = p:GetBoneRotation("Head")

Player:GetBoneInstance

Player:GetBoneInstance(name: string) -> Instance?

Returns the Instance for a named bone/body part, or nil if it cannot be resolved.

local inst = p:GetBoneInstance("Head")

Player:IsBoneVisible

Player:IsBoneVisible(name: string) -> boolean?

Returns whether a specific named bone has clear line of sight to the camera, or nil if the bone does not exist on this rig or the check could not run this frame.

if p:IsBoneVisible("Head") then end

Part handles

Part:GetPartPosition

Part:GetPartPosition() -> Vector3?

Returns the part’s world position, or nil if it cannot be read.

local pos = part:GetPartPosition()

Part:GetPartSize

Part:GetPartSize() -> Vector3?

Returns the part’s size, or nil if it cannot be read.

local size = part:GetPartSize()

Part:GetPartRotation

Part:GetPartRotation() -> {number}?

Returns the part’s rotation as a row-major 3x3 matrix (9 numbers), or nil if it cannot be read.

local r = part:GetPartRotation()

Part:GetPartInstance

Part:GetPartInstance() -> Instance?

Returns the underlying Instance for the part handle, or nil.

local inst = part:GetPartInstance()

Part:GetPartAddress

Part:GetPartAddress() -> number?

Returns the raw memory address backing the part, or nil.

local addr = part:GetPartAddress()

Note

entity.GetPlayers, entity.GetLocalPlayer, entity.GetClosestPlayer, and entity.GetClosestToCursor return opaque Player handles; entity.GetParts returns Part handles. A handle points at one entry in the cache, so once that player or part leaves the map its reads return nil rather than erroring; re-query each frame instead of holding a handle across frames. Reading an unknown key off a handle also returns nil.