Player

Defined in: server/api.d.ts:1439

A connected KCDC player and the body they occupy.

Extends

• BasePlayer

Constructors

Constructor

new Player(id): Player

Defined in: server/api.d.ts:1444

Creates a script wrapper for an existing connected player with this ID; it neither connects nor spawns anyone.

Parameters

id

number

Network entity identifier.

Returns

Player

Inherited from

BasePlayer.constructor

Methods

addBuff()

addBuff(buff): boolean

Defined in: server/api.d.ts:1951

Puts a status effect on this player’s body. The server runs no effects of its own, so this asks their client rather than writing anything, and it lands a moment later – hasBuff right after this call still says false. Watch playerBuffAdded for the moment it is really on.

The ask is not a promise, either: the game refuses an effect that conflicts with one already there, and a second drink folds into the first rather than stacking.

Parameters

buff

string

Buff GUID, or the exact name the game’s own buff tables use. Buffs.find resolves either.

Returns

boolean

True when the instruction went out; false for an unknown buff or a player with no connection to ask.

---

addPerk()

addPerk(perk): boolean

Defined in: server/api.d.ts:1767

Gives this player a perk outright, spending no point and skipping the perk screen’s requirements. It still has to be one the game can add: an owned or blocked perk is turned down by the game itself.

Parameters

perk

string

A perk’s name or GUID.

Returns

boolean

True when the order went out. Throws for an unknown perk.

---

addPerkPoints()

addPerkPoints(track, count): boolean

Defined in: server/api.d.ts:1782

Gives this player unspent perk points in one tree, on top of what their levels earned.

Parameters

track

string

The tree to add to: a track name, or main for the main-level bank.

count

number

How many, from 1 to 65535.

Returns

boolean

True when the order went out.

---

addXp()

addXp(track, xp): boolean

Defined in: server/api.d.ts:1752

Grants XP on one track, through the game’s own path on the player’s client – so their perks’ XP multipliers apply, a level crossed pops the game’s own level-up, and a level grants its perk points. Rates, budgets and caps do not apply: those rule over what a player earns, and this is the server giving.

Parameters

track

string

A track name. Not fencing: the game derives it from the weapon skills.

xp

number

XP, in the game’s own units.

Returns

boolean

True when the order went out. Throws for an unknown track or an xp that is not positive.

---

cancelCombat()

cancelCombat(opponent): boolean

Defined in: server/api.d.ts:1808

Ends melee combat between these two players and retires their pending blows against each other. Other opponents are left alone. A later attack can start combat again. Consent and timeout rules belong to your resource.

Parameters

opponent

Player

The other player. Both sides are cancelled.

Returns

boolean

True when sent; false for disconnected players, the same player, or different virtual worlds.

---

carryItem()

carryItem(item): boolean

Defined in: server/api.d.ts:2050

Has this player carry an item in their arms, the way the game’s own people carry firewood, sacks and baskets: the carrying walk, and the put-down at the end. While it is carried they walk, since the game has no running with a load.

It is an instruction to their client, so the carry lands when that client reports it: playerCarryItem and carriedItem follow. A carry a script ordered is not put to playerCarryingItem. The item never enters their inventory. Put down – with the game’s own key or putDownItem – it falls from their hands and becomes a carryable GroundItem where it lands, which playerPutDownItem hands over and anybody can take up again.

Their hands have to be free – a drawn weapon or a torch makes their game refuse the carry, and nothing is reported.

Parameters

item

string | GroundItem

What to carry. A name from Animations.props() whose hand the game has a carrying walk for – the baskets (basket_full_wood, basket_b_apples, stonebasket, eggbasket, shoppingbasket), firewoodChipsHand, the buckets (waterBucket, milkBucket), and for a man only the sacks (sack, sack_miller), barrel and crate_with_silver – puts a new one straight into their hands. A GroundItem of such a class has them pick that one up off the ground with the game’s own bend-down; it has to be a single item within their reach.

Returns

boolean

True when the order went out; false when they cannot act, are riding, already carry an item or a body, the stack is not resting within their reach or somebody else is taking it, or they have no connection. Throws for an item with no carrying walk, or none for this player’s body.

---

clearBuffs()

clearBuffs(tag): boolean

Defined in: server/api.d.ts:1965

Clears every effect in one of the game’s own families at once: one call for all poisons, or all bleeding, without naming them. Buffs.tags lists the families. Note that World.setTime does not fast-forward effects – their time runs off each client’s frame delta and never reads the calendar – so a scripted sleep has to clear what it means to end.

Parameters

tag

string

An effect family, from Buffs.tags – poison, bleed, alcohol_drunk, unconscious.

Returns

boolean

True when the instruction went out; false for a tag no buff table uses or a player with no connection to ask.

---

dismount()

dismount(): Horse | null

Defined in: server/api.d.ts:2033

Takes this player out of whatever saddle they are in: their own client gets them off, and horseDismount is raised.

Returns

Horse | null

The horse they were taken off, or null when they were not riding one.

---

dropInventory()

dropInventory(options?): Stash | null

Defined in: server/api.d.ts:1929

Moves this player’s items into a container spawned at their body, as a death drop: playerInventoryChanged (reason drop) and stashInventoryChanged follow, then the container is anyone’s to open. At most 128 rows go. What happens to it next – who may loot it, when it goes – is the script’s.

Parameters

options?

keepEquipped keeps the units their body wears or holds.

keepEquipped?

boolean

Returns

Stash | null

The container, or null when there was nothing to drop or the player has no inventory.

---

emit()

emit(eventName, payloadJson?): void

Defined in: server/api.d.ts:8939

