Player
A connected player. Reads and actions go through the facade at call time, so a handle held across ticks never returns stale data (a disconnected player returns nil, err). A player id is reused after the player leaves, but a handle is not: it stays bound to its connection, id() still returns the old id, and actions affect no one, even if another player now holds that id.
Player:id
Returns id integer
Player:name
Returns name string|nil, err string|nil
Player:is_alive
Returns alive boolean|nil, err string|nil
Player:is_spawned
Returns spawned boolean|nil, err string|nil
Player:is_paused
True while the player's game is paused (its menu is open). Its body stays in place and its input is neutral.
Returns paused boolean|nil, err string|nil
Player:health
The player's health as tracked by the server. Commands can raise or lower it; the player's own frames and accepted damage can only lower it. Other players see the same value.
Returns health number|nil, err string|nil
Player:armor
The player's armor as tracked by the server; works like Player:health.
Returns armor number|nil, err string|nil
Player:money
Returns money integer|nil, err string|nil
Player:heading
Heading in degrees (the teleport convention), as of the player's latest sync.
Returns heading number|nil, err string|nil
Player:velocity
Velocity in m/s (world axes), as of the player's latest sync while alive.
Returns x number|nil, y number|string|nil, z number|nil
Player:is_ducked
Whether the player is crouching, as of its latest sync while alive.
Returns ducked boolean|nil, err string|nil
Player:is_on_ground
Whether the player is standing on something, as of its latest sync while alive.
Returns on_ground boolean|nil, err string|nil
Player:camera_front
The direction the player's camera faces, as a unit vector; zero before its first sync.
Returns x number|nil, y number|string|nil, z number|nil
Player:keys
The names of the keys the player holds: "forward", "backward", "left", "right", "sprint", "jump", "walk", "fire", "aim" (also reported while the game aims without the key). A dead, frozen or paused player holds none. Consistent with player_key_change.
Returns keys string[]|nil, err string|nil
Player:ping
The smoothed round-trip time of the player's connection, in ms. The server measures it once a second with a keepalive and with every reliable event the player acknowledges, so it stays current for idle players too. An event that was lost and resent counts with the time until it arrived. The client can understate or overstate it, so treat it as advisory. nil without err before the first sample.
Returns ping integer|nil, err string|nil
Player:state
What the player is doing in the world: "pre_spawn" (until its first spawn is confirmed), "on_foot", "driver", "passenger", "dead" (until the next spawn is confirmed), "spectating" (its camera follows a player wherever its body is, even while dead; use player_death and Player:is_alive for the state of the body).
Returns state string|nil, err string|nil
Player:target
The living player this player aims at, among those shown to it, as of its latest sync. This is a client claim that the server checks only for being near the camera ray, not for line of sight: do not base rewards or punishments on it. nil without err when there is none.
Returns target Player|nil, err string|nil
Player:skin
Skin model and variant.
Returns model integer|nil, variant integer|string|nil
Player:wanted
Wanted level set by set_wanted; kept across respawns, 0 for a new connection.
Returns level integer|nil, err string|nil
Player:virtual_world
Returns virtual_world integer|nil, err string|nil
Player:interior
Interior from the last teleport, spawn or respawn (0 = outside).
Returns interior integer|nil, err string|nil
Player:walking_style
Returns style integer|nil, err string|nil
Player:fighting_style
4 normal, 5 boxing, 6 kung fu, 7 knee-head, 15 grab-kick (the default), 16 elbow.
Returns style integer|nil, err string|nil
Player:team
The player's team (set_team), or nil with no error when it has none.
Returns team Team|nil, err string|nil
Player:is_visible
False while the gamemode hides the player (set_visible). An edit session also hides it without changing this value.
Returns visible boolean|nil, err string|nil
Player:is_headless
True while the player's head is hidden (set_headless).
Returns headless boolean|nil, err string|nil
Player:is_frozen
True while the player's controls are disabled (set_frozen).
Returns frozen boolean|nil, err string|nil
Player:is_nametag_visible
Whether other players see this player's nametag; with viewer, whether that player sees it (a per-viewer setting takes precedence). Range and walls still apply on each client.
Parameters
viewerPlayer|nil
Returns visible boolean|nil, err string|nil
Player:nametag_text
The text the player's nametag shows instead of its name; nil when it shows the name.
Returns text string|nil, err string|nil
Player:nametag_distance
How far from the camera the player's nametag shows, in meters.
Returns distance number|nil, err string|nil
Player:color
The player's color on its nametag and in the player list: the set_color value, otherwise its team's; nil means the theme's color.
Returns
colorinteger|nil— 0xRRGGBB, string|nil err
Player:camera_mode
What the player's camera shows: "own", "fixed" or "spectate".
Returns mode string|nil, err string|nil
Player:spectate_target
The player its camera follows; nil unless it is spectating.
Returns target Player|nil, err string|nil
Player:is_on_fire
True while the player is burning, as reported by its own client (set alight by set_on_fire or by any fire). Client-reported: do not base rewards or kills on it.
Returns on_fire boolean|nil, err string|nil
Player:special_action
The player's special action (set_special_action). It ends on death, on respawn, or when the player's game ends it (dropping the jetpack with the enter key, entering a vehicle).
Returns action SpecialAction|nil, err string|nil
Player:gravity
The gravity of the player's body (set_gravity), in game units; 0.008 is the game's default.
Returns gravity number|nil, err string|nil
Player:drunk_level
How drunk the player is (set_drunk_level), from 0 (sober) to 255.
Returns level integer|nil, err string|nil
PlayerStat
Type: "stamina"|"lung_capacity"
Player:stat
A stat of the player's body (set_stat), 0..1000. An unknown name raises a Lua error.
Parameters
statPlayerStat
Returns value integer|nil, err string|nil
Player:world_bounds
The rectangle the player is confined to (set_world_bounds) as min_x, min_y, max_x, max_y; nil when unbounded.
Returns min_x number|nil, min_y number|nil, max_x number|nil, max_y number|nil
Player:vehicle
The vehicle this player occupies and its seat (0 = driver); nil when on foot.
Returns vehicle Vehicle|nil, seat integer|string|nil
Player:remote_vehicle
The RC vehicle this player drives remotely (dlmp.set_remote_vehicle); nil when there is none.
Returns rc Vehicle|nil, err string|nil
Player:armed
The currently held weapon as {weapon, slot, clip, total}, or nil when unarmed.
Returns weapon table|nil, err string|nil
Player:weapon
The stored inventory entry for a weapon type as {weapon, slot, clip, total}, or nil when the player does not have that type.
Parameters
weaponinteger
Returns weapon table|nil, err string|nil
Player:skills
Stored weapon skills as a table keyed by the 0..10 skill index that set_weapon_skill takes, each value 0..1000. Returns nil, err for a disconnected player.
Returns skills table<integer, integer>|nil, err string|nil
Player:animation
The stored current animation as a table, or nil when none is playing.
Returns animation table|nil, err string|nil
Player:position
The player's world position.
Returns x number, y number, z number
Player:edit_camera
The last reported position and facing of the player's edit-session camera. Client-reported, never authoritative.
Returns x number|nil, y number|nil, z number|nil, front_x number|nil, front_y number|nil, front_z number|nil
Player:send_message
Sends a server message to the player's chat: a string in the theme's text color, or colored runs.
Parameters
messagestring|DlmpMessageRun[]
Returns ok boolean|nil, err string|nil
Player:send_chat
Sends a chat line under the player's name to recipients: a list of players (players who left are skipped; the sender receives it only if listed) or dlmp.root for everyone. The text follows the same rules as player chat: no control or format characters, trimmed, cut to 1024 bytes; if nothing is left, fails with nil, err. Colored runs are not supported.
Parameters
Returns ok boolean|nil, err string|nil
Player:give_weapon
Parameters
weaponintegerammointegerset_current(optional)boolean
Returns ok boolean|nil, err string|nil
Player:set_health
Sets health, up or down (0..200); 0 kills. Fails with nil, err before the player's first frame of a life, while dead, and once the server has counted it dead (health 0, its vehicle blew up with it inside, a stealth kill on it).
Parameters
valuenumber
Returns ok boolean|nil, err string|nil
Player:set_armor
Parameters
valuenumber
Returns ok boolean|nil, err string|nil
Player:add_health
Adds to health up to max, never lowering it; fails in the same cases as Player:set_health.
Parameters
amountnumbermaxnumber
Returns ok boolean|nil, err string|nil
Player:add_armor
Parameters
amountnumbermaxnumber
Returns ok boolean|nil, err string|nil
Player:spawn
Parameters
argsSpawnArgs
Returns ok boolean|nil, err string|nil
Player:set_respawn
Sets where and when the player respawns after this death. The respawn places it in args.interior (0 = outside, the default); its virtual world is unchanged.
Parameters
argsRespawnArgs
Returns ok boolean|nil, err string|nil
Player:set_skin
Parameters
modelintegervariantinteger
Returns ok boolean|nil, err string|nil
Player:set_wanted
Parameters
levelinteger
Returns ok boolean|nil, err string|nil
Player:kick
Disconnects the player and shows it reason (optional, at most 64 bytes); player_disconnect follows with reason "kicked".
Parameters
reason(optional)string
Returns ok boolean|nil, err string|nil
Player:ban
Bans the player's IP address; see dlmp.ban_ip.
Parameters
reason(optional)stringseconds(optional)integer
Returns ok boolean|nil, err string|nil
Player:take_weapon
Parameters
weaponinteger
Returns ok boolean|nil, err string|nil
Player:set_ammo
Parameters
weaponintegerammointegerclip(optional)integer
Returns ok boolean|nil, err string|nil
Player:clear_weapons
Returns ok boolean|nil, err string|nil
Player:set_armed_weapon
Parameters
weaponinteger
Returns ok boolean|nil, err string|nil
Player:set_weapon_skill
Sets one weapon-skill slot. skill is the 0..10 class index, value the 0..1000 level. Stored state (persists across respawns); read it back with skills.
Parameters
skillintegervalueinteger
Returns ok boolean|nil, err string|nil
Player:teleport
Moves the player; args.interior also becomes its interior. Moving to another interior first removes the player from its vehicle.
Parameters
argsTeleportArgs
Returns ok boolean|nil, err string|nil
Player:waypoint
The waypoint on the player's map, as last changed by the player, by the game removing it on arrival, or by set_waypoint.
Returns
xnumber|nilynumber|nil— nil when there is none
Player:set_waypoint
Puts a waypoint on the player's map, replacing the player's own. Does not raise player_waypoint (one the client sent earlier may still arrive).
Parameters
xnumber— -3000..3000ynumber— -3000..3000
Returns ok boolean|nil, err string|nil
Player:clear_waypoint
Removes the waypoint from the player's map. Does not raise player_waypoint.
Returns ok boolean|nil, err string|nil
Player:set_virtual_world
Moves the player to virtual world vw without changing its position. Players see only the players, vehicles and pickups in their own virtual world and interior. A seated player leaves its vehicle first; the vehicle stays in its world.
Parameters
vwinteger
Returns ok boolean|nil, err string|nil
Player:set_time
Parameters
hourintegerminuteinteger
Returns ok boolean|nil, err string|nil
Player:set_weather
Parameters
weatherinteger
Returns ok boolean|nil, err string|nil
Player:set_money
Parameters
amountinteger
Returns ok boolean|nil, err string|nil
Player:give_money
Parameters
deltainteger
Returns ok boolean|nil, err string|nil
Player:apply_animation
Parameters
argsAnimationArgs
Returns ok boolean|nil, err string|nil
Player:clear_animations
Returns ok boolean|nil, err string|nil
Player:set_animation_progress
Parameters
progressnumber
Returns ok boolean|nil, err string|nil
Player:set_animation_speed
Parameters
speednumber
Returns ok boolean|nil, err string|nil
Player:set_walking_style
Parameters
styleinteger
Returns ok boolean|nil, err string|nil
Player:set_fighting_style
Sets the unarmed and brass-knuckle combo set; kept across respawns and skin changes.
Parameters
styleinteger— 4 normal, 5 boxing, 6 kung fu, 7 knee-head, 15 grab-kick, 16 elbow
Returns ok boolean|nil, err string|nil
Player:set_visible
Hides the player from other players or shows it again. Others receive no data about a hidden player: it leaves their stream and their spectating of it ends, though a resource's own blip or label on it remains. The player still sees itself, unless an edit session's free camera is active. Survives death; ends on disconnect. A seated player cannot be hidden, and a hidden player cannot take a seat.
Parameters
visibleboolean
Returns ok boolean|nil, err string|nil
Player:set_headless
Hides or restores the head; kept across skin changes, cleared on respawn.
Parameters
headlessboolean
Returns ok boolean|nil, err string|nil
Player:set_frozen
Disables or restores the player's controls. A frozen player does nothing on its own, on foot or driving; the vehicle it drives is held still (except a train), and the gamemode can still teleport the player and seat it. Kept through death; respawn clears it, so freeze a new life from player_spawn. If set before the first spawn, it applies from that spawn on.
Parameters
frozenboolean
Returns ok boolean|nil, err string|nil
Player:set_nametag_visible
Shows or hides the player's nametag for every viewer without a per-viewer setting. Valid in any life state; kept across respawns and cleared on disconnect, like all nametag state.
Parameters
visibleboolean
Returns ok boolean|nil, err string|nil
Player:set_nametag_visible_for
Shows or hides the player's nametag for one viewer, overriding set_nametag_visible; nil removes the override. Cleared when either player disconnects.
Parameters
viewerPlayervisibleboolean|nil
Returns ok boolean|nil, err string|nil
Player:set_nametag_text
Shows text on the player's nametag instead of its name; nil restores the name. One line; control and format characters are removed; must be under 64 bytes and not empty after removal.
Parameters
textstring|nil
Returns ok boolean|nil, err string|nil
Player:set_nametag_distance
Sets how far from the viewer's camera the player's nametag shows, in meters: above 0, at most 300; defaults to 70.
Parameters
distancenumber
Returns ok boolean|nil, err string|nil
Player:set_color
Sets the player's color on its nametag, in the player list, and in new chat lines and kill feed rows, the same for every viewer; it overrides the team's color. nil reverts to the team's color, or to the theme's without a team. Valid in any life state; kept across respawns, cleared on disconnect. Blips are not affected: pass player:color() to dlmp.create_blip or Blip:set_color to match.
Parameters
colorinteger|nil— 0xRRGGBB
Returns ok boolean|nil, err string|nil
Player:set_name
Renames the player: 3 to 32 characters within 64 bytes of UTF-8, no control or format characters, words separated by a single plain space. The name must not be taken by another player, ignoring case and treating _ as a space. Valid in any life state; lasts until the player disconnects (the next connection joins under its own name). Lines already in chat and the kill feed keep the old name.
Parameters
namestring
Returns ok boolean|nil, err string|nil
Player:set_chat_bubble
Shows a chat bubble with text above the player to other players for time_ms, wrapped onto several lines; a new bubble replaces the previous one. Control and format characters are removed; must be under 256 bytes and not empty after removal. Also shown while the nametag is hidden, with the nametag's range and wall rules applied to its own distance. The player does not see its own bubble.
Parameters
textstringtime_msinteger— 1..3600000colorinteger|nil— 0xRRGGBB; nil uses the theme's text colordistancenumber|nil— meters from the viewer's camera: above 0, at most 300; defaults to 70
Returns ok boolean|nil, err string|nil
Player:clear_chat_bubble
Removes the player's chat bubble before it expires.
Returns ok boolean|nil, err string|nil
Player:set_camera
Fixes the player's camera at a position, looking at a point, moving there from the current view over transition_ms (0 or nil: instantly; at most 60000). While any camera other than its own is active, the player has no control (is_frozen is unchanged), and vehicles, pickups and labels stream around the camera along its path instead of around the body. Kept through death; respawn ends it, so set it for a new life from player_spawn. If set before the first spawn, it applies from that spawn on. Both points must be within 100000 on each axis and at least 0.01 apart.
Parameters
xnumberynumberznumberlook_xnumberlook_ynumberlook_znumbertransition_msinteger|nil
Returns ok boolean|nil, err string|nil
Player:spectate
Makes this player's camera follow another player, on foot and in vehicles; the mouse orbits the target. The target must be spawned and in this player's world; it may die and respawn. When it leaves that world or the server, the camera returns to the player and spectate_lost fires. prev and next name actions from dlmp.register_action; the spectator panel shows their keys. Switching the target on a key press is up to the gamemode, with another spectate.
Parameters
targetPlayeropts{ prev: string|nil, next: string|nil }|nil
Returns ok boolean|nil, err string|nil
Player:reset_camera
Returns the camera to the player and restores its controls, unless set_frozen is in effect.
Returns ok boolean|nil, err string|nil
Player:set_team
Moves the player to a team, or removes it from its team with nil. Valid in any life state; kept across respawns, cleared on disconnect.
Parameters
teamTeam|nil
Returns ok boolean|nil, err string|nil
Player:set_on_fire
Sets a living player on foot on fire, or extinguishes it. The fire burns out on its own and water extinguishes it; its damage has no attacker.
Parameters
on_fireboolean
Returns ok boolean|nil, err string|nil
SpecialAction
"jetpack": flies; "hands_up": stands still with raised hands; "phone": walks with a phone to the ear; "dance1" to "dance4": dances in place in one of four styles, with the direction keys playing moves; "carry": walks with the arms held as if carrying something, without sprinting or jumping.
Type: "none"|"jetpack"|"hands_up"|"phone"|"dance1"|"dance2"|"dance3"|"dance4"|"carry"
Player:set_special_action
Sets a living player's special action, or ends it with "none". An action can start only on foot and replaces a playing animation; the player can drop a jetpack, and death and respawn end any action. An unknown name raises a Lua error. Presentation only: the server does not prevent a player with raised hands, a phone, a dance or the carry pose from moving, sprinting, shooting or ending it.
Parameters
actionSpecialAction
Returns ok boolean|nil, err string|nil
Player:set_velocity
Launches a living player on foot with a velocity in m/s (at most 100 in magnitude): its client applies it to the body once, and the game moves the body from there. An upward component lifts it off the ground.
Parameters
xnumberynumberznumber
Returns ok boolean|nil, err string|nil
Player:set_gravity
Sets the gravity of the player's body in game units, -0.1..0.1: 0.008 (or nil) is the game's default; lower values make it jump higher and fall slower, 0 makes it float, and below 0 pulls it up. Affects only its body: vehicles and other players keep the game's gravity. Everyone sees it fall the same way. Kept through death and respawn.
Parameters
gravitynumber|nil
Returns ok boolean|nil, err string|nil
Player:set_drunk_level
Sets how drunk the player is, from 0 (sober) to 255; only its own client shows the effect. Kept until changed; a respawn resets it to sober.
Parameters
levelinteger
Returns ok boolean|nil, err string|nil
Player:set_stat
Sets a stat of the player's body, 0..1000; both start at full. "stamina": how long it can sprint and swim fast; "lung_capacity": how long it can hold its breath under water. Kept through death and respawn.
Parameters
statPlayerStatvalueinteger
Returns ok boolean|nil, err string|nil
Player:set_world_bounds
Confines the player, and the vehicle it drives, to a rectangle of the world: its client puts it back at the edge, and the server clamps any position it reports to the edge. Kept through death and respawn.
Parameters
min_xnumbermin_ynumbermax_xnumbermax_ynumber
Returns ok boolean|nil, err string|nil
Player:clear_world_bounds
Removes the world bounds, so the player can go anywhere again.
Returns ok boolean|nil, err string|nil