Configuration Guide

The /Config/ path contains several .json files which can be used to configure the game:

Admin Rights

"adminrights" is an array of objects defining the rights for each admin level. Individual rights can be configured in the admin account using file browser.

• type: number, the admin level
• commands: array of string, such as ["profile", "summon"], define which commands the admin can use (/profile, /summon), sometimes this is also used to enable the corresponding buttons in the admin menu (command "summon" enables the Summon button in the "Admin actions" menu, which is actually only setting the player chat to /summon params)
• paths: array of string, gives access to paths in the file browser, such as ["rw /Config/*", "rw /Admins/*", "rw /DB/*"]. Available paths are /Config, /Files, /Scripts, /Maps, /Admins and /DB.

Auto Spawns

"autospawns" is any array of objects defining what items to automatically spawn on certain maps:

• map: string, map name
• spawns: array of objects, example: {"spawntype":"trash", "npcclass":"trash", "markers":null, "itemnr":40}; npcclass must be "trash", "arrow", "movingcar" or "mob"; counts how many npcs of a built-in class exist, and spawns "itemnr" items of "spawntype" either randomly or at locations defined with the "markers" class

Bans

"bans" is an array of objects defining which players should be blocked from entering the game, can also be used to restrict access to new servers:

• active: boolean, default true, can be used to enable to disable certain rules
• message: string, text to display to the user
• disconnect: boolean, if the player should be disconnected
• showtoadmins: boolean, print the login attempt on admin console
• rules: array of objects {action:string, ip:"*" or [ips], os:"*" or [operating systems], userid:"*" or [player ids]}, action can be "allow" or "deny"

When deciding if a player should be allowed or denied access, then all matching rules will be applied one by one: checking if the ip, os and userid contain the player's ip, os (iOS, Android) or id, and depending on the action allow or deny. The last matching rule decides the fate of the player.

Building Zones

"buildingzones" is an array of objects defining which maps belong to a base / castle. The base themselves are currently defined in DB (game.buildings, read-only).

• template: string, the map name
• kickonlag: boolean, kicks players out from the map if the ping is higher than sparmaxlag from main.json
• baseentercooldown: number, doesn't let players enter the base / building immediately after dying for the specified number of seconds, works with npcclass baseentry
• zones: array of objects defining which parts of the map belong to which base / castle. This is usually the full map. Attributes are name: string, area: {x:number,y:number,w:number,h:number}, enterto and leaveto {mapname:string,templatename:string,x:number,y:number,w:number,h:number} wich specify the locations where /enter and /leave are leading to

Chat Commands

"chatcommands" is an array of objects defining what special animation is displayed when players type a certain chat command:

• command: string, the text to type, such s "hug"
• ani: string, the animation (bani file without .bani) which is shown when the player types the command

Client Config

Defines a variable "gameconfig" with the client-side parameters such as if the minimap is round, number of hotkeys and what upload types are allowed. Only parameters which are relevant and still supported are listed here:

