Песочница/Pok/3

Модульный набор {{#invoke:Сущность}} + {{#invoke:Сущность/поля}} + {{#invoke:GetField}} предназначен для:

• автоматической сборки карточек сущностей (компонентов и прототипов) по их ID;
• описания полей в шаблонах компонентов (какие поля идут в карточку, как подписаны);
• удобного доступа к данным из JSON (как простыми значениями, так и готовыми вызовами шаблонов).

Ниже описан общий принцип работы и отдельные режимы.

Общий принцип работы

• В шаблонах компонентов/прототипов (Template:Component/..., Template:prototype/...) через {{#invoke:Сущность/поля}} описываются поля:
  • лейблы (cardLabel_*) и содержимое (cardContent_*), заголовки (title_*) и т. п.;
  • мета‑информация о том, какие ключи доступны для card / title и в каком порядке.
• {{#invoke:Сущность}} по ID сущности:
  • находит связанные с ней компоненты и прототипы по JSON‑данным;
  • для каждого компонента/прототипа читает шаблоны и метаданные;
  • собирает все поля в единую структуру;
  • формирует один вызов карточки {{карточка/сущность|...}} (и блоки заголовков).
• Внутри полей можно писать вики‑параметры {{{...}}} и вызывать дополнительные модули.
• {{#invoke:GetField}} даёт доступ к JSON‑данным на низком уровне:
  • как «расплющенный» набор параметров (flattenField);
  • как отдельные значения (get);
  • как готовые вызовы шаблонов с нужными параметрами (getTpl, getTplProto).

Модуль:Сущность/поля

Шаблоны компонентов используют модуль Сущность/поля для объявления полей, которые будут собираться в карточку.

Пример шаблона компонента:

{{#invoke:Сущность/поля|main
 |cardLabel_Стоимость   = [[Стоимость]]
 |cardContent_Стоимость = '''{{{price}}}'''
}}

Другой компонент может добавлять тот же ключ:

{{#invoke:Сущность/поля|main
 |cardContent_Стоимость  = '''{{{superPrice}}}'''
}}

Особенности:

• Пара cardLabel_<Ключ> / cardContent_<Ключ> описывает одну строку карточки (лейбл и содержимое).
• Если несколько шаблонов дают один и тот же cardContent_Ключ, содержимое объединяется, а лейбл берётся первый непустой.
• То же относится к другим режимам, перечисленным в мета‑JSON шаблона (разделы card, title и т. п.), которые читает {{#invoke:Сущность}}.

Модуль:Сущность

p.get: основная сборка карточки

Вызов:

{{#invoke:Сущность|get
 | <ID или список ID>
 | blacklist=...
 | whitelist=...
 | ignoreComponents=...
 | ignorePrototypes=...
}}

• 1‑й параметр — id или список id через запятую.
• По этому ID модуль находит:
  • компоненты из component.json;
  • прототипы из prototype.json;

и для каждого — соответствующие шаблоны Template:component/... / Template:prototype/....

• Шаблоны описывают свои поля через Сущность/поля.

После сборки модуль:

• формирует один вызов {{карточка/сущность|...}} со всеми разделами и полями;
• дополняет выход при необходимости (блоки title и т. п.);
• прогоняет результат через frame:preprocess, чтобы отрендерить разметку.

Параметры фильтрации:

• |blacklist = — список режим_Ключ через запятую, чтобы исключить поле:
  • пример: blacklist=card_Наносит повреждения,title_Что‑то;
• |whitelist = — наоборот, список разрешённых режим_Ключ, остальные игнорируются;
• |ignoreComponents = / |ignoreComponent = — список имён компонентов через запятую, которые полностью игнорируются для этого вызова;
• |ignorePrototypes = / |ignorePrototype = — аналогично для прототипов.

Пример простой сборки (через шаблон‑обёртку):

{{Сущность/карточка|MyEntityId}}

где в шаблоне Сущность/карточка внутри:

{{#invoke:Сущность|get|{{{1}}}}}

p.preview: предпросмотр полей конкретного шаблона

Используется для проверки, что компонент/прототип правильно описал свои поля.

{{#invoke:Сущность|preview
 | Component/meleeWeapon
}}

• Показывает, какие card / title‑поля объявлены в Template:Component/meleeWeapon.
• Удобно при разработке шаблонов компонентов.

p.jsonList: вывод JSON в виде списка

Режим похож на стандартный arraymap, но работает с JSON.

{{#invoke:Сущность|jsonList
 | <json или {{{...}}}>
 | type = list / enum
 | prefix = * 
 | sep = : 
 | key_pattern = (.*)
 | key_replace = \1
 | value_pattern = (.*)
 | value_replace = \1
}}

Примеры JSON:

 <!-- <syntaxhighlight lang=json> -->
{
  "Blunt": 10,
  "Slash": 5
}

или

 <!-- <syntaxhighlight lang=json> -->
["Knife", "Sword", "Bat"]

Основные опции:

• |type =:
  • list — список строк (с префиксом, например * );
  • enum — перечисление через запятую (A, B, C без префикса).
• |prefix = — префикс строки списка (по умолчанию * ).
• |sep = — разделитель для ключ: значение (по умолчанию : ).
• |key_pattern = / |key_replace = — regex и замена для ключей.
• |value_pattern = / |value_replace = — regex и замена для значений.

Дополнительно:

• в шаблоне замены поддерживаются:
  • \1 — собственное значение (ключ или значение);
  • \2 в value_replace — **сырой ключ** (после key_pattern, но до key_replace);
  • \2 в key_replace — итоговое отформатированное значение (после value_replace).

Пример, где сначала форматируем тип урона, а затем подставляем его в описание:

{{#invoke:Сущность|jsonList
 | {{{damage.types}}}
 | type = enum
 | key_replace = \1              <!-- "Blunt" -->
 | value_replace = '''\1''' \2   <!-- "'''10''' Blunt" -->
}}

p.json: превращение JSON в вызовы шаблонов

Режим для случаев, когда в JSON лежит список эффектов/объектов, и нужно по каждому вызвать отдельный шаблон.

{{#invoke:Сущность|json
 | <json или {{{...}}}>
 | <путь_к_шаблону>
}}

• **1‑й параметр / json=** — строка JSON.
• **2‑й параметр / template=** — путь к шаблону, например Component/adjustPlant.

Ожидаемый формат JSON‑массива:

 <!-- <syntaxhighlight lang=json> -->
[
  {
    "!type:PlantAdjustNutrition": {
      "amount": 0.1
    }
  },
  {
    "!type:PlantAdjustWeeds": {
      "amount": 2
    }
  },
  {
    "!type:PlantAdjustPests": {
      "amount": 2
    }
  }
]

Для каждого элемента создаётся вызов:

{{Component/adjustPlant
 |id=!type:PlantAdjustNutrition
 |amount=0.1
}}
{{Component/adjustPlant
 |id=!type:PlantAdjustWeeds
 |amount=2
}}
{{Component/adjustPlant
 |id=!type:PlantAdjustPests
 |amount=2
}}

Особенности:

• Если JSON — объект вида { "id1": {...}, "id2": {...} }, происходит аналогичный проход по парам ключ → объект.
• Все вызовы склеиваются через перевод строки и прогоняются через frame:preprocess, поэтому внутри шаблона можно использовать любую вики‑разметку.

Модуль:GetField

Модуль GetField используется для доступа к тем же JSON‑данным .../data, но на более низком уровне.

p.flattenField: расплющивание записи в параметры

{{#invoke:GetField|flattenField
 | <id>
 | <путь_к_json_странице>
}}

Например:

{{#invoke:GetField|flattenField
 | MyEntityId
 | component/item.json
}}

Возвращает строку вида:

damage.types={"Blunt":10}|wieldSound=someSound|...

Особенности:

• Вложенные объекты кодируются в JSON и заворачиваются в <nowiki>, чтобы их можно было безопасно передавать как параметр.
• Массивы кодируются в JSON без <nowiki>, чтобы удобно обрабатывать их модулями вроде Сущность.jsonList.

Этот режим используется внутри GetField.getTpl и других обёрток.

p.get: получение значения по пути

{{#invoke:GetField|get
 | <id или пусто для "default">
 | <путь_к_json_странице>
 | <ключ.с.точками>
}}

Примеры:

{{#invoke:GetField|get
 | MyEntityId
 | component/item.json
 | damage.types
}}

Если в JSON:

 <!-- <syntaxhighlight lang=json> -->
"damage": {
  "types": {
    "Blunt": 10
  }
}

то результатом будет:

{"Blunt":10}

то есть:

• для таблиц модуль пытается сделать mw.text.jsonEncode(v) и вернуть JSON‑строку;
• для простых значений возвращается строка tostring(v).

Если keyPath пуст, возвращается весь объект (как JSON).

p.getTpl: вызов шаблона по данным JSON

{{#invoke:GetField|getTpl
 | <id>
 | <путь_к_json_странице>
 | <путь_к_шаблону>
}}

Пример:

{{#invoke:GetField|getTpl
 | MyEntityId
 | component/item.json
 | Component/meleeWeapon
}}

Работа:

• внутри вызывает flattenField, получая строку key=value|...;
• формирует строку вида:

{{Component/meleeWeapon
 |id=MyEntityId
 |damage.types=...
 |...
}}

• и прогоняет её через frame:preprocess, возвращая итоговый рендер.

Это удобный способ «подключить» шаблон компонента к данным из JSON без ручного перечисления параметров.

p.getTplProto: вызов шаблона по прототипам

{{#invoke:GetField|getTplProto
 | <searchId>
 | <protoId>
 | <путь_к_шаблону>
}}

• Ищет в prototype.json все записи, где protoId встречается у searchId.
• Для каждого найденного ID вызывает getTpl и возвращает все вызовы, склеенные через перевод строки и отрендеренные.

Используется для случаев, когда сущность использует **несколько** прототипов одного типа, и нужно вывести по одному шаблону на каждый прототип.

Типичный рабочий поток

1. В JSON‑файлах (component.json, prototype.json и др.) описываются сущности и связи компонент/прототипов.
2. Для каждого компонента/прототипа создаются шаблоны Template:Component/..., Template:prototype/..., которые:
   • вызывают {{#invoke:Сущность/поля|main ...}} для описания полей карточки;
   • при необходимости используют GetField / Сущность.jsonList / Сущность.json для форматирования сложных JSON‑полей.
3. Для вывода карточки на странице сущности используется:
   • либо прямой {{#invoke:Сущность|get|MyEntityId}},
   • либо шаблон‑обёртка {{Сущность/карточка|MyEntityId}}.
4. Для специализированных списков/таблиц:
   • Сущность.jsonList — если нужно красиво показать массив/словарь из JSON;
   • Сущность.json — если нужно превратить список эффектов в набор вызовов шаблона;
   • GetField.get — если нужно точечно вытащить одно поле;
   • GetField.getTpl / getTplProto — если нужно строить шаблоны по данным JSON автоматически.