Map and terrain (Civ5)

From Civilization Modding Wiki
Jump to: navigation, search

This page is a part of the Lua and UI Reference.


Coordinates systems

Civ5 uses three different coordinates systems for plots:

  • The world coordinates. The coordinates of the plot's graphics in the 3D space where the world is rendered. This system is only used when you want to display an icon over the map, through a WorldAnchor.
  • The grid coordinates. The logical coordinates of a plot. This is the system returned by Plot:GetX() and Plot:GetY()
  • The hex coordinates. The logical coordinates of a plot. Some computations are easier to perform in this system.
The grid coordinates: horizontal and vertical axes are orthogonal.
The hex coordinates: the vertical axis makes a 60° angle with the horizontal axis.

The reason behind the coexistence of the grid and hex coordinates is because most computations are easier to perform in the hex system. For example, if you wish to examine the neighbors of a plot...

  • In the grid coordinates, you first need to test whether y is odd or even. Depending on the result, the offsets of the top plots will be { (0,1), (1,1) } or { (-1,1), (0,1)}.
  • However no such test is required in the hex system: the top offsets are always { (-1,1), (0,1) }.

Helpful functions

The following global functions will help you:

Vector2 Vector2(int x, int y) makes a 2D vector.
int, int ToGridFromHex(int x, int y)
int, int, int GridToWorld(int x, int y)
Vector2 ToHexFromGrid(Vector2 hexPos)
Vector3 HexToWorld(Vector2 hexPos)

Plots indexing

The function Map.GetPlotByIndex(int index) takes an index and returns a plot. This index can be computed as follow:

local w = Map.GetGridSize()
local index = gridX + gridY * w

Enumerating neighbor plots

The best way is to use Map.PlotDirection(int x, int y, DirectionType direction).

local x, y = ... -- Initialize those
for i = 0, 5 do
    local plot = Map.PlotDirection(x, y, i)
    -- Do something with plot

Enumerating plots in a certain range

If you need to enumerate plots in specific orders, you should look at Border and plots iterator, a great library from Whoward69 who provides nice iterators for different scan orders.

Otherwise, Map.PlotXYWithRangeCheck offers a simple way to scan all plots within a certain range.

local x, y = ... -- Initialize those
local range = 5
for dx = -range, range do
    for dy = -range, range do
        local plot = Map.PlotXYWithRangeCheck(x, y, dx, dy, range)
        if plot then
            -- Do whatever you want with this plot

The world is not flat

Maps can be wrapped along X or Y. You can get those values through Map.IsWrapX() and Map.IsWrapY().

  • When wrapped along X, reaching the west side of the map brings you to the east side.
  • When wrapped along Y, reaching the north side brings you to the south side.
  • A map can neither be wrapped along X, neither around Y. For example a map that only covers a part of the world.
  • A map cannot be both wrapped along X and Y.



The nature, aspect and value of a Plot in civ5 are defined by the following data:

  • PlotType. It can be ocean (includes lakes and coasts), land, hills or mountain.
  • TerrainType. It can be ocean, coast (lake or coast), grasslands, plains, tundra or snow. A coast is automatically a lake if it belongs to a water area not larger than nine plots (see the next section).
  • FeatureType. It can be none, forest, jungle, floodplains, marsh, oasis, ice, fallout or any natural wonder.
  • ResourceType and a quantity value. It can be any resource: gold, gems, horses, fish, etc.
  • ImprovementType and a "pillaged" boolean flag. It can be any improvement: mines, farm, etc. Goodies, city ruins and barbarian camps are also improvements.
  • RouteType. It can be none, road or railroad.
  • ArtStyleType. It can be South America, Asian, European, Middle-East, Polynesian Greco-Roman or Barbarian. It decides which graphics will be used to render the plot.
  • Besides of those, a plot also stores its coordinates, references to the city and units it hosts, its owner index, and visibility flags for every player in the game.


  • The map is divided into different areas: one per landmass and one per watermass. That is, all plots in an island belong to the same area, which is different from the closest continent's area. Every lake or inner sea also has their own areas.
  • Areas are represented in the API by the Area type.
  • Water areas that contains nine plots at most are lakes. Otherwise they are oceans.
  • Areas are computed when the map is generated, through Map.RecalculateAreas(). You should not recompute them unless you turn some plots from water to land and reciprocally.
  • In Civ4 impassable plots had their distinct areas and they could diode a landmass into sub-areas. This is no longer true in civ5.



You can only query or modify three edges per plot: E, SE, SW
Illustration of the FlowDirectionType on every edge.

Every plot has:

  • Three status getters:
    • bool Plot:IsWOfRiver(). Checks the east edge (IsWOfRiver stands for "is at the west of a river")
    • bool Plot:IsNWOfRiver(). SE edge.
    • bool Plot:IsNEOfRiver(). SW edge.
  • Three direction getters:
  • Three setters:
  • Two generalized getters that return true if there is a river in the specified direction (or towards the specified plot):

Generalized functions

The fact that you can only query three edges is troublesome. Here are simple functions to circumvent this limitation. Note that the HasRiver function is redundant with the IsRiverCrossing and IsRiverCrossingToPlot methods.

function HasRiver(plot, direction)
    if direction == 1 then return plot:IsWOfRiver() end
    if direction == 2 then return plot:IsNWOfRiver() end
    if direction == 3 then return plot:IsNEOfRiver() end
    local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
    return HasRiver(neighbor, direction - 3)

function GetRiverFlow(plot, direction)
    if direction == 1 then return plot:GetRiverEFlowDirection() end
    if direction == 2 then return plot:GetRiverSEFlowDirection() end
    if direction == 3 then return plot:GetRiverSWFlowDirection() end
    local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
    return GetRiverFlow(neighbor, direction - 3)

function SetRiver(plot, direction, hasRiver, flowDirection)
    if direction == 1 then return plot:SetWOfRiver(hasRiver, flowDirection) end
    if direction == 2 then return plot:SetNWOfRiver(hasRiver, flowDirection) end
    if direction == 3 then return plot:SetNEOfRiver(hasRiver, flowDirection) end
    local neighbor = Map.PlotDirection(plot:GetX(), plot:GetY(), direction)
    return SetRiver(neighbor, direction - 3, hasRiver, flowDirection)