Npc

A character the server spawns and owns. The nearest player's game within 150 m simulates its body, including movement, pathfinding and fights, and other games show what that one reports. The server holds its health, inventory and orders, so all players see the same NPC. Orders such as moveTo, follow, flee, patrol and attack use the game's movement and pathfinding.

npc.create()

Npc.create(options)

Spawns an NPC. By default it is vulnerable, lootable, at full health, and in its soul's clothes.

npc.placements()

Npc.placements()

The level's people as it places them, on the server's level: { name, guid, level, layer, soul, actorClass, position, rotation }. These are their first positions, not where a schedule or quest has them. It spawns nothing, so a script can build its own population from them.

npc.adopt()

Npc.adopt(placedGuid, options)

Gives one of the level's people to a script, as a server NPC at the level's position for them. The body stays when players leave, and the same GUID again gives the same NPC, without applying the options again. Null if the GUID is not in the level. Throws a TypeError for unusable arguments.

npc.setPopulation()

Npc.setPopulation(settings)

Settings for the level's people, on by default. All players see the same ones, spawned around players at the level's positions. They walk a relaxed round of neighbouring places, a patrol scripts can replace with any order. They do not follow the level's schedules, and those a quest stages are left out, though Npc.adopt can still get them. people-population.json in the resources folder sets the same. Throws a RangeError or TypeError for an unusable value.

npc.roles()

Npc.roles()

The named kinds of NPC: guard, guard_alt, knight, bandit, bandit_alt, cuman, townsman, townsman_alt, townswoman and townswoman_alt. Each maps to a soul from the game's data, giving a suitable look and gender. Pass the name as `soul` to Npc.create, where other values must be a soul GUID.

npc.all()

Npc.all(dimension)

All NPCs, or those in one dimension.

npc.getById()

Npc.getById(id)

The NPC with this network id, or null.

npc.removeAll()

Npc.removeAll(dimension)

Removes all NPCs, or those in one dimension, and returns how many.

npc.setAnimalPopulation()

Npc.setAnimalPopulation(config)

Sets the animal population: whether it runs, the most animals, and rules per kind.

npc.setAnimalPopulationEnabled()

Npc.setAnimalPopulationEnabled(enabled)

Turns the animal population on or off.

npc.setAnimalSpecies()

Npc.setAnimalSpecies(kind, settings)

Sets the rules for one animal class, as a percentage or an options object.

npc.animalPopulation

animalPopulation

The current animal population settings.

npc.animalSpots()

Npc.animalSpots(level)

The game's animal spawn points in a level.

npc.setHarvestTable()

Npc.setHarvestTable(table)

Sets what skinning each animal class gives. {} turns off the game's gutting for all animals.

npc.harvestTable

harvestTable

The current harvest table.

npc.animals()

Npc.animals()

Animals from the population, living and dead, as Npc objects. They belong to no resource and stay when a resource stops.

npc.appearance

appearance

Its character parts: { body, head, hair, beard }.

npc.setAppearance()

setAppearance(request)

Gives it other character parts, with names from Appearances.options for its gender. Parts left out stay, and '' restores the soul's. Returns false for an unknown name, or a beard the face cannot have.

npc.setCombatSkill()

setCombatSkill(skill)

Sets how often it parries and how hard it hits. null restores the game's fighting.

npc.combatSkill

combatSkill

Its combat skill, { defense, damage }.

npc.outfit

outfit

The pieces from setOutfit's list, or null if it wears its soul's clothes.

npc.wearing

wearing

The item classes from wear.

npc.wear()

wear(itemClasses)

Makes it wear these item classes, by name or GUID from Inventory.classes.

npc.setOutfit()

setOutfit(outfit)

Dresses it in one of the game's outfits, by a name or GUID from Player.outfitSets, returning true if its gender has one by that name. Or it takes a list of item classes, each by name, id or { item, quality, health }. It then wears and holds exactly these, including clothing, armour, weapons, shields and ammunition, on all its bodies, as worn rows of getInventory() replacing those from an earlier setOutfit or wear. Returns true once sent, and throws for an unusable item or if the inventory has no room.

npc.soul

soul

The game soul it was created from, which gives its character, skills and look.

npc.actorClass

actorClass

Its actor class in the game.

npc.placedGuid

placedGuid

Always 0, since a scripted NPC is not one of the level's.

npc.name

name

Its name. You can assign to it, and nearby players see the new name.

npc.health

health

Its health, 0 to 100. Setting 0 kills it, firing npcDeath with no killer, and more than maxHealth is limited to it.

npc.maxHealth

maxHealth

Its maximum health, which is 100.

npc.alive

alive

Whether it is alive.

npc.invulnerable

invulnerable

Whether blows take no health.

npc.fightsBack

fightsBack

Whether it strikes back.

npc.damage()

damage(amount, attacker = null)

Takes health as a scripted hit, firing npcDamage, and npcDeath if none is left. Returns false for a dead, invulnerable or gone NPC.

npc.kill()

kill(killer = null)

Kills it with the game's death, firing npcDeath. Returns false for a dead or gone NPC.

npc.revive()

revive(health = MAX_HEALTH)

Brings back a dead NPC where it lies, firing npcRevive. Returns false for a living or gone NPC.

npc.getInventory()

getInventory()

What it carries.

npc.lootable

lootable

Whether its dead body can be searched.

npc.harvested

harvested

Whether its carcass has been skinned.

npc.harvestable

harvestable

Whether its carcass can be skinned now.

npc.brain

brain

Whether the game's brain runs it. When false, it stays put and does not think, perceive or fight on its own.