Emits a named script event to this player’s client connection.

Parameters

eventName

string

Client event name.

payloadJson?

string

Optional JSON payload forwarded verbatim to the owning client.

Returns

void

Inherited from

BasePlayer.emit

---

getDerivedStat()

getDerivedStat(stat): number

Defined in: server/api.d.ts:1730

Reads a computed stat from the latest body snapshot. Bleeding, Sleeping, Consciousness, Drunkenness and Poisoning follow the body as it changes; the others are sampled about every 250 ms to a hundredth of a native unit, then replicated. Values use native units and can be negative; they are not universally percentages. Returns zero without a valid snapshot. Throws for an unknown stat or invalid arguments. These readings do not override another player’s native calculations.

Parameters

stat

"bleeding" | "sleeping" | "consciousness" | "drunkenness" | "poisoning" | "charisma" | "visibility" | "conspicuousness" | "noise" | "dirtiness" | "bloodiness" | "smell" | "smellIntensity" | "fragrance" | "carriedWeight" | "inventoryCapacity" | "encumbrance" | "hangover" | "alcoholism" | "armorRating" | "overallArmorDefense" | "overallWeaponAttack" | "normalizedRunSpeed" | "runSpeedBase" | "morale"

A DerivedPlayerStat value.

Returns

number

---

getInventory()

getInventory(): InventoryState | null

Defined in: server/api.d.ts:1942

Reads this player’s inventory; the same as Inventory.get(player).

Returns

InventoryState | null

A copy of it, or null for a player who is not connected.

---

getIP()

getIP(): string

Defined in: server/api.d.ts:8945

Returns this player’s current remote network address.

Returns

string

Address string, or an empty string when the player or peer is unavailable.

Inherited from

BasePlayer.getIP

---

getNametagColor()

getNametagColor(): number

Defined in: server/api.d.ts:8926

Reads this player’s nametag color.

Returns

number

Packed 0xAARRGGBB color; opaque white when untinted.

Inherited from

BasePlayer.getNametagColor

---

getNametagText()

getNametagText(): string

Defined in: server/api.d.ts:8920

Reads this player’s nametag text override.

Returns

string

The override, or an empty string when the player’s own name is drawn.

Inherited from

BasePlayer.getNametagText

---

getStat()

getStat(stat): number

Defined in: server/api.d.ts:1724

Reads the latest reported stat in native units. Returns zero when no valid body snapshot exists; check player.ready to distinguish that from a real zero. Throws for an unknown stat or invalid arguments.

Parameters

stat

"health" | "stamina" | "exhaust" | "hunger"

A PlayerStat value.

Returns

number

---

getTrack()

getTrack(track): TrackProgress | null

Defined in: server/api.d.ts:1737

Where this player stands on one track: level, XP towards the next one, and unspent perk points.

Parameters

track

string

A track name, from Progression.tracks().

Returns

TrackProgress | null

The progress, or null before their client’s first report. Throws for a track name the tables do not carry.

---

giveItem()

giveItem(item, amount?): boolean

Defined in: server/api.d.ts:1914

Grants items into this player’s inventory, which the server holds; their game shows them on the next tick and announces them with its own “You received” toast. Inventory.add does the same, can set the items’ properties, and can leave out the toast.

Parameters

item

string

Item class GUID, or the exact name the game’s own item tables use.

amount?

number

How many to grant; defaults to 1, and at most 10000.

Returns

boolean

True when the items were added; false for an unknown item, an amount outside 1..10000, or a player with no inventory.

---

hasBuff()

hasBuff(buff): boolean

Defined in: server/api.d.ts:1972

Whether this player’s last report carried that status effect.

Parameters

buff

string

Buff GUID, or the exact name the game’s own buff tables use.

Returns

boolean

True when it did; false for an unknown buff, or a player who has reported nothing yet.

---

hasPerk()

hasPerk(perk): boolean

Defined in: server/api.d.ts:1744

Whether this player owns a perk.

Parameters

perk

string

A perk’s name or GUID.

Returns

boolean

True when their last report carried it.

---

heal()

heal(options?): boolean

Defined in: server/api.d.ts:2003

Nurses this player back, on their own client and with the game’s own recipe – the one its quests use for a full heal: the remove_injuries and remove_all_posions cures, which each wipe their whole kind of effect as they land, then health raised through the soul’s own setter, the way a potion raises it. What comes off raises playerInjuryHealed and playerBuffRemoved as usual.

It does not revive anybody: a dead player stays dead until revive.

Parameters

options?

What to restore; everything when left out. health: true or absent for all of it, a number to raise it to that much (never lowers it), false to leave it. injuries: clear every limb injury, and with it the bleeding a badly hurt limb causes. poisons: clear every poison. bleeding: clear the standalone bleeding effect.

bleeding?

boolean

health?

number | boolean

injuries?

boolean

poisons?

boolean

Returns

boolean

True when the orders went out; false for a player with no connection to ask. Throws for a health that is not a finite, non-negative number.

---

isNametagHealthVisible()

isNametagHealthVisible(): boolean

Defined in: server/api.d.ts:8914

Checks whether the health bar under this player’s nametag is shown.

Returns

boolean

True unless the health bar was hidden; false also when this game has no nametags.

Inherited from

BasePlayer.isNametagHealthVisible

---

isNametagVisible()

isNametagVisible(): boolean

Defined in: server/api.d.ts:8908

Checks whether this player’s nametag is shown to other players.

Returns

boolean

True unless the nametag was hidden; false also when this game has no nametags.

Inherited from

BasePlayer.isNametagVisible

---

kick()

