See also: FieldTypes

AllCastles

This function returns an array of MapCastleBean objects within an area. The first fieldId will be the northwest (top left) most corner of the area. The second fieldId will be the southeast (bottom right) most corner of the area. Both values must be field id not coordinates.

This example returns an array of all MapCastleBean objects within the state of Friesland:

• scanrec 0,0 199,199
  castles = AllCastles(GetFieldId(0,0),GetFieldId(199,199))
  
  Result:
  Too long to post, just try it ;)

This example will return an array of all MapCastleBean objects within a specified distance. Like a radius but in a rectangle...

• distance = 5
  execute "rescanrec {city.x - distance},{city.y - distance} {city.x + distance},{city.y + distance}"
  castles = AllCastles(GetFieldId(city.x - distance,city.y - distance),GetFieldId(city.x + distance , city.y + distance))
  
  echo "There are {castles.length} cities within {distance} miles of {city.name}({city.coords})." 
  
  label next
  info = castles.shift()
  if info == null end
  echo  "Coord: {FieldIdToCoords(info.id)}, Username: {info.userName}, Alliance: {info.allianceName}, Prestige: {info.prestige}"
  goto next
  
  Result (debug off to reduce confusion/spam):
  12:58:08 SCAN COMPLETED: 455,350 465,360
  12:58:09 There are 6 cities within 5 miles of MyCity(460,355).
  12:58:12 Coord: 455,353, Username: Bob, Alliance: null, Prestige: 4991
  12:58:16 Coord: 457,353, Username: Fred, Alliance: null, Prestige: 8060
  12:58:20 Coord: 459,357, Username: George, Alliance: null, Prestige: 10847
  12:58:24 Coord: 457,358, Username: George, Alliance: null, Prestige: 10847
  12:58:28 Coord: 464,360, Username: Harry, Alliance: null, Prestige: 0
  12:58:32 Coord: 460,355, Username: YayMe, Alliance: 123456, Prestige: 14517826
  12:58:35 Script stopped

FieldIdToCoords

This function converts a field id into coordinates.

This example finds the coordinates of a field id:

• fid = 284460
  echo FieldIdToCoords(fid)
  
  Result:
  14:58:01 Starting script
  14:58:01 Running line 1
  14:58:01 fid = 284460
  14:58:02 Running line 2
  14:58:02 460,355
  14:58:03 Script stopped

FindField

See also: FieldTypes

This function can find objects on the map within a specified radius of the searching city. You can for example use FindField to generate a list of all players near you, or all npcs level 10 within 20 miles, or whatever. The FieldTypes usable with FindField are linked above. The level is optional and can be omitted, or you may use "0" for any level. You can echo the results directly, or find and manipulate them from $result.

This example finds all the flats within a specified radius around your city, then echos the level of each:

• radius = 20
  execute "rescanmap {city.coords} {radius}"
  flats = FindField(city.x,city.y,radius,10)
  echo "There are {flats.length} flats around {city.name} ({city.coords})."
  
  label checkFlat
  thisFlat = flats.shift()
  if thisFlat == null end
  echo  "Coord: {FieldIdToCoords(thisFlat)} is a level {GetLevel(thisFlat)} flat."
  if flats.length goto checkFlat
  
  Result (debug off to reduce confusion/spam):
  17:02:45 SCAN COMPLETED: 422,319 radius 20
  17:02:46 There are 12 flats around MyCity (422,319).
  17:02:49 Coord: 410,321 is a level 3 flat.
  17:02:53 Coord: 414,320 is a level 5 flat.
  17:02:57 Coord: 414,327 is a level 4 flat.
  17:03:01 Coord: 419,331 is a level 9 flat.
  17:03:05 Coord: 421,306 is a level 1 flat.
  17:03:09 Coord: 422,309 is a level 3 flat.
  17:03:13 Coord: 423,301 is a level 2 flat.
  17:03:17 Coord: 423,308 is a level 1 flat.
  17:03:21 Coord: 424,301 is a level 10 flat.
  17:03:25 Coord: 424,311 is a level 3 flat.
  17:03:29 Coord: 425,302 is a level 9 flat.
  17:03:33 Coord: 425,306 is a level 1 flat.
  17:03:35 Script stopped

This example gets a list of all npcs level 10 within 20 miles of your city, and then sorts them into an array of nearest to furthest from your city. Note - these are fieldIds not coordinates. You can turn the fieldIds into coordinates using FieldIdToCoords

• list = FindField(city.x,city.y,20,12,10).sort(city.compareByDistanceToCastle)
  echo list
  
  Result:
  17:09:36 251614,250815,250014,250813,251613,250015,252412,254818,246020,250823,243621,247602,237221,244396
  17:09:37 Script stopped

FormatDistance

This function finds the distance between two field ids and displays it in a nice readable format.

Basic example:

• echo FormatDistance(12345,23456)
  
  Result:
  15:27:46 Starting script
  15:27:46 Running line 1
  15:27:46 90.09 miles
  15:27:47 Script stopped

This example finds the distance between your own city and a target coordinates:

• targ = "123,456"
  targetId = GetFieldId(targ)
  distance = FormatDistance(city.fieldId,targetId)
  echo "Distance from {city.coords} to {targ} is {distance}.
  
  Result:
  15:29:56 Starting script
  15:29:56 Running line 1
  15:29:56 targ = 123,456
  15:29:57 Running line 2
  15:29:57 targetId = 364923
  15:29:58 Running line 3
  15:29:58 distance = 351.80 miles
  15:29:59 Running line 4
  15:29:59 Distance from 460,355 to 123,456 is 351.80 miles.
  15:30:00 Script stopped

