Generated Maps:Library Functions

From Age of Empires 4 Modding

Return to Generated Maps - Home

This is a work in progress. Not all functions are listed here.

Function Location Description
CreateTeamMappingTable() library\map_setup.lua You need this to use in conjunction with the placePlayerStarts functions. The Team Mapping Table is created from the info in the lobby. It is a table containing each team and which players make them up. Formatted as follows if you need to use it for something in your map: teamMappingTable[teamIndex].players[playerIndex].playerID
GrowTerrainAreaToSizeWeighted() library\map_setup.lua Useful for creating islands and land masses of a certain terrain type.
PlacePlayerStartsRing() library\map_setup.lua This function places all players in a ring around the edge of the map, with a variable amount of the centre of the map unavailable for spawn locations.
PlacePlayerStartsDivided() library\map_setup.lua This function places two teams of players in two horizontal or vertical bands. Useful for maps that have some sort of dividing geography down the center.
SetCoarseGrid() library\map_setup.lua Meters per square is set to 40 with the exception of the Micro sized map. Using this function, the minimum size of a map is 13x13 which equates to 33 meters per square for Micro size map, and 40 for all other sized maps. If you use function SetCustomCoarseGrid(), you can make a map with a lower grid size.
SetCustomCoarseGrid() library\map_setup.lua Sets the map grid to be a custom dimension. NOTE: this will make all terrain features relatively smaller. Be careful using grids of too high a resolution.
SetUpTeams() library\player_starts.lua Not required for team setup or assignment. Map will still load without this function and team assignments will still work properly. Returns two tables that might be helpful for use, but not required: teamTable, playersPerTeam

CreateTeamMappingTable()[edit]

You need this to use in conjunction with the placePlayerStarts functions. The Team Mapping Table is created from the info in the lobby. It is a table containing each team and which players make them up. Formatted as follows if you need to use it for something in your map: teamMappingTable[teamIndex].players[playerIndex].playerID

Arguments[edit]

  • null

Returns[edit]

teamMappingTable (table)

Examples[edit]

From the library\map_template.lua 

teamMappingTable = CreateTeamMappingTable()

GrowTerrainAreaToSizeWeighted()[edit]

Useful for creating islands and land masses of a certain terrain type.

Arguments[edit]

  • startRow (integer)

The grid row where you want to start the draw.

  • startCol (integer)

The grid column where you want to start the draw.

  • numPasses (integer)

The larger the value, the larger the drawn area.

  • terrainToChange (array)

Specifies which terrain type(s) you want to replace with the new terrain type argument terrainToChange.

  • terrainToChange (string/terrain variable)

Which terrain to place/change.

  • topSelectionWeight (float)

Between zero and one, specify how random you want the area to be drawn. With lower decimal values, the drawn area is a rounder shape (0.01), and a higher value (like 1.0 being max) branches out in random directions like a crushed spider.

  • terrainGrid (table e.g. terrainLayoutResult)

Your terrainLayoutResult table.

Returns[edit]

areaSquares (nil)

Examples[edit]

Example of replacing the tt_none terrain type with tt_plains. 

GrowTerrainAreaToSizeWeighted(mapHalfSize, mapHalfSize, 20, { tt_none }, tt_plains, 0.5, terrainLayoutResult)

PlacePlayerStartsRing()[edit]

This function places all players in a ring around the edge of the map, with a variable amount of the centre of the map unavailable for spawn locations.

Arguments[edit]

  • teamMappingTable (table)

The Team Mapping Table is created from the info in the lobby. It is a table containing each team and which players make them up. See CreateTeamMappingTable().

  • minTeamDistance (float)

How far apart the "team locations" must be. A "team location" is a central spot around which players from that team will be placed. This is a distance relative to the course grid squares.

  • minPlayerDistance (float)

How far each player must be from another player. When using "Teams Apart", this determines how far opposite teams can be from one another also.

  • edgeBuffer (integer)

Determines how many squares around a grid's perimeter players cannot spawn

  • innerExclusion (float)

