Difference between revisions of "Mapgen Parameters"

From Minetest Developer Wiki
Jump to navigation Jump to search
(lua_api.txt -> lua_api.md)
 
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
All map generator algorithms have a few common parameters, plus any mapgen-specific options such as noise parameters or threshhold values.  Only mapgen-generic parameters are listed here; mapgen-specific ones are listed in the corresponding mapgen wiki page.
+
All map generator algorithms have a few common parameters, plus any mapgen-specific options such as noise parameters or threshhold values.
 
= Mapgen parameter source precedence =
 
= Mapgen parameter source precedence =
 
There are several sources which the map generator may retrieve parameters from.  In order from highest precedence to lowest they are:
 
There are several sources which the map generator may retrieve parameters from.  In order from highest precedence to lowest they are:
Line 5: Line 5:
 
* Lua mods
 
* Lua mods
 
* map_meta.txt
 
* map_meta.txt
−
* Config file
+
* Game-specific config file
 +
* Global config file
 
* Default settings (set in defaultsettings.cpp)
 
* Default settings (set in defaultsettings.cpp)
 
* Default object constructor values
 
* Default object constructor values
Line 16: Line 17:
 
|-
 
|-
 
! Mapgen name !! Developer responsible !! Description
 
! Mapgen name !! Developer responsible !! Description
 +
|-
 +
| v5 || missing info || Description needed
 
|-
 
|-
 
| v6 || kwolekr, celeron55 || The current default map generator.  Uses an improved Mapgen v2 algorithm for base terrain; terrain is generated entirely using 2D Perlin noise.
 
| v6 || kwolekr, celeron55 || The current default map generator.  Uses an improved Mapgen v2 algorithm for base terrain; terrain is generated entirely using 2D Perlin noise.
Line 21: Line 24:
 
| v7 || kwolekr || The next generation map generator with an emphasis on generating interesting and playable terrain.  Has full support for the internal biome infrastructure and uses a mixture of 2D and both positive and negative 3D noise for terrain.
 
| v7 || kwolekr || The next generation map generator with an emphasis on generating interesting and playable terrain.  Has full support for the internal biome infrastructure and uses a mixture of 2D and both positive and negative 3D noise for terrain.
 
|-
 
|-
−
| indev || proller || Mapgen v6 with some interesting experimental features and tweaks added, such as floatlands, terrain that gets higher in scale the further the from the origin, and extremely large caves.
+
| valleys || missing info || Description needed
 +
|-
 +
| carpathian || missing info || Description needed
 +
|-
 +
| fractal || missing info || Generates maps based on Mandelbrot fractal series
 
|-
 
|-
−
| math || proller || Generates terrain based off of 3d fractals, e.g. Mandelbulb.  Not intended to be used for a traditional game of Minetest.
+
| flat || missing info || Generates completely flat world. Replaces the flat flag in mg_flags. Caves, dungeons, decorations, and biomes need to be explicitly excluded to make a flat and empty world.
 
|-
 
|-
 
| singlenode || celeron55 || Places only a single node everywhere, namely the one aliased to mapgen_singlenode (by default air).  Intended to be used by mods that perform total mapgen takeovers.
 
| singlenode || celeron55 || Places only a single node everywhere, namely the one aliased to mapgen_singlenode (by default air).  Intended to be used by mods that perform total mapgen takeovers.
 
|}
 
|}
 +
example: <code>mg_name = v7</code>
  
 
== Seed ==
 
== Seed ==
−
A 64-bit unsigned integer value.  At this time, only the lower 32 bits are currently used for randomization.
+
A 64-bit unsigned integer value.  At this time, only the lower 32 bits are currently used for randomization.<br>
 +
example: <code>seed = 1246106421</code>
  
 
== Water level ==
 
== Water level ==
 
The y coordinate at which water starts being placed, for mapgens that do place water.
 
The y coordinate at which water starts being placed, for mapgens that do place water.
 
<br />
 
<br />
−
This is also the position at which blocks are assumed to be underground if no block above is present, and thus is not given sunlight.
+
This is also the position at which blocks are assumed to be underground if no block above is present, and thus is not given sunlight.<br>
 +
example: <code> water_level = 1 </code>
 +
 
 +
== Mapgen Limit ==
 +
Limit of map generation, in nodes, in all 6 directions from (0, 0, 0).
 +
* Only mapchunks completely within the mapgen limit are generated.
 +
* Value is stored per-world.
 +
* type: int min: 0 max: 31000<br>
 +
example : <code>mapgen_limit = 4500</code>
  
 
== Flags parameter ==
 
== Flags parameter ==
−
The flags parameter is a set of booleans indicating whether or not a certain option is enabled.  Flags can be a combination of the possible values detailed in the table below.
+
The flags parameter is a set of booleans indicating whether or not a certain option is enabled.  Global flags applying to all map generators are listed in [[mg_flags]]. Other map generator-specific flags are shown below.
 
