Runtime classServer APIGenerated

Horse

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

Replicated KCD2 horse handle.

Extends

Entity

Constructors

Constructor

new Horse(id): Horse

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

Creates a script wrapper for an existing horse with this ID; use Horse.spawn() to spawn one.

Parameters

id

number

Network entity identifier.

Returns

Horse

Inherited from

Entity.constructor

Methods

destroy()

destroy(): void

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

Despawns this horse on every client after emitting horseDestroy.

Returns

void

dismountRider()

dismountRider(): Player | null

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

Takes whoever is in the saddle out of it: their own client is told to get off, and horseDismount is raised.

Returns

Player | null

The player taken off, or null when the saddle was already empty.

equipGear()

equipGear(item): boolean

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

Puts one piece of gear in its own slot, replacing what was there and keeping the rest.

Parameters

item

string

An item class name or GUID from Horse.gearItems().

Returns

boolean

True when it was put on; false for an item that is not horse gear, a caparison on a horse with no saddle, or a horse that is gone.

giveTo()

giveTo(player): void

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

Makes this horse another player’s. Every client makes it that player’s horse in the game’s own terms – theirs is never a stolen horse – and horseOwnerChanged follows. Ownership decides nothing about who may ride it: that is horseMounting’s to refuse. Throws when player is not a connected player.

Parameters

player

Player | null

The horse’s new owner, or null to leave it ownerless.

Returns

void

hold()

hold(): void

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

Cancels navigation and holds an unridden horse where it stands. Does not take control from a rider.

Returns

void

kill()

kill(): boolean

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

Kills this horse on the client running it, the way any other death happens there: the body falls, anyone riding it comes off, and horseDeath follows with a null killer and the reason scripted.

Returns

boolean

True when the horse was alive; false when it was already dead.

moveTo()

moveTo(position, options?): boolean

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

Routes an unridden horse over the server navigation mesh. Mounting cancels the order. Returns false without a mesh, for a dead or mounted horse, or invalid input.

Parameters

position

Vector3

Destination in world coordinates.

options?

Defaults to walking and a 1.5 metre arrival radius.

radius?

number

speed?

"walk" | "jog" | "run"

Returns

boolean

patrol()

patrol(points, options?): boolean

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

Patrols using the NPC route state machine. Requires a loaded mesh and an alive, unridden horse. Mounting cancels the patrol.

Parameters

points

Vector3[]

One to 256 waypoints.

options?

Defaults to walking, looping, and no wait.

loop?

boolean

speed?

"walk" | "jog" | "run"

waitSeconds?

number

Returns

boolean

pullDownRider()

pullDownRider(attacker): boolean

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

Has a player pull this horse’s rider down, on every client.

Parameters

attacker

Player

The player dragging the rider out of the saddle.

Returns

boolean

True when the request went out; false when nobody is riding it.

rearAndThrowDown()

rearAndThrowDown(): boolean

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

Rears the horse on every client so it throws its rider off. The game’s own animation, not a pose.

Returns

boolean

True when the request went out; false when nobody is riding it.

removeGear()

removeGear(slot): boolean

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

Takes one piece of gear off. Removing the saddle removes the caparison too, since it lies on the saddle.

Parameters

slot

"head" | "torso" | "saddle" | "shoe"

The slot to empty.

Returns

boolean

True when something was taken off; false when the slot was already empty.

revive()

revive(): boolean

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

Brings a dead horse back where it lies, at its full health.

Returns

boolean

True when the horse was dead; false when it was alive.

setGear()

setGear(gear): boolean

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

Dresses this horse in exactly this gear on every client, the one running it included: what it wore before is taken off. Throws on an item that is not horse gear, one keyed under the wrong slot, or a caparison (torso) with no saddle under it. Not subject to gearLocked or horseGearChanging, which govern players; horseGearChanged follows with a null player.

Parameters

gear

string | { head?: string | null; saddle?: string | null; shoe?: string | null; torso?: string | null; }

A preset from Horse.gearPresets() (horse_noble05), or item class names or GUIDs by slot from Horse.gearItems(), where a missing key or null leaves that slot empty; {} is a bare horse.

Returns

boolean

True when the gear was written; false when the horse is gone.

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

Entity.setVirtualWorld

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

Entity.setVisibleTo

toString()

toString(): string

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

Formats this horse handle for logging and debugging.

Returns

string

The horse ID, its soul, and its rider.

Inherited from

Entity.toString

all()

static all(): Horse[]

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

Lists every horse the server currently has.

Returns

Horse[]

One handle per live horse, in no particular order.

breeds()

static breeds(): string[]

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

The horses Horse.spawn knows by name: every horse the game gives a character of its own – the ones its traders sell and the named horses of its quests – plus horse, the generic one.

Returns

string[]

Breed names, horse first and the rest alphabetical.

gearItems()

static gearItems(slot?): string[]

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