GetDetailInfo

This function is used to get detailed information about a field id. Field id is required as a parameter, priority, expire seconds, and compare seconds are optional.

Priority is a true/false value to determine whether to place a request to the top of the queue for faster processing. It is only used if we have to queue update request. The default is false.

ExpireSeconds is how long since map data was last updated until the bot considers data "expired". This uses current time or value of "now" parameters as described below. The default is 0. If data is considered expired, the bot will queue an update request as needed.

CompareSeconds is the timestamp used to compare with for ExpireSeconds. The bot uses the current time if this is set to 0. The default is 0.

This example returns previously cached map data if we have it cached less than 30 seconds ago (then it returns null, and auto-requests map update)

• id = GetFieldId(123,234)
  data = GetDetailInfo(id, false, 30) 
  data = GetDetailInfo(id, false, 0, date().getTime() - 30000) // same as the line above

The above would make "data" into a variable containing the MapCastleBean object for that field id, which you could then reference, for example:

• id = GetFieldId(123,234)
  data = GetDetailInfo(id, false, 30) 
  if data == null repeat // repeat above if the map detail info is not available yet
  echo data.name
  echo data.id
  
  Result:
  16:17:39 Grassland
  16:17:40 187323
  16:17:41 Script stopped

Or you can even echo the entire object with all it's properties like so:

• id = GetFieldId(123,234)
  data = GetDetailInfo(id, false, 30) 
  if data == null repeat // repeat above if the map detail info is not available yet
  echo json_encode(data)
  
  Result:
  16:16:54 {"id":187323,"prestige":0,"furlough":false,"name":"Grassland","lastUpdated":1419714992381,"changeface":0,"canLoot":false,"honor":0,"playerLogoUrl":null,"canScout":true,"zoneName":"LOWER LORRAINE","canOccupy":true,"state":1,"npc":false,"userName":null,"canTrans":false,"flag":null,"allianceName":null,"relation":6,"canSend":false}
  16:16:55 Script stopped

GetFieldId

This function converts coordinates into a field id.

The field id is a number between 0-63999. Each number directly corresponds to a square on the 800x800 grid map. The game server uses field ids to reference all the squares on the map... 0,0 has field id of 0.... 1,0 has field id of 1... 799,0 has field id of 799... 1,1 is field id 800... and so on. Many of the advanced scripting functions require you to convert your coordinates into fieldIds to use them.

This example finds the coordinates of a field id:

• coords = "460,355"
  echo GetFieldId(coords)
  
  Result:
  15:07:40 Starting script
  15:07:40 Running line 1
  15:07:40 coords = 460,355
  15:07:42 Running line 2
  15:07:42 284460
  15:07:43 Script stopped

GetFieldName

This function converts a numeric field value into a named string, for example:

• // get the name of field type 3
  echo GetFieldName(3)
  
  Result:
  18:42:42 Hill
  18:42:43 Script stopped

• // first get the type of the 1st valley held in the city, then get the name for that type
  echo city.fields[0].type
  echo GetFieldName(city.fields[0].type)
  
  Result:
  18:47:30 5
  18:47:31 Grassland
  18:47:32 Script stopped

The possible field numerics -> strings are as follows:

• 1  Forest    
  2  Desert    
  3  Hill      
  4  Swamp     
  5  Grassland 
  6  Lake      
  10 Flat      

GetLevel

This function returns the level of whatever is located at a certain field id.

• echo "The object on the map at {FieldIdToCoords(1234)} is level {GetLevel(1234)}." //This is a level 1 desert at coords 434,1 on the map
  
  Results: 
  16:28:35 Running line 1
  16:28:35 The object on the map at 434,1 is level 1.
  16:28:36 Script stopped

GetZoneName

This function returns the name of the state a field id is located in.

• echo "My city is located in {GetZoneName(city.fieldId)}."
  
  Results: 
  16:34:28 Running line 1
  16:34:28 My city is located in thuringia.
  16:34:29 Script stopped

MapDistance

This function finds the distance between two sets of coordinates on the map.

This example finds the distance between your own city and target coordinates, rounded to 2 decimal places:

• targX = 123
  targY = 456
  distance = round(MapDistance(city.x,city.y,targX,targY),2)
  echo "Distance from {city.coords} to {targX},{targY} is {distance} miles."
  
  Result:
  15:36:13 Starting script
  15:36:13 Running line 1
  15:36:13 targX = 123
  15:36:14 Running line 2
  15:36:14 targY = 456
  15:36:15 Running line 3
  15:36:15 distance = 351.81
  15:36:16 Running line 4
  15:36:16 Distance from 460,355 to 123,456 is 351.81 miles.
  15:36:17 Script stopped

StateCoords

The function returns the state coordinates range, or null if invalid. You may use the zone name or number, for example "Friesland" or 0.

Some examples:

• echo StateCoords("upper lorraine")  // outputs "0,400 199,599"
  echo StateCoords(8)                 // outputs "0,400 199,599"
  
  echo StateCoords("all")             // outputs "0,0 799,799"
  
  state = "Lombardy"
  coords = StateCoords(state)         // coords = "200,600 399,799"
  if !coords die "Unknown state name '{state}'"
  execute "scanmap {coords}"          // scanmap 200,600 399,799

---

CategoryFunctions