<br />
 
<br />
 
Like all other config and Lua flag fields, they are represented as a comma-delimited string.
 
Like all other config and Lua flag fields, they are represented as a comma-delimited string.
Line 45: Line 62:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! Lua/config flag name !! Internal constant !! Respected by !! Description
+
! Lua/config flag name !! Defaults  !! Allowed values
 
|-
 
|-
−
| trees || MG_TREES || v6, indev || Place trees on the map according to the tree noise distribution.
+
| mgv5_spflags || caverns || caverns, nocaverns
 
|-
 
|-
−
| caves || MG_CAVES || v6, indev, v7 || Carve out caves from the terrain.
+
| mgv6_spflags || jungles,biomeblend,mudflow,snowbiomes,trees || jungles, biomeblend, mudflow, snowbiomes, flat, trees, nojungles, nobiomeblend, nomudflow, nosnowbiomes, noflat, notrees
 
|-
 
|-
−
| dungeons || MG_DUNGEONS || v6, indev, v7 || Randomly place dungeons onto the map.
+
| mgv7_spflags || mountains,ridges,nofloatlands,caverns || mountains, ridges, floatlands, caverns, nomountains, noridges, nofloatlands, nocaverns
 
|-
 
|-
−
| flat || MG_FLAT || v6, indev, v7 || Make all terrain occur at the y position 0, resulting in a flat map.  Note that this attribute does NOT turn off trees, caves, or any other feature.
+
| mgcarpathian_spflags || caverns || caverns, nocaverns
 
|-
 
|-
−
| nolight || MG_NOLIGHT || v6, indev, v7, singlenode || Do not calculate lighting; instead leave set to 0 (total darkness).  This is intended to be set by custom Lua map generators, NOT end users.
+
| mgflat_spflags || nolakes,nohills || lakes, hills, nolakes, nohills
 
|-
 
|-
−
| v6_jungles || MGV6_JUNGLES || v6, indev || Place 0.3-style jungles on the map according to v6's own (NOTE: not biome) humidity noise distribution.
+
| mgvalleys_spflags || altitude_chill,humid_rivers,vary_river_depth,altitude_dry || altitude_chill, noaltitude_chill, humid_rivers, nohumid_rivers, vary_river_depth, novary_river_depth, altitude_dry, noaltitude_dry
−
|-
 
−
| v6_biome_blend || MGV6_BIOME_BLEND || v6, indev || Dither nodes between biomes to create a transition between them.
 
−
|-
 
−
| v7_mountains || MGV7_MOUNTAINS ||  || Place 3d noise-defined mountains.  Currently, not user-accessible.
 
−
|-
 
−
| v7_ridges || MGV7_RIDGES ||  || Place 3d noise-defined rivers and ridges.  Currently, not user-accessible.
 
 
|}
 
|}
 +
 +
Other fine-tuning parameters are available for each map generator, and can be found in lua_api.md.
  
 
== Chunk size ==
 
== Chunk size ==
Line 71: Line 84:
 
Don't mess around with this if you don't know what you're doing!  This parameter cannot be modified through the Lua API.
 
Don't mess around with this if you don't know what you're doing!  This parameter cannot be modified through the Lua API.
  
−
= Mapgen Parameter Lua API =
+
{{Incomplete}}
−
The task of getting and setting mapgen parameters is much trickier than it seems it should be.  For this reason there exists a small but effective set of API for accomplishing this.<br />
+
 
−
== minetest.register_on_mapgen_init() ==
+
[[Category:Core Engine]]
−
Reading the configuration file for parameter overrides is incorrect, since there are many other sources the mapgen parameters could be set according to.  Further, since the map metadata is only loaded after the mods have initially run and before the environment has been created, a direct query cannot be made.  For this reason there is a callback that can be registered on mod load, using ''minetest.register_on_mapgen_init()'', which runs on mapgen initialization.  If certain decorations, or nodes, etc. must be registered according to the mapgen being used or any other mapgen params, this is the appropriate callback in which to accomplish this.
 
−
<br />
 
−
''minetest.register_on_mapgen_init(function(mgparams))'' is passed a table containing the mapgen parameters currently being used.
 
−
<br />
 
−
Valid fields of mgparams are: ''mgname'', ''seed'', ''water_level'', ''flags''
 
−
<br />
 
−
== minetest.set_mapgen_params() ==
 
−
This is the API used to set mapgen parameters from within Lua.  It may ONLY be executed within a ''minetest.register_on_mapgen_init'' callback; calls made outside will not have any effect.
 