• gamename: string, name displayed in the menu
• aboutme: string, text to be displayed in the default aboutme screen
• primaryweapon: string, default "sword", can be "gun" or "sword"
• defaultmapname: string, default "main", important for minimap and daynight mode
• filespath: string, pre-configured, CDN URL where the game files are located
• enablegrab: boolean, default true, invokes event onPlayerGrabs on NPCs in front of the player when pressing the secondary weapon button
• alwaysgrab: boolean, default false, disable placing bombs with the grab button
• enablebackpackani: boolean, default false, sets animation "backback_open" when opening the inventory
• enablesleep: boolean, default true, sets animation "player_sleep" when the player is on tiletype bed, on a NPC with animation option isbed, or NPC with image containing _bed
• enabletitles: boolean, default true, enables player.title display
• hotkeys: number, default 5, number of hotkeys, also needs css to display
• shiftchat: boolean, default false, tilts the chat a few pixels if enabled
• clearcolor: array of {red,green,blue} numbers, default [0.1568,0.1568,0.1568], instead of black background show a specific color such as darkgray
• uploadavailabletypes: array of strings, default ["HEAD", "BODY", "HAT"], specifies which graphics can be uploaded for the character look
• uploadpricehat: number, default 5000, price of hat uploads
• uploadpricehead: number, default 3000, price of head uploads
• uploadpricebody: number, default 3000, price of body uploads
• giftopprice: number, default 500, additional upload feed for gif images (animated gifs)
• clancreateprice: number, default 500, price for founding a new clan
• clanrenameprice: number, default 100, price for renaming a clan, if available
• clanmemberlimit: number, default 24, limit of the number of players which are able to join
• minimaparea: object, default {x:270, y:124, w:45, h:45}, part of the main map which should be displayed when the player is in a house
• minimapdynamic: boolean, default true, shows part of the map where the player currently is, instead of showing the whole map
• minimapround: boolean, default false, rounded minimap
• minimaphead: boolean, default true, display head graphics on the minimap
• noplayercount: boolean, default false, hide the online player number on the minimap
• noguimaps: array of strings, default ["ban"], lists maps where the normal interface should not be shown to players
• mapfullwindow: boolean, default true, specifies if the map should fill the whole screen
• extendedemoticons: boolean, default false, enables emoticons for keys B, E, G, R, Y
• emoticonoffset: object, default {x:-8, y:-75}, drawing offset for emoticons
• idlepose: string, default "player_idlepose1", animation to display after idleposetime seconds
• idleposetime: number, default 60, time how long the player must not move before the idle pose animation is shown
• randomatk2: boolean, default true, sets animation to "player_atk2" for 25% of cases
• searchcategories: array of strings, default ["hat","head","armor","loot","weapon","furniture","weaponskin"], specifies which item categories are shown in the search item window, for quicker access
• ignoremodtimefor: array of strings, default ["_hatc", "_headc", "_bodyc", "_clanlogoc"], don't add the file modification time to the link
• story.youtubelink etc.: string, html code for displaying Youtube videos, TikTok videos etc.
• enable360projectiles: boolean, default false, enables shooting in 360 degrees directions using the weapon pad
• clicktoshoot: boolean, false false, enables shooting on mouse click/tap, only works with enable360projectiles

Hitpoints

Defines the hitpoints for players and hitpoints and respawn times for monsters/mobs. This is also used by scripts via Server.getconfig("hitpoints", "type").index[this.monstertype]. The "hitpoints" array contains objects with following attributes:

• type: string, either "player", an npcclass such as "destructable", or monster type such as "ogre"
• hitpoints: number, initial and maximum hitpoints
• respawnmin: number, seconds after which to respawn
• respawnmax: number, maximum seconds after which to respawn
• spawnboss: number, after how many kills a "bosstype" monster should be spawned
• bosstype: string, the boss monster type to spawn
• noautorefillhp: boolean, doesn't heal the monster when this set to true

Houses

This is not used anymore, it has been replaced by just listing all objects of type "house" and "ladder".

In-App Purchases

This is not used anymore, now replaced with script events.

Main

The main server configuration. This is a nearly complete list. Some deprecated settings are not listed, such as for account creation.

