|
|
| (не показаны 4 промежуточные версии этого же участника) |
| Строка 1: |
Строка 1: |
| {{docpage}}{{TOC hidden}}
| |
| {{OnLua|Сущность|module1=Сущность|module2=Сущность/поля|module3=GetField}}
| |
|
| |
|
| Модульный набор {{tl|Модуль:Сущность}} + {{tl|Модуль:Сущность/поля}} + {{tl|Модуль:GetField}} предназначен для:
| |
| * автоматической сборки карточек сущностей (компонентов и прототипов) по их ID;
| |
| * описания полей в шаблонах компонентов (какие поля идут в карточку, как подписаны);
| |
| * удобного доступа к данным из 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 автоматически.
| |
