235 lines
8.0 KiB
Markdown
235 lines
8.0 KiB
Markdown
---
|
|
title: Basic Map Operations
|
|
layout: default
|
|
root: ../..
|
|
idx: 3.1
|
|
description: Basic operations like set_node and get_node
|
|
redirect_from: /en/chapters/environment.html
|
|
---
|
|
|
|
## Introduction <!-- omit in toc -->
|
|
|
|
In this chapter, you will learn how to perform basic actions on the map, such as
|
|
adding, removing, and finding nodes.
|
|
|
|
- [Map Structure](#map-structure)
|
|
- [Reading](#reading)
|
|
- [Reading Nodes](#reading-nodes)
|
|
- [Finding Nodes](#finding-nodes)
|
|
- [Writing](#writing)
|
|
- [Writing Nodes](#writing-nodes)
|
|
- [Removing Nodes](#removing-nodes)
|
|
- [Loading Blocks](#loading-blocks)
|
|
- [Deleting Blocks](#deleting-blocks)
|
|
|
|
## Map Structure
|
|
|
|
The Minetest map is split into MapBlocks, each MapBlocks being a cube of
|
|
size 16. As players travel around the map, MapBlocks are created, loaded,
|
|
activated, and unloaded. Areas of the map which are not yet loaded are full of
|
|
*ignore* nodes, an impassable unselectable placeholder node. Empty space is
|
|
full of *air* nodes, an invisible node you can walk through.
|
|
|
|
An active MapBlock is one which is loaded and has updates running on it.
|
|
|
|
Loaded map blocks are often referred to as *active blocks*. Active Blocks can be
|
|
read from or written to by mods or players, and have active entities. The Engine
|
|
also performs operations on the map, such as performing liquid physics.
|
|
|
|
MapBlocks can either be loaded from the world database or generated. MapBlocks
|
|
will be generated up to the map generation limit (`mapgen_limit`) which is set
|
|
to its maximum value, 31000, by default. Existing MapBlocks can, however, be
|
|
loaded from the world database outside of the generation limit.
|
|
|
|
## Reading
|
|
|
|
### Reading Nodes
|
|
|
|
You can read from the map once you have a position:
|
|
|
|
```lua
|
|
local node = core.get_node({ x = 1, y = 3, z = 4 })
|
|
print(dump(node)) --> { name=.., param1=.., param2=.. }
|
|
```
|
|
|
|
If the position is a decimal, it will be rounded to the containing node.
|
|
The function will always return a table containing the node information:
|
|
|
|
* `name` - The node name, which will be *ignore* when the area is unloaded.
|
|
* `param1` - See the node definition. This will commonly be light.
|
|
* `param2` - See the node definition.
|
|
|
|
It's worth noting that the function won't load the containing block if the block
|
|
is inactive, but will instead return a table with `name` being `ignore`.
|
|
|
|
You can use `core.get_node_or_nil` instead, which will return `nil` rather
|
|
than a table with a name of `ignore`. It still won't load the block, however.
|
|
This may still return `ignore` if a block actually contains ignore.
|
|
This will happen near the edge of the map as defined by the map generation
|
|
limit (`mapgen_limit`).
|
|
|
|
### Finding Nodes
|
|
|
|
Minetest offers a number of helper functions to speed up common map actions.
|
|
The most commonly used of these are for finding nodes.
|
|
|
|
For example, say we wanted to make a certain type of plant that grows
|
|
better near mese; you would need to search for any nearby mese nodes,
|
|
and adapt the growth rate accordingly.
|
|
|
|
`core.find_node_near` will return the first found node in a certain radius
|
|
which matches the node names or groups given. In the following example,
|
|
we look for a mese node within 5 nodes of the position:
|
|
|
|
```lua
|
|
local grow_speed = 1
|
|
local node_pos = core.find_node_near(pos, 5, { "default:mese" })
|
|
if node_pos then
|
|
core.chat_send_all("Node found at: " .. dump(node_pos))
|
|
grow_speed = 2
|
|
end
|
|
```
|
|
|
|
Let's say, for example, that the growth rate increases the more mese there is
|
|
nearby. You should then use a function that can find multiple nodes in the area:
|
|
|
|
```lua
|
|
local pos1 = vector.subtract(pos, { x = 5, y = 5, z = 5 })
|
|
local pos2 = vector.add(pos, { x = 5, y = 5, z = 5 })
|
|
local pos_list =
|
|
core.find_nodes_in_area(pos1, pos2, { "default:mese" })
|
|
local grow_speed = 1 + #pos_list
|
|
```
|
|
|
|
The above code finds the number of nodes in a *cuboid volume*. This is different
|
|
to `find_node_near`, which uses the distance to the position (ie: a *sphere*). In
|
|
order to fix this, we will need to manually check the range ourselves:
|
|
|
|
```lua
|
|
local pos1 = vector.subtract(pos, { x = 5, y = 5, z = 5 })
|
|
local pos2 = vector.add(pos, { x = 5, y = 5, z = 5 })
|
|
local pos_list =
|
|
core.find_nodes_in_area(pos1, pos2, { "default:mese" })
|
|
local grow_speed = 1
|
|
for i=1, #pos_list do
|
|
local delta = vector.subtract(pos_list[i], pos)
|
|
if delta.x*delta.x + delta.y*delta.y + delta.z*delta.z <= 5*5 then
|
|
grow_speed = grow_speed + 1
|
|
end
|
|
end
|
|
```
|
|
|
|
Now the code will correctly increase `grow_speed` based on mese nodes in range.
|
|
|
|
Note how we compared the squared distance from the position, rather than square
|
|
rooting it to obtain the actual distance. This is because computers find square
|
|
roots computationally expensive, so they should avoided as much as possible.
|
|
|
|
There are more variations of the above two functions, such as
|
|
`find_nodes_with_meta` and `find_nodes_in_area_under_air`, which work similarly
|
|
and are useful in other circumstances.
|
|
|
|
## Writing
|
|
|
|
### Writing Nodes
|
|
|
|
You can use `set_node` to write to the map. Each call to set_node will cause
|
|
lighting to be recalculated and node callbacks to run, which means that set_node
|
|
is fairly slow for large numbers of nodes.
|
|
|
|
```lua
|
|
core.set_node({ x = 1, y = 3, z = 4 }, { name = "default:mese" })
|
|
|
|
local node = core.get_node({ x = 1, y = 3, z = 4 })
|
|
print(node.name) --> default:mese
|
|
```
|
|
|
|
set_node will remove any associated metadata or inventory from that position.
|
|
This isn't desirable in all circumstances, especially if you're using multiple
|
|
node definitions to represent one conceptual node. An example of this is the
|
|
furnace node - whilst you conceptually think of it as one node, it's actually
|
|
two.
|
|
|
|
You can set a node without deleting metadata or the inventory like so:
|
|
|
|
```lua
|
|
core.swap_node({ x = 1, y = 3, z = 4 }, { name = "default:mese" })
|
|
```
|
|
|
|
### Removing Nodes
|
|
|
|
A node must always be present. To remove a node, you set the position to `air`.
|
|
|
|
The following two lines will both remove a node, and are both identical:
|
|
|
|
```lua
|
|
core.remove_node(pos)
|
|
core.set_node(pos, { name = "air" })
|
|
```
|
|
|
|
In fact, remove_node is just a helper function that calls set_node with `"air"`.
|
|
|
|
## Loading Blocks
|
|
|
|
You can use `core.emerge_area` to load map blocks. Emerge area is asynchronous,
|
|
meaning the blocks won't be loaded instantly. Instead, they will be loaded
|
|
soon in the future, and the callback will be called each time.
|
|
|
|
```lua
|
|
-- Load a 20x20x20 area
|
|
local halfsize = { x = 10, y = 10, z = 10 }
|
|
local pos1 = vector.subtract(pos, halfsize)
|
|
local pos2 = vector.add (pos, halfsize)
|
|
|
|
local context = {} -- persist data between callback calls
|
|
core.emerge_area(pos1, pos2, emerge_callback, context)
|
|
```
|
|
|
|
Minetest will call `emerge_callback` whenever it loads a block, with some
|
|
progress information.
|
|
|
|
```lua
|
|
local function emerge_callback(pos, action,
|
|
num_calls_remaining, context)
|
|
-- On first call, record number of blocks
|
|
if not context.total_blocks then
|
|
context.total_blocks = num_calls_remaining + 1
|
|
context.loaded_blocks = 0
|
|
end
|
|
|
|
-- Increment number of blocks loaded
|
|
context.loaded_blocks = context.loaded_blocks + 1
|
|
|
|
-- Send progress message
|
|
if context.total_blocks == context.loaded_blocks then
|
|
core.chat_send_all("Finished loading blocks!")
|
|
else
|
|
local perc = 100 * context.loaded_blocks / context.total_blocks
|
|
local msg = string.format("Loading blocks %d/%d (%.2f%%)",
|
|
context.loaded_blocks, context.total_blocks, perc)
|
|
core.chat_send_all(msg)
|
|
end
|
|
end
|
|
```
|
|
|
|
This is not the only way of loading blocks; using an
|
|
[Lua Voxel Manipulator (LVM)](../advmap/lvm.html) will also cause the
|
|
encompassed blocks to be loaded synchronously.
|
|
|
|
## Deleting Blocks
|
|
|
|
You can use delete_blocks to delete a range of map blocks:
|
|
|
|
```lua
|
|
-- Delete a 20x20x20 area
|
|
local halfsize = { x = 10, y = 10, z = 10 }
|
|
local pos1 = vector.subtract(pos, halfsize)
|
|
local pos2 = vector.add (pos, halfsize)
|
|
|
|
core.delete_area(pos1, pos2)
|
|
```
|
|
|
|
This will delete all map blocks in that area, *inclusive*. This means that some
|
|
nodes will be deleted outside the area as they will be on a mapblock which overlaps
|
|
the area bounds.
|