A value between 0 and 1 that determines the percentage of the interior of the grid to block from player spawning. e.g. On a 20x20 grid, a 0.5 innerExclusion would black out the centre 10x10.

  • cornerThreshold (integer)

Used for making players not spawn directly in corners. It describes the number of squares away from the corner that are blocked from spawns.

  • impasseTypes (table)

A list of terrain types that the spawning function will avoid when placing players. It will ensure that players are not placed on or adjacent to squares in this list.

  • impasseDistance (float)

The distance away from any of the impasseTypes that a viable player start needs to be. All squares closer than the impasseDistance will be removed from the list of squares players can spawn on.

  • topSelectionThreshold (float)
How strict you want to be on allies being grouped as closely as possible together. If you make this number larger, the list of closest spawn. Locations will expand, and further locations may be chosen.
I like to keep this number very small, as in the case of 0.02, it will take the top 2% of spawn options only. Relic Developer
  • playerStartTerrain (string/terrain variable)

The terrain type containing the standard distribution of starting resources.

  • startBufferTerrain (string/terrain variable)

The terrain placed around player spawns. This terrain will stomp over other terrain. We use this to guarantee building space around player starts.

  • startBufferRadius (float)

The radius in which we place the startBufferTerrain around each player start.

  • placeBufferTerrain (boolean)

true will place the startBufferTerrain terrain, false will not.

  • terrainGrid (table e.g. terrainLayoutResult)

Your terrainLayoutResult table.

Returns[edit]

terrainGrid (table e.g. terrainLayoutResult)

Examples[edit]

From the library\map_template.lua 

teamMappingTable = CreateTeamMappingTable()
minTeamDistance = 8.5
minPlayerDistance = 3.5
edgeBuffer = 1
innerExclusion = 0.4
cornerThreshold = 2

impasseTypes = {}
table.insert(impasseTypes, tt_impasse_mountains)
table.insert(impasseTypes, tt_river)
impasseDistance = 2.5

topSelectionThreshold = 0.02
playerStartTerrain = tt_player_start_classic_plains
startBufferTerrain = tt_plains
startBufferRadius = 2
placeStartBuffer = true

terrainLayoutResult = PlacePlayerStartsRing(teamMappingTable, minTeamDistance, minPlayerDistance, edgeBuffer, innerExclusion, cornerThreshold, impasseTypes, impasseDistance, topSelectionThreshold, playerStartTerrain, startBufferTerrain, startBufferRadius, placeStartBuffer, terrainLayoutResult)

PlacePlayerStartsDivided()[edit]

This function places two teams of players in two horizontal or vertical bands. Useful for maps that have some sort of dividing geography down the center.

Arguments[edit]

  • teamMappingTable (table)

The Team Mapping Table is created from the info in the lobby. It is a table containing each team and which players make them up. See CreateTeamMappingTable().

  • minTeamDistance (float)

How far apart the "team locations" must be. A "team location" is a central spot around which players from that team will be placed. This is a distance relative to the course grid squares.

  • minPlayerDistance (float)

How far each player must be from another player. When using "Teams Apart", this determines how far opposite teams can be from one another also.

  • edgeBuffer (integer)

Determines how many squares around a grid's perimeter players cannot spawn

  • innerExclusion (float)

A value between 0 and 1 that determines the percentage of the interior of the grid to block from player spawning. e.g. On a 20x20 grid, a 0.5 innerExclusion would black out the centre 10x10.

  • cornerThreshold (integer)

Used for making players not spawn directly in corners. It describes the number of squares away from the corner that are blocked from spawns.

  • isVertical (boolean)

true will spawn players opposite from each other vertically, false will spawn them opposite horizontally.

  • impasseTypes (table)

A list of terrain types that the spawning function will avoid when placing players. It will ensure that players are not placed on or adjacent to squares in this list.

  • impasseDistance (float)

The distance away from any of the impasseTypes that a viable player start needs to be. All squares closer than the impasseDistance will be removed from the list of squares players can spawn on.

  • topSelectionThreshold (float)