• idletimeout: number, default 600, players are disconnected after this number of seconds
• offlineinactivetime: number, default 2592000 (1 month), after this time the player is not receiving notifications anymore
• notificationspamtime: number, default 43200 (1/2 day), delay before sending another Facebook notification
• notificationspamtimeios: number, default 60, minimum delay between two push notifications
• mindelaymailing: number, default 3600, delay before allowing another mass push notification by admins
• tilesize: number, must be 32, tile unit in pixels
• zoneWidth: number, default 26, width of one synchronisation zone on the map
• zoneHeight: number, default 16, height of one synchronisation zone on the map
• defaultmapname: string, default "main", map for start and unstick
• defaultx: number, default 128, horizontal position for start and unstick
• defaulty: number default 128, vertical position for start and unstick
• reviveatstart: boolean, default false, lets the player restart at the start position instead of same place as before, can be prevented by buying unlimitedrevive items
• startbombs: number, default 5, how many bombs to receive on first login
• startcoins: number, default 30, how many coins to receive on first login
• startarrows: number, default 0, how many arrows/bullets the player has when starting
• startmessage: string, is shown to the player on first login
• isgunserver: boolean, default false, specifies whether guns are the default weapon
• maxarrows: number, default 30, maximum number of arrows/bullets the player can hold
• maxbombs: number, default 99, maximum number of bombs the player can hold
• nopkinhouses: boolean, default true, prevents pvp in "inside" maps
• pkinsides: array of maps, exampl: ["halloween_inside"], allow player killing in these inside maps
• pkprotecttime: number, default 5, how many seconds to protect players after login or being killed previously
• pkmindelay: number, default 0.2, don't allow two consecutive attacks in this time span to avoid instant kills
• unstickdelay: number, default 10, wait this number of seconds before using /unstick on pvp maps
• maxhousesperplayer: number, default 3, how many houses a player can build/own at the same time
• playerhouseenterpos: example: [64, 64], default x and y position when entering a house
• clanhouseenterpos: example: [64, 64], default x and y position when entering a clan house
• preloadmaptemplates: array of maps, example: ["newmap","main","jail","inside"], preload maps even if no player is on the map, to prevent loading delays
• sparmaxlag: number, example: 1500, in milli seconds, maximum lag in spar and events before a player is kicked
• dontcountinvitespars: boolean, defines if spars by invitation should count towards the total spar score
• sparpracticemaps: array of map names, spar wins/losses are not counted here
• warpmaps: array of map names, example: ["inside_furnitureshop"], special maps which you are allowed to warp to from any other map (to buy furniture for your house)
• dontunloadmaps: array of maps, maps which should not be unloaded from memory even if there are no players
• allowplayerlandwarp: boolean, default true, if players are allowed to right-click warp on their own player land
• jailmaps: array of maps, example: ["jail"], maps which are considered to be jails and prevent certain features such as warping, sending PMs etc.
• jailenterpos: example: [64, 64], x and y position where to enter on the jail map
• banmaps: array of maps, example: ["ban"], maps where no interface is shown for the player and most features are disabled
• banenterpos: example: [15, 10], x and y position on ban.json map
• iconsonminimap: boolean, default true, weither to show player icons on the mini map
• lootprotecttime: number, default 10, number of seconds after which all players can pick up dropped items, not just players who have hurt a monster
• castleflagbyprojectile: boolean, default false, if the castle/base flag can be destroyed using projectiles
• castledisablesnow: boolean, default true, weither snowballs should be disabled on castles/bases
• zoneownerleaveondeath: boolean, default false, if the base owner should be warped out of the base when dying
• offlinepms: boolean, default true, if it should be possible to message offline players
• adminwelcomemessage: string, default "Welcome to the Admin Console of Avalonia Online!", message shown in the admin console when opening
• allowtrade: boolean, default true, weither to allow trading between players
• allowtradeuploads: boolean, default true, weither to allow trading of uploaded customs
• adminlevelhighstealth: number, default 7, which adminlevel allows /stealth high
• autorefillhp: boolean, default false, decides if players should auto-heal
• uploadavailabletypes: ["HAT", "HEAD", "BODY"], allowed upload types (needs to be additionally allowed on client config)
• giftopprice: number, default 500, additional coins required when uploading gif customs
• clancreateprice: number, default 500, price for creating a clan
• clanrenameprice: number, default 100, price for renaming a clan
• clanmemberlimit: number, default 24, limit for how many members can join a clan at the same time
• clandisbandbonus: number, default 200, price for disbanding a clan (currently not possible)
• clannameminimumlength: number, default 3, minimum length of clan names
• clanrenametimeaftercreation: number, default 604800, in seconds, disallows renaming of clans after this time, it will then require an admin to rename it
• clantransfertimeaftercreation: number, in seconds, disallows transfer of leadership after this time if configured
• addcoinslimit: number, default 9999999, limit for the /addcoins command
• hideaddcoinsmessage: boolean, default false, doesn't show a message to the player when calling player.addcoins
• youtubelink: string, html code for youtube videos in status
• instagramlink: string, html code for instagram stories in status
• facebooklink: string, html code for Facebook posts in status
• tiktoklink: string, html code for TikTok videos in status
• twitchlink: string, html code for Twitch videos in status
• scriptnpcimage: string, default "bbuilder_stone1.png", image used for /scriptnpc
• availablespawnmonsters: array of string, default ["guard","ogre"], allowed monster types for /addmonsters type, which is adding a spawner at the current position
• allowmobspawninnonpvp: boolean, default false, let's you spawn mobs in non-PvP zones with autospawns.json
• disablemapstories: boolean, default false, if automatic display of guides based on map position should be disabled
• iseaster: boolean, default false, enables the display of eggs in profile
• eastereggitem: array of itemid, example: ["egg2021x1", "egg2021x2", "egg2021x3"], when defined then it will count how many of these items the player owns and shows it in the player profile
• isxmas: boolean, default false, enables the display of xmas item count in profile (can also be other currencies)
• xmascurrency: string, example: "shrimps", the item count to show in player profile
• eventcurrency: string, example: "eventcoin", the event item count to show in player profile
• sharecurrency: string, example: "nitrocoin", the nitro item count to show in player profile
• allowedscores: array of string, default ["kills", "mobkills", "spar"], which scores are counted and stored in database, add additional score types for use with player.addscore
• disablemobprofile: boolean, default false, weither to disable tap/click on monsters to show a monster profile
• languages: array of string, example: ["de","es","fr"], translated server languages (in the Translations git project)
• statusoptions: object, example: { "allowedTags": ["h3"], "allowedAttributes": { "*": [ "style" ]}}, which html tags are allowed in status, and which attributes are allowed in html tags
• defaultarmor: string, default "clotharmor", which body item to start with
• defaultweapon: string, default "sword1", which weapon to start with
• defaulthead: string, default "bbuilder_head1.png", which head graphics to start with
• defaulthead_female: string, default "bbuilder_head2.png", default head graphics for female players (if gender is known)
• defaulthat: string, which hat to start with
• deathanimation": string, default "player_death3", animation to show when the player dies
• startitems": array of itemid, default ["clotharmor", "sword1", "head1", "head2", "fist"], items the player gains when starting the game
• startitemsbyos: object with arrays for each OS, default {"iOS":["ioshat"],"Android": ["androidhat"]}, can be used to give special OS additional started hats, to incentivise downloading the app on other platforms
• weaponunequipitem: string, default "fist", which item to equip when unequipping a weapon
• equipcooldownms: number, default 1500, milli seconds between switching weapons
• playerscriptclasses: array of string, default ["player_events"], script classes which player objects should automatically join to handle specific player events
• bombcooldown: object, default {"nr": 5,"timems": 3000}, specifies how many bombs you can plant in a specific time (milli seconds)
• basechangetagcooldown: number, doesn't let players enter the base / building again for some seconds after changing the clan tag, works with npcclass baseentry
• enablenewguestaccounts: boolean, default false, allows playing before registering
• guestfeatures: object of type {chat:boolean, pvp:boolean}, defines if guest accounts can chat or PvP
• enableproxycheck: boolean, default false, enables the proxy check for player.proxy and player.vpn
• servermovementfps: number, enables player movement interpolation on server for better melee detection, possible values 20, 30, 60
• servermeeleeglobal: boolean, default false, enables server-side melee hit detection on all maps
• servermeeleemaps: array of map names, enabled server-side melee hit detection on specific maps
• disablemobkillmessage: boolean, default false, disables the message "You've defeated the..."