−
If there are multiple callbacks registered to run on_mapgen_init and there are multiple calls to set_mapgen_params, the effective parameter modification is the one passed to the most recent call to ''minetest.set_mapgen_params()''.  Also, since parameter modification does not take effect until after all on_mapgen_init callbacks have been completed, prior staged changes are not visible to later callbacks.
 
−
<br />
 
−
''minetest.set_mapgen_params(params)'' is passed a table containing the mapgen parameters that are staged to be modified; valid fields are: ''mgname'', ''seed'', ''water_level'', ''flags'', and ''flagmask''.
 
−
The ''flags'' field is a comma-delimited string of flag names as described in the previous section that are to be SET; the flagmask field is a comma-delimited string of flag names that are to be MODIFIED.  In other words, to set a flag, it must be present in both ''flags'' and ''flagmask'' fields, and to unset a flag, it must be present in the ''flagmask'' field but not in the ''flags'' field.
 
−
If a flag is present in ''flags'' but not in ''flagmask'', the result is undefined.
 

Latest revision as of 11:18, 1 May 2023

All map generator algorithms have a few common parameters, plus any mapgen-specific options such as noise parameters or threshhold values.

Mapgen parameter source precedence

There are several sources which the map generator may retrieve parameters from. In order from highest precedence to lowest they are:

  • Hard-coded
  • Lua mods
  • map_meta.txt
  • Game-specific config file
  • Global config file
  • Default settings (set in defaultsettings.cpp)
  • Default object constructor values

List of mapgen parameters

Mapgen name

The name of the map generator algorithm being used. Currently supported:

Mapgen name Developer responsible Description
v5 missing info Description needed
v6 kwolekr, celeron55 The current default map generator. Uses an improved Mapgen v2 algorithm for base terrain; terrain is generated entirely using 2D Perlin noise.
v7 kwolekr The next generation map generator with an emphasis on generating interesting and playable terrain. Has full support for the internal biome infrastructure and uses a mixture of 2D and both positive and negative 3D noise for terrain.
valleys missing info Description needed
carpathian missing info Description needed
fractal missing info Generates maps based on Mandelbrot fractal series
flat missing info Generates completely flat world. Replaces the flat flag in mg_flags. Caves, dungeons, decorations, and biomes need to be explicitly excluded to make a flat and empty world.
singlenode celeron55 Places only a single node everywhere, namely the one aliased to mapgen_singlenode (by default air). Intended to be used by mods that perform total mapgen takeovers.

example: mg_name = v7

Seed

A 64-bit unsigned integer value. At this time, only the lower 32 bits are currently used for randomization.
example: seed = 1246106421

Water level

The y coordinate at which water starts being placed, for mapgens that do place water.
This is also the position at which blocks are assumed to be underground if no block above is present, and thus is not given sunlight.
example: water_level = 1

Mapgen Limit

Limit of map generation, in nodes, in all 6 directions from (0, 0, 0).

  • Only mapchunks completely within the mapgen limit are generated.
  • Value is stored per-world.
  • type: int min: 0 max: 31000

example : mapgen_limit = 4500

Flags parameter

The flags parameter is a set of booleans indicating whether or not a certain option is enabled. Global flags applying to all map generators are listed in mg_flags. Other map generator-specific flags are shown below.
Like all other config and Lua flag fields, they are represented as a comma-delimited string. E.g. the flag string "trees, caves, flat" would direct the Mapgen to create flat terrain with trees and caves.
An exhaustive list of currently recognized Mapgen flags:

Lua/config flag name Defaults Allowed values
mgv5_spflags caverns caverns, nocaverns
mgv6_spflags jungles,biomeblend,mudflow,snowbiomes,trees jungles, biomeblend, mudflow, snowbiomes, flat, trees, nojungles, nobiomeblend, nomudflow, nosnowbiomes, noflat, notrees
mgv7_spflags mountains,ridges,nofloatlands,caverns mountains, ridges, floatlands, caverns, nomountains, noridges, nofloatlands, nocaverns
mgcarpathian_spflags caverns caverns, nocaverns
mgflat_spflags nolakes,nohills lakes, hills, nolakes, nohills
mgvalleys_spflags altitude_chill,humid_rivers,vary_river_depth,altitude_dry altitude_chill, noaltitude_chill, humid_rivers, nohumid_rivers, vary_river_depth, novary_river_depth, altitude_dry, noaltitude_dry

Other fine-tuning parameters are available for each map generator, and can be found in lua_api.md.

Chunk size

The side length (in MapBlocks) of the cubic area that is generated at once. Default is 5; larger values take longer to generate but blocks generate quicker on average and could produce larger, more intricate caves and dungeons.
Don't mess around with this if you don't know what you're doing! This parameter cannot be modified through the Lua API.

Mbox important.png This article is incomplete.
Please help expand this article to include more useful information.
Retrieved from "http://dev.minetest.net/index.php?title=Mapgen_Parameters&oldid=6377"