npc.targetable

targetable

Whether players can lock on to it.

npc.attackable

attackable

False means players cannot fight it. They cannot lock on, and their blows, shots and horses' hits land nowhere, so it does not react and the game sees no attack to punish. It still talks, walks and trades. Also an option of Npc.create. True by default.

npc.interactable

interactable

Whether the use key works on it, firing npcInteract.

npc.frozen

frozen

While true, it stays where it is and keeps its order. You can assign to it.

npc.nameplate

nameplate

Whether its name is drawn over its head for all players, as for a player, with the name or setNameplateText's text, and a health bar below. Off by default. Any player can still turn plates off on their own screen with the client's Nameplates.

npc.isNameplateVisible()

isNameplateVisible()

Whether its plate is drawn, the same switch as `nameplate`. False by default.

npc.setNameplateVisible()

setNameplateVisible(visible)

Shows or hides its plate for all players, the same switch as `nameplate`.

npc.isNameplateHealthVisible()

isNameplateHealthVisible()

Whether the health bar shows. True by default.

npc.setNameplateHealthVisible()

setNameplateHealthVisible(visible)

Turns the health bar on or off, while the name stays.

npc.getNameplateText()

getNameplateText()

The text drawn in place of its name, or '' while the name is drawn.

npc.setNameplateText()

setNameplateText(text = '')

Sets the plate's text, up to 64 UTF-8 bytes on one line. Its real `name` stays, and is still used for conversation and its soul.

npc.getNameplateColor()

getNameplateColor()

The plate text's colour as 0xAARRGGBB, opaque white unless tinted.

npc.setNameplateColor()

setNameplateColor(color)

Tints the plate's text.

npc.locomotion

locomotion

How the simulating game moves the body for moveTo, follow, flee and patrol. 'native', the default, walks it with the game's movement and animations. 'kinematic' moves it along the way at the order's pace, on the ground and facing its direction, with no walking animations. Neither finds a way around obstacles by itself. Only these two strings are accepted, and anything else throws.

npc.setSpeaking()

setSpeaking(talking, style)

Starts a repeating talking animation from the game's face clips until stopped, for all clients including later joiners. It is not lip-sync, so use it with say. Returns true once sent, and false for a dead NPC. An unknown style throws a TypeError.

npc.lootOf()

lootOf()

The game's loot candidates for this animal, by soul. It rolls nothing and fills nothing, so the script chooses and writes the carcass's inventory. Each row is { item (class GUID), name, amount (the most units), fraction and variation (the game's share and spread, not a drop chance), food, harvester (a special_ part or trophy) }. Null for a body that is not an animal with a game preset, including wild dogs.

npc.setExpression()

setExpression(fragment, options)

Changes its expression for all clients, including later joiners, alongside body animations. It affects eyes, brows and mood, so use setSpeaking for the mouth. Returns true once sent, and false for a dead NPC. Invalid arguments throw a TypeError.

npc.faction

faction

The faction row your resource gave it, or 0: a whole number from 0 to 65535 the server keeps for your scripts. The body currently keeps its soul's faction in the game.

npc.pin()

pin(player)

Lets one player's game run it regardless of distance, for a scene played to that player. While pinned, it goes dormant when that player is out of range, rather than moving to someone else, and it unpins when they leave the server.

npc.pinnedTo

pinnedTo

The player it is pinned to, or null.

npc.simulator

simulator

The player whose game runs it, or null.

npc.velocity

velocity

Its velocity.

npc.dimension

dimension

Its dimension. Change it with setDimension.

npc.position

position

Its location. Assigning teleports it.

npc.rotation

rotation

The direction it faces. Assigning turns it.

npc.setDimension()

setDimension(world)

Moves it to another dimension, where only players there see it.

npc.showOnlyTo()

showOnlyTo(player)

Lets one player see it even outside its dimension, or nobody extra with null.

npc.remove()

remove()

Removes it, firing npcDestroy first.

npc.hold()

hold()

Drops its order and keeps it still.

npc.intent

intent

What it was told: 'hold', 'moveTo', 'follow', 'flee', 'lookAt' or 'attack'.

npc.routeState

routeState

Its patrol, { routeId, waypointIndex, lap, direction, phase }, or null if not patrolling.

npc.status

status

How its order is going.

npc.moveTo()

moveTo(position, options)

Walks to a position, with `speed` 'walk', 'jog' or 'run', and `radius`.

npc.patrol()

patrol(route, options)

Walks a route or list of points.

npc.follow()

follow(target, options)

Trails a player or NPC, 3 m behind by default.

npc.flee()

flee(from, options)

Runs away, 30 m by default.

npc.lookAt()

lookAt(target)

Turns towards a player, NPC or position.

npc.attack()

attack(target, options)

Fights a living player or NPC within 128 m. `weapon` can select, for example, 'bow'.

npc.teleport()

teleport(position, rotation)

Moves it at once.

npc.playAnimation()

playAnimation(fragment, options = {})

Plays a Mannequin fragment with tags, as for a player, or a game clip. Nearby players see it, and so does a player arriving later or simulating it next, until stopAnimation or the next playAnimation. npcAnimationEnd reports how it ended: 'finished', 'interrupted', 'refused', 'stopped' or 'replaced'. Returns true when the request goes out.

npc.stopAnimation()

stopAnimation()

Ends what playAnimation started at once and returns the body to its order, and npcAnimationEnd says 'stopped'. Returns true when the request goes out.

npc.say()

say(text, options = {})

Shows text in the game's speech bubble over its head for nearby players. '' removes it.

npc.id

id: number

The network id.