Player Type
Player
Represents a player character in Old School RuneScape, including the local player and other players visible in the game world.
Methods
is_valid()
Check if underlying pointer is non-null.
Returns: boolean - true if valid, false otherwise
name()
Get player display name.
Returns: string - The player's username
Example:
local player = players:local_player()
print("Player name:", player:name())
x()
Get world X coordinate.
Returns: number - The X coordinate in the game world
y()
Get world Y coordinate.
Returns: number - The Y coordinate in the game world
floor()
Get floor/plane level.
Returns: number - The floor level (0-3)
tile()
Get position as a Tile object with x, y, and floor.
Returns: Tile or nil - The tile object representing the player's position
Example:
local player = players:local_player()
local tile = player:tile()
if tile then
print(string.format("Player is at (%d, %d, %d)", tile.x, tile.y, tile.floor))
end
local_x()
Get local X coordinate (relative to the region).
Returns: number - The local X coordinate
local_y()
Get local Y coordinate (relative to the region).
Returns: number - The local Y coordinate
render_height()
Get render height in pixels.
Returns: number - The render height
orientation()
Get orientation (direction the player is facing).
Returns: number - The orientation value
base_point()
Get base point on screen.
Returns: (number, number) - Tuple of (x, y) screen coordinates
next_point()
Get next point on screen (used for click prediction on moving entities).
Returns: (number, number) - Tuple of (x, y) screen coordinates
move_mouse_to()
Move the mouse to this player with human-like movement. Uses the player's clickable point.
Returns: boolean - true on success, false if the position is invalid or the move fails
Example:
local other = players:find_first({name = "Friend"})
if other and other:move_mouse_to() then
mouse:right_click_current()
end
track()
Start tracking this player: the mouse follows the player until the entity is invalid, another mouse action is performed, or you call mouse:stop_track().
Returns: void
Example:
local other = players:find_first({name = "Friend"})
if other then
other:track()
sleep(1000)
mouse:stop_track()
end
set_bounding_model(x1, x2, y1, y2, z1, z2)
Set custom bounding model dimensions for this player. Falls back to the default captured model if not set.
Parameters:
| Name | Type | Description |
|---|---|---|
| x1 | number | Minimum X coordinate |
| x2 | number | Maximum X coordinate |
| y1 | number | Minimum Y coordinate |
| y2 | number | Maximum Y coordinate |
| z1 | number | Minimum Z coordinate |
| z2 | number | Maximum Z coordinate |
Returns: void
Example:
local player = players:local_player()
-- Set custom bounding model dimensions
player:set_bounding_model(-50, 50, -100, 0, -50, 50)
remove_bounding_model()
Remove the custom bounding model, falling back to the default captured model.
Returns: void
Example:
local player = players:local_player()
-- Remove custom bounding model to use default
player:remove_bounding_model()
movement_animation_id()
Get movement animation ID.
Returns: number - The animation ID for movement
movement_animation_frame()
Get movement animation frame.
Returns: number - The current frame of the movement animation
movement_animation_cycle()
Get movement animation cycle.
Returns: number - The animation cycle counter
animation_id()
Get current animation ID.
Returns: number - The active animation ID (-1 if none)
Example:
local player = players:local_player()
local anim = player:animation_id()
if anim ~= -1 then
print("Player is performing animation:", anim)
end
animation_frame()
Get animation frame.
Returns: number - The current frame of the animation
animation_cycle()
Get animation cycle.
Returns: number - The animation cycle counter
animation_delay()
Get animation delay.
Returns: number - The delay before animation starts
idle_animation_id()
Get idle animation ID (the animation when standing still).
Returns: number - The idle animation ID
in_combat()
Check if player is in combat.
Returns: boolean - true if in combat, false otherwise
Example:
local player = players:local_player()
if player:in_combat() then
print("Currently in combat!")
end
click()
Human-like left click the player.
Returns: boolean - true if clicked successfully, false otherwise
interact(filter_input)
Right-click and select menu option by filters.
Parameters:
| Name | Type | Description |
|---|---|---|
| filter_input | table or nil | Optional menu item filters |
Returns: boolean - true if interaction succeeded, false otherwise
Example:
local other_player = players:find_first({name = "PlayerName"})
if other_player then
other_player:interact({action = "Trade with"})
end
is_moving_entity()
Check if player is moving on screen (base_point != next_point).
Returns: boolean - true if moving on screen, false otherwise
is_busy()
Check if player is busy (animating or moving).
Returns: boolean - true if busy, false otherwise
Example:
local player = players:local_player()
while player:is_busy() do
wait()
end
print("Player is now idle")
is_idle()
Check if player is idle (not animating or moving).
Returns: boolean - true if idle, false otherwise
Example:
local player = players:local_player()
if player:is_idle() then
-- Safe to start next action
end
is_animating()
Check if player is currently animating.
Returns: boolean - true if animating, false otherwise
is_moving()
Check if player is currently moving.
Returns: boolean - true if moving, false otherwise
Example:
local player = players:local_player()
if player:is_moving() then
print("Player is walking/running")
end
is_interacting()
Check if player is interacting with something (returns boolean).
Returns: boolean - true if interacting with any actor, false otherwise
Example:
local player = players:local_player()
if player:is_interacting() then
print("Player is in combat or interacting")
end
interacting()
Get the actor (Player or NPC) the player is interacting with.
Returns: LuaActor or nil - The actor being interacted with, or nil if not interacting
Example:
local player = players:local_player()
local target = player:interacting()
if target then
if target:is_npc() then
local npc = target:as_npc()
print("Fighting NPC:", npc:name())
elseif target:is_player() then
local other_player = target:as_player()
print("Interacting with player:", other_player:name())
end
end
interacted_by()
Get the actor (Player or NPC) that is interacting with this player.
Returns: LuaActor or nil - The actor that is interacting with this player, or nil if none
Example:
local player = players:local_player()
local attacker = player:interacted_by()
if attacker then
if attacker:is_npc() then
local npc = attacker:as_npc()
print("Being attacked by NPC:", npc:name())
elseif attacker:is_player() then
local other_player = attacker:as_player()
print("Being attacked by player:", other_player:name())
end
end
is_visible()
Check if player is visible in the viewport.
Returns: boolean - true if visible on screen, false otherwise
appearance()
Get player appearance as array of 12 item IDs.
Returns: table - Array of item IDs representing equipped items
Note: Returns item IDs, not kit IDs.
combat_level()
Get player combat level.
Returns: number - The combat level
Example:
local other_player = players:find_first({name_contains = "Player"})
if other_player then
local level = other_player:combat_level()
print("Combat level:", level)
end
skull_head_icon()
Get skull head icon ID.
Returns: number - The skull icon ID, or -1 if no skull
prayer_head_icon()
Get prayer head icon ID.
Returns: number - The prayer icon ID, or -1 if no prayer icon
reachable()
Check if player is reachable from the local player's position using pathfinding.
Returns: boolean - true if the player can be reached from the local player's current position, false otherwise
Example:
local other_player = players:find_first({name_contains = "Player"})
if other_player and other_player:reachable() then
other_player:interact({action = "Trade with"})
else
print("Player is not reachable")
end