Horses and dogs

Horses

kcds.characters.Horse is a horse the server spawns. Its coat and tack look the same in all games. It can have an owner and a rider, follow orders, and has its health kept by the server.

const { Horse } = kcds.characters;
const { Vector3 } = kcds.math;

const spot = player.position.clone().add(player.rotation.rotateVector(new Vector3(0, 3, 0)));
const pebbles = Horse.spawn(spot, player.rotation, '', 'Pebbles', 'horse_noble05');

pebbles.setDimension(player.dimension);
pebbles.giveTo(player);
player.mount(pebbles);

Spawning

Horse.spawn(position, orientation, soul?, name?, gear?, options?)

• soul is a breed from Horse.breeds(), which comes from the server's horse config, or a soul GUID.
• gear is its tack (see below). Without it, the horse wears one of the game's generic sets.
• { knockOut: true } makes a fatal blow knock it out instead.

Also available are Horse.all(), Horse.getById(id) and destroy().

Owner and rider

giveTo(player) sets the owner, and null removes it. owner, rider and mounted read the current state. An owner mounts their own horse, and for anyone else it counts as a stranger's horse, as in the game. With removedWithOwner, which is true by default, the horse goes when its owner leaves.

player.mount(horse, { instant }) puts a player standing nearby in the saddle, and player.dismount() takes them out. Return false from horseMounting to refuse a ride.

player.whistle() calls the player's horse like the game's companion key, and fires playerWhistle.

Health

health, alive, knockedOut (also unconscious), kill(), knockDown(), wake(health?) and revive(health?).

Orders

moveTo(position, { speed }), patrol(points, { speed, loop, waitSeconds }) and hold(). travelStatus tells you how it is going. A rider stays in control.

Tack

gear is { saddle, head, torso, shoe }, with item class names or null for empty. It is the same on all clients, including the rider's.

An owner can also change tack on the Horse tab of the game's inventory screen. A piece put on comes from the saddlebags or the owner's inventory. A piece taken off goes to the saddlebags, or to the owner's inventory when the saddlebags refuse it.

Two things can stop an owner's change. gearFixed = true refuses them all, and horseGearChanging, given the horse, the player and the resulting gear, can return false. Neither affects setTack, fitGear or takeOffGear called from scripts.

Buffs

addBuff(buff) puts a game buff, by GUID or table name, on the horse's body in all games. Examples are konskeZavody_horseBoost_diff3 (a race boost) and item_horse_shoe. removeBuff(buff), hasBuff(buff), clearBuffs() and buffs work on the server's list of up to sixteen names. A buff that wears off is applied again while it remains on the list. Custom buffs from kcds.players.Buffs.register are only for players and throw here.

Looks

look and setLook({ body, head, hair, tail }) take names from HorseLooks. body is the coat, head the breed and hair the mane.

Events

horseSpawn, horseOwnerChanged, horseMounting, horseMount, horseDismount, horseGearChanging, horseGearChanged, horseDamage, horseDeath, horseKnockedOut, horseWake, horseRevive, horseDestroy.

Which game simulates a horse

A game can run a horse's AI only when it has finished loading the current world and started gameplay, so connections that only receive world data do not run it. While a mounted rider reloads, the simulation waits for them, and a nearby player does not take over. A horse with no rider can move to another eligible game during loading.

Dogs

kcds.characters.Dog is a companion belonging to a player. It is an NPC of the game's dog class with an owner and a mode.

const { Dog } = kcds.characters;

const mutt = Dog.spawn(player, player.position, player.rotation, '', 'Mutt');
mutt.mode = 1; // follow

Modes

When hunting, the dog counts as the attacker in npcDamage.

objective reports what it is doing: 'waiting', 'following', 'searching', 'hunting', or 'idle' in a mode not yet implemented.

In Follow, the dog trots three metres behind its owner and runs if it falls over four metres further back. Since it is an NPC, moveTo(position, { speed }) also works, with walk, jog or run.

Owner

giveTo(player) (or null), owner, removedWithOwner, destroy(). player.dog gives the player's dog.

Fighting dogs

If a player locks on to a dog that is not their own, the dog fights them, since the game's lock-on only accepts a body that fights, and their blows then land (npcDamage). The owner's lock-on does nothing. The same applies to a WildDog, Wolf or Boar, while other animals flee.

Events

As with other NPCs, npcDamage and npcDeath fire for its body. Its own events are dogSpawn, dogOwnerChanged, dogModeChanged and dogDestroy.

Reference: Horse, HorseLooks, Dog.