Player

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 onHurt(attacker, damage) - Called when the player receives damage; return {cancelled:true} to block the damage or {cancelled:false} to allow it.
function onDeath(killer) - Called when the player dies; check killer.type == "player" to determine if the killer was a player.
function onDamage(target, damage) - Called when the player deals damage to a target. Return an object like { damage: damage, cancelled: cancelledValue } to modify the damage or cancel the event.
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 onSparWin(loserid, loserinfo) - 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
function onEquipPet(item) - called on server when the player equips a pet
function onCarEnter(itemid) - called on server when the player gets into a car (a mount with mounttype "car")
function onCarExit(itemid) - called on server when the player gets out of a car
function onCarTaken(parkedbyid, itemid) - called on server when the player takes over a parked or NPC car; parkedbyid is the user id of the player who left the car there, or null
function onTradeFinished(otherplayer, mycoins, myitems, othercoins, otheritems) - called on server for both players when a trade completed
function onAttackTriggered(currenttime, lastattacktime) - called on server when the player triggers an attack
function onTransferAccount(fromid, toid) - called on server when an admin uses /transferaccount
function onCompletePayment(productid, isvalid, istest) - called on server after a purchase when main.json completepaymentbyscript is enabled
function onLoadPaymentPackages(platform, mincoins) - called on server when the client requests the coin packages, answer with player.sendpaymentpackages(data)

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.scriptclasses: array, read-only, list of script classes assigned to the player
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.mask: string, itemid of the current mask
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), 2 (medium stealth) and 3 (high stealth); stealth is only allowed for players with adminlevel > 0, medium stealth only for adminlevel >= adminlevelmediumstealth and high stealth only for adminlevel >= adminlevelhighstealth (main config); values above the player's allowed level are capped
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.profilestoryid: integer, read-only, the story id from the player's profile
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.itemset: string, A temporary inventory property that allows creating a new inventory for the player by assignment, which can be reset to the original inventory by setting to null.
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.screensize: array, server-side, is the screen size of the player (width, height)
player.friends: array, server-side list of player ids of the player's friends
player.followconsolechat: boolean, server-side, true if the admin has opened the admin console and is following the console chat
player.pet: object, a pet item which is currently equipped by the player
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 (text chat, PMs and voice chat); setting it turns a permanent mute on or off
player.mutetimeleft: number, server-side, read-only, seconds until a timed mute ends, -1 = permanent, 0 = not muted
player.mutereason: string, server-side, read-only, the reason given for the current mute
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
player.istalking: boolean, server-side, read-only, true while the player has the chat input open (e.g. to wait for the rest of a sentence)
player.blockedplayers: array, server-side, read-only, ids of the players this player has blocked
player.cardamage: string, server-side, read-only, visual damage of the car the player is driving as hex string (8 characters per impact), null if undamaged; see player.repaircar()
player.escortpassenger: number, server-side, read-only, user id of the player riding on the back seat of the player's car, or null
player.maskimage: string, client-side read only, full image URL of the current mask
player.ammocount: number, client-side read only, ammo of weapons whose projectile has an ammotype (see also player.arrows)

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.tradinglocked: boolean - Gets or sets whether the player's trading is locked. Assign true to prevent the player from initiating or participating in trades, or false to allow trading. This property can be read (returns a boolean) or set as needed.
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.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.setchat(text:string) - sets the chat text for the player
player.say(text:string [, delay:number]) - makes the player say text with optional delay (default 5 seconds)
player.setzoom(value:number) - sets the zoom level for the player
player.setbody(itemid:string) - sets the body armor for the player
player.sethead(itemid:string) - sets the head item for the player
player.sethat(itemid:string) - sets the hat item for the player
player.setmask(itemid:string) - sets the mask item for the player
player.setbow(itemid:string) - sets the bow item for the player
player.setmount(itemid:string) - sets the mount item for the player
player.setshield(itemid:string) - sets the shield item for the player
player.setweapon(itemid:string) - sets the weapon item for the player
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.visitclanland(clanid) - visits the clan land of the specified clan id
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]) - server-side, invokes onServerACTION on the client-side part of the player scripts (by default player_events.js)
player.triggerserver(action:string [, ...parameters]) - client-side, invokes onClientACTION 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.addfriend(id) - server-side, adds a player to the friends list
player.removefriend(id) - server-side, removes a player from the friends list
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.sendpaymentpackages(data:object) - sends payment packages data to the player
player.identify(type) - client-side, show login interface for "facebook", "google", "steam" or "cognito", only works if not identifed yet (player.guest)
player.movepadvector - 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.setcamerazoom(params:object) - client-side, smoothly adjusts camera zoom. Parameters: zoom (0.25–4.0, default 1.0), speed (0.001–1.0, default 0.05), zoomSpeed (overrides speed for zoom only), instant (boolean, skip transition), priority (number, default 0), blend (0–2.0 seconds, default 0.22).
player.resetcamerazoom() - client-side, restores the camera zoom to the level it was at before any script-applied zoom
player.preloadasset(assets:string|array) - client-side, preloads one or more asset files before they are needed. Supports .bani (animations), .png/.jpg/.gif (images), and .wav/.mp3/.ogg (sounds).
player.scheduleevent(delay:number, event:string [, ...params]) - client-side, schedules a named event to fire after delay seconds; triggers onEVENT on the player script
player.cancelevents(event:string) - client-side, cancels all pending scheduled events with the given name
player.sleep(delay:number) - client-side, pauses script execution for delay seconds (script-manager sleep)
player.attack() - client-side, triggers the player's current attack action and activates nearby NPCs in the current direction
player.getsettings() - returns an object with the current player settings, works server- and client-side:
player.setsettings(options:object) - updates the player's settings using a configuration object (server-side). Includes validation against allowed parameters.
player.hotkeys - object (server-side), gets all saved hotkey configurations for the player.
player.sethotkey(key:number, itemid:string) - server-side, saves an item to the specified hotkey slot number.
player.mute(seconds:number [, reason:string, admin:player]) - server-side, mutes the player for text chat, PMs and voice chat; seconds 0 = permanent; timed mutes end automatically; the optional admin player is stored as the one who muted
player.unmute() - server-side, ends a mute
player.cleareffect() - removes the current effect (see player.seteffect)
player.getachievementstatus(): object - server-side, returns the achievement status {title, logo} shown for the player, or undefined
player.setachievementstatus(title:string, logo:string) - server-side, sets the achievement status; call with null values to remove it
player.pingmap(x:number, y:number [, text:string]): boolean - server-side, marks a spot on the minimap / map screen for the player's friends and clan members for a few seconds (text max 40 characters); limited by mappinginterval in main.json
player.repaircar() - server-side, repairs the visual damage of the car the player is driving (e.g. for a body shop NPC)
player.hideplayer(userid:number): boolean - server-side, hides another online player for this player only
player.showplayer(userid:number): boolean - server-side, shows a player again that was hidden with hideplayer
player.isplayerhidden(userid:number): boolean - server-side, checks if a player is hidden for this player
player.grantlandpermission(userid:number): boolean - server-side, allows another player to move furniture on this player's land; the player must be on their own playerland
player.revokelandpermission(userid:number): boolean - server-side, removes a land permission granted before
player.haslandpermission(ownerid:number): boolean - server-side, checks if this player is allowed to move furniture on the land of the specified owner
player.getlandpermissions(): array - server-side, returns the user ids which have permission on this player's land

setting	description
soundsoff	Turn off sound effects
sfxvol	Sound effects volume
musicoff	Turn off background music
musvol	Music volume
hideminimap	Hide the minimap (on right side)
noministories	No guide videos on mini map
gamezoom	Game zoom (0.4 - 2.5)
clientmaxfps	Max FPS (20 - 360)
smallsync	Only show players near you
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
buttonzoom	Button zoom (0.5 - 2)
buttonspacing	Add button spacing
notranslate	Turn off translation
floatingmovement	Touch anywhere to move (mobile)
newfont	New text font
notileanimations	Disable tile animations
hitbox	Draw Hit Box/Circle
mode3d	3D view (experimental)
voicechat	Voice chat on (starts automatically on voice chat maps)
voiceoff	Voice chat off
voiceinvol	Microphone volume (0 - 2)
voicevol	Voice chat volume (0 - 2)
houseopen	House is open for visitors

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, clanname, adminlevel, mutetimeleft, mutereason, 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), mute(seconds,reason,admin), unmute(), 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)