Document upright world planes; mod documentation

docs/ru.md

@@ -0,0 +1,59 @@
+# Tile Rendering — общий движок тайловых карт
+
+Tile Rendering рисует тайловые карты. На вход он получает подготовленное описание карты — землю, объекты, персонажей, источники света — и превращает его в картинку, но сам не решает, под каким углом на неё смотреть. Этот выбор делает небольшой мод-**рендерер**: **Top-down Tiles** показывает карту строго сверху, **Isometric Tiles** — ромбовидной сеткой. Одна и та же карта, те же события и сохранения работают с любым из них.
+
+Сам по себе этот мод не используется: он входит в каждую игру с тайловыми картами — например, в RPG Plus — вместе хотя бы с одним рендерером.
+
+![Одна и та же карта деревни, нарисованная обоими рендерерами: слева квадратный вид сверху, справа изометрия.](assets/same-map-two-projections.jpg)
+
+## Кто за что отвечает
+
+```text
+ content mods            maps, tilesets, events, characters (rpg_demo_game, village_pack…)
+      │
+ RPG mod (rpg)           walking, collisions, events, the camera target, lighting rules
+      │  prepares a "render scene": visuals in cell space, lights, the current frame
+      ▼
+ Tile Rendering          shared drawing: ground chunks, autotiles, sorting, shading,
+ (this mod)              asset loading, the interaction marker, picking
+      │  asks the selected renderer for a projection
+      ▼
+ renderer mod            Square (topdown)  ·  Isometric (isometric)
+                         how a cell maps to screen pixels
+```
+
+- **Игровая логика остаётся квадратной.** Перемещение, коллизии, события и сохранения во всех проекциях работают с логической сеткой. Рендерер меняет лишь то, где что рисуется, и на какую клетку попадает клик.
+- **Один путь отрисовки для игры и редактора.** Редактор RPG-карт рисует холст тем же рендерером, что и игра.
+- **Свет и время суток** задаются в клетках, поэтому лампа освещает одни и те же клетки в обеих проекциях; тайлы и персонажи делят один материал, смешивающий время суток и точечные источники света.
+
+## Выбор проекции
+
+Проекция — настройка игры, **Проекция карты** (`tile.renderer`), в группе **Мир** настроек коллекции. Варианты — **Вид сверху** (`topdown`) и **Изометрия** (`isometric`); в RPG Plus выбран `topdown`. Чтобы сменить её, откройте **Моды и коллекции → Коллекции → RPG Plus → Изменить схему**, задайте проекцию и проследите, чтобы в игру входил соответствующий мод-рендерер.
+
+- Если настройка называет рендерер, которого в игре нет, карта не переключится на другой; в журнале будут перечислены доступные рендереры.
+- Если настройка пуста, а установлен ровно один рендерер, используется он.
+- Для одного запуска ключ командной строки `--tile-renderer=isometric` (или `topdown`) переопределяет настройку.
+
+## Авторам модов: новая проекция
+
+Мод-рендерер зависит от `tile_render_base` и содержит один класс, реализующий `ITileRendererFactory`:
+
+- `Id` — значение, которое игроки выбирают в **Проекции карты**, например `hex`;
+- `Projection(tileSize)` — отображение «клетка → пиксели», которым пользуются игра, редактор и выбор щелчком мыши;
+- `Create()` — новое представление карты; общее представление холста можно переиспользовать со своей проекцией.
+
+Фабрика находится автоматически при загрузке мода и убирается при выгрузке. Чтобы проекция появилась в **Проекции карты**, добавьте вариант в `collection_settings.json` своего мода — как это делает Top-down Tiles:
+
+```json
+{
+  "options": [
+    { "key": "tile.renderer", "value": "topdown", "name": "collection_settings/topdown" }
+  ]
+}
+```
+
+Ключ `name` переводится в `locale/collection_settings_<lang>.properties`.
+
+## Если что-то пошло не так
+
+1. **Карта пуста, а в журнале написано, что рендерер недоступен.** **Проекция карты** игры называет мод-рендерер, которого нет в составе игры; добавьте его или поменяйте настройку.