NPC Reference

The NPC object can be accessed by the identifier this. If you change a property (such as image or ani) and want it to be permanent, then call this.save(). Most attributes can also be changed by calling setATTRIBUTE(name) such as this.setchat(text). NPC functions are currently also available as global functions, so that you can call either "this.say(text)" or "say(text)", although the use of this.say is recommended. Object attributes defined in Tiled can also be accessed by script, such as this.npcclass.

Events

• function onEVENT() - custom events scheduled by calling scheduleevent
• function onCreated() - the NPC has been loaded (server or map loaded), important for script classes
• function onUpdated() - the script has been updated with the in-game editor
• function onTimeout() - when calling settimeout this event is automatically invoked after the specified time
• function onPlayerTouchsMe(pl) - the player collides with the NPC (the player moved)
• function onPlayerSays(pl) - a player is in a distance of around 300 pixels or less, and is chatting
• function onMouseDown(pl) - a player taps or clicks on the NPC
• function onPlayerAttacks(player) - Player uses a melee attack on the NPC
• function onNPCTouch(pl) - the NPC collides with the player (the NPC moved) (client-script only)
• function onActivated(player, dir:integer) - client-side event when an item is used by the player
• function onBombButton(player) - client-side event when the bomb/bow/grab button has been pressed
• function onStartEvent() - an event has been started on the map with /editevent
• function onFinishEvent() - an event has been stopped on the map with /editevent
• function onStoryEnd(storyid:number) - when a non-looping story finishes (setstory)
• function onEffectStart(effecttype) - npc.seteffect(delay, type, params) is called
• function onEffectEnd(effectype) - the effect ended after the specified delay

Attributes

• this.id: string, read-only, identifies the NPC, you can use Server.searchnpcs({id:ID}) to find it
• this.itemid: string, set by the system for furniture npcs and similar
• this.networkid: integer, needed for some internal functions to synchronise objects
• this.map: map object, see more at the Maps section
• this.ownerid: number, read-only, id of the player who owns this furniture
• this.npcclass: string, read-only, the built-in class of the NPC, this is "scriptnpc" for NPCs added with /addscriptnpc
• this.mobtype: string, read-only, only on server, the monster type referring to info in monsters.json and hitpoints.json
• this.hp: integer, hitpoints, read-only
• this.maxhp: integer, max-hitpoints, read-only
• this.name: string, you can use Server.searchnpcs({name:NAME}) to find the NPC
• this.namecolor: string, can be name ("pink") or html hex color ("#ffc0c0")
• this.tags: array of strings, you can use Server.searchnpcs({tag:tag}) to find the NPC
• this.chat: string
• this.weapon: string
• this.weapondata: object
• this.body: string
• this.head: string
• this.hat: string
• this.bow: string
• this.mount: string
• this.image: string, image of the NPC
• this.ani: string, can contain fixed frames (idle[1]) and comma-separated parameters which can be accessed in the .bani file with PARAM1 etc.
• this.aniarg1..9: string, the ARG1..9 values in the .bani files
• this.x, y, z, dir: number, current NPC position and direction
• this.angle: number, for animations which use "OBJECT" as rotation
• this.zoom: number, default 1
• this.storyid: integer, current story played back by the NPC
• this.waypoints: array of objects, play back the specified waypoints, get waypoints by clicking on the waypoints button in story windows
• this.scriptclasses: array of strings, read-only, lists the join()ed classes
• this.drawunder: boolean, makes the npc rener underneath the player if set true (client-script only)
• this.nonblocking: boolean, makes the npc not block the player (client-script only)
• this.emitters: array or object, for testing particle emitters (client-script only)
• this.editfields: array of objects, by default [{label:"Image:", name:"image"}, {label:"Name:", name:"name"}, {label:"Chat:", name:"chat"}, {label:"Story:", name:"storyid"}], for scriptnpcs to display different editor variables, don't forget to also add the variables to scriptsyncvars.json; the editfields can also be checkbox: true, readonly: true and adminonly:true (only admin can change the property)
• this.editdescription: string, for scriptnpcs to display a text at the top of the edit window
• this.isdead: boolean
• this.sidekick: object {ani, head, hat, idle, walk, ...} which defines the current pet / sidekick following the NPC
• this.icon: string, the icon of dropitems, can also be used for the ICON placeholder in animations
• this.height: number, sets the interactive height of the npc, multiplied by the main.json tilesize.
• this.width: number, sets the interactive width of the npc, multiplied by the main.json tilesize.
• this.islocalnpc: boolean, is true for npcs added in Tiled
• this.dontsave: boolean, is true if saving is disabled for this NPC
• this.effect: string, the effect type the npc currently has
• this.attacktype: string, the attacktype of mobs
• this.melee: string, the melee weapon of mobs
• this.runawayhp: number, the runawayhp attribute of mobs (run away from player if hitpoints drop below this value)

