Skip to content

Server

Server Reference#

Attributes#

  • Server.playercount: number
    Current count of players that are logged in to the game.
    Note: Now returns the number of players excluding "ghosts" (not logged in/just viewers).

  • Server.totalplayercount: number
    Current count of players connected to the server.
    Note: This is the total number of players including ghosts/viewers.

  • Server.uptime: number
    In seconds, time since start/restart of the server process.

Functions#

  • Server.searchplayers(options:{}) - returns an array of players which match the options. Possible combinations for options are: {id:number}, {map:string}, {map, area:{x,y,w,h}}, {clanname:string}, {clanid:integer}, {map:string, clanname:string}, {map:string, clanid:integer}, {} (full server)
  • Server.searchPlayers(options:{}) - alias for Server.searchplayers() with capital P, same functionality

Example:

function onPlayerTouchsMe(player) {
  // Find all the players on the map with the same clan name as the player that has touched the object
  const players = Server.searchPlayers({ map: player.map.name, clanname: player.clanname });

  // A message to show the players it has found with the above criteria
  this.say(`Found ${players.length} members of ${player.clanname} (${player.clanid})! List on console.`);

  // Loop through all the players it has found and set their chat
  players.forEach(online => {
      online.chat = "Found"; // Make the player say 'Found' if they meet the criteria above
  });
};
  • Server.searchnpcs({map, area:{x, y, w, h} }) or alternatively {id:ID} or {name:NAME} (name search right now only returns a single NPC)

Example:

function onUpdated(player) {
  const npcs = Server.searchnpcs({
    map: this.map,
    area: { x: this.x - 20, y: this.y - 20, w: 40, h: 40 }
  });

  for (const npc of npcs) {
    npc.scheduleevent(0, 'otherEvent', this);
  }
}

// Add the onOtherEvent function to the other NPCs to see them triggered.
function onOtherEvent(caller) {
  echo('called NPC: ' + this.id + ' from ' + caller.id);
}
  • Server.getconfig(filewithoutextension: string [, indexAttribute] [, categoryAttribute]) - loads a configuration file (fast), the configuration should have the structure {filename:[objects]}, the returned object also contains ways for quick lookup: objects: array of all objects, index[name] one object, category[name] array of objects
  • Server.getyamlconfig(filewithoutextension: string) - loads and parses a YAML configuration file (.yaml) from the configuration folder into a javascript object. The results are cached for faster access. Example: let data = Server.getyamlconfig("mysettings");
  • Server.addenvironmentzone(id:string, environment:object [, durationms:number]): boolean - adds a temporary environment zone, environment is {x, y, w, h, weather:string or array of strings, map, template, name}; the zone is removed automatically after durationms if specified (max. 100 temporary zones), players inside get onEnvironmentZone (Example: Environment Zones)
  • Server.removeenvironmentzone(id:string): boolean - removes a temporary environment zone
  • Server.getenvironmentzones() - returns an array of currently active environment/weather zones globally.
  • Server.addweatherzone(id:string, weather:string, zone:{x,y,w,h}, map:string [, template:string, durationms:number]): boolean - shortcut for addenvironmentzone with a weather animation
  • Server.removeweatherzone(id:string): boolean - same as removeenvironmentzone
  • Server.getweatherzones() - returns the currently active weather zones
  • Server.jailplayer(userid:number, duration:number, reason:string) - jails a player (online or offline) like /jail, a duration of 0 unjails
  • Server.getitemlist(itemtype: string) - shortcut to load categories of items, returns an array
  • Server.getitemconfig(itemid: string) - shortcut to load an item

Server.getconfig/getitemconfig examples:

echo("default weapon: " + Server.getconfig("main").defaultweapon);
  -> sword1
echo("config skeleton: ", Server.getconfig("monsters", "type").index["skeleton"]);
  -> { type: 'skeleton', name: 'Pirate Skeleton', ...}
echo("config item nr: " + Server.getconfig("items", "itemid", "itemtype").objects.length);
  -> 591
echo("config weapon nr: " + Server.getconfig("items", "itemid", "itemtype").categories["weapon"].length);
  -> 97
echo("config weapon nr simple: " + Server.getitemlist("weapon").length);
  -> 97
echo("config sword1: ", Server.getconfig("items", "itemid", "itemtype").index["sword1"]);
  -> { itemid: 'sword1', name: 'Standard Sword', itemtype: 'weapon', ...}  
echo("config sword1 simple: ", Server.getitemconfig("sword1"));
  • Server.message(message:string [, options:object]) - displays a message for all players, similar to /servermessage; options parameter can include {name:string, head:string, hat:string} for the optional look of the admin/sender
  • Server.sendnotification(playerid:number, title: string, message: string) - sends a push notification to the (offline) player
  • Server.sendmailing(title, message [, callback]) - sends a push notification to all players with push notification, use a callback function or await to get the error or "success". Messages will be blocked if you send too quickly (setting mindelaymailing in the main server options)
  • Server.setambient(red:number, green:number, blue:number) - sets the current ambient color for all players (day-night-effect)
  • Server.getmap(map:string) - returns a map object if already loaded
  • Server.loadmap(map:string, template:string) - forces loading of a map, uses the specified template if it's not already loaded
  • Server.openai(messages: array of objects [, model]) - contacts ChatGPT, can be used to answer user messages or similar, messages is an array of {role:string, content:string}, only works if an openai key is configured for the server; the default model is configured with openaimodel in server.json (default "gpt-6-luna"), reasoning effort with openaireasoningeffort. This function must be called with await inside an async function. See the example.