Player Reference

The player who was causing the event can be accessed with the identifier player. You can add custom variables to the player object (player.myvar = 123). These are kept until the player logouts, and are saved to the player object permanently when being configured in syncscriptvars.json.

Events

• function onEVENT() - custom events scheduled by calling scheduleevent
• function onTimeout() - when calling settimeout this event is automatically invoked after the specified time
• function onStoryEnd(storyid:number) - when a non-looping story finishes (setstory)
• function onLogin() - called on player login
• function onDeath(killer) - called when a player dies, check killer.type == "player" to see if the killer was a player
• function onKill(victim, rejectReason) - called when the player kills another player, rejectReason can be "sameip", "playerland", "clanland" (it's not adding a playerkill then)
• function onClanJoin(clan) - called on server when the player accepted a clan invitation
• function onClanCapture(buildingname) - called on server when the player overtakes a castle/base with their clan
• function onConsoleOpen() - called when an admin opens the admin console
• function onConsoleClose() - called when an admin closes the admin console
• function onConsoleChat(message) - called when an admin types something, return true if you have processed the message (and don't want to show it on the console)
• function onEffectStart(effecttype) - player.seteffect(delay, type, params) is called
• function onEffectEnd(effectype) - the effect ended after the specified delay
• function onEnterMap(map, template, oldpos:{x,y,map,template}) - the player enters a new map or warps
• function onItemPurchase(price, itemid, item) - called on server when the player bought an item
• function onSoldItems(price, itemid, item, itemnr) - called on server when the player sold items
• function onJobDone(jobname) - called on the server when the player reaped an apple tree or picks up mushrooms
• function onNameChange(oldName, newName) - called when the name or clan tag changes
• function onOnlineHour(newhours) - called on server when the player played one more hour
• function onRevive() - called on server when the player revived from death
• function onSays() - the player says something, check this.chat
• function onSparLost() - called on server when the player lost a spar (this is also be called on login after leaving a spar)
• function onSparWon(victimid, victiminfo) - called on server when the player won a spar
• function onStoryPublish(story) - called on server when the player recorded and published a story
• function onWeaponChange(oldWeapon, newWeapon) - called on server when the weapon changes
• function onCoinsChange(), onBodyChange(), onHatChange(), onHeadChange(), onShieldChange() - called on client when an attribute of the player has changed, for display

Attributes

• player.type: string, always "player"
• player.id: integer, the unique player id, read-only
• player.networkid: integer, needed for some internal functions to synchronise objects
• player.isonline: boolean, if the player is currently online (might be false for DB.loadplayer)
• player.map: map object, see more at the Maps section
• player.hp: integer, hitpoints, kills if set to zero
• player.maxhp: integer, max-hitpoints, sets temporary max hp
• player.name: string, read-only
• player.namecolor: string, can be name ("pink") or html hex color ("#ffc0c0")
• player.coins: integer, read only
• player.bombs: integer, value between 0 and maxbombs configuration
• player.arrows: integer, arrows or bullets for the equipped weapon or bow, value between 0 and maxarrows configuration
• player.chat: string
• player.weapon: string, itemid of the equipped weapon
• player.weaponimage: string, client-side read only, full image URL of the current weapon
• player.weapondata: object, current weapon item or weapon mode (if it has multiple modes)
• player.body: string, itemid of the current body
• player.bodyimage: string, client-side read only, full image URL of the current body
• player.head: string, itemid of the current head
• player.headimage: string, client-side read only, full image URL of the current head
• player.hat: string, itemid of the current hat
• player.hatimage: string, client-side read only, full image URL of the current hat
• player.bow: string, itemid of the equipped bow
• player.bowimage: string, client-side read only, full image URL of the current bow
• player.bowdata: object, read only, current bow item
• player.shield: string, itemid of the equipped shield
• player.shieldimage: string, client-side read only, full image URL of the current shield
• player.mount: string, itemid of the current mount
• player.mountimage: string, client-side read only, full image URL of the current mount
• player.mountdata: object, read only, current mount item
• player.ani: string, can contain fixed frames (idle[1]) and comma-separated parameters which can be accessed in the .bani file with PARAM1 etc.
• player.color: string, client-script only - comma separated value of r,g,b,a with 0.0-1.0 value, set with array [r,g,b,a] from either animation or client-script
• player.aniarg1..9: string, the ARG1..9 values in the .bani files
• player.x, y, z, dir: number, current player position and direction
• player.angle: number, for animations which use "OBJECT" as rotation
• player.zoom: number, default 1
• player.level: number, unused (was supposedly be for "experience" levelups)
• player.onlinetime: integer, seconds of playing the game, on client-side only updated at login
• player.kills, player.streak, player.mobkills, player.sparwins, player.sparlost: integer
• player.deaths: integer, currently not counted/increased
• player.adminlevel: integer
• player.stealth: integer, server-side, can be 0 (off), 1 (on) and 2 (high stealth); stealth is only allowed for players with adminlevel > 0, high stealth only for adminlevel >= adminlevelhighstealth (main config)
• player.clanname: string, the current clan name / tag of the player, can be temporary changed
• player.clanid: integer, read-only, the id of the current clan
• player.effect: string, the effect type the player currently has
• player.storyid: integer, current story played back by the player
• player.waypoints: array of objects, play back the specified waypoints, get waypoints by clicking on the waypoints button in story windows
• player.emitters: array or object, for testing particle emitters (client-script only)
• player.language: string, the language of the player, "en", "de", "fr" etc.
• player.isdead: boolean, read-only
• player.deathtime: Date, read-only, last time of death
• player.sidekick: object {ani, head, hat, idle, walk, ...} which defines the current pet / sidekick following the player; if the server has pet items then this should not be changed because it uses the same system
• player.title: string, a title which is shown in profile and can be changed by admins with the command /settitle
• player.titlecolor: string, can be name ("pink") or html hex color ("#ffc0c0")
• player.strafelock: boolean, client-side, lock strafe movement for the player, or see if the player has locked it ('O' key)
• player.tiletype: number, client-side, current tile type below the player
• player.muted: boolean, server-side, if the player is currently muted by admins
• player.landtemplate: string, server-side, the current player land map template
• player.statusban: boolean, server-side, if the player is banned from changing the status
• player.status: string, server-side, the current profile status of the player
• player.instagram: string, server-side, the instagram link of the player profile
• player.youtube: string, server-side, the youtube link of the player profile
• player.facebook: string, server-side, the facebook link of the player profile
• player.twitch: string, server-side, the twitch link of the player profile (not supported yet)
• player.tiktok: string, server-side, the tiktok link of the player profile
• player.injail: boolean, server-side, if the player is in a jail map
• player.intrade: boolean, server-side, if the player is currently trading
• player.ip: string, server-side, the ip address of the player (if online)
• player.ping: number, server-side, ping in milliseconds
• player.platform: string, the app platform (iphone, android, steam, web, facebook)
• player.os: string, server-side, the operating system (iOS, Android, Windows, ...)
• player.browser: string, server-side, browser such as Safari, Chrome, or Electron for Steam users
• player.ispvp: boolean, is true if the player is not in a nopkzone, updates when moving
• player.movetime: Date, server-side, the time of the last player movement
• player.ghost: boolean, true if the client is only viewing (login screen)
• player.guest: boolean, true if the player is not registered yet (device login)
• player.proxy: boolean, server-side, can be "yes"/"no"/undefined depending on if the player connection is a proxy, requires enableproxycheck enabled in the server options
• player.vpn: boolean, server-side, can be "yes"/"no"/undefined depending on if the player connection is a vpn, requires enableproxycheck enabled in the server options
• player.isfrozen: boolean, client-side, the player is frozen (see player.freeze())
• player.isfiring: boolean, client-side, the player is frozen or firing a weapon
• player.isreloading: boolean, client-side, the player is currently reloading the weapon
• player.uploadsblocked: boolean, server-side, if the player is currently blocked from uploading custom graphics

Functions

• player.freeze(freezetime:number [, firetime:number]) - freeze player for certain time in seconds, client-script only, second parameter is optional and specifies the time until you can shoot again, can be higher than freezetime
• player.checkbreak(itemid): boolean - check if weapon/bow will break on use
• player.disconnect() - disconnects player from the game.
• player.heal() - refills hitpoints
• player.hasitem(itemid:string): boolean - tells you if the player has a certain item
• player.getitemnr(itemid:string): integer - returns how many items of a type the player has
• player.getitems([type | [type1, type2, ...]]): array of items - returns all player items, or items of a special type such as "hat" or multiple item types such as ["hat","head"]
• player.itemslocked: boolean - if true then the player cannot buy items and cannot trade, set by admins with /lockitems
• player.itemslockedorbyevent: boolean - checks if the inventory is locked or the player is playing an event where the inventory is locked
• player.additem(itemid:string [, amount:number, options:object]): boolean - adds an item, with optional amount, logs to scriptitems.log. additem can only fail if the amount is invalid, the item doesn't exit or the stacklimit is reached. With player.additem(itemid, 1, {ignorestacklimit:true}) the stack limit check can be disabled. With player.additem(itemid, 1, {noautoequip:true}) you add the item without equipping it automatically.
• player.removeitem(itemid:string [, amount:number]): boolean - removes an item, with optional amount which must be lesser or equal the amount of items the player possesses, logs to scriptitems.log
• player.buyitem(item:object[, onbuy:function]) - opens the item purchase dialog, with optional callback when the players clicks/taps on the buy button
• player.buycoins(amount:number) - opens the coins dialog to let the player purchase coins to be able to buy an item of the specified coins value
• player.setani(ani:string[, ...parameters]) - shows an animation until the player moves again, filename without file extension
• player.setaniarg(index:number, value:string) - sets aniarg1-9 using index and value
• player.offsetx(delta:number): number - returns the new x coordinate when the player moves delta tiles forward
• player.offsety(delta:number): number - returns the new y coordinate when the player moves delta tiles forward
• player.showhp(nr:number, type:string, hitpoints:number, maxhitpoints:number) - shows a temporary number floating over the head of the player. Type can be "healed" for green and "inflicted" otherwise. If you specify hitpoints and maxhitpoints, then the health bar is shown over the head of the player.
• player.setmap(map:string, template:string, x:number, y:number) - moves the player, do ("outside", "unknown", 0, 0) to move out of a house
• player.showmessage(message:string) - shows a message at the top of the screen
• player.showpm(message:string, senderlook:object [, data:object], onreply:function) - sends a PM to the player (Example: PMs)
• player.showprofile(id:number) - shows the profile of another player
• player.showurl(url:string) - opens the URL in a new window, currently only works on mobile because of popup blocker
• player.unstick() - unsticks the player
• player.echo(text:string [, ...objects to print]) - outputs text on the admin console for this admin only
• player.addcoins(amount:number, reason:string) - adds coins, must be greater than 0 and less or equal to option "addcoinslimit" in the main.json configuration, reason is mandatory, it's logged to scriptcoins.log
• player.removecoins(amount:number, reason:string) - removes coins, must be greater than 0 and less or equal to option "removecoinslimit" if configured in the main.json, reason is mandatory, it's logged to scriptcoins.log
• player.addscore(type:string [, nr:number]) - adds a score entry for the current day, can be used by scorestatue npcs, you need to add the type to allowedscores in the main.json config
• player.setambient(red:number, green:number, blue:number) - sets the current ambient color for the player (day-night-effect)
• player.setfocus(type:string, x:number, y:number); - Moves player camera focus to specified location. (Example: setFocus). Type can be "sit" (in spar) or "freeze".
• player.resetfocus(); - Resets camera focus back to normal, see player.setfocus() for more details.
• player.translate(message:string [, paramarray]): string - returns the translated text with the user language, the text must be added to the Translation git project, if you use placeholders like %s and %d then they will be filled with the values from paramarray
• player.seteffect(delay:number, type:string, params:object); - Adds an effect to the player. (Example: setEffect)
• player.save() - saves the player to database; use this when you add variables to scriptsyncvars.json and want the change to be permanent; you don't need to call this after adding coins and items
• player.setstory(storyid: number [, options: object, (storyid) => { ... }]) - plays a story with options, default {loop:false, freeze:true, position:"relative", screenzoom:1}, you can set position to "absolute", the "copylook" option is always false for players; third parameter is a callback when the non-looping story ends
• player.setwaypoints(waypoints [, options, () => { ... }]) - sets waypoints with options and atend callback, see setstory
• player.visithouse(profileid) - visit the house of another player
• player.screenshake({strength:number,duration:number}) - adds a screenshake effect with strength (pixels) and duration (milliseconds)
• player.hasadmincommand(command: string): boolean - return true/false wether the player has the right to the given admin command
• player.triggerclient(action:string [, ...parameters]) - invokes onClientACTION on the client-side part of the player scripts (by default player_events.js)
• player.triggerserver(action:string [, ...parameters]) - invokes onServerACTION on the server-side part of the player script (by default player_events.js)
• player.filtertext(text:string [, type:string]) - replaces swear swords with stars, type can be "chat", "all", "name", "news", "status", "story"
• player.hasunlimitedammo() - checks if the player has unlimited ammo
• player.clearunlimitedammo() - removes unlimited ammo from the player
• player.hasunlimitedrevive() - checks if the player has unlimited revive
• player.clearunlimitedrevive() - removes unlimited revive from the player
• player.shoot([itemid:string, angle:number, offset:[dx,dy]]) - server-side, shoots a projectile in the current direction of the player with the specified weapon, or use the current weapon if not specified; second parameter is an optional angle, third parameter offset in tiles
• player.play(sound:string) - plays a .wav sound file from the sounds/ folder only for the player.
• player.isblocked(id): boolean - server-side, checks if the player has blocked a player of that id
• player.isfriend(id): boolean - server-side, checks if the player has friended a player of that id
• player.invitetotrade(id) - sends an invitation to trade to the player of that id
• player.resetsparstats() - server-side, removes the sparwins and sparlost variables and removes all spar statistics from database
• player.getmenuscript(name:string) - gets the "weapon script" which is defined in menubuttons.json and handles specific menus, this way you can trigger the client or server-side part of menus or let that script handle other tasks
• player.identify(type) - client-side, show login interface for "facebook", "google", "steam" or "cognito", only works if not identifed yet (player.guest)
• player.movedpadvector - client-side, returns {x:number,y:number}, the current keyboard movement or movepad direction, {x:1,y:0} means movement to the right
• player.movebyvector({x:number,y:number}, speed:number [, slide:boolean]) - client-side, moves the player horizontally or vertically with the specified speed (in tiles per second)
• player.getsettings() - returns an object with the current player settings, works server- and client-side:

setting	description
soundsoff	Turn off sound effects
sfxvol	Sound effects volume
musicoff	Turn off background music
musvol	Music volume
hidehome	Hide the home button
hideminimap	Hide the minimap (on right side)
noministories	No guide videos on mini map
nomobilezoom	Zoom out the game (mobile)
zoom2x	Zoom in the game (desktop)
hidenames	Hide player names (show with N key)
hidesidekicks	Hide pets which follow other players
nohouseinvites	No house invitations
noclaninvites	No clan invitations
nosparinvites	No spar invitations
notradeinvites	No trade invitations
nolikemsg	No like notifications
nopmnotification	Don't show received messages
nopvpwarning	Don't display enter/leave PvP zone
noweather	Hide weather effects
nodaynight	No day-night cycle
noingametv	No TV videos
nofont	Simple game font
sortbytime	Sort items by time
fps20	Limit to 20 fps
buttonzoom	Button zoom
buttonspacing	Add button spacing
hitbox	Draw Hit Box/Circle
mode3d	3D view (experimental)

Offline players

DB.loadplayer returns an offlineplayer object if the requested player is currently offline. These player objects have limited attributes and functions:

• read-only: isonline, type, id, name, adminlevel, itemslocked, itemslockedorbyevent, namecolor, landtemplate, statusban, instagram, youtube, facebook, twitch, tiktok, injail, intrade, profilestoryid, map, x, y, coins, bombs, arrows, aniarg1..9, onlinetime, deaths, kills, streak, mobkills, sparwins, sparlost, level
• read-write: muted, title, weapon, body, head, hat, bow, mount, shield
• functions: getsettings(), isblocked(id), getachievementstatus(), setmap(map,template,x,y), addcoins(amount,reason), removecoins(amount,reason), hasunlimitedammo(), hasitem(itemid), getitemnr(itemid), getitems(type), additem(itemid,amount,options), removeitem(itemid,amount)