Functions

• this.say(text:string [,delay:number]) - shows text, by default for 5 seconds but you can optionally specify the number of seconds
• this.setimg(image:string) - changes the image of the NPC, must include the file extensions and exist in the npcs/ folder of the Files project
• this.setani(ani:string [, ...parameters]) - sets the animation (.bani file) of the NPC, without file extension
• this.setaniarg(index:number, value:string) - sets aniarg1-9 using index and value
• this.move(timeinseconds:number, x:number, y:number, z:number) - moves to the specified position in the specified time, updates the direction of the NPC. On server this is currently updating the position of the NPC immediately, but players see it moving smoothly. Also works by client-side scripts (only moves locally then).
• this.setmap(map:string, template:string, x:number, y:number) - server-side, moves the npc to a new map
• this.offsetx(delta:number): number - returns the new x coordinate when the NPC moves delta tiles forward
• this.offsety(delta:number): number - returns the new y coordinate when the NPC moves delta tiles forward
• this.showhp(nr:number, type:string, hitpoints:number, maxhitpoints:number) - shows a temporary number floating over the NPC. Type can be "healed" for green and "inflicted" otherwise. If you specify hitpoints and maxhitpoints, then the health bar is shown over the NPC.
• this.play(sound:string) - plays a sound effect to near players
• this.setmusic(fileorurl:string) - plays a music, only works on client-side, switches off when leaving the map
• this.stopmusic() - stops a music previously played with setmusic
• this.shoot([itemid:string, angle:number, offset:[dx,dy]]) - server-side, shoots a projectile in the current direction of the NPC with the specified weapon, or use the current weapon if not specified; second parameter is an optional angle, third parameter offset in tiles
• this.settimeout(timeinseconds:number) - schedules a "timeout" event which is invoked after the specified time on the same script
• this.scheduleevent(delayinseconds:number, eventname:string [, ...additional parameters]) - schedules a custom event which is invoked after the specified time with optional additional parameters which are passed to the onEventname function
• this.cancelevents(event:string)
• this.save() - saves the NPC to database
• this.join(classname: string) - joins a script class, call save() afterwards to make it permanent
• this.leave(classname: string) - leaves a script class
• this.sleep(delay: number) - pauses the script for the specified number of seconds
• this.setstory(storyid: number [, options: object, (storyid) => { ... }]) - plays a story with options, default {loop:true, copylook:true, position:"absolute"}, you can set position to "relative" to start from the current position and set a callback when the non-looping story ends
• this.setwaypoints(waypoints [, options, () => { ... }]) - sets waypoints with options and atend callback, see setstory
• this.destroy() - deletes the NPC permanently (scriptnpcs) or until next map reload (Tiled npcs)
• this.triggerclient(player, action:string [, ...parameters]) - invokes onClientACTION on the client-side part of the script
• this.triggerserver(player, action:string [, ...parameters]) - invokes onServerACTION on the server-side part of the script
• this.creategui(id:string, classes:string, css:string, html:string) - like GUI.create, but automatically removes the gui when the weapon script is unequipped
• this.gethouse(houseinfo => { ... }) - loads house info with callback, if this is a house
• this.deletehouse(() => { ... }) - deletes house with callback, if this is a house
• this.savehouse(playerid:number, template:string, houseid => { ... }) - stores a new house to database, with callback when done
• this.hasitem(itemid:string): boolean - tells you if the NPC has a certain item
• this.getitemnr(itemid:string): integer - returns how many items of a type the NPC has
• this.getitems([type | [type1, type2, ...]]): array of items - returns all NPC items, or items of a special type such as "hat" or multiple item types such as ["hat","head"]
• this.seteffect(delay:number, type:string, params:object); - Adds an effect to the npc. (Example: setEffect)