update world-generator.md

doc/ru/world-generator.md

@@ -88,18 +88,18 @@ structures = [
 - ключ forest - имя биома
 - parameters - веса и центральные значения параметров для биома. См. раздел [выбор биома](#выбор-биома). Количество записей должно соответствовать количеству параметров выбора биомов.
 - layers - слои блоков от верхнего к нижнему.
-	- height - высота слоя в блоках. -1 используется для обозначения безразмерного (заполняющего) слоя, который может быть только один. Его высота вычисляется автоматически.
+    - height - высота слоя в блоках. -1 используется для обозначения безразмерного (заполняющего) слоя, который может быть только один. Его высота вычисляется автоматически.
-	- block - полное имя блока
+    - block - полное имя блока
-	- below-sea-level - может ли слой быть сгенерированным ниже уровня моря (пример: дёрн). При значении false, при генерации ниже уровня моря, слой будет заменён на следующий.
+    - below-sea-level - может ли слой быть сгенерированным ниже уровня моря (пример: дёрн). При значении false, при генерации ниже уровня моря, слой будет заменён на следующий.
 - sea-layers - слои океана. Положение верхнего слоя совпадает с высотой уровня моря.
 - plant-chance - вероятность генерации растения на блоке поверхности.
 - plants - растения, случайно расставляемые на поверхности.
-	- weight - вес, напрямую влияющий на шанс выбора конкретного растения.
+    - weight - вес, напрямую влияющий на шанс выбора конкретного растения.
-	- block - блок растения
+    - block - блок растения
 - structure-chance - вероятность генерации малой структуры на блоке поверхности.
 - structures - структуры, случайно расставляемые на поверхности.
-	- name - имя структуры, объявленной в `structures.json`.
+    - name - имя структуры, объявленной в `structures.json`.
-	- weight - вес, напрямую влияющий на шанс выбора конкретной структуры.
+    - weight - вес, напрямую влияющий на шанс выбора конкретной структуры.
 
 ### Параметры биомов
 
@@ -113,14 +113,14 @@ structures = [
 -- w, h - ширина и высота карты (в точках)
 -- bpd  - (blocks per dot) число блоков на точку (масштаб)
 function generate_biome_parameters(x, y, w, h, seed, bpd)
-	-- создание карт высот (Heightmap) для каждого параметра биомов
+    -- создание карт высот (Heightmap) для каждого параметра биомов
-	-- ...
+    -- ...
-	return карты_через_запятую
+    return карты_через_запятую
 end
 
 -- пример
 function generate_biome_parameters(x, y, w, h, seed, s)
-	-- карта температур
+    -- карта температур
     local tempmap = Heightmap(w, h)
     tempmap.noiseSeed = seed + 5324
     tempmap:noise({x, y}, 0.04*s, 6)
@@ -182,18 +182,18 @@ map:dump('export:test.png')
 
 ```lua
 map:noise(
-	-- смещение координат
+    -- смещение координат
-	offset: {number, number},
+    offset: {number, number},
-	-- коэфициент масштабирования координат
+    -- коэфициент масштабирования координат
-	scale: number,
+    scale: number,
-	-- число октав шума (по-умолчанию: 1)
+    -- число октав шума (по-умолчанию: 1)
-	[опционально] octaves: integer,
+    [опционально] octaves: integer,
-	-- множитель амплитуды шума (по-умолчанию: 1.0)
+    -- множитель амплитуды шума (по-умолчанию: 1.0)
-	[опционально] multiplier: number,
+    [опционально] multiplier: number,
-	-- карта смещений координаты X при генерации шума
+    -- карта смещений координаты X при генерации шума
-	[опционально] shiftMapX: Heightmap,
+    [опционально] shiftMapX: Heightmap,
-	-- карта смещений координаты Y при генерации шума
+    -- карта смещений координаты Y при генерации шума
-	[опционально] shiftMapY: Heightmap,
+    [опционально] shiftMapY: Heightmap,
 ) -> nil
 ```
 
@@ -214,30 +214,30 @@ map:noise(
 Фрагмент создается вызовом функции:
 ```lua
 generation.create_fragment(
-	-- точка A
+    -- точка A
-	a: vec3,
+    a: vec3,
-	-- точка B
+    -- точка B
-	b: vec3,
+    b: vec3,
-	-- автоматически обрезать фрагмент, если возможно
+    -- автоматически обрезать фрагмент, если возможно
-	crop: bool
+    crop: bool
 ) -> VoxelFragment
 ```
 
 Фрагмент может быть загружен из файла:
 ```lua
 generation.load_fragment(
-	-- файл фрагмента
+    -- файл фрагмента
-	filename: str
+    filename: str
 ) -> VoxelFragment
 ```
 
 Фрагмент может быть сохранен в файл:
 ```lua
 generation.save_fragment(
-	-- сохраняемый фрагмент
+    -- сохраняемый фрагмент
-	fragment: VoxelFragment,
+    fragment: VoxelFragment,
-	-- файл
+    -- файл
-	filename: str
+    filename: str
 ) -> nil
 ```
 
@@ -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` - блок, которые следует использовать в фрагментах для обозначения пустого пространства, которое не должно заполняться блоками при генерации в мире.