How strict you want to be on allies being grouped as closely as possible together. If you make this number larger, the list of closest spawn. Locations will expand, and further locations may be chosen.
I like to keep this number very small, as in the case of 0.02, it will take the top 2% of spawn options only. Relic Developer
  • playerStartTerrain (string/terrain variable)

The terrain type containing the standard distribution of starting resources.

  • startBufferTerrain (string/terrain variable)

The terrain placed around player spawns. This terrain will stomp over other terrain. We use this to guarantee building space around player starts.

  • startBufferRadius (float)

The radius in which we place the startBufferTerrain around each player start.

  • placeBufferTerrain (boolean)

true will place the startBufferTerrain terrain, false will not.

  • terrainGrid (table e.g. terrainLayoutResult)

Your terrainLayoutResult table.

Returns[edit]

terrainGrid (table e.g. terrainLayoutResult)

Examples[edit]

From the skirmish_maps\mountain_pass.lua 

startLocationPositions = {} -- set up list to store all player locations

minTeamDistance = gridSize * 1.2
edgeBuffer = 1
cornerThreshold = 0
spawnBlockers = {}
table.insert(spawnBlockers, tt_mountain_range)
table.insert(spawnBlockers, tt_mountains)
table.insert(spawnBlockers, tt_mountains_small)
		

if(#teamMappingTable == 2) then
	terrainLayoutResult = PlacePlayerStartsDivided(teamMappingTable, minTeamDistance, minPlayerDistance, edgeBuffer, 0.425, cornerThreshold, false, spawnBlockers, 1, 0.05, playerStartTerrain, tt_plains_smooth, 2, true, terrainLayoutResult)
else
	terrainLayoutResult = PlacePlayerStartsRing(teamMappingTable, minTeamDistance, minPlayerDistance, edgeBuffer, 0.38, cornerThreshold, spawnBlockers, 2, 0.05, playerStartTerrain, tt_plains_smooth, 2, true, terrainLayoutResult)
end

SetCoarseGrid()[edit]

Meters per square is set to 40 with the exception of the Micro sized map. Using this function, the minimum size of a map is 13x13 which equates to 33 meters per square for Micro size map, and 40 for all other sized maps. If you use function SetCustomCoarseGrid(), you can make a map with a lower grid size.

Arguments[edit]

  • null

Returns[edit]

mapSize (int)

Examples[edit]

From the library/map_template.lua 

--setting useful variables to reference world dimensions. This sets the map to our default resolution of 40m per grid square, which is reccommended.
--when generating our maps, each square on the grid is represented by a terrain type (hills, mountain, plains, etc) whose height is determined
--by a height/width calculation. When you change grid resolution, this calculation is affected. For example, with a higher resolution grid
--(for example 25m vs the standard 40m), all terrain features will be generated smaller, which in the case of things like mountains, can
--affect their ability to create impasse on the map. Use a custom resolution at your own discretion, but do not expect that all terrain
--will work as intended. Terrain types have been tuned at the default 40m resolution.

gridHeight, gridWidth, gridSize = SetCoarseGrid()

SetCustomCoarseGrid()[edit]

Sets the map grid to be a custom dimension. NOTE: this will make all terrain features relatively smaller. Be careful using grids of too high a resolution.

Arguments[edit]

  • metersPerSquare (int)

Returns[edit]

mapSize (int)

Examples[edit]

From the library/map_template.lua 

gridHeight, gridWidth, gridSize = SetCustomCoarseGrid(40)

SetUpTeams()[edit]

Not required for team setup or assignment. Map will still load without this function and team assignments will still work properly. Returns two tables that might be helpful for use, but not required: teamTable, playersPerTeam

Arguments[edit]

  • null

Returns[edit]

teamTable (table)

playersPerTeam (table)

Examples[edit]

From the library\map_template.lua 

teamsList, playersPerTeam = SetUpTeams()
Retrieved from "https://wiki.aoemods.com/w/index.php?title=Generated_Maps:Library_Functions&oldid=200"