@@ Строка 1: / Строка 1: @@
-<dpl>
+{{docpage}}{{TOC hidden}}
-   namespace          = File
+{{OnLua|Сущность|module1=Сущность|module2=Сущность/поля|module3=GetField}}
-   categoriesminmax   = 1,
-   notcategory        = Запрос на удаление
+Модульный набор {{tl|Модуль:Сущность}} + {{tl|Модуль:Сущность/поля}} + {{tl|Модуль:GetField}} предназначен для:
-  notcategory        = Файлы:Имеющие описание
+* автоматической сборки карточек сущностей (компонентов и прототипов) по их ID;
-   format   = ,,# [[%PAGE%]]\n,
+* описания полей в шаблонах компонентов (какие поля идут в карточку, как подписаны);
-</dpl>
+* удобного доступа к данным из JSON (как простыми значениями, так и готовыми вызовами шаблонов).
+Ниже описан общий принцип работы и отдельные режимы.
+== Общий принцип работы ==
+* В шаблонах компонентов/прототипов (<code>Template:Component/...</code>, <code>Template:prototype/...</code>) через {{tl|Модуль:Сущность/поля}} описываются поля:
+** '''лейблы''' (<code>cardLabel_*</code>) и '''содержимое''' (<code>cardContent_*</code>), заголовки (<code>title_*</code>) и т. п.;
+** '''мета‑информация''' о том, какие ключи доступны для <code>card</code> / <code>title</code> и в каком порядке.
+* {{tl|Модуль:Сущность}} по ID сущности:
+** находит связанные с ней компоненты и прототипы по JSON‑данным;
+** для каждого компонента/прототипа читает шаблоны и метаданные;
+** собирает все поля в единую структуру;
+** формирует один вызов карточки <code><nowiki>{{карточка/сущность|...}}</nowiki></code> (и блоки заголовков).
+* Внутри полей можно писать вики‑параметры <code>{{{...}}}</code> и вызывать дополнительные модули.
+* {{tl|Модуль:GetField}} даёт доступ к JSON‑данным на низком уровне:
+** как «расплющенный» набор параметров (<code>flattenField</code>);
+** как отдельные значения (<code>get</code>);
+** как готовые вызовы шаблонов с нужными параметрами (<code>getTpl</code>, <code>getTplProto</code>).
+== Модуль: Сущность/поля ==
+Шаблоны компонентов используют модуль <code>Сущность/поля</code> для объявления полей, которые будут собираться в карточку.
+Пример шаблона компонента:
+<pre>
+{{#invoke:Сущность/поля|main
+ |cardLabel_Стоимость   = [[Стоимость]]
+ |cardContent_Стоимость = '''{{{price}}}'''
+}}
+</pre>
+Другой компонент может добавлять тот же ключ:
+<pre>
+{{#invoke:Сущность/поля|main
+ |cardContent_Стоимость  = '''{{{superPrice}}}'''
+}}
+</pre>
+Особенности:
+* Пара <code>cardLabel_<Ключ></code> / <code>cardContent_<Ключ></code> описывает одну строку карточки (лейбл и содержимое).
+* Если несколько шаблонов дают один и тот же <code>cardContent_Ключ</code>, содержимое '''объединяется''', а лейбл берётся первый непустой.
+* То же относится к другим режимам, перечисленным в мета‑JSON шаблона (разделы <code>card</code>, <code>title</code> и т. п.), которые читает {{tl|Модуль:Сущность}}.
+== Модуль: Сущность ==
+=== p.get: основная сборка карточки ===
+Вызов:
+<pre>
+{{#invoke:Сущность|get
+ | <ID или список ID>
+ | blacklist=...
+ | whitelist=...
+ | ignoreComponents=...
+ | ignorePrototypes=...
+}}
+</pre>
+* '''1‑й параметр''' — <code>id</code> или список <code>id</code> через запятую.
+* По этому ID модуль находит:
+** '''компоненты''' из <code>component.json</code>;
+** '''прототипы''' из <code>prototype.json</code>;
+и для каждого — соответствующие шаблоны <code>Template:component/...</code> / <code>Template:prototype/...</code>.
+* Шаблоны описывают свои поля через <code>Сущность/поля</code>.
+После сборки модуль:
+* формирует один вызов <code><nowiki>{{карточка/сущность|...}}</nowiki></code> со всеми разделами и полями;
+* дополняет выход при необходимости (блоки title и т. п.);
+* прогоняет результат через <code>frame:preprocess</code>, чтобы отрендерить разметку.
+Параметры фильтрации:
+* {{пм|blacklist}} — список <code>режим_Ключ</code> через запятую, чтобы исключить поле:
+** пример: <code>blacklist=card_Наносит повреждения,title_Что‑то</code>;
+* {{пм|whitelist}} — наоборот, список разрешённых <code>режим_Ключ</code>, остальные игнорируются;
+* {{пм|ignoreComponents}} / {{пм|ignoreComponent}} — список имён компонентов через запятую, которые полностью игнорируются для этого вызова;
+* {{пм|ignorePrototypes}} / {{пм|ignorePrototype}} — аналогично для прототипов.
+Пример простой сборки (через шаблон‑обёртку):
+<pre>
+{{Сущность/карточка|MyEntityId}}
+</pre>
+где в шаблоне <code>Сущность/карточка</code> внутри:
+<pre>
+{{#invoke:Сущность|get|{{{1}}}}}
+</pre>
+=== p.preview: предпросмотр полей конкретного шаблона ===
+Используется для проверки, что компонент/прототип правильно описал свои поля.
+<pre>
+{{#invoke:Сущность|preview
+ | Component/meleeWeapon
+}}
+</pre>
+* Показывает, какие <code>card</code> / <code>title</code>‑поля объявлены в <code>Template:Component/meleeWeapon</code>.
+* Удобно при разработке шаблонов компонентов.
+=== p.jsonList: вывод JSON в виде списка ===
+Режим похож на стандартный <code>arraymap</code>, но работает с JSON.
+<pre>
+{{#invoke:Сущность|jsonList
+ | <json или {{{...}}}>
+ | type = list / enum
+ | prefix = *
+ | sep = :
+ | key_pattern = (.*)
+ | key_replace = \1
+ | value_pattern = (.*)
+ | value_replace = \1
+}}
+</pre>
+Примеры JSON:
+<pre> <!-- <syntaxhighlight lang=json> -->
+{
+   "Blunt": 10,
+   "Slash": 5
+}
+</pre> <!-- </syntaxhighlight> -->
+или
+<pre> <!-- <syntaxhighlight lang=json> -->
+["Knife", "Sword", "Bat"]
+</pre> <!-- </syntaxhighlight> -->
+Основные опции:
+* {{пм|type}}:
+** <code>list</code> — список строк (с префиксом, например <code>* </code>);
+** <code>enum</code> — перечисление через запятую (<code>A, B, C</code> без префикса).
+* {{пм|prefix}} — префикс строки списка (по умолчанию <code>* </code>).
+* {{пм|sep}} — разделитель для <code>ключ: значение</code> (по умолчанию <code>: </code>).
+* {{пм|key_pattern}} / {{пм|key_replace}} — regex и замена для ключей.
+* {{пм|value_pattern}} / {{пм|value_replace}} — regex и замена для значений.
+Дополнительно:
+* в шаблоне замены поддерживаются:
+** <code>\1</code> — собственное значение (ключ или значение);
+** <code>\2</code> в <code>value_replace</code> — '''сырой ключ''' (после <code>key_pattern</code>, но до <code>key_replace</code>);
+** <code>\2</code> в <code>key_replace</code> — итоговое отформатированное значение (после <code>value_replace</code>).
+Пример, где сначала форматируем тип урона, а затем подставляем его в описание:
+<pre>
+{{#invoke:Сущность|jsonList
+ | {{{damage.types}}}
+ | type = enum
+ | key_replace = <nowiki>\1</nowiki>              <!-- "Blunt" -->
+ | value_replace = <nowiki>'''\1''' \2</nowiki>   <!-- "'''10''' Blunt" -->
+}}
+</pre>
+=== p.json: превращение JSON в вызовы шаблонов ===
+Режим для случаев, когда в JSON лежит список эффектов/объектов, и нужно по каждому вызвать отдельный шаблон.
+<pre>
+{{#invoke:Сущность|json
+ | <json или {{{...}}}>
+ | <путь_к_шаблону>
+}}
+</pre>
+* '''1‑й параметр / <code>json=</code>''' — строка JSON.
+* '''2‑й параметр / <code>template=</code>''' — путь к шаблону, например <code>Component/adjustPlant</code>.
+Ожидаемый формат JSON‑массива:
+<pre> <!-- <syntaxhighlight lang=json> -->
+[
+  {
+    "!type:PlantAdjustNutrition": {
+      "amount": 0.1
+    }
+  },
+  {
+    "!type:PlantAdjustWeeds": {
+      "amount": 2
+    }
+  },
+   {
+    "!type:PlantAdjustPests": {
+      "amount": 2
+    }
+  }
+]
+</pre> <!-- </syntaxhighlight> -->
+Для каждого элемента создаётся вызов:
+<pre>
+{{Component/adjustPlant
+ |id=!type:PlantAdjustNutrition
+ |amount=0.1
+}}
+{{Component/adjustPlant
+ |id=!type:PlantAdjustWeeds
+ |amount=2
+}}
+{{Component/adjustPlant
+ |id=!type:PlantAdjustPests
+ |amount=2
+}}
+</pre>
+Особенности:
+* Если JSON — объект вида <code>{ "id1": {...}, "id2": {...} }</code>, происходит аналогичный проход по парам <code>ключ → объект</code>.
+* Все вызовы склеиваются через перевод строки и прогоняются через <code>frame:preprocess</code>, поэтому внутри шаблона можно использовать любую вики‑разметку.
+== Модуль: GetField ==
+Модуль <code>GetField</code> используется для доступа к тем же JSON‑данным <code>.../data</code>, но на более низком уровне.
+=== p.flattenField: расплющивание записи в параметры ===
+<pre>
+{{#invoke:GetField|flattenField
+ | <id>
+ | <путь_к_json_странице>
+}}
+</pre>
+Например:
+<pre>
+{{#invoke:GetField|flattenField
+ | MyEntityId
+ | component/item.json
+}}
+</pre>
+Возвращает строку вида:
+<pre>
+damage.types={"Blunt":10}|wieldSound=someSound|...
+</pre>
+Особенности:
+* Вложенные объекты кодируются в JSON и заворачиваются в <code><nowiki><nowiki></nowiki></code>, чтобы их можно было безопасно передавать как параметр.
+* Массивы кодируются в JSON без <code><nowiki><nowiki></nowiki></code>, чтобы удобно обрабатывать их модулями вроде <code>Сущность.jsonList</code>.
+Этот режим используется внутри <code>GetField.getTpl</code> и других обёрток.
+=== p.get: получение значения по пути ===
+<pre>
+{{#invoke:GetField|get
+ | <id или пусто для "default">
+ | <путь_к_json_странице>
+ | <ключ.с.точками>
+}}
+</pre>
+Примеры:
+<pre>
+{{#invoke:GetField|get
+ | MyEntityId
+ | component/item.json
+ | damage.types
+}}
+</pre>
+Если в JSON:
+<pre> <!-- <syntaxhighlight lang=json> -->
+"damage": {
+   "types": {
+    "Blunt": 10
+   }
+}
+</pre> <!-- </syntaxhighlight> -->
+то результатом будет:
+<pre>
+{"Blunt":10}
+</pre>
+то есть:
+* для таблиц модуль пытается сделать <code>mw.text.jsonEncode(v)</code> и вернуть JSON‑строку;
+* для простых значений возвращается строка <code>tostring(v)</code>.
+Если <code>keyPath</code> пуст, возвращается весь объект (как JSON).
+=== p.getTpl: вызов шаблона по данным JSON ===
+<pre>
+{{#invoke:GetField|getTpl
+ | <id>
+ | <путь_к_json_странице>
+ | <путь_к_шаблону>
+}}
+</pre>
+Пример:
+<pre>
+{{#invoke:GetField|getTpl
+ | MyEntityId
+ | component/item.json
+ | Component/meleeWeapon
+}}
+</pre>
+Работа:
+* внутри вызывает <code>flattenField</code>, получая строку <code>key=value|...</code>;
+* формирует строку вида:
+<pre>
+{{Component/meleeWeapon
+ |id=MyEntityId
+ |damage.types=...
+ |...
+}}
+</pre>
+* и прогоняет её через <code>frame:preprocess</code>, возвращая итоговый рендер.
+Это удобный способ «подключить» шаблон компонента к данным из JSON без ручного перечисления параметров.
+=== p.getTplProto: вызов шаблона по прототипам ===
+<pre>
+{{#invoke:GetField|getTplProto
+ | <searchId>
+ | <protoId>
+ | <путь_к_шаблону>
+}}
+</pre>
+* Ищет в <code>prototype.json</code> все записи, где <code>protoId</code> встречается у <code>searchId</code>.
+* Для каждого найденного ID вызывает <code>getTpl</code> и возвращает все вызовы, склеенные через перевод строки и отрендеренные.
+Используется для случаев, когда сущность использует '''несколько''' прототипов одного типа, и нужно вывести по одному шаблону на каждый прототип.
+== Типичный рабочий поток ==
+# В JSON‑файлах (<code>component.json</code>, <code>prototype.json</code> и др.) описываются сущности и связи компонент/прототипов.
+# Для каждого компонента/прототипа создаются шаблоны <code>Template:Component/...</code>, <code>Template:prototype/...</code>, которые:
+#* вызывают <code><nowiki>{{#invoke:Сущность/поля|main ...}}</nowiki></code> для описания полей карточки;
+#* при необходимости используют <code>GetField</code> / <code>Сущность.jsonList</code> / <code>Сущность.json</code> для форматирования сложных JSON‑полей.
+# Для вывода карточки на странице сущности используется:
+#* либо прямой <code><nowiki>{{#invoke:Сущность|get|MyEntityId}}</nowiki></code>,
+#* либо шаблон‑обёртка <code><nowiki>{{Сущность/карточка|MyEntityId}}</nowiki></code>.
+# Для специализированных списков/таблиц:
+#* <code>Сущность.jsonList</code> — если нужно красиво показать массив/словарь из JSON;
+#* <code>Сущность.json</code> — если нужно превратить список эффектов в набор вызовов шаблона;
+#* <code>GetField.get</code> — если нужно точечно вытащить одно поле;
+#* <code>GetField.getTpl</code> / <code>getTplProto</code> — если нужно строить шаблоны по данным JSON автоматически.

Песочница/Pok/3: различия между версиями