update world-generator.md

doc/ru/world-generator.md

@@ -245,6 +245,113 @@ generation.save_fragment(
 
 Фрагмент может быть обрезан до размеров содержимого (воздух игнорируется) вызовом метода `fragment:crop()`.
 
+## Генерация карты высот
+
+По-умолчанию, движок генерирует карту высот, состоящую из нулей.
+
+Для генерации пользовательских карт высот требуется реализовать функцию:
+```lua
+function generate_heightmap(
+    x, y, -- смещение карты высот
+    w, h, -- размер карты высот, ожидаемый движком
+    seed, -- зерно мира
+    bpd,  -- число блоков на точку карты (blocks per dot) - масштаб
+    [опционально] inputs -- массив входных карт параметров биомов
+    -- (см. свойство heightmap-inputs генератора)
+) --> Heightmap
+```
+
+Пример генерации карты высот из простого симплекс-шума с приведением
+к нужному диапазону:
+
+```lua
+function generate_heightmap(x, y, w, h, seed, bpd)
+    -- создаем карту высот с заданным размером
+    local map = Heightmap(w, h)
+    -- настраиваем зерно шума
+    map.noiseSeed = seed
+    -- шум с масштабом 1/10 на 4 октавы с амплитудой 0.5
+    map:noise({x, y}, 0.1*bpd, 4, 0.5)
+    -- сдвигаем высоты к положительному диапазону
+    map:add(0.5)
+    return map
+end
+```
+
+## Ручная расстановка структур
+
+### Размещения структур/тоннелей
+
+Размещение структуры / линии представляет собой массив из заданного
+набора параметров.
+
+Структура:
+```lua
+{имя_структуры, позиция_структуры, поворот, [опционально] приоритет}
+```
+
+Где:
+- имя_структуры - строка содержащая имя структуры, зарегистрированная в structures.toml.
+- позиция_структуры - vec3 (массив из трех чисел) относительно позиции чанка.
+- поворот - число от 0 до 3 обозначающая поворот структуры по оси Y.
+- приоритет - число определяющее порядок установки структур. Структуры с меньшем приоритетом перекрываются структурами с большим.
+
+Тоннель:
+```lua
+{":line", блок_заполнитель, точка_а, точка_б, радиус}
+```
+
+Где:
+- блок_заполнитель - числовой id блока, из которого будет состоять структура.
+- точка_а, точка_б - vec3, vec3 позиции начала и конца тоннеля.
+- радиус - радиус тоннеля в блоках
+
+
+### Расстановка малых структур
+
+```lua
+function place_structures(
+    x, z, -- позиция начала области в блоках
+    w, d, -- размер области в блоках
+    seed, -- зерно мира
+    heights, -- карта высот чанка
+    chunk_height, -- высота чанка
+) --> массив размещений структур
+```
+
+Структуры могут размещаться за пределами чанка, но не дальше, чем на один чанк.
+
+Пример:
+
+```lua
+function place_structures(x, z, w, d, seed, hmap, chunk_height)
+    local placements = {}
+    local height = hmap:at(w/2, h/2) * chunk_height
+
+    -- устанавливает башню по центру чанка
+    table.insert(placements, {
+        'tower', {w/2, height, d/2}, math.random() * 4, 2
+    })
+    return placements
+end
+```
+
+### Расстановка 'широких' структур
+
+Структуры и тоннели могут размещаться за пределами чанка, но не дальше, чем на число чанков, указанное в свойстве генератора `wide-structs-chunks-radius`.
+
+В отличие от прошлой функции, сюда не передается карта высот,
+так как вызов происходит на ранних этапах генерации чанка.
+
+```lua
+function place_structures_wide(
+    x, z, -- позиция начала области в блоках
+    w, d, -- размер области в блоках
+    seed, -- зерно мира
+    chunk_height, -- высота чанка
+) --> массив размещений структур / тоннелей
+```
+
 ## Структурный воздух
 
 `core:struct_air` - блок, которые следует использовать в фрагментах для обозначения пустого пространства, которое не должно заполняться блоками при генерации в мире.