Finish 0.3.26.8

docs/source/development/child_projects.rst

@@ -25,6 +25,8 @@ utg — генератор русского текста
 :github: https://github.com/the-tale/utg
 
 
+.. _deworld_project:
+
 deworld — генератор карты для игры
 ----------------------------------
 
@@ -39,7 +41,11 @@ deworld — генератор карты для игры
 - направление ветра
 - растительность
 
-Параметры влияют друг на друга, что позволяет получить «естественное» изменение карты.
+Каждому параметру соответствует отдельный слой данных, который пересчитывается каджый шаг на основе данных всех слоёв предыдущего шага.
+
+Игровые объекты могут влиять на изменение параметров, устанавливая «точки влияния», которые изменяют параметры слоя в заданной области.
+
+За счёт подобного подхода удаётся получить «реалистичное» изменение ланшафта не сходящееся к стабильному состоянию (так как влияние игровых объектов постоянно меняется, мешая сходимости).
 
 :github: https://github.com/the-tale/deworld
 

docs/source/development/guides/index.rst

@@ -5,3 +5,4 @@
    :maxdepth: 2
 
    mails
+   map

docs/source/development/guides/map.rst

@@ -0,0 +1,86 @@
+Карта мира и работа с ней
+=========================
+
+На этой странице в общих чертах описывается техническое устройство карты мира.
+
+Карта изменяется раз в час под влиянием параметров, задаваемых действиями игроков, и своего предыдущего состояния.
+
+Карта всегда представляется клеточным полем.
+
+Весь код (кроме низкоуровневого моделирования ландшафта) можно найти:
+
+- Python: `модуль the_tale.game.map <https://github.com/the-tale/the-tale/tree/develop/src/the_tale/the_tale/game/map>`_.
+- JavaScript `модуль map2.js <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/static/game/map/map2.js>`_
+
+Уровни формирования карты
+-------------------------
+
+Формирование карты можно разбить на несколько уровней, на каждом из которых она обрабатывается особым образом.
+
+- Моделирование базовых параметров мира.
+- Выделение биомов — узнаваемых типов ландшафта, которые лучше всего соответствуют параметрам клетки карты (горы, джунгли, равнина, etc.).
+- Фомирование схемы тайлового отображения карты — именно эта схема отдаётся браузеру и по ней рисуется карта.
+- Отображение карты браузером.
+
+Моделирование параметров мира
+-----------------------------
+
+Моделирование карты осуществляется отдельной библиотекой :ref:`deworld <deworld_project>`:
+
+- github: https://github.com/the-tale/deworld
+- :ref:`немного документации <deworld_project>`
+
+Моделируется несколько базовых параметров (высота, температура, растительность, etc.) с учётом влияния игровых объектов.
+
+На выходе этого этапа карта представлена набором слоёв, с нормированными величинами каждого параметра (например, температуры).
+
+Игровые объекты влияют на эти параметры, задавая «точки влияния». Кажая точка описывается:
+
+- координатами клетки на карте;
+- описанием области, на которую распространяются изменения;
+- слоем, который она изменяет;
+- величиной и правилами изменения параметра слоя.
+
+Описание «точек влияния» можно найти в `исходниках игры <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/game/map/generator/power_points.py>`_.
+
+Также, по этим данным формируется текстовое описание клетки. `Исходный код <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/game/map/generator/descriptors.py>`_.
+
+Выделение биомов
+----------------
+
+Поскольку реализовать отображение карты для всех возможных сочетаний параметров сложно, у нас выделено несколько выделяющихся типов ландшафта, которые мы называем биомами.
+
+Для каждой клетки карты биом выбирается по следующему алгоритму:
+
+- Пространство значений каждого параметра бьётся на интервалы (например, влажность, измеряемая от 0 до 1 бьётся, на 10 интервалов с шагом 0.1).
+- Для каждого сочетания биома с интервалом значения в балансе игры прописано количество «очков», которое биом получит, если значение параметра в клетке попадает в интервал.
+- Для каждого биома считается сумма очков всех параметров клетки.
+- Биомом клетки выбирается биом с максимальным количеством очков.
+
+`Файл с очками биомов <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/game/map/fixtures/bioms.xls>`_
+
+Фомирование схемы отображения карты
+-----------------------------------
+
+Данных о биомах и объектах карты уже хватило бы, чтобы нарисовать её в клиентах игры. Но, чтобы упростить реализацию новых клиентов, мы делаем предобработку данных карты.
+
+В итоге клиенту возвращается двухмерный массив. В каждой клетке массива находится список идентификаторов спрайтов, которые нужно отобразить и угол их поворота. Спрайты указаны в порядке отрисовки.
+
+Получение карты и её формат описаны :ref:`документации нашего API <external_api__region>`.
+
+Отображение карты клиентом
+--------------------------
+
+Клиенту остаётся получить инструкцию по отрисовке карты и исполнить её.
+
+- `Python код с отрисовкой карыт <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/game/map/management/commands/map_visualize_region.py>`_
+- `Javascript код с отрисовко карты <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/static/game/map/map2.js>`_
+
+Обновление карты на сервере
+---------------------------
+
+Для обновления карты на сервере есть отдельная команда.
+
+.. code-block: bash
+
+   django-admin map_update_map --settings the_tale.settings

docs/source/external_api/methods.rst