kick(reason?): void

Defined in: server/api.d.ts:8932

Disconnects this player from the server.

Parameters

reason?

string

Optional reason shown to the disconnected player; omitting it uses the generic kicked reason.

Returns

void

Inherited from

BasePlayer.kick

---

mount()

mount(horse, options?): boolean

Defined in: server/api.d.ts:2065

Puts this player in a horse’s saddle. Everyone near enough to watch sees it the way it was asked for – the get-on, or the instant seat – while a client that only streams the rider in later finds them already seated. It is an instruction to their client, so the seat is reported back like any other mount: horseMounting can still refuse it, and horseMount and player.horse follow once it lands. The player has to be standing near the horse; teleport them beside it first.

Parameters

horse

Horse

The horse to get on.

options?

instant puts them straight into the seat, as the game’s own forced mount does; by default they play the get-on a player plays at a horse.

instant?

boolean

Returns

boolean

True when the order went out; false when the horse is dead or somebody else is riding it, or the player has no connection.

---

playAnimation()

playAnimation(fragment, options?): boolean

Defined in: server/api.d.ts:1842

Makes this player’s body play one of the game’s animations, on their own screen and on everybody else’s – a wave, a bow, a woodcutter’s swing with the axe in hand. It is state rather than a one-off: a player who streams in or joins while it plays sees it too, and it lasts until stopAnimation or the next playAnimation, even after a one-shot has finished.

A new playAnimation, stopAnimation and teleport cut a running animation at once rather than waiting for it to finish. The game can cut it short too: a hit, a fall or drawing a weapon ends it, and so can the player walking off from one that leaves the legs free. loop starts it again when that happens, and keeps a one-shot going pass after pass with no gap between them.

playerAnimationEnd fires once when the animation this request started is over, and says how. A loop ends only by being stopped or replaced.

A hand tag is only half of holding something. r_bucket makes the body move as if it carried a bucket, but the bucket itself is a props entry.

Parameters

fragment

string

A Mannequin fragment, as Animations.list names it. "" plays none and only puts the props and tags on, which with a hand tag like r_bucket makes the player carry something while they walk.

options?

clip plays a clip the server streams instead of a fragment (animations/kcdc/<resource>/wave.caf, the fragment left ""), tags pick the variant, loop repeats it until stopped, lockMovement holds the player still, props puts up to two models in their hands.

clip?

string

lockMovement?

boolean

loop?

boolean

props?

{ hand?: "right" | "left"; item?: string; joint?: string; model?: string; position?: Vector3 | Partial<Vector3>; rotation?: Vector3 | Partial<Vector3> | Quaternion; } | object[]

tags?

string

Returns

boolean

True when the request went out; false for a player with no body yet. Throws for a prop or option it cannot use.

---

putDown()

putDown(): boolean

Defined in: server/api.d.ts:2039

Has this player put down the body on their shoulder, with the game’s own put-down. It is an instruction to their client, so the carry ends when that put-down lands: playerPutDown follows then, and carrying reads null from that moment.

Returns

boolean

True when the order went out; false when they carry nobody or have no connection.

---

putDownItem()

putDownItem(options?): boolean

Defined in: server/api.d.ts:2057

Has this player put down the item in their arms, with the game’s own put-down. It is an instruction to their client, so the carry ends when that put-down lands: playerPutDownItem follows then.

Parameters

options?

immediate lets go at once, without the put-down.

immediate?

boolean

Returns

boolean

True when the order went out; false when they carry no item or have no connection.

---

removeBuff()

removeBuff(buff): boolean

Defined in: server/api.d.ts:1958

Asks this player’s own client to take a status effect off: the exact instance when a report named one, and every instance of that definition otherwise.

Parameters

buff

string

Buff GUID, or the exact name the game’s own buff tables use.

Returns

boolean

True when the instruction went out; false for an unknown buff or a player with no connection to ask.

---

removePerk()

removePerk(perk): boolean

Defined in: server/api.d.ts:1774

Takes a perk away. The point it cost is not refunded; respecPerks is the way to hand points back.

Parameters

perk

string

A perk’s name or GUID.

Returns

boolean

True when the order went out. Throws for an unknown perk.

---

respecPerks()

respecPerks(): boolean

Defined in: server/api.d.ts:1788

The game’s own respec: every perk learnt on the perk screen is taken away and every tree’s points are rebuilt from the player’s current levels. Perks the game granted on its own stay.

Returns

boolean

True when the order went out.

---

restoreProgression()

restoreProgression(snapshot): boolean

Defined in: server/api.d.ts:1795

Puts a stored progression back: levels, XP, perks and unspent points, through the game’s own paths. Only ever raises – a track already past the snapshot keeps its level – so call it as the player arrives, from playerReady, on the fresh character every session starts with.

Parameters

snapshot

ProgressionSnapshot

What player.progression returned, as the resource stored it.

Returns

boolean

True when every order went out.

---

revive()

revive(): boolean

Defined in: server/api.d.ts:1801

Requests revival of this player after playerDied.

Returns

boolean

True when sent; false when disconnected, no death was reported, or revival was already requested.

---

setAppearance()

setAppearance(appearance): boolean

Defined in: server/api.d.ts:1886

Asks this player’s own client to wear a different body – face, hair, beard and skin. The owning client is authoritative for its body, so this is a request that lands on their next frame rather than a write; read player.appearance back to see what they actually put on.