Map Markers

"mapmarkers" is an array of objects defining what map image and what icons on the map should be displayed:

• title: string, a custom display name for the map
• template: string, the map template name
• bigmap: string, the map image to be used for the M map and minimap (if dynamic map as on Corleone Online)
• markers: array of {x:number,y:number,text:string,icon:string}, the position must be defined in tiles coordinates (/getposition) not pixels, the icon must exist in the /Files/gui/ folder

Menu Buttons

"menubuttons" is an array of objects defining available menu buttons (for the "main" menu) and additional scripted buttons. Also see Menu Buttons.

• menu: string, either "main", "admin", "profilemore", "adminactions", "clans", "manageclan", "claninfo"
• buttonid: string, reference build-in menus such as "about" or custom scripted buttons
• image: string
• text: string, button name
• help: string, text shown when hovering the button with the mouse
• scriptclasses: array of strings, example: ["menu_viewclanland"], list of client scripts which receive the onActivated(player, data, newmenu, oldmenu) event once the button is tapped/clicked
• conditions: array of strings, button is only shown on specified platforms or when system features are available, can be a combination of: "facebook", "filereader" (system supports file upload), "ios", "!ios", "android", "!android", "steam", "!steam", "mobile", "!mobile", or any variable defined in the data parameter for GUI.addmenubuttons.

