Merge pull request #539 from MihailRis/update-docs

Update 0.28 docs

doc/en/block-properties.md

@@ -62,6 +62,7 @@ Rotation profile (set of available block rotations and behaviour of placing bloc
 - "none" - no rotation available (default profile)
 - "pipe" - wood logs, pipes, pillars
 - "pane" - panels, doors, signs
+- "stairs" - "pane" + flipped variants
 
 ## Lighting
 

doc/en/resources.md

@@ -6,7 +6,9 @@ Resources include:
 - framebuffers
 - and other limited resources
 
-At the moment only **cameras** are implemented.
+At the moment only the following are implemented:
+- camera - **camera**.
+- post-effect - **effect slot**.
 
 The resources requested by the pack are specified through the *resources.json* file in the format:
 ```json

doc/en/scripting.md

@@ -19,6 +19,7 @@ Subsections:
     - [file](scripting/builtins/libfile.md)
     - [gfx.blockwraps](scripting/builtins/libgfx-blockwraps.md)
     - [gfx.particles](particles.md#gfxparticles-library)
+    - [gfx.posteffects](scripting/builtins/libgfx-posteffects.md)
     - [gfx.text3d](3d-text.md#gfxtext3d-library)
     - [gfx.weather](scripting/builtins/libgfx-weather.md)
     - [gui](scripting/builtins/libgui.md)

doc/en/scripting/builtins/libgfx-posteffects.md

@@ -0,0 +1,37 @@
+# gfx.posteffects library
+
+A library for post-processing effects control.
+
+The effect slot is a resource and must be declared in resources.json in the root directory of the pack:
+
+```json
+{
+    "post-effect-slot": [
+        "slot_name"
+    ]
+}
+```
+
+```lua
+-- Returns the index of the effect slot by name (pack:slot_name).
+-- If the specified slot does not exist, returns -1
+gfx.posteffect.index(name: str) --> int
+
+-- Assigns the effect to the slot
+gfx.posteffect.set(slot: int, effect: str)
+
+-- Returns the effect intensity (from 0.0 to 1.0)
+-- If the slot is empty, returns 0.0
+gfx.posteffect.get_intensity(slot: int) --> number
+
+-- Sets the effect intensity (from 0.0 to 1.0)
+-- (The correctness of processing the parameter between 0.0 and 1.0 
+-- depends on the effect)
+gfx.posteffect.set_intensity(slot: int, intensity: number)
+
+-- Returns true if the slot is not empty and the effect intensity is non-zero
+gfx.posteffect.is_active(slot: int) --> bool
+
+-- Sets parameters values ('param' directives)
+gfx.posteffect.set_params(params: table)
+```

doc/en/scripting/ui.md

@@ -202,6 +202,17 @@ Here, *color* can be specified in the following ways:
 |----------|--------|------|-------|-----------------------------|
 | src      | string | yes  | yes   | id of the embedded document |
 
+## Select
+
+Derived from button with access to properties such as the text to display.
+
+Properties:
+
+| Name    | Type   | Read | Write | Description                                      |
+|---------|--------|------|-------|--------------------------------------------------|
+| value   | string | yes  | yes   | Selected value                                   |
+| options | table  | yes  | yes   | List of options (tables `{value=..., text=...}`) |
+
 ## Inventory
 
 Properties:

doc/en/xml-ui-layouts.md

@@ -163,6 +163,25 @@ Container for embedding an external document. Content is scaling to the iframe s
 
 - `src` - document id in the format `pack:name` (`pack/layouts/name.xml`)
 
+## *select*
+
+Drop-down list. Options are described by `option` sub-elements, the `value` attribute of which contains the value, the inner text is the text displayed in the UI.
+
+Example of list description:
+
+```xml
+<select selected="entity" width="200"
+        onselect="function(opt) print(opt) end">
+    <option value="block">Block</option>
+    <option value="item">Item</option>
+    <option value="entity">Entity</option>
+</select>
+```
+
+- `width` - minimum content width. Default: 100.
+- `selected` - initially selected value. Default: "".
+- `onselect` - function to which the user-selected value is passed
+
 # Inventory elements
 
 ## *inventory*

doc/ru/block-properties.md

@@ -63,6 +63,7 @@
 - "none" - вращение блока отключено (по-умолчанию)
 - "pipe" - профиль "труба". Примеры блоков: бревно, труба, лампочка
 - "pane" - профиль "панель". Примеры блоков: панель, дверь, табличка
+- "stairs" - профиль "ступеньки" ("pane" + перевернутые варианты)
 
 ### Испускаемые частицы - *particles*
 

doc/ru/resources.md

@@ -6,7 +6,9 @@
 - фреймбуферы
 - и подобные ограниченные по количеству ресурсы
 
-На данный момент реализованы только **камеры**.
+На данный момент реализованы только:
+- camera - **камера**.
+- post-effect - **слот эффектов**.
 
 Запрашиваемые паком ресурсы указываются через файл resources.json в формате:
 ```json

doc/ru/scripting.md

@@ -19,6 +19,7 @@
     - [file](scripting/builtins/libfile.md)
     - [gfx.blockwraps](scripting/builtins/libgfx-blockwraps.md)
     - [gfx.particles](particles.md#библиотека-gfxparticles)
+    - [gfx.posteffects](scripting/builtins/libgfx-posteffects.md)
     - [gfx.text3d](3d-text.md#библиотека-gfxtext3d)
     - [gfx.weather](scripting/builtins/libgfx-weather.md)
     - [gui](scripting/builtins/libgui.md)

doc/ru/scripting/builtins/libgfx-posteffects.md

@@ -0,0 +1,37 @@
+# Библиотека gfx.posteffects
+
+Библиотека для работы с эффектами пост-обработки.
+
+Слот эффектов является ресурсом, и должен быть объявлен в resources.json в корневой директории пака:
+
+```json
+{
+    "post-effect-slot": [
+        "имя_слота"
+    ]
+}
+```
+
+```lua
+-- Возвращает индекс слота эффектов по имени (пак:имя_слота).
+-- При отсутствии указанного слота возвращает -1
+gfx.posteffect.index(name: str) --> int
+
+-- Назначает эффект на слот
+gfx.posteffect.set(slot: int, effect: str)
+
+-- Возвращает интенсивность эффекта (от 0.0 до 1.0)
+-- Если слот пуст, возвращает 0.0
+gfx.posteffect.get_intensity(slot: int) --> number
+
+-- Устанавливает интенсивность эффекта (от 0.0 до 1.0)
+-- (Корректность обработки параметра между значениями 0.0 и 1.0 зависит
+-- от эффекта
+gfx.posteffect.set_intensity(slot: int, intensity: number)
+
+-- Возвращает true если слот не пуст и интенсивность эффекта ненулевая
+gfx.posteffect.is_active(slot: int) --> bool
+
+-- Устанавливает значения параметров (директивы 'param')
+gfx.posteffect.set_params(params: table)
+```

doc/ru/scripting/ui.md

@@ -169,7 +169,6 @@ document["worlds-panel"]:clear()
 | src      | string | да     | да     | отображаемая текстура  |
 | region   | vec4   | да     | да     | под-регион изображения |
 
-
 ## Холст (canvas)
 
 Свойства:
@@ -203,6 +202,17 @@ document["worlds-panel"]:clear()
 |----------|--------|--------|--------|----------------------------|
 | src      | string | да     | да     | id встраиваемого документа |
 
+## Меню выбора (select)
+
+Является производным от кнопки с доступом к свойствам, таким как отображаемый текст.
+
+Свойства:
+
+| Название | Тип    | Чтение | Запись | Описание                                                       |
+|----------|--------|--------|--------|----------------------------------------------------------------|
+| value    | string | да     | да     | Выбранное значение                                             |
+| options  | table  | да     | да     | Список опций (таблиц `{value=..., text=...}`)                  |
+
 ## Инвентарь (inventory)
 
 Свойства:

doc/ru/xml-ui-layouts.md

@@ -164,6 +164,25 @@
 
 - `src` - id документа в формате `пак:имя` (`пак/layouts/имя.xml`)
 
+## Меню выбора - *select*
+
+Раскрывающийся список. Опции описываются под-элементами `option`, атрибут `value` которых содержит значение, внутренний текст - текст отображаемый в UI.
+
+Пример описания списка:
+
+```xml
+<select selected="entity" width="200" 
+        onselect="function(opt) print(opt) end">
+    <option value="block">Блок</option>
+    <option value="item">Предмет</option>
+    <option value="entity">Сущность</option>
+</select>
+```
+
+- `width` - минимальная ширина содержимого. По-умолчанию: 100.
+- `selected` - изначально выбранное значение. По-умолчанию: "".
+- `onselect` - функция, в которую передаётся выбранное пользователем значение
+
 # Элементы инвентаря
 
 ## Инвентарь - *inventory*