Gender is applied before the parts, because it decides which half of the game’s catalog the names come from – and it is the one part of this with a price. A soul’s gender lives on its archetype, so changing it moves the player to the game’s own counterpart archetype, which also carries four authored numbers: base armour, the conspicuousness and visibility pair, and unarmed attack. Nothing reads those on the puppets other people see, but on the body its owner plays they are a real change. Ask for a gender only when you mean it; a male-to-male change never touches the archetype.

Everyone starts as Henry, so a server that wants people to tell each other apart has to call this.

Face and beard travel together whether or not both are named. Beards are modelled per face, so changing either into a pair that was never modelled is refused whole rather than applied without the beard; Appearances.beards says which pairs are real.

Parameters

appearance

Partial<Appearance>

The parts to change. Anything left out keeps what the player is wearing, and an empty string hands that part back to the game. Names come from Appearances.options, except the beard, which comes from Appearances.beards.

Returns

boolean

True when the request went out; false for a name that is not in the catalog, a gender it does not belong to, a beard that face cannot wear, or a player with no connection to ask.

---

setDisguise()

setDisguise(model): boolean

Defined in: server/api.d.ts:2016

Draws this player as a static mesh instead of themselves – a barrel, a haystack, a cart wheel – on their own screen and on everybody else’s. It is state: a player who streams in or joins sees it too, and it lasts until the next call.

Only the look and the collision change. The body is hidden rather than replaced, and its collision cylinder is resized around the mesh, so the player walks and is traced against in roughly the mesh’s shape – a client’s World.raycast with mode: "anything" finds them where the mesh is drawn, and says which player it found. The mesh turns with the body. They keep everything else a person has: they can still be hurt, bleed and die, and nothing stops them drawing a weapon, which a gamemode that does not want that has to take away.

The game’s own camera sits in the head, which the mesh now covers: pair this with the client’s Camera.setThirdPerson for the disguised player. Nametags are not touched; setNametagVisible is the call for that. NPCs still see a person.

The owning client is authoritative for its body, so this is a request that lands on their next frame; player.disguise reads what they actually have on.

Parameters

model

string | null

A mesh from the prop catalog, by its objects/...cgf path or its file stem, or one this server streams by its full path – anything Prop.spawn takes. Null puts the player back in their own body.

Returns

boolean

True when the request went out; false for a player with no connection to ask. Throws for a model the catalog does not carry.

---

setFacialExpression()

setFacialExpression(fragment, options?): boolean

Defined in: server/api.d.ts:1863

Sets this player’s facial expression, on their own screen and on everybody else’s, alongside whatever their body plays. It is state: a player who streams in sees it, and it lasts until the next call.

The expression is the eyes, brows and mood. It never moves the mouth – the game’s own FE_DialogueSpeaking animates only the eyes and leaves the mouth to the voice line being spoken. setTalking is the mouth.

A mood tag is one of the body’s own tags, so it can change the mood of the body’s idle too, for as long as the expression holds.

Parameters

fragment

string

A fragment on the face’s own scope: FE_Default, FE_DialogueIdle or FE_DialogueSpeaking for a held mood, or an ADLG_FA_* gesture (ADLG_FA_Smile, ADLG_FA_Wink, ADLG_FA_Laugh, ADLG_FA_Surprise…) that plays once. "" hands the face back to the game.

options?

tags pick the variant: for the FE_* fragments the mood, happy, angry, sad, nervous, pensive, arogant or drunk, as Animations.list("FE_") spells them.

tags?

string

Returns

boolean

True when the request went out; false for a player with no body yet. Throws for an argument it cannot use.

---

setHealth()

setHealth(value): boolean

Defined in: server/api.d.ts:1987

Sets this living player’s health, raising or lowering it. Lowering raises playerDamage with a null attacker and the amount removed; a fatal change also raises playerDied with a null killer. This includes restoring a lower saved value. Zero can kill; this never revives a dead player. Leaves injuries, poison and bleeding in place. Call after playerSpawned or playerReady when restoring a saved value. The client applies the request asynchronously; health continues to show its last report until a new one arrives.

Parameters

value

number

Health in the same units as player.health. Clamped to maxHealth on the player’s client.

Returns

boolean

True when sent; false when the body is missing, not ready or dead. Throws unless value is a finite number from 0 to 1000000, with positive health greater than 0.00001 after conversion to native float units. A request for a life that has since ended is ignored.

---

setHunger()

setHunger(value): boolean

Defined in: server/api.d.ts:1994

Sets this living player’s nourishment, raising or lowering it. Call after playerSpawned or playerReady when restoring a saved value. The client applies the request asynchronously; hunger continues to show its last report until a new one arrives.

Parameters

value

number

Nourishment in the same units as player.hunger. Higher means better fed. Clamped to maxHunger on the player’s client.

Returns

boolean

True when sent; false when the body is missing, not ready or dead. Throws unless value is a finite number from 0 to 1000000 that does not round from positive to zero in native float units. A request for a life that has since ended is ignored.

---

setLevel()

setLevel(track, level): boolean

Defined in: server/api.d.ts:1760

Raises one track to a level, as the game’s own AdvanceToSkillLevel does: exactly the XP between the two levels, with the level-ups and perk points on the way. The game has no way to lower a level, so asking for one below the current level throws.

Parameters

track

string

A track name. Not fencing.

level

number

The level to raise it to, at most the game’s cap of 30.

Returns

boolean

True when the order went out; false for a level past the cap.

---

setMovementMode()

setMovementMode(mode): boolean

Defined in: server/api.d.ts:1906

Puts a pace rule on this player. walkByDefault makes walking the pace they keep coming back to and leaves their own key working; walkEnforced forbids running and sprinting outright, and their key stops mattering.