Mob Status

"mobstatus" is an array of objects defining the status in the profile shown when you tap/click on a monster:

• status: string

Monsters

"monsters" is an array of objects defining the look and weapons of certain monsters types:

• type: string, id (name) of the monster
• title: string, displayed name of the monster
• attacktype: string, can be "sword", "mobsword", "shark", "sharkswim", "crab" (melee monsters) or "gun" and "bow" (projectile shooting monsters)
• zoom: number, default 1, can increase or decrease the size of the monster
• armor, head, hat: string, look of the monster (armor=body)
• idle, walk, atk, hurt, look, death: string, overwrite the default animations
• weapon: string, weapon of the monsters
• bow: string, weapon of the monster if attacktype is "bow"
• melee: string, if attacktype is "gun" or "bow" and the player is close, then this melee weapon will be used to attack the player
• runawayhp: number, default 0, the monsters prefers to run away from the player if the hitpoints are below this value
• istempspawn: boolean, default false, set to true to have the monster being removed after 30 seconds, you can also specify spawnlifetime (seconds)

Nopk Zones

"nopkzones" is an array of objects defining places where players cannot hurt or kill each other:

• template: string, the map name
• zones: array of objects {x:number,y:number,w:number,h:number}, the area of the map where playerkilling (pk) is disabled

Player Anis

"playeranis" is an array of objects defining which animations are allowed to be used by client-side. This is also used for optimisation, so that we don't need to send the full animation name each type a player animation is changed.

• animation: string, the animation name (without .bani extension)
• code: number, an unique number identifying this animation, should be increased by 1 for each new animation added

Projectiles

"projectiles" is an array of objects defining the projectile templates:

• type: string, example: "arrow", identifier of the projectiles to be used in gun items
• image: string, example: "arrow_idle.bani", image or animation to be displayed
• arrow: string, example: "bbuilder_arrow1.png", the ARROW parameter in the projectile animation
• zangle: number, example: 0.8, upwards movement (z axis) of the projectile
• gravity: number, example: 0.03, reduces zangle by this amount each second
• speed: number, example: 9, how far the projectiles moves each second, in tiles units (32 pixels)
• hittype: string, example: "arrow", if this is "arrow" or "bullet" then it hurts the player/object, if it's "snow" then it freezes the player on impact
• hitlevel: number, example: 8, similar to sword level if this is type "arrow" (2 levels stronger than sword)
• damage: number or array, example: [8,12], defines how much damage the projectile causes on impact
• damagestackable: boolean, if true then the damage can be applied several times in short time (shotgun)
• collidetiles: boolean, specifies if this projectile should stop at walls
• impact: object, example: {damage: [12,18], radius: 2, explosions: [ [0, 0] ]}, damage when the projectile lands or hits a wall; {spawn:string} is spawning items (from spawns.json); {scriptclasses:[string]} adds a scriptnpc at the impact position with the specified scriptclasses

Script Sync Vars

"scriptsyncvars" is an array of objects defining which attributes of players and NPCs should be saved to database and sent to the client (players browser):

• type: string, either "player", "npc" or "map"
• save: array of variable names to save to database (to make the variables permanent)
• client: array of variable names to sent to the client

Spawns

