rudzik8
/
MineClone2
forked from VoxeLibre/VoxeLibre
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Apply markdown format to mcl_mapgen api doc

This commit is contained in:
kay27 2022-01-20 00:44:23 +04:00
parent b3e8f24876
commit 679a1db436
1 changed files with 85 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
mods/CORE/mcl_mapgen/API.md
View File

@ -1,99 +1,119 @@
# mcl_mapgen # mcl_mapgen
============ ------------
Helps to avoid problems caused by 'chunk-in-shell' feature of mapgen.cpp. Helps to avoid problems caused by 'chunk-in-shell' feature of mapgen.cpp.
It also queues your generators to run them in proper order: It also queues your generators to run them in proper order:
### mcl_mapgen.register_on_generated(lvm_callback_function, order_number) ### mcl_mapgen.register_on_generated(lvm_callback_function, order_number)
========================================================================= -------------------------------------------------------------------------
Replacement of engine API function `minetest.register_on_generated(function(vm_context))` Replacement of engine API function `minetest.register_on_generated(function(vm_context))`
It is still unsafe. Cavegen part can and will overwrite outer 1-block layer of the chunk which is expected to be generated. It is still unsafe. Cavegen part can and will overwrite outer 1-block layer of the chunk which is expected to be generated.
Nodes marked as `is_ground_content` could be overwritten. Air and water are usually 'ground content' too. Nodes marked as `is_ground_content` could be overwritten. Air and water are usually 'ground content' too.
For Minetest 5.4 it doesn't recommended to place blocks within lvm callback function. For Minetest 5.4 it doesn't recommended to place blocks within lvm callback function.
See https://git.minetest.land/MineClone2/MineClone2/issues/1395 See https://git.minetest.land/MineClone2/MineClone2/issues/1395
`lvm_callback_function`: chunk callback LVM function definition:
`function(vm_context)`: * `lvm_callback_function`: chunk callback LVM function definition:
`vm_context` will pass into next lvm callback function from the queue! * `function(vm_context)`:
`vm_context`: a table which already contains some LVM data as the fields, and some of them can be added in your lvm callback function: * `vm_context` will pass into next lvm callback function from the queue!
`vm`: curent voxel manipulator object itself; * `vm_context`: a table which already contains some LVM data as the fields, and some of them can be added in your lvm callback function:
`chunkseed`: seed of this mapchunk; * `vm`: curent voxel manipulator object itself;
`minp` & `maxp`: minimum and maximum chunk position; * `chunkseed`: seed of this mapchunk;
`emin` & `emax`: minimum and maximum chunk position WITH SHELL AROUND IT; * `minp` & `maxp`: minimum and maximum chunk position;
`area`: voxel area, can be helpful to access data; * `emin` & `emax`: minimum and maximum chunk position WITH SHELL AROUND IT;
`data`: LVM buffer data array, data loads into it before the callbacks; * `area`: voxel area, can be helpful to access data;
`write`: set it to true in your lvm callback functionm, if you changed `data` and want to write it; * `data`: LVM buffer data array, data loads into it before the callbacks;
`param2_data`: LVM buffer data array of `param2`, !NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - you load it yourself: * `write`: set it to true in your lvm callback functionm, if you changed `data` and want to write it;
`vm_context.param2_data = vm_context.param2_data or vm_context.vm:get_param2_data(vm_context.lvm_param2_buffer)` * `param2_data`: LVM buffer data array of `param2`, *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - you load it yourself:
`write_param2`: set it to true in your lvm callback function, if you used `param2_data` and want to write it; * `vm_context.param2_data = vm_context.param2_data or vm_context.vm:get_param2_data(vm_context.lvm_param2_buffer)`
`light`: LVM buffer data array of light, !NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - you load it yourself: * `write_param2`: set it to true in your lvm callback function, if you used `param2_data` and want to write it;
`vm_context.light = vm_context.light or vm_context.vm.get_light_data(vm_context.lvm_light_buffer)` * `light`: LVM buffer data array of light, *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - you load it yourself:
`write_light`: set it to true in your lvm callback function, if you used `light` and want to write it; * `vm_context.light = vm_context.light or vm_context.vm.get_light_data(vm_context.lvm_light_buffer)`
`lvm_param2_buffer`: static `param2` buffer pointer, used to load `param2_data` array; * `write_light`: set it to true in your lvm callback function, if you used `light` and want to write it;
`shadow`: set it to false to disable shadow propagation; * `lvm_param2_buffer`: static `param2` buffer pointer, used to load `param2_data` array;
`heightmap`: mapgen object contanting y coordinates of ground level, * `shadow`: set it to false to disable shadow propagation;
!NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - load it yourself: * `heightmap`: mapgen object contanting y coordinates of ground level,
`vm_context.heightmap = vm_context.heightmap or minetest.get_mapgen_object('heightmap')` * *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - load it yourself:
`biomemap`: mapgen object contanting biome IDs of nodes, * `vm_context.heightmap = vm_context.heightmap or minetest.get_mapgen_object('heightmap')`
!NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - load it yourself: * `biomemap`: mapgen object contanting biome IDs of nodes,
`vm_context.biomemap = vm_context.biomemap or minetest.get_mapgen_object('biomemap')` * *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - load it yourself:
`heatmap`: mapgen object contanting temperature values of nodes, * `vm_context.biomemap = vm_context.biomemap or minetest.get_mapgen_object('biomemap')`
!NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - load it yourself: * `heatmap`: mapgen object contanting temperature values of nodes,
`vm_context.heatmap = vm_context.heatmap or minetest.get_mapgen_object('heatmap')` * *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - load it yourself:
`humiditymap`: mapgen object contanting humidity values of nodes, * `vm_context.heatmap = vm_context.heatmap or minetest.get_mapgen_object('heatmap')`
!NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - load it yourself: * `humiditymap`: mapgen object contanting humidity values of nodes,
`vm_context.humiditymap = vm_context.humiditymap or minetest.get_mapgen_object('humiditymap')` * *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - load it yourself:
`gennotify`: mapgen object contanting mapping table of structures, see Minetest Lua API for explanation, * `vm_context.humiditymap = vm_context.humiditymap or minetest.get_mapgen_object('humiditymap')`
!NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS! - load it yourself: * `gennotify`: mapgen object contanting mapping table of structures, see Minetest Lua API for explanation,
`vm_context.gennotify = vm_context.gennotify or minetest.get_mapgen_object('gennotify')` * *NO ANY DATA LOADS INTO IT BEFORE THE CALLBACKS* - load it yourself:
`order_number` (optional): the less, the earlier, * `vm_context.gennotify = vm_context.gennotify or minetest.get_mapgen_object('gennotify')`
e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS` * `order_number` (optional): the less, the earlier,
* e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS`
### mcl_mapgen.register_mapgen_block_lvm(lvm_callback_function, order_number) ### mcl_mapgen.register_mapgen_block_lvm(lvm_callback_function, order_number)
============================================================================= -----------------------------------------------------------------------------
Registers lvm callback function to be called when current block (usually 16x16x16 nodes) generation is REALLY 100% finished. Registers lvm callback function to be called when current block (usually 16x16x16 nodes) generation is REALLY 100% finished.
`vm_context` passes into lvm callback function. `vm_context` passes into lvm callback function.
`lvm_callback_function`: the block callback LVM function definition - same as for chunks - see definition example above; * `lvm_callback_function`: the block callback LVM function definition - same as for chunks - see definition example above;
`order_number` (optional): the less, the earlier, * `order_number` (optional): the less, the earlier,
e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS` * e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS`
### mcl_mapgen.register_mapgen_block(node_callback_function, order_number) ### mcl_mapgen.register_mapgen_block(node_callback_function, order_number)
========================================================================== --------------------------------------------------------------------------
Registers node_callback function to be called when current block (usually 16x16x16 nodes) generation is REALLY 100% finished. Registers node_callback function to be called when current block (usually 16x16x16 nodes) generation is REALLY 100% finished.
`node_callback_function`: node callback function definition: * `node_callback_function`: node callback function definition:
`function(minp, maxp, seed)`: * `function(minp, maxp, seed)`:
`minp` & `maxp`: minimum and maximum block position; * `minp` & `maxp`: minimum and maximum block position;
`seed`: seed of this mapblock; * `seed`: seed of this mapblock;
`order_number` (optional): the less, the earlier, * `order_number` (optional): the less, the earlier,
e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS` * e.g. `mcl_mapgen.order.BUILDINGS` or `mcl_mapgen.order.LARGE_BUILDINGS`
### mcl_mapgen.register_mapgen(callback_function, order_number) ### mcl_mapgen.register_mapgen(callback_function, order_number)
=============================================================== ---------------------------------------------------------------
Registers callback function to be called when current chunk generation is REALLY 100% finished. Registers callback function to be called when current chunk generation is REALLY 100% finished.
For LVM it's the most frustrating function from this mod. For LVM it's the most frustrating function from this mod.
It can't provide you access to mapgen objects. They are probably gone long ago. It can't provide you access to mapgen objects. They are probably gone long ago.
Don't use it for accessing mapgen objects please. Don't use it for accessing mapgen objects please.
To use VM you have to run `vm_context.vm = mcl_mapgen.get_voxel_manip(vm_context.emin, vm_context.emax)`. To use VM you have to run `vm_context.vm = mcl_mapgen.get_voxel_manip(vm_context.emin, vm_context.emax)`.
`callback_function`: callback function definition: * `callback_function`: callback function definition:
`function(minp, maxp, seed, vm_context)`: * `function(minp, maxp, seed, vm_context)`:
`minp` & `maxp`: minimum and maximum block position; * `minp` & `maxp`: minimum and maximum block position;
`seed`: seed of this mapblock; * `seed`: seed of this mapblock;
`vm_context`: a table - see description above. * `vm_context`: a table - see description above.
`order_number` (optional): the less, the earlier. * `order_number` (optional): the less, the earlier.
### mcl_mapgen.register_mapgen_lvm(lvm_callback_function, order_number) ### mcl_mapgen.register_mapgen_lvm(lvm_callback_function, order_number)
======================================================================= -----------------------------------------------------------------------
Registers lvm callback function to be called when current chunk generation is REALLY 100% finished. Registers lvm callback function to be called when current chunk generation is REALLY 100% finished.
It's the most frustrating function from this mod. It can't provide you access to mapgen objects. They are probably gone long ago. It's the most frustrating function from this mod. It can't provide you access to mapgen objects. They are probably gone long ago.
Don't use it for accessing mapgen objects please. Don't use it for accessing mapgen objects please.
`vm_context` passes into lvm callback function. `vm_context` passes into lvm callback function.
`lvm_callback_function`: the block callback LVM function definition - same as above; * `lvm_callback_function`: the block callback LVM function definition - same as above;
`order_number` (optional): the less, the earlier. * `order_number` (optional): the less, the earlier.
### mcl_mapgen.get_far_node(pos) ### mcl_mapgen.get_far_node(pos)
================================ --------------------------------
Returns node if it is generated, otherwise returns `{name = "ignore"}`. Returns node if it is generated, otherwise returns `{name = "ignore"}`.
## Constants: ### mcl_mapgen.clamp_to_chunk(x, size)
--------------------------------------
Returns new `x`, slighty tuned to make structure of size `size` be within single chunk side of 80 nodes.
### function mcl_mapgen.get_chunk_beginning(x)
----------------------------------------------
Returns chunk beginning of `x`. It is the same as `minp.axis` for per-chunk callbacks, but we don't always have `minp`.
## Constants:
* `mcl_mapgen.EDGE_MIN`, `mcl_mapgen.EDGE_MAX` - world edges, min & max. * `mcl_mapgen.EDGE_MIN`, `mcl_mapgen.EDGE_MAX` - world edges, min & max.
* `mcl_mapgen.seed`, `mcl_mapgen.name` - mapgen seed & name. * `mcl_mapgen.seed`, `mcl_mapgen.name` - mapgen seed & name.
* `mcl_mapgen.v6`, `mcl_mapgen.superflat`, `mcl_mapgen.singlenode` - is mapgen v6, superflat, singlenode. * `mcl_mapgen.v6`, `mcl_mapgen.superflat`, `mcl_mapgen.singlenode` - is mapgen v6, superflat, singlenode.