The two are different things and both are worth having: a default is a preference, an enforcement is a rule. Nothing about either goes out to anybody else – the pace every other player draws comes from this body’s own published animation tags, so a walking player already looks like one everywhere.

A default holds across sprints. The game itself ends every sprint in a jog, deliberately, so the client puts the walk back once the sprint is over rather than during it, and a player who chose to jog keeps jogging: only the pace the sprint took is given back. On a gamepad the stick’s own deflection decides the pace, which the rule neither reads nor overrides.

Enforcement holds the engine’s own run and sprint permissions, the same pair the game clears while somebody carries a body, and hands back what it found when the rule is lifted. Sprinting cannot shake it off.

Parameters

mode

Partial<MovementMode>

The whole rule. A key left out is off, because the server keeps no copy of what this player is currently under.

Returns

boolean

True when the rule went out; false for a player with no connection to ask.

---

setNametagColor()

setNametagColor(color): void

Defined in: server/api.d.ts:8969

Tints the text on this player’s nametag.

Parameters

color

number

Packed 0xAARRGGBB color.

Returns

void

Inherited from

BasePlayer.setNametagColor

---

setNametagHealthVisible()

setNametagHealthVisible(visible): void

Defined in: server/api.d.ts:8957

Shows or hides the health bar under this player’s nametag, leaving the name itself alone.

Parameters

visible

boolean

True to show the health bar under this player’s name, false to hide it.

Returns

void

Inherited from

BasePlayer.setNametagHealthVisible

---

setNametagText()

setNametagText(text?): void

Defined in: server/api.d.ts:8963

Overrides the text drawn on this player’s nametag.

Parameters

text?

string

Text to show instead of the player’s name, cut to 64 bytes; empty or omitted restores the name.

Returns

void

Inherited from

BasePlayer.setNametagText

---

setNametagVisible()

setNametagVisible(visible): void

Defined in: server/api.d.ts:8951

Shows or hides the name over this player’s head for every other player. The health bar has its own switch, and each player can still hide all nametags locally.

Parameters

visible

boolean

True to show this player’s nametag to everyone, false to hide it.

Returns

void

Inherited from

BasePlayer.setNametagVisible

---

setOutfit()

setOutfit(preset): boolean

Defined in: server/api.d.ts:1936

Dresses this player in one of the game’s own outfits. Every piece of clothing they wear comes off and stays in their inventory, and a new set of the outfit’s clothes is added and worn; weapons and everything else are left as they are. Their game dresses them a moment later, as it does after Inventory.set.

Parameters

preset

string

One of the game’s own outfits for this player’s gender, by a name from Player.outfitPresets(player.appearance.gender) or its GUID.

Returns

boolean

True when the inventory was changed; false for a preset that is not in the catalog or is the other gender’s, a player with no inventory, or an inventory with no room.

---

setStat()

setStat(stat, value): boolean

Defined in: server/api.d.ts:1980

Sets health, stamina, energy or nourishment on the living body. Call once player.ready is true. Lowering health raises playerDamage with a null attacker; a fatal change also raises playerDied with a null killer. Zero health can kill. Does not clear buffs or revive; normal regeneration and consumption continue.

Parameters

stat

"health" | "stamina" | "exhaust" | "hunger"

Writable PlayerStat; derived stats are rejected.

value

number

Finite native value from 0 to 1000000, clamped to the native maximum. Positive health must exceed 0.00001; positive values must not underflow to zero.

Returns

boolean

True when sent, not confirmation of application; false for a missing, unready or dead body. Throws for invalid arguments or a read-only stat. Requests for a previous life are discarded. Read getStat after the client’s next report to observe the result.

---

setTalking()

setTalking(talking, style?): boolean

Defined in: server/api.d.ts:1873

Moves this player’s mouth as if they were talking, on their own screen and on everybody else’s, until told to stop – for text chat, voice chat or a scene. It is a looping talk animation, not lip-sync: it follows no words.

The game’s own lip-sync wins while it plays a voice line on the same body, and the loop comes back after it.

Parameters

talking

boolean

Whether the mouth moves.

style?

"neutral" | "happy" | "drunk" | "chew"

How: neutral (the default), happy, drunk or chew.

Returns

boolean

True when the request went out; false for a player with no body yet. Throws for a style it does not know.

---

setVirtualWorld()

setVirtualWorld(world): void

Defined in: server/api.d.ts:8797

Moves this entity into another virtual world.

Parameters

world

number

Virtual-world identifier used to partition replication and visibility.

Returns

void

Inherited from

BasePlayer.setVirtualWorld

---

setVisible()

setVisible(visible): boolean

Defined in: server/api.d.ts:2027

Stops drawing this player’s body, or draws it again – on their own screen and on everybody else’s. The body goes with everything on it: what it wears, the weapons on its back and belt, and whatever it is holding. It is state, like a disguise: somebody who streams in or joins sees nothing of a hidden player either, and it lasts until the next call or until they leave.

Nothing but the drawing changes. They stand where they stood, keep their collider, their soul and their weapons, so a hidden player still blocks a doorway, can still be hit and traced against, still fights and still dies – and the NPCs around them never stopped seeing a person. Nametags are separate; setNametagVisible is the call for that.

Their own camera sits in their head, so a hidden player simply sees no arms in first person. The owning client is authoritative for its body, so this is a request that lands on their next frame; player.visible reads what they actually have.

Parameters

visible

boolean

False to stop drawing this player’s body, true to draw it again.

Returns

boolean

True when the request went out; false for a player with no connection to ask. Throws unless visible is a boolean.

---

setVisibleTo()

setVisibleTo(player): void

Defined in: server/api.d.ts:8803