@@ -359,7 +359,7 @@
                  "actors": [                  // список «актёров», участвующих в задании
                    [
                      "строка",                // название актёра
-                     <целое число>",                // тип актёра (список типов приведён в описании API)
+                     <целое число>,           // тип актёра (список типов приведён в описании API)
                      <quest_actor_info>       // данные, специфичные для конкретного типа актёра
                    ]
                  ]
@@ -772,7 +772,7 @@
              "practical": <целое число>             // идентификатор практической особенности характера
          }
        },
-       …
+       ...
     ]
 
     <attributes_info> = {                                // информация о всех параметрах города
@@ -795,14 +795,14 @@
         "percents": <дробное число>, // текущая доля (от 0 до 1)
         "delta": <дробное число>,    // изменение в день
         "persons": <дробное число>}, // влияние Мастеров (от 0 до 1)
-      …
+      ...
     ]
 
     <bills_info> = [
       { "id": <целое число>,           // идентификатор записи
         "caption": "строка",           // название записи
-        "properties": ["строка", …] }, // перечень описаний эффектов
-      …
+        "properties": ["строка", ...] }, // перечень описаний эффектов
+      ...
     ]
 
     <habits_info> = {  // информация о каждой черте города в формате "идентификатор черты": {информация о черте}
@@ -811,10 +811,10 @@
                         "delta": <дробное число>,              // величина изменения черты за один час
                         "positive_points": <дробное число>,    // суммарное позитивное влияние героев на черту города
                         "negative_points": <дробное число> },  // суммарное негативное влияние героев на черту города
-      …
+      ...
     }
 
-    <chronicle_info> = [("строка", "строка", "строка"), …] // последние записи из летописи о городе в формате ("короткая дата", "длинная дата", "текст")
+    <chronicle_info> = [("строка", "строка", "строка"), ...] // последние записи из летописи о городе в формате ("короткая дата", "длинная дата", "текст")
 
     <accounts_info> = {
       "<целое число>": {            // идентификатор игрока
@@ -828,15 +828,15 @@
           "level": <целое число> }, // уровень
         "clan": <целое число>|null  // идентификатор клана
       },
-      …
+      ...
     }
 
     <clans_info> = {
      "<целое число>": {     // идентификатор клана
        "id": <целое число>, // идентификатор клана
        "abbr": "строка",    // аббревиатура
        "name": "строка"},   // полное название
-     …
+     ...
     }
 
     <job_info> = {
@@ -896,6 +896,7 @@
       "clans": <clans_info>               // краткая дополнительная информация о кланах, связанных с Мастером
     }
 
+.. _external_api__region:
 
 Карта: получить карту
 ---------------------
@@ -910,8 +911,63 @@
 :ошибки:
     * no_region_found - для заданного хода нет сохранённых данных
 
-**Стабильность формата данных в ответе не гарантируется.**
+Формат данных в ответе.
+
+.. code-block:: javascript
+
+    {
+        "turn": <целое>,                // номер хода, на котором была создана эта версия карты
+        "region": {                     // описание карты
+            "format_version": "строка", // версия формата
+            "map_version": "строка",    // уникальный идентификатор этой версии карты
+            "width": <целое>,           // размер карты по ширине
+            "height": <целое>,          // размер карты по высоте
+
+            "draw_info":           // инструкция по отрисовке
+            [                      // строки карты
+                [                  // столбцы карты
+                    [              // список спрайтов конкретной клетки
+                        [<целое>,  // идентикаитор спрайта
+                         <целое>], // идентификатор поворота:
+                                   // 0 — 0 градусов
+                                   // 1 — 90 градусов
+                                   // 2 — 180 градусов
+                                   // 3 — 270 градусов
+                        ...
+                    ]
+                ]
+            ],
+
+            "places": {                    // перечень городов
+                "<целое>": {               // идентификатор города
+                    "name": "строка",      // название
+                    "race": <целое>,       // раса
+                    "pos": {"y": <целое>,  // координаты клетки на карте
+                            "x": <целое>},
+                    "id": <целое>,         // идентификатор города
+                    "size": <целое>        // размер
+                }
+            },
+            "roads": {                     // перечень дорог
+                "<целое>": {
+                    "point_1_id": <целое>, // из каого объекта (города) идёт дорога
+                    "point_2_id": <целое>, // в какой объект (город) идёт дорога
+                    "id": <целое>,         // идентификатор дороги
+                    "exists": true|false,  // видим ли дорога на карет
+                    "length": <дробное>,   // длинна дороги
+                    "path": "строка"       // путь из точки 1 в точку 2 по клеткам, последовательность символов:
+                                           // l — left — влево
+                                           // r — right — вправо
+                                           // u — up — вверх
+                                           // d — down — вниз
+                }
+            }
+        }
+    }
+
+Актуальный список спрайтов можено найти `в константах браузерного клиента <https://static.the-tale.org/static/244/game/data/constants.js>`_.
 
+Более удобное описание спрайтов можно найти в `python коде <https://github.com/the-tale/the-tale/blob/develop/src/the_tale/the_tale/game/map/relations.py>`_
 
 Карта: получить список версий карт
 ----------------------------------
@@ -929,5 +985,5 @@
 .. code-block:: javascript
 
     {
-        "turns": [<целое>, …] // номер хода, для которого есть карта
+        "turns": [<целое>, ...] // номер хода, для которого есть карта
     }