Различия

Здесь показаны различия между двумя версиями данной страницы.

--- authors_main:task_editor:advanced:inventory [2026/06/15 22:31]
admin [Как отобразить инвентарь на уровне]
+++ authors_main:task_editor:advanced:inventory [2026/09/18 06:51] (текущий)
@@ Строка 2: / Строка 2: @@
 ====== Инвентарь игрока ======
-Движок QEng поддерживает систему виртуального инвентаря команд или одиночных игроков. Это позволяет реализовывать квесты с поиском и использованием предметов (ключей, инструментов, валюты).
+Инвентарь — это сумка с предметами, которые игрок находит по ходу игры и применяет к вещам на уровне: ключ к замку, лом к крышке, монету к автомату. Предмет — это строка-ключ (''hammer123''), и вся игра с ним сводится к кодам: применил предмет — движок вбил за игрока код.
-===== Что такое инвентарь? =====
+Версий инвентаря две, и они живут рядом.
-В интерфейсе игрового окна инвентарь отображается как список предметов с изображениями, кратким описанием и кнопкой действия.
-{{ :authors_main:inventory.png?800 |Пример отображения инвентаря на уровне}}
+  * **Вторая** — панель внизу экрана, сумка со счётчиком, предметы применяются к **зонам** на картинке задания. Включается одной строкой в скрипте, места в тексте задания не требует. Про неё вся эта страница.
+  * **Первая** — список предметов в отведённом автором блоке, у предмета две кнопки: «глаз» и «применить». Она [[#первая_версия|работает как работала]] и описана в конце страницы; у идущих игр её не отбирают.
-Каждый предмет представляет собой уникальный текстовый идентификатор (ключ), который можно добавлять, удалять или "активировать" (использовать).
+Уровень выбирает одну из двух: какую функцию позвал скрипт, та и рисует.
-===== Как отобразить инвентарь на уровне =====
+===== Что видит игрок =====
-. В тексте задания (в режиме **"Источник"**) вставьте HTML-блок, где должен отображаться список предметов:
+Внизу экрана — кнопка-сумка. На ней общее число предметов и отдельно «+N» — сколько новых; пока новые есть, сумка подрагивает.
-<code HTML>
-<div id="inventory_container">Загрузка инвентаря...</div>
-</code>
-. В скрипт задания (поле скрипта внизу уровня) добавьте JS-вызов:
+{{ :authors_main:task_editor:advanced:inventory2_bag.png?800 |Свёрнутая сумка: сколько всего предметов и сколько из них новых}}
+По кнопке раскрывается полоса предметов; новые в ней подсвечены жёлтым и перестают быть новыми, как только игрок их тронул — навёл мышь, тапнул, потащил.
+{{ :authors_main:task_editor:advanced:inventory2_panel.png?800 |Раскрытая панель: полоса предметов внизу экрана, новый предмет подсвечен}}
+Применить предмет можно двумя способами, и они равноправны:
+  * **перетащить** предмет на место применения;
+  * **нажать** на предмет, а потом на место применения.
+Как только предмет «в руках», на уровне загораются все места, куда его можно применить, — **зоны**. Рядом с сумкой в тот же момент появляются ещё два приёмника: «применить» (без зоны, просто само по себе) и «глаз» — посмотреть предмет крупно.
+{{ :authors_main:task_editor:advanced:inventory2_zones.png?800 |Предмет в руках: на картинке загорелись зоны, рядом с сумкой — «глаз» и «применить»}}
+Отпустил мимо или нажал пустое место — предмет вернулся в сумку.
+Что вышло из применения, игрок видит на самом предмете: подошло — предмет подпрыгивает зелёным, не подошло — мотает головой красным. Если предмет забрал бонус, он растворяется там, куда его донесли. Пока ответ не пришёл, предмет пульсирует на месте.
+Раскрытая панель и место, до которого игрок долистал полосу, переживают перезагрузку страницы: код вбит, уровень сменился — сумка осталась открытой на том же месте.
+Панель прижата к низу окна, а не стоит в тексте задания, поэтому на телефоне предмет и место применения не обязаны помещаться на экран одновременно.
+{{ :authors_main:task_editor:advanced:inventory2_phone.png?400 |Узкий экран: полоса и приёмники прижаты к низу и не уезжают со скроллом}}
+===== Как включить =====
+В **скрипт задания** (поле внизу уровня):
 <code JavaScript>
-showInventoryItems('inventory_container');
+showInventoryItems2({gameId: 1234});
 </code>
-===== Управление предметами =====
+Больше ничего не нужно: ни блока в тексте задания, ни ''id'' — панель движок рисует сам.
+''gameId'' — игра, в папке которой лежат картинки предметов. Можно не указывать, тогда берётся текущая игра, — но см. [[#картинки_при_копировании_игры|про копирование игры]].
+> **Вызов должен стоять именно в скрипте задания.** Движок подключает вторую версию, увидев ''showInventoryItems2'' в скрипте уровня; из текста задания, из бонуса или из общей шапки игры он её не подключит — функции просто не будет.
+>
+> И **вызов должен быть один**: он забирает накопленный список предметов, и второй за ту же отрисовку нарисует пустую сумку.
+===== Предметы =====
+==== Откуда берутся ====
+Предмет выдаётся из **«Текста после решения»** бонуса — в режиме **«Источник»**:
-==== Добавление предмета в инвентарь ====
-Добавление предметов привязано к решению бонусов (или сквозных бонусов).
-. Создайте бонус на уровне (например, "Найти молоток").
-. В поле **"Текст после решения"** бонуса в режиме **"Источник"** (Source) вставьте скрипт:
 <code HTML>
 <script>
@@ Строка 36: / Строка 67: @@
 </script>
 </code>
-После того как команда введет верный ответ для этого бонуса, предмет с ключом ''hammer123'' появится в их инвентаре.
-==== Изображения предметов ====
+Забирается оттуда же, бонусом более позднего шага:
-Для корректного отображения предмета ''hammer123'' загрузите на cdn игры два файла картинок со строгими названиями:
-  * **''item_hammer123.jpg''** — превью предмета, показываемое в списке инвентаря.
-  * **''item_hammer123_big.jpg''** — детальное изображение, показываемое при клике по значку глаза (детальный просмотр).
-==== Удаление предмета из инвентаря (Использование/Потеря) ====
-Чтобы забрать предмет у команды (например, при отдаче персонажу или использовании для открытия двери):
-. Создайте бонус, активируемый при прохождении.
-. В его **"Текст после решения"** в режиме **"Источник"** пропишите:
 <code HTML>
 <script>
@@ Строка 53: / Строка 76: @@
 </code>
-<note important>
+> Тексты решённых бонусов движок выполняет **заново на каждой перерисовке страницы**. Поэтому список предметов не хранится нигде: он каждый раз собирается с нуля из того, что уже решено. Сервер про предметы не знает ничего.
-**Важно:** Если предмет был добавлен с помощью **сквозного** бонуса, то удалить его обычным бонусом нельзя. Его нужно удалять также через сквозной бонус с более высоким порядковым номером.
-</note>
+Из этого же следует и обратный приём: выдавать предметы не бонусами, а **самим скриптом задания**, посчитав по вбитым кодам, что сейчас должно лежать в сумке. Так сделан уровень-пример с полкой — книгу можно поставить, снять и заменить другой, и отдельных кодов на это не нужно.
+> **Сквозной бонус.** Предмет, выданный сквозным бонусом, обычным бонусом уровня не забрать — только сквозным с бо́льшим порядковым номером.
+**На следующий уровень предмет сам не переезжает.** Бонус уровня на другом уровне не выполняется, значит, и предмета там нет. Вещь, которую носят через всю игру, выдаётся **сквозным** бонусом.
+==== Картинки предметов ====
+Картинка предмета ищется по имени файла: **''item_<ключ>''** — иконка в полосе, **''item_<ключ>_big''** — то, что открывается по «глазу».
+Заливать обе руками не надо. Залейте **одну** картинку с именем ''item_hammer123.png'' в файлы игры: если она от **512 точек по обеим сторонам**, движок сам разложит её на иконку и большую версию. Мельче — останется одним файлом, и «глаз» покажет её же.
+В списке залитых файлов у такой картинки появляется готовая строка ''addInventoryItem('hammer123')'' — по клику она копируется в буфер. Вставлять в бонус нужно именно её: предмет подключается ключом, а не адресом файла.
+Имя такого файла движок сохраняет как есть, даже если галочка «Сохранить название» снята: инвентарь ищет картинку по имени. Ключ берётся из имени вместе с регистром — это ровно та строка, что уходит в ''addInventoryItem()''.
+=== Формат ===
+По умолчанию движок ищет ''.jpg''. Картинки в другом формате — в том числе прозрачные png, ради которых в панели и сделаны слот и тень, — объявляются один раз на игру, в **«Общем HTML-заголовке»**:
+<code HTML>
+<script>
+setInventoryImageExt('png');
+setInventoryBigExt('png');
+</script>
+</code>
+Иконка и крупный вид объявляются отдельно: они могут быть в разных форматах. Поштучное исключение — вторым аргументом:
+<code JavaScript>
+addInventoryItem('map7', {icon: 'png', big: 'png'});
+</code>
+Расширение **не входит в ключ**: ключ — это код, который уходит на сервер.
+=== Картинки при копировании игры ===
+Картинки предметов берутся из папки той игры, чей номер вы передали. Копирование игры файлы не копирует, поэтому в копии картинки пропадут — если ''gameId'' не назван явно или указывает на саму копию.
+Привяжите инвентарь к игре, в которую залиты картинки:
+<code JavaScript>
+showInventoryItems2({gameId: 3493});
+</code>
+Тот же номер можно задать один раз на всю игру, в **«Общем HTML-заголовке»**, — он копируется вместе с игрой:
+<code HTML>
+<script>
+setInventoryGameId(3493);
+</script>
+</code>
+===== Зоны применения =====
+**Зона** — место на уровне, к которому применяют предмет: дверь, замок, торговец, слот полки. У зоны есть код.
+Когда игрок применяет предмет к зоне, движок вбивает **составной код: код зоны + ключ предмета**. Лом (''crowbar'') на зону ''lid'' — это код ''lidcrowbar''. Такой код и должен стоять у бонуса, который открывает крышку.
+{{ :authors_main:task_editor:advanced:inventory2_apply.gif |Лом на рычаг: код — это имя зоны плюс ключ предмета}}
+Зона, под которую кода нет, просто отвечает «не подошло», и предмет возвращается в сумку. Придумывать «пустые» зоны не нужно: зона без подходящего предмета ничем не грозит.
+Применение **без зоны** — «применить» рядом с сумкой — вбивает код, равный ключу предмета (как в первой версии).
+> **Код зоны и ключ склеиваются без разделителя**, поэтому имена стоит разводить самому: зона ''slot'' с предметом ''1book'' и зона ''slot1'' с предметом ''book'' дадут один и тот же код.
+Проверять на стороне игрока, какой предмет к какой зоне подходит, движок не умеет и не будет: тогда правильный ответ лежал бы в исходнике страницы. Любой предмет на любую зону — это просто код, и отвечает на него сервер.
+==== Как задать зону ====
+Четыре способа, и все они про одно и то же — точку и радиус вокруг неё. Различаются тем, откуда берётся точка.
+=== Точка на картинке (инлайновый svg) ===
+Основной способ, когда на картинке несколько мест применения. В тексте задания, в режиме **«Источник»**:
+<code HTML>
+<svg viewBox="0 0 800 600">
+  <image href="https://cdn.qeng.org/f/g/1234/room.jpg" width="800" height="600"/>
+  <circle data-inventory-zone="door" cx="410" cy="255" r="40" fill="none"/>
+  <circle data-inventory-zone="chest" cx="96" cy="470" r="55" fill="none"/>
+</svg>
+</code>
+Координаты живут в системе ''viewBox'', то есть привязаны к картинке, а не к экрану: телефон, десктоп, поворот, зум — точка остаётся на том же месте рисунка. Пересчитывать ничего не надо.
+''r'' — радиус применения **в единицах картинки**. На маленьком экране картинка ужимается, и вместе с ней ужималась бы зона, — движок сам поднимает область попадания до пальца.
+Годятся не только ''circle'': у любой фигуры берётся её габаритный прямоугольник.
+> Картинка, вставленная как ''<img>'', так не размечается: у внешнего svg нет доступного движку содержимого. Для картинки в ''<img>'' — способ с процентами ниже.
+=== Проценты на картинке ===
+Самый дешёвый способ, когда svg разводить не хочется:
+<code HTML>
+<img src="..." data-inventory-zones="door:41,42 chest:12,78,6">
+</code>
+Через двоеточие — код зоны, дальше проценты от размеров самой картинки: x, y и (необязательно) радиус. Зон в одном атрибуте может быть сколько угодно, через пробел.
+Свой значок так задать нельзя — только общий на все зоны носителя. Нужен свой у каждой, берите ''data-inventory-zone'' на отдельных элементах или ''addInventoryZone()''.
+=== Любой элемент страницы ===
+<code HTML>
+<div data-inventory-zone="npc">Торговец</div>
+<img src="..." data-inventory-zone="lock">
+</code>
+Область попадания — прямоугольник элемента целиком. Это ответ для случая «зона — это блок текста, картинка целиком или кнопка».
+=== Из скрипта ===
+Зона, которой на уровне сначала нет, объявляется вызовом — в скрипте задания или в «Тексте после решения» бонуса:
+<code JavaScript>
+addInventoryZone('box', {el: '#room', x: 120, y: 150, r: 45});
+</code>
+Первый аргумент — код зоны. Дальше:
+^ Поле ^ Что значит ^
+| ''el'' | носитель: селектор или элемент. **Обязателен** — он задаёт систему координат |
+| ''x'', ''y'' | позиция внутри носителя; без них — центр элемента, а область попадания — весь его прямоугольник |
+| ''r'' | радиус применения; без него — размер значка, поднятый до пальца |
+| ''icon'' | свой значок зоны; без него общий |
+**Единицы определяет носитель**: инлайновый svg — координаты его ''viewBox'', любой другой элемент — проценты его прямоугольника (радиус — проценты меньшей стороны). Одни и те же ''{x: 150, y: 262}'' на svg и на картинке означают разное. Абсолютных экранных координат нет намеренно: они уехали бы на первом же другом экране.
+Повторный вызов с тем же кодом не заводит вторую зону, а **обновляет существующую**. Значит, зону можно и двигать: пересчитал позицию — позвал ещё раз.
+Убрать — ''removeInventoryZone('door')''. Зону из разметки этот вызов тоже снимет, но только до ближайшего автообновления: html придёт с сервера снова, и зона вернётся. Убирать её надо там же, где убирается всё остальное на уровне, — [[authors_main:task_editor:advanced:edit_templates|шаблоном на сервере]].
+Зона из скрипта **перекрывает** зону из разметки с тем же кодом.
+==== Свой значок зоны ====
+По умолчанию у всех зон один общий полупрозрачный значок. Свой задаётся в разметке атрибутом ''data-inventory-zone-icon'' или полем ''icon'' у ''addInventoryZone()'', и вид его объявлять не надо — движок различает сам:
+<code HTML>
+<circle data-inventory-zone="door" data-inventory-zone-icon="fa-lock" .../>
+<circle data-inventory-zone="gate" data-inventory-zone-icon="/f/g/123/door.png" .../>
+<circle data-inventory-zone="safe" data-inventory-zone-icon="🔑" .../>
+</code>
+  * ''fa-lock'' — значок font-awesome;
+  * путь или адрес — своя картинка;
+  * что угодно ещё — просто символ.
+==== Зоны, которых ещё нет ====
+Набор зон обычно зависит от того, что игрок уже сделал: у вскрытого ящика зон нет, щель автомата появляется вместе с монетой. Разметку под это удобно собирать [[authors_main:task_editor:advanced:edit_templates|шаблонами]] ''{% match bonus_N %}'' — они считаются на сервере, поэтому в исходнике страницы у игрока лежат только те слои и зоны, что видны сейчас.
+В скрипте задания шаблоны работают так же, но строки шаблона комментируются двойным слэшем — движок снимает комментарий сам:
+<code JavaScript>
+// {% match bonus_2}:{
+//   {%= leverdncrowbar}:{
+addInventoryZone('leverup', {el: '#quest_room', x: 288, y: 305, r: 45});
+//   %}
+//   {%= ?}:{
+addInventoryZone('leverdn', {el: '#quest_room', x: 315, y: 112, r: 45});
+//   %}
+// %}
+</code>
+===== Что стоит знать =====
+  * **Ключ предмета — это код.** Точки, кавычки и расширения в него класть нельзя.
+  * **Применение всегда молчаливое:** в форме ответов ничего не появляется. Вся обратная связь — на самом предмете и на зоне.
+  * **Вердикт движок читает из блока «Предыдущие ответы».** Если мониторинг на уровне выключен, предмет просто молча вернётся в сумку — без зелёного и красного.
+  * **Один и тот же неверный код второй раз не уходит на сервер.** Предмет вернётся сразу, с тем же вердиктом, что и в прошлый раз, — попытка не тратится.
+  * **Спрятанный носитель зоны не даёт.** Зона на элементе внутри свёрнутого ''<details>'', на ''display: none'' или на ещё не загрузившейся картинке не появится — до тех пор, пока носитель не покажется. Пересчёт движок делает сам: при изменении размеров окна, загрузке картинки и в момент, когда игрок берёт предмет.
+  * **Пока предмет в руках, значок зоны лежит поверх страницы** и перехватывает клик по тому, что под ним, — в том числе по вашей кнопке.
+  * **Синонимы бонуса — это состояние.** Значение бонуса в шаблоне — его **последний** вбитый ответ, а каждый новый синоним заменяет предыдущий. Поэтому рычаг ходит туда-сюда, а книга ставится и снимается: два синонима у одного бонуса вместо двух бонусов.
+  * **Описание бонуса ''%hide%''** не видно в исходнике страницы до решения — цепочку применений не подсмотреть.
+  * Скрытый движком бонус печатается **без** вбитого ответа. Если ответ нужен скрипту, прячьте блок бонусов стилем, а не пометкой.
+  * Панель живёт снаружи автообновляемой части страницы: чужой код или новая подсказка её не закроют и выбранный предмет не отберут.
+  * Раскрытая панель отодвигает низ страницы. Свой прижатый к низу блок с ней поспорит.
+Чего у инвентаря нет: **количества** (предмет либо есть, либо нет — «три монеты» делаются тремя предметами или кодами), сортировки и перетаскивания предмета на предмет.
+===== Примеры в игре =====
+  * [[https://qeng.org/game.php?jump_to&gid=3493&task_id=83700|Инвентарь: комната]] — предметы находят и применяют к точкам на картинке: лом, рычаг, замок, крышка, монета в автомат. Зоны из скрипта, слои сцены — шаблонами.
+  * [[https://qeng.org/game.php?jump_to&gid=3493&task_id=83701|Инвентарь: полка]] — предметы не выдаются бонусами вовсе: что лежит в сумке и что стоит на полке, скрипт каждый раз считает по вбитым кодам.
+У обоих уровней внутри есть раздел «Как так сделать?» с разбором.
+===== Первая версия =====
+Работает как работала. Отличается тем, что инвентарь рисуется в отведённом автором блоке, зон нет, а у выбранного предмета две кнопки — «глаз» и «применить».
+{{ :authors_main:inventory.png?800 |Инвентарь первой версии: предметы приходят за решённые бонусы}}
+{{ :authors_main:inventory_item.png?800 |Выбранный предмет: «глаз» показывает картинку крупно, галочка — использует предмет}}
+  - В текст задания (в режиме **«Источник»**) — блок, где показывать список:
+<code HTML>
+<div id="inventory_container">Загрузка инвентаря...</div>
+</code>
+  - В скрипт задания — вызов:
+<code JavaScript>
+showInventoryItems('inventory_container');
+</code>
+Вторым параметром — та же привязка картинок к чужой игре: ''showInventoryItems('inventory_container', 1234)''.
+Предметы выдаются и забираются так же, ''addInventoryItem()'' и ''removeInventoryItem()'' в «Тексте после решения» бонуса. Кнопка «применить» вбивает код, равный ключу предмета.
+{{ :authors_main:inventory_use.gif |Предмет приходит за бонус, а «использовать» вбивает его код за игрока}}
+Пример в игре: [[https://qeng.org/game.php?jump_to&gid=3493&task_id=68367|Инвентарь]].
-==== Кнопка "Использовать" ====
+===== Смотрите также =====
-При клике игроком по кнопке **"Использовать"** у предмета в инвентаре, движок автоматически пытается вбить код, совпадающий с идентификатором предмета.
-* Например, при использовании предмета ''hammer123'' в поле ввода ответов автоматически отправится код ''hammer123''.
-===== Демонстрация =====
+  * [[authors_main:task_editor:advanced:edit_templates|Шаблоны]] — ''{% match bonus_N %}'' для сцены и зон, зависящих от состояния уровня.
-Рабочий пример уровня с инвентарем и кодом можно посмотреть в [[https://qeng.org/game.php?gid=3493&tid=68367|Демо-игре для авторов]].
+  * [[authors_main:task_editor:advanced:composite_codes|Составные коды]] — итоговый код уровня, собранный из частей.
+  * [[authors_main:task_editor:advanced:author_scripts|Интерактивные элементы (скрипты)]] — остальные функции, доступные в скрипте задания.