Restricts replication of this entity to one owning connection while preserving normal range and visibility checks.

Parameters

player

Entity | null

Player-owned entity whose connection should exclusively receive this entity, or null to clear the restriction.

Returns

void

Inherited from

BasePlayer.setVisibleTo

---

setWorldBuilderEnabled()

setWorldBuilderEnabled(enabled): boolean

Defined in: server/api.d.ts:1893

Grants or revokes World Builder access for this player. Multiplayer connections start without access. Enabling allows F7 and the client MapEditor.open API; disabling also closes an open editor. The permission lasts until changed or disconnected and does not affect other players. Offline editing is always allowed.

Parameters

enabled

boolean

Whether this player may open World Builder.

Returns

boolean

True when the permission was sent; false for a player with no connection. Throws unless enabled is a boolean.

---

spawn()

spawn(position, rotation?): boolean

Defined in: server/api.d.ts:1820

Puts this player somewhere, as a spawn rather than as a teleport: their client holds the body still until there is real ground under it, so it cannot fall through a world that has not streamed in yet.

Called from a playerSpawning handler this is the answer to that request – the player is still behind their loading screen, and nothing is seen. Called at any other time it moves a player who is already in the world, which is visible.

Nothing else names a spawn: with no handler calling this, everybody arrives at the level’s own start point, because every client asks the game for the identical map start.

Parameters

position

Vector3 | Partial<Vector3>

Where the body goes; a Vector3 or any object carrying x, y and z.

rotation?

Vector3 | Quaternion

Which way they face: a Quaternion, or a Vector3 of Euler degrees.

Returns

boolean

True when the placement was accepted; false for a position that is not somewhere in the world, or a player with no connection to ask.

---

stopAnimation()

stopAnimation(options?): boolean

Defined in: server/api.d.ts:1851

Ends what playAnimation started at once, takes its props away and hands the body back to the game. A stance tag the animation set goes with it, so without standUp a seated player pops upright.

The stand-up is an animation of its own: it raises its own playerAnimationEnd, fragment StandUp or GetUp, once the player is on their feet, and a playAnimation during it replaces it.

Parameters

options?

standUp plays the game’s own way back to standing when the animation held the body in a sitting or lying stance tag (sittingNoTable, lyingGround): StandUp or GetUp, in the variant that fits that stance. Without it, or for a stance the game authors no way out of (beggarKneel), the body goes straight back to standing.

standUp?

boolean

Returns

boolean

True when the request went out; false for a player with no body yet.

---

takeItem()

takeItem(item, amount?): Promise<{ ok: boolean; reason: string; removed: number; requested: number; }>

Defined in: server/api.d.ts:1922

Takes items of a class out of this player’s inventory, across its rows, all of them or none. The server holds the inventory, so the promise is already settled when it is returned; it stays a promise so existing scripts keep working. Their game announces the loss with its own toast; Inventory.remove can leave it out. To move items between players use Inventory.transfer, which cannot lose them half way.

Parameters

item

string

Item class GUID, or the exact name the game’s own item tables use. The same spelling giveItem takes.

amount?

number

How many units to take; defaults to 1, and at most 10000. Zero is refused rather than read as “all of them”.

Returns

Promise<{ ok: boolean; reason: string; removed: number; requested: number; }>

An object carrying removed (the amount when it happened, otherwise 0), requested, ok, and reason (empty on success, otherwise the inventory code, such as insufficientItems).

---

teleport()

teleport(position, label?): boolean

Defined in: server/api.d.ts:1828

Asks this player’s own client to put them somewhere else. The owning client is authoritative for its body’s pose, so this is a request that lands on their next frame rather than a write.

Parameters

position

Vector3 | Partial<Vector3>

World-space destination; a Vector3 or any object carrying x, y and z.

label?

string

Optional name for the destination, echoed back in the client’s own teleport panel. Display only.

Returns

boolean

True when the request went out; false when the position is not finite or the player has no connection to ask.

---

toString()

toString(): string

Defined in: server/api.d.ts:1718

Formats this player handle for logging and debugging.

Returns

string

The player’s network entity ID and nickname.

Inherited from

BasePlayer.toString

---

all()

static all(): Player[]

Defined in: server/api.d.ts:2078

Lists every player currently connected, including those whose body has no pose yet.

Returns

Player[]

One handle per connected player, in no particular order.

---

getById()

static getById(id): Player | null

Defined in: server/api.d.ts:2085

Looks a player up by their network entity ID.

Parameters

id

number

Network entity identifier.

Returns

Player | null

The player’s handle, or null when no connected player has that ID.

---

outfitPresets()

static outfitPresets(gender?): string[]

Defined in: server/api.d.ts:2072

The game’s own outfits, from its clothing presets: what player.setOutfit and Npc.setOutfit dress a body in. Many belong to one named character.

Parameters

gender?

"male" | "female"

Only the outfits authored for this gender. The game will not put a man’s clothes on a woman or the reverse, so player.setOutfit takes only the presets of the player’s own appearance.gender.

Returns

string[]

Preset names, men’s first, each gender’s in name order.

Properties

agility

readonly agility: number

Defined in: server/api.d.ts:1571

Agility, in the game’s own units.

---

alive

readonly alive: boolean

Defined in: server/api.d.ts:1481

Whether this player has health left. False also while no soul has been published.

---

appearance

readonly appearance: Appearance

Defined in: server/api.d.ts:1461

What this player’s body looks like, as their own client last published it. Every part is empty until something chooses one, which is the default body – and why everyone looks the same until a resource says otherwise.