"spawns" is an array of objects defining what items to spawn when players or monsters are killed:

• type: string, examples: "player", "ogre" or "shovelloot", the spawn type
• items: array, example: [{"itemid":"firework1", "chance":6}], the items to spawn, with itemid and either "chance" (percentage) or "min" and "max" items to spawn, optional "from" of how many items must exist before any are dropped

Swear Words

"swearwords" is a simple array of objects defining disallowed chat words and where to check them:

• text: string, the text to check for (no wildcards at this moment)
• action: string, always "warning"
• scope: either "all" or array of text types to check this in, full list would be ["chat", "pm", "clanpm", "name", "news", "rank", "status", "story", "trade"]
• maxonlinetime: number, if you only want to show it to new players then specify here the number of seconds until which this word is locked, such as: 3600 for only disallowing the word for players with less than one hour of onlinetime

Tile Jobs

"tilejobs" define parameters for certain jobs. Used in the weapon_shovel script, using Server.getconfig("tilejobs", null, "weapontype").categories["shovel"]. Currently used attributes:

• active: boolean, default true
• maps: array of string, on which maps you can use the shovel
• tiledefinitions: object, array of tiles accepted for each tile image
• debris: object, example: {"image": "corleone_grasshole.png", "lifetime":5}, hole npc to put at the digged place
• blocktime: number, in seconds, don't dig on the same place for a certain time
• chance: number, in percent, of the job succeeding
• spawn: string, items to spawn

Weather Zones

"weatherzones" is an array of objects defining what animation effects (bani) to display on certain maps and areas:

• map: string, map name
• zones: array of objects, example: {"x":0, "y":0, "w":134, "h":84, "weather":"weather_snow"}, define areas of x, y, w(width), h(height) and the bani to display (weather)

Items Guide

The /Config/items path contains several .json files which can be used to configure the game items:

Items can be stored in different folders and are saved in the .json format. For example an arrow would be stored like so: /Config/items/arrow/arrow1.json.

There are more attributes depending on type, and can be access by scripts with player.weapondata.

Item Attributes

• itemid: string, unique item id, must match the file name
• name: string, item name
• image: string, image url, located in /Files/npcs
• icon: string, image url for inventory icon, located in /Files/icons
• price: number, default price of the item
• sellprice: number, price of item to be sold by the player
• itemtype: string, examples: "hat", "head", "weapon", "bomb", "bow", "valuable", "unlimitedammo", "unlimitedrevive", type of item used in sorting and placing item into a folder in the players inventory
• weapontype: string, subtype of weapon, examples: "sword", "bow", "gun", "script", "item", "torch", influences the behaviour how the weapon is equipped and in which item folder it is shown
• description: string, items general description that can be viewed in the shop npc
• scriptclasses: array of strings, example ["weapons/bugnet", ...], list of client scripts which receive the onActivated(player, data) event once the item is equipped
• stackable: boolean, default false, allows an item to stack (keep more than one in inventory)
• stacklimit: number, default 1, how many of this the player can keep in inventory
• allowtrade: boolean, default true, allows or disallows the item to be traded in game
• isbreakable: boolean, default false, removes the weapon once usecount times of using the item
• nobreakmessage: boolean, default false, don't show a message when breaking the weapon
• unlimitedtime: number, defines how long the unlimitedammo or unlimitedrevive effect lasts
• lightradius: number, default 1, for weapons, expands the radius of the cutouthole effect on maps, use 2 to double it
• statsvariable: string, for npcclass dropitem, specifies which score type is added when you pick up an egg or similar
• nomobkills: boolean, doesn't increase player.mobkills when the player kills this NPC/mob/monster
• projectile: string, the gun/bow projectile
• altprojectiles: array of string, alternative projectile types which can be shot by client-side scripts

Example Arrow Item Config

See even more examples at Item Creation.

{
    "itemid": "arrow1",
    "name": "1 Arrow",
    "image": "bbuilder_icon_arrow1.png",
    "icon": "bbuilder_icon_arrow1.png",
    "price": 1,
    "itemtype": "arrow",
    "limitpickup": 1
}