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, read only
- player.arrows: integer, read only, arrows or bullets for the equipped weapon or bow
- 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.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
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.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.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)