Read back rather than assumed after setAppearance: the owning client is authoritative for its own body, so a new look appears here once they have actually put it on.

---

bleeding

readonly bleeding: number

Defined in: server/api.d.ts:1541

How heavily the body is bleeding; 0 when it is not.

---

buffs

readonly buffs: BuffState[]

Defined in: server/api.d.ts:1705

The status effects on this player’s body, as their own client last reported them: potions, poison, injury, drunkenness, illness, unconsciousness, and anything this server added. Perks and equipment effects are not in here – they follow state that already replicates.

This is the list of named effects. For how drunk, poisoned, hurt or tired someone actually is, read drunkenness, poisoning, bleeding, consciousness, hunger and exhaust instead: those are live numbers and need no name to look up.

Empty until the player’s client sends its first report, shortly after they connect; playerBuffAdded fires for whatever it was already carrying.

---

canAct

readonly canAct: boolean

Defined in: server/api.d.ts:1486

Whether the body can be driven at all: alive, conscious and not asleep.

---

carriedBy

readonly carriedBy: Player | null

Defined in: server/api.d.ts:1681

The player carrying this one’s body, or null.

---

carriedItem

readonly carriedItem: string | null

Defined in: server/api.d.ts:1686

The item this player carries in their arms, by its item name, or null. Set once playerCarryItem has fired, cleared once playerPutDownItem has.

---

carrying

readonly carrying: Player | null

Defined in: server/api.d.ts:1676

The player whose body this one carries on their shoulder, or null. Set once playerCarry has fired, cleared once playerPutDown has.

---

combatZone

readonly combatZone: number

Defined in: server/api.d.ts:1631

Which direction of the combat star this player is aiming at, as a row of the game’s zone table, or -1 when they are aiming at none.

---

consciousness

readonly consciousness: number

Defined in: server/api.d.ts:1551

How conscious the body is; 0 is knocked out.

---

crouched

readonly crouched: boolean

Defined in: server/api.d.ts:1611

Whether this player is crouched, as their own game’s crouch action reports it. False once their body is gone.

---

discordId

readonly discordId: string

Defined in: server/api.d.ts:8881

Authenticated Discord identifier, or an empty string when unavailable.

Inherited from

BasePlayer.discordId

---

disguise

readonly disguise: string | null

Defined in: server/api.d.ts:1466

The prop-catalog mesh this player’s body is drawn as, by its objects/...cgf path, or null while they look like themselves. Published by their own client, so it follows setDisguise once they have actually put it on.

---

dog

readonly dog: Dog | null

Defined in: server/api.d.ts:1696

The dog companion this player has, or null when they have none. One dog per player, as in the game.

---

drunkenness

readonly drunkenness: number

Defined in: server/api.d.ts:1556

How drunk the body is; 0 is sober.

---

equipment

readonly equipment: string[]

Defined in: server/api.d.ts:1646

Item classes this player is wearing, each as 32 hex digits. What they actually have on rather than a preset, so a bare body reads as an empty array.

---

exhaust

readonly exhaust: number

Defined in: server/api.d.ts:1521

Current energy reserve, in the game’s own units. Higher means better rested.

---

fistsUp

readonly fistsUp: boolean

Defined in: server/api.d.ts:1621

Whether this player has their fists – or their weapon – up. Stays true after the arm comes down, which is how the engine holds it.

---

guard

readonly guard: number

Defined in: server/api.d.ts:1626

The arm guard in the engine’s own levels: 0 arms down, 1 the guard a player holds.

---

hardwareId

readonly hardwareId: string

Defined in: server/api.d.ts:8886

Framework hardware identifier, or an empty string when unavailable.

Inherited from

BasePlayer.hardwareId

---

health

readonly health: number

Defined in: server/api.d.ts:1496

Current health, in the game’s own units. 0 while no soul has been published.

---

healthPercent

readonly healthPercent: number

Defined in: server/api.d.ts:1491

Health as a percentage from 0 to 100 – what the nametag bar draws. Derived from the pair behind it, so it survives a maximum that changes.

---

healthyStamina

readonly healthyStamina: number

Defined in: server/api.d.ts:1516

The stamina ceiling the body’s injuries currently allow, which is at or below maxStamina.

---

horse

readonly horse: Horse | null

Defined in: server/api.d.ts:1691

The horse this player is riding, or null when they are on foot.

---

hunger

readonly hunger: number

Defined in: server/api.d.ts:1531

Current nourishment, in the game’s own units.

---

id

readonly id: number

Defined in: server/api.d.ts:8765

Immutable network entity identifier.

Inherited from

BasePlayer.id

---

inAir

readonly inAir: boolean

Defined in: server/api.d.ts:1606

Whether the body is off the ground – fallen or mid-jump – as its own physics reports it, debounced past the flicker a stair step causes.

---

injuries

readonly injuries: Injuries

Defined in: server/api.d.ts:1712

Which limbs are injured, as the player’s own client last reported them – the same report buffs reads, named by limb so nobody has to know the six buff names. All false until the first report arrives. playerInjured and playerInjuryHealed fire as a flag changes.

What an injury does is the game’s own: a hurt head, torso or arm weakens its stats, a hurt leg takes away running and sprinting, and a badly hurt limb bleeds. Everybody else sees the consequences rather than the injury: the owner’s slower pace, the lower stamina ceiling, bleeding, and the hurt gait the game plays once health is low. The game has no leg-specific limp animation, so there is nothing more to show.

---

ip

readonly ip: string

Defined in: server/api.d.ts:8896

Current remote network address, or an empty string when unavailable.

Inherited from

BasePlayer.ip

---

leftHandItem

readonly leftHandItem: string

