Players

A player is a pid from 0 to GetMaxPlayers() - 1, assigned at the handshake and reused after a disconnect. Functions that read a player who is not connected return nil.

Who is here

Function
`GetPlayers()` → `{pid, ...}`	every connected player, in join order
`GetPlayerCount()`	how many
`GetPlayerName(pid)` → `name \| nil`	`nil` when not connected
`IsPlayerConnected(pid)`	handshake done
`IsPlayerInWorld(pid)`	spawned and replicated — positions and vitals mean something
`GetPlayerPing(pid)`	milliseconds
`GetPlayerIP(pid)`	the address, for bans and logs

Position

Function
`GetPlayerPos(pid)` → `x, y, z \| nil`	metres in the level’s world space
`GetPlayerYaw(pid)` → `degrees`	0 faces +Y, counter-clockwise
`GetPlayerVelocity(pid)` → `vx, vy, vz \| nil`	m/s
`SetPlayerPos(pid, x, y, z [, yaw])`	moves the player’s game client (a teleport); `z < 0` = on the terrain
`GetTerrainHeight(x, y)` → `metres \| nil`	the level’s heightmap (`[validation] heightmap`); `nil` without one or outside it

A mounted player’s position and velocity are the horse’s.

Spawning

Function
`SetSpawnInfo(pid, x, y, z, yaw [, clothingPreset, weaponPreset, appearance])`	where and as what the next spawn happens
`SpawnPlayer(pid)`	spawns (or re-spawns) at the `SetSpawnInfo` point
`GetDefaultSpawn()` → `x, y, z, yaw`	the server’s spawn from `server.toml` `[spawn]`

SetSpawnInfo’s presets are GUIDs from the game’s clothing_preset / weapon_preset tables; "" keeps the server default. appearance is a soul_id from Libs/Tables/rpg/soul*.xml whose face the others see; "" picks one from the server’s pool ([spawn] appearances) by the player’s name.

The usual flow: set the point in OnPlayerRequestSpawn and return true. A mode that returns false there holds the player until it calls SpawnPlayer itself. See Callbacks.

Spawn-point helpers, plain Lua kept by the prelude:

Function
`AddSpawnPoint(x, y, z, yaw [, tag])`	remember a point under a tag
`GetSpawnPoints([tag])`	the list
`GetRandomSpawnPoint([tag])` → `x, y, z, yaw \| nil`	one at random
`ClearSpawnPoints([tag])`

Vitals

The server owns every player’s health, stamina and injuries ([combat] in server.toml): 100 at every spawn, 0 = dead until the respawn.

Function
`GetPlayerHealth(pid)`, `GetPlayerMaxHealth(pid)`
`SetPlayerHealth(pid, health)`	clamped to `0..max`; the client shows it; `0` kills (`OnPlayerDeath` with attacker `-1`)
`IsPlayerDead(pid)`
`GetPlayerStamina(pid)`, `GetPlayerMaxStamina(pid)`, `SetPlayerStamina(pid, stamina)`	swings and hits taken cost it; it regenerates after a pause
`GetPlayerInjuries(pid)` → `{part, ...}`	the injured body parts, `{}` when whole
`IsPlayerInjured(pid [, part])`	any part, or that one
`GetBodyPartName(part)`	`"head"`, `"torso"`, `"arm_left"`, `"arm_right"`, `"leg_left"`, `"leg_right"`
`GetPlayerBleeding(pid)` → `health/s`	`0` = not bleeding; `IsPlayerBleeding(pid)`
`HealPlayer(pid)`	full health and stamina; injuries, bleeding and the server’s buffs gone; the client shows it
`GetPlayerWeapon(pid)` → `name`	the weapon the damage model charges the player’s hits to; `""` bare-handed
`GetPlayerEquipment(pid)` → `{itemClass, ...}`	what the client reports as equipped: armour, clothing, weapons (class GUIDs)

Body parts are BODY_PART_HEAD, BODY_PART_TORSO, BODY_PART_ARM_LEFT, BODY_PART_ARM_RIGHT, BODY_PART_LEG_LEFT, BODY_PART_LEG_RIGHT = 1–6.

Fights

Only a fighting pair’s clients let the game’s lock-on pick each other’s body. The server starts a fight when a swing reaches a body and on /fight <name>; a mode can too.

Function
`StartFight(a, b)` → `bool`	the two fight; `false` when pvp is off or one is not standing. On a running fight it restarts the `[combat] fight_timeout` clock
`EndFight(a, b)` → `bool`	over, as `/peace`, a death or a disconnect end it
`AreFighting(a, b)`
`GetPlayerOpponents(pid)` → `{pid, ...}`

Stats and skills

A core stat ("strength", "agility", "vitality", "speech") or a skill (the game’s names — "marksmanship", "warfare", …) raised to a level 1–30 on the player’s own soul, kept on the record and re-applied at every spawn. The game never lowers a level.

Function
`SetPlayerStat(pid, stat, level)`, `GetPlayerStat(pid, stat)`	`0` = never set
`SetPlayerSkill(pid, skill, level)`, `GetPlayerSkill(pid, skill)`

Leaving

Function
`Kick(pid, reason)`	`OnPlayerDisconnect` follows with `"kicked: <reason>"`
`Ban(pid, reason [, seconds])`	kicks and bans the name and the address — see Bans

Storage

Function
`SetPlayerData(pid, key, value)`, `GetPlayerData(pid, key)`	per-player values, private to the server, cleared on disconnect
`SetSavedData(pid, key, value)`, `GetSavedData(pid, key)`	your own per-name values (strings; `nil` removes), persisted with the player record
`GetSavedPlayer(pid)` → `{visits, playTime, x, y, z, yaw} \| nil`	the server’s record of the name: visits, seconds played, last position (refreshed on disconnect and every minute; `x..yaw` absent until the first visit ended)

Persistence is [persistence] file in server.toml; names are case-insensitive. Values a mode wants every client to read go in the state bags instead.

Accounts and admins

Function
`IsPlayerRegistered(pid)`	the name is claimed (`/register`)
`IsPlayerLoggedIn(pid)`	proved this session (`/login`)
`IsPlayerAdmin(pid)`	a logged-in owner of a name on `[accounts] admins`, or one `SetPlayerAdmin` promoted
`SetPlayerAdmin(pid, on)`	promote or demote for the session
`GetAdminNames()` → `{name, ...}`	the `[accounts] admins` list

Admin status unlocks the server’s built-in admin commands and whatever the mode gates on it. The accounts themselves: Chat commands → Accounts.