Every item class a horse can wear, from the game’s own tables: saddles, bridles and chanfrons, caparisons and trappings, horseshoes.

Parameters

slot?

"head" | "torso" | "saddle" | "shoe"

Only the gear for this slot; omitted lists all of it.

Returns

string[]

Item class names, saddles first.

gearPresets()

static gearPresets(): string[]

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

The game’s own sets of horse tack, from its clothing presets: the generic horse_common, horse_noble, horse_nomad and horse_draft families, and the named horses’ own. Any of them goes to setGear or Horse.spawn by name.

Returns

string[]

Preset names, alphabetical.

getById()

static getById(id): Horse | null

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

Looks a horse up by its network entity ID.

Parameters

id

number

Network entity identifier.

Returns

Horse | null

The horse’s handle, or null when no live horse has that ID.

spawn()

static spawn(position?, rotation?, soul?, name?, gear?): Horse

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

Spawns and replicates a horse.

Parameters

position?

Vector3 | Partial<Vector3>

Optional world-space spawn position; omitted components default to zero.

rotation?

Vector3 | Quaternion

Optional initial orientation: a Quaternion, or a Vector3 of Euler angles in degrees.

soul?

string

Optional breed from Horse.breeds() (pebbles), or a soul GUID from the game’s tables; omitted spawns the generic riding horse.

name?

string

Optional name every client shows for the horse; omitted leaves the name its soul carries.

gear?

string | { head?: string | null; saddle?: string | null; shoe?: string | null; torso?: string | null; }

Optional gear the horse is born wearing on every client, as setGear takes it; {} spawns it bare. Omitted, it wears the game’s own tack: a named horse’s own preset, or one of the generic ones (horse_common01, horse_common02).

Returns

Horse

The newly spawned horse handle.

Properties

alive

readonly alive: boolean

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

False once the horse has died. A dead horse is still an entity: its body stays where it fell, nobody can ride it, and revive or destroy are the ways out.

destroyWithOwner

destroyWithOwner: boolean

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

Whether this horse is despawned when its owner disconnects. True by default. Set it to false to keep the horse in the world: it is left ownerless instead (horseOwnerChanged with a null player) until giveTo hands it to someone. Saving it across server restarts is the script’s own business.

gear

readonly gear: object

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

What this horse wears, by slot: saddle (the saddlebags are part of it, and so is the carrying capacity they add), head (a bridle or chanfron), torso (a caparison), shoe. Item class names, null for an empty slot. A spawned horse wears the game’s own tack for it unless Horse.spawn said otherwise. The gear changes the horse’s stats as well as its look.

head

head: string | null

saddle

saddle: string | null

shoe

shoe: string | null

torso

torso: string | null

gearLocked

gearLocked: boolean

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

While true, players’ own changes to this horse’s gear are refused and put back, before horseGearChanging is asked. Scripts can still change it. False by default.

health

health: number

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

Health, as the client running this horse last reported it off the animal’s own soul – 0 before any client has. Assigning sets it on that client, clamped to maxHealth; 0 kills. A dead horse ignores the write: revive is what brings one back.

id

readonly id: number

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

Immutable network entity identifier.

Inherited from

Entity.id

inventoryCapacity

readonly inventoryCapacity: number

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

What this horse can carry, in the game’s own weight units, or 0 before any client has reported it. Derived by the engine, so read-only.

maxHealth

readonly maxHealth: number

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

The most health this horse can have, from its soul; 0 before any client has run it.

maxStamina

readonly maxStamina: number

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

The most stamina this horse can have; 0 before any client has run it.

mounted

readonly mounted: boolean

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

Whether a player is currently riding this horse.

name

name: string

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

Name every client shows for this horse. Assignment renames it on all of them; empty means the name its soul carries stands. A rider keeps the name it mounted with until it dismounts.

navigationStatus

readonly navigationStatus: string

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

The current route’s status: idle, running, reached, blocked, or failed.

owner

readonly owner: Player | null

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

The player this horse belongs to, or null when it is nobody’s. Set with giveTo.

ownerId

readonly ownerId: number

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

Network ID of the player this horse belongs to, or 0 when it is nobody’s. Not necessarily its rider.

position

position: Vector3

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

Authoritative world-space position; assignment forces replicated state.

Inherited from

Entity.position

rider

readonly rider: Player | null

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

The player in the saddle, or null when the horse is riderless.

riderId

readonly riderId: number

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

Network ID of the player in the saddle, or 0 when the horse is riderless.

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

Entity.rotation

soul

readonly soul: string

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

GUID of the soul this horse was spawned against, which decides its appearance.

stamina

readonly stamina: number

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

Stamina, as its client last reported it – the bar the game draws for a ridden horse, spent by galloping. Read-only: the game runs it.

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

Entity.state

virtualWorld

readonly virtualWorld: number

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

Current virtual-world identifier.

Inherited from

Entity.virtualWorld