Defined in: server/api.d.ts:1641

Item class drawn in the left hand as 32 hex digits, or an empty string when the hand is empty.

---

level

readonly level: number

Defined in: server/api.d.ts:1651

The player’s main level, the one the game derives from the stats, as their client last reported it. 0 until the first report.

---

levels

readonly levels: TrackLevels

Defined in: server/api.d.ts:1656

The level of every skill and stat, keyed by track name, as this server last accepted it. All zero until the first report.

---

lookDirection

readonly lookDirection: Vector3

Defined in: server/api.d.ts:1601

World-space direction the head and eyes are turned towards. Zero while the body has reported none.

---

maxExhaust

readonly maxExhaust: number

Defined in: server/api.d.ts:1526

Maximum energy reserve, in the game’s own units.

---

maxHealth

readonly maxHealth: number

Defined in: server/api.d.ts:1501

Health capacity, in the game’s own units.

---

maxHunger

readonly maxHunger: number

Defined in: server/api.d.ts:1536

Nourishment capacity, in the game’s own units.

---

maxStamina

readonly maxStamina: number

Defined in: server/api.d.ts:1511

Stamina capacity, in the game’s own units. Collapses to 0 for a tick around death, which is real rather than a bad read.

---

mounted

readonly mounted: boolean

Defined in: server/api.d.ts:1671

Whether this player is in a saddle.

---

nickname

readonly nickname: string

Defined in: server/api.d.ts:1449

The name this player connected under, or an empty string once their body is gone.

---

perks

readonly perks: string[]

Defined in: server/api.d.ts:1661

Every perk the player owns, by name.

---

physicsProfile

readonly physicsProfile: number

Defined in: server/api.d.ts:1616

The ragdoll physics profile the body is in, or 255 when it has none to report.

---

ping

readonly ping: number

Defined in: server/api.d.ts:8891

Current round-trip latency in milliseconds, or -1 when unavailable.

Inherited from

BasePlayer.ping

---

playerIndex

readonly playerIndex: number

Defined in: server/api.d.ts:1454

Connection slot this player holds, or 65535 when unassigned. Stable for the length of the session and reused afterwards.

---

poisoning

readonly poisoning: number

Defined in: server/api.d.ts:1561

How poisoned the body is; 0 is clean.

---

position

position: Vector3

Defined in: server/api.d.ts:8775

Authoritative world-space position; assignment forces replicated state.

Inherited from

BasePlayer.position

---

progression

readonly progression: ProgressionSnapshot | null

Defined in: server/api.d.ts:1666

Everything about this player’s progression, as plain JSON to store however the resource likes. A player starts every session with a fresh character, so restoreProgression with a stored snapshot is how progression outlives a disconnect. Null until their client’s first report.

---

ready

readonly ready: boolean

Defined in: server/api.d.ts:1476

Whether this player’s body has both a pose and a soul, which is what everyone else waits for before spawning a puppet for them. False for the first moments of a connection.

---

relativeSkills

readonly relativeSkills: SoulSkills

Defined in: server/api.d.ts:1591

The same nine skills as the engine’s relative values.

---

relativeStats

readonly relativeStats: SoulStats

Defined in: server/api.d.ts:1581

The same three attributes as the engine’s relative values, which is what its own modifiers are expressed in.

---

rightHandItem

readonly rightHandItem: string

Defined in: server/api.d.ts:1636

Item class drawn in the right hand as 32 hex digits, or an empty string when the hand is empty. A class rather than an item: no engine-local identifier crosses the wire.

---

rotation

rotation: Vector3 | Quaternion

Defined in: server/api.d.ts:8780

Authoritative rotation; reads return a quaternion and assignments accept a quaternion or Euler angles in degrees.

Inherited from

BasePlayer.rotation

---

skills

readonly skills: SoulSkills

Defined in: server/api.d.ts:1586

The nine combat and survival skills a hit or a draw is evaluated against. Read as a whole rather than one at a time: the snapshot carries them together.

---

sleeping

readonly sleeping: number

Defined in: server/api.d.ts:1546

Sleepiness the game has accumulated for this body; above 0 means asleep.

---

stamina

readonly stamina: number

Defined in: server/api.d.ts:1506

Current stamina, in the game’s own units.

---

state

readonly state: StateBag

Defined in: server/api.d.ts:8785

Arbitrary key/value state carried by this entity. The server writes it and every client that can see the entity receives it; see StateBag.

Inherited from

BasePlayer.state

---

steamId

readonly steamId: string

Defined in: server/api.d.ts:8876

Authenticated Steam identifier, or an empty string when unavailable.

Inherited from

BasePlayer.steamId

---

strength

readonly strength: number

Defined in: server/api.d.ts:1566

Strength, in the game’s own units.

---

velocity

readonly velocity: Vector3

Defined in: server/api.d.ts:1596

On the owning machine, the velocity the body’s own animation was driven by this frame, not the one its physics settled on. Everywhere else, measured from successive replicated positions.

---

virtualWorld

readonly virtualWorld: number

Defined in: server/api.d.ts:8770

Current virtual-world identifier.

Inherited from

BasePlayer.virtualWorld

---

visible

readonly visible: boolean

Defined in: server/api.d.ts:1471

Whether this player’s body is drawn at all – itself, what it wears and what it carries. True for everybody until something hides them. Published by their own client, so it follows setVisible once they have actually stopped drawing. A hidden player is only invisible: they still stand where they stand, still collide, can still be hit, and NPCs still see them.

---

vitality

readonly vitality: number

Defined in: server/api.d.ts:1576

Vitality, in the game’s own units.