Розбіжності

Тут показані розбіжності між вибраною ревізією та поточною версією сторінки.

--- uk:authors_main:admin_api:admin_api_import_game [2023/04/15 20:41]
admin
+++ uk:authors_main:admin_api:admin_api_import_game [2026/09/18 06:51] (поточний)
@@ Рядок 1: / Рядок 1: @@
 {{indexmenu_n>2}}
-===== Импорт игры из JSON.ua =====
+===== Імпорт гри з JSON =====
-===== Инструменты импорта =====
+===== Інструменти імпорту =====
-Импорт игры или её частей из её JSON можно провести двумя способами:
+Імпорт гри або її частин з її JSON можна зробити кількома способами:
-  - Вставить нужный JSON объект на страницу https://qeng.org/import_tasks.php, указав айди игры, и нажав Импортировать. Эта же ссылка доступна из пункта меню "Импорт заданий" на странице редактирования игры.
+  - У [[uk:authors_main:task_editor:editor|редакторі гри]] натиснути **"Вставити завдання з буфера..."** під списком завдань. Це найзвичайніший шлях: редактор розбере JSON, покаже, що в ньому знайшлося, і додасть обране в чернетку — на сервер воно поїде після кнопки "Зберегти...". Докладніше: [[uk:authors_main:task_editor:task_json|JSON завдання та гри]].
-  - (вариант для программистов) Отправить POST запрос на https://qeng.org/import_tasks.php?gid=<ваш айди игры>&json=1, в котором в body будет корректно сформированный JSON объект. Для аутентификации необходимо удержать cookie с запроса на авторизацию, о чём детально написано тут: [[api_embed_engine|Встраивание движка в другие сервисы]]
+  - Вставити потрібний JSON на сторінку https://qeng.org/import_tasks.php, зазначивши айді гри та натиснувши "Імпортувати". Це саме посилання також доступне з пункту меню "Імпорт завдань" у вкладці "Корисні посилання" редактора.
+  - У картці конкретного завдання натиснути кнопку **"JSON"** у заголовку і вставити туди JSON одного рівня. Це дозволяє швидко оновлювати налаштування, коди, бонуси та підказки конкретного рівня.
+{{ :authors_main:admin_api:import_tasks_uk.png?800 |Сторінка імпорту: номер гри, поле для JSON і посилання на документацію та перевірку}}
-===== Варианты объектов для импорта =====
+  - (варіант для програмістів) Відправити POST запит на https://qeng.org/import_tasks.php?gid=<ваш айді гри>&json=1 із заголовком Content-Type: application/json, в якому у body буде коректно зформований JSON обʼєкт. Для автентифікації необхідно отримати cookie з запиту на авторизацію, про що детально описано тут: [[uk:authors_main:admin_api:api_embed_engine|Вбудовування движка в інші сервіси]]
-Каждый объект, который можно импортировать, можно экспортировать для получения его структуры в текущей игре, как описано в секции [[admin_json_export|инструкций экспорта]].
+===== Варіанти об'єктів для імпорту =====
-==== Заливка новых уровней ====
-Если необходимо добавить НОВЫЕ уровни в игру, то JSON будет списком из одного или нескольких уровней, разделённых запятыми. Чтобы уровень добавился, а не обновился существующий, он должен НЕ иметь поля number внутри секции настроек task. Описание структуры уровня [[admin_api_json#Пример уровня целиком|тут]].
-==== Редактирование существующих уровней ====
+Кожен об'єкт, який можна імпортувати, можна експортувати для отримання його структури в поточній грі, як описано в розділі [[uk:authors_main:admin_api:admin_json_export|інструкцій експорту]].
-Если необходимо обновить СУЩЕСТВУЮЩИЕ уровни в игре, то JSON будет списком из одного или нескольких уровней, разделённых запятыми, причём поле number в секции настроек task должно быть передано (отвечает номер уровня, который редактируется). Описание структуры уровня [[admin_api_json#Пример уровня целиком|тут]].
-Настройки игры из секции task, если присутствуют в JSON - значения в движке будут заменены на новые. Если поля отсутствуют в предоставленном JSON - то они будут оставлены как было.
+==== Заливка нових рівнів ====
+Якщо необхідно додати НОВІ рівні в гру, то JSON буде списком з одного або кількох рівнів, розділених комами. Щоб рівень додався, а не оновився існуючий, він повинен НЕ мати поля number всередині секції налаштувань task. Опис структури рівня [[uk:authors_main:admin_api:admin_api_json#приклад_рівня_цілком|тут]].
-Для остальных секций (codes, bonuses, hints), если секция присутствует в JSON - то она полностью заменит существующую. Если отсутствует - то секция остаётся, как была.
+==== Редагування існуючих рівнів ====
+Якщо необхідно оновити ІСНУЮЧІ рівні в грі, то JSON буде списком з одного або кількох рівнів, розділених комами, причому поле number в секції налаштувань task має бути передано (відповідає номеру рівня, який редагується). Опис структури рівня [[uk:authors_main:admin_api:admin_api_json#приклад_рівня_цілком|тут]].
-==== Заливка всей игры ====
+Налаштування гри з секції task, якщо присутні в JSON - значення в двигуні будуть замінені на нові. Якщо поля відсутні в наданому JSON - то вони будуть залишені як було.
-Есть возможность залить всю игру из JSON целиком. Для этого JSON должен быть полным JSON игры, как описано на странице [[admin_api_json#Пример всей игры целиком|описания структуры JSON]]. Также в JSON необходимо добавить поле ''%%"delete_all_tasks": 1%%'', чтобы удалить все существующие уровни и перезалить игру заново, например:
+Для інших секцій (codes, bonuses, hints), якщо секція присутня в JSON - то вона повністю замінить існуючу. Якщо відсутня - то секція залишається як була.
+Рівень можна знайти не лише за номером: якщо в секції task передати ''id'' рівня (його видає [[uk:authors_main:admin_api:admin_json_export#експорт_з_ідентифікаторами|експорт з ids=1]]), то оновиться саме цей рівень, навіть якщо ви одночасно змінюєте йому номер. Якщо рівня з таким ''id'' у грі немає - імпорт поверне помилку, а не створить новий.
+Щоб змінити окремі коди, бонуси чи підказки, не пересилаючи список цілком, є [[#точкове_редагування|секції *_edit]].
+==== Заливка всієї гри ====
+Є можливість залити всю гру з JSON цілком. Для цього JSON має бути повним JSON гри, як описано на сторінці [[uk:authors_main:admin_api:admin_api_json#приклад_всієї_гри_цілком|опису структури JSON]]. Також в JSON необхідно додати поле ''%%"delete_all_tasks": 1%%'', щоб видалити всі існуючі рівні та перезалити гру заново, наприклад:
 <code JavaScript [enable_line_numbers="false"]>
 {
@@ Рядок 27: / Рядок 36: @@
         "name": "#New Unnamed Game 2",
     },
-    "tasks": [{"task": {"number": 1, "working_name": "Название"}, "codes": [], "bonuses": [], "hints": []}],
+    "tasks": [{"task": {"number": 1, "working_name": "Назва"}, "codes": [], "bonuses": [], "hints": []}],
     "gbonuses": [],
     "lines": [],
@@ Рядок 34: / Рядок 43: @@
 </code>
-Настройки игры из секции game, если присутствуют в JSON - значения в движке будут заменены на новые. Если поля отсутствуют в предоставленном JSON - то они будут оставлены как было в игре раньше.
+Налаштування гри з секції game, если присутні в JSON - значення в двигуні будуть замінені на нові. Якщо поля відсутні в наданому JSON - то вони будуть залишені як було в грі раніше.
+Для інших секцій (gbonuses, lines), якщо секція присутня в JSON - то вона повністю замінить існуючу. Якщо відсутня - то секція залишається як була.
+===== Точкове редагування =====
+Секції ''codes'', ''bonuses'', ''hints'', ''gbonuses'' та ''tasks'' замінюють список цілком - це зручно, коли ви формуєте гру заново, але означає, що заради одного зміненого коду доводиться пересилати весь рівень.
+Поруч із кожною такою секцією є її "редагуючий" варіант: ''codes_edit'', ''bonuses_edit'', ''hints_edit'', ''gbonuses_edit'', ''tasks_edit''. У ньому перелічуються лише ті елементи, які ви змінюєте:
+<code JavaScript [enable_line_numbers="false"]>
+{
+    "tasks_edit": [
+        {
+            "task": {"id": 123, "working_name": "Нова назва"},
+            /* у рівня змінюється лише назва - текст завдання пересилати не треба */
+            "codes_edit": [
+                {"id": 56, "delete": 1},
+                /* цей код видаляється */
+                {"id": 55, "code": "abc"},
+                /* у цього змінюється лише поле code */
+                {"code": "новий код"}
+                /* а цей додається в кінець списку */
+            ]
+        }
+    ]
+}
+</code>
+Правила:
+  * елемент адресується за ''id'' - його можна отримати [[uk:authors_main:admin_api:admin_json_export#експорт_з_ідентифікаторами|експортом з ids=1]];
+  * якщо ''id'' немає, елемент шукається за ''number'' (порядковим номером у списку);
+  * якщо немає ні того, ні іншого - елемент додається в кінець списку;
+  * ''"delete": 1'' видаляє елемент. Видалення застосовуються раніше за інші зміни, тому в одному запиті можна видалити один код і додати інший;
+  * елементи, які ви не згадали, лишаються недоторканими - у цьому вся відмінність від звичайної секції;
+  * передаються лише змінені поля, решта лишається як була;
+  * поле ''number'' у кодів, бонусів і підказок двигун перераховує сам, щоб номери йшли поспіль без пропусків (на них посилаються підказки на кшталт ''%%%codes 2-5%%%'').
+Вказувати для одного списку одразу і ''codes'', і ''codes_edit'' не можна - друга секція правила б елементи, які перша щойно видалила.
+==== Видалення рівня ====
+Рівень видаляється через ''tasks_edit'':
+<code JavaScript [enable_line_numbers="false"]>
+{
+    "tasks_edit": [
+        {"task": {"id": 123}, "delete": 1},
+        {"task": {"id": 124, "number": 1}}
+        /* і, наприклад, зсунути наступний рівень на звільнений номер */
+    ]
+}
+</code>
+Разом із рівнем видаляються його коди, бонуси, підказки та **відповіді команд**. Щоб видалити всі рівні одразу, використовується ''%%"delete_all_tasks": 1%%'' (див. вище).
+=== Розпочата гра ===
+**Будь-який імпорт у вже розпочату гру рушій відхиляє** — відповідає ''GAME_STARTED''. Це захист: імпорт править гру, в яку просто зараз грають.
+Зняти його на один запит можна полем ''%%"allow_active_game": 1%%'' у корені JSON. Тоді імпорт пройде, і **видалити одне завдання теж можна** — рушій скаже попередженням, скільки відповідей команд при цьому піде, по кожному завданню окремо.
+А ось ''%%"delete_all_tasks": 1%%'' у розпочатій грі заборонено й із ним: він забрав би відповіді всіх команд разом. Відповідь — ''DELETE_FORBIDDEN''.
+Номери рівнів двигун не чіпає: на них посилаються лінійки, тому після видалення рівня перенумерацію решти ви задаєте самі, у тому ж запиті.
+==== Помилки ====
+  * ''ROW_ID_NOT_FOUND'' - елемента з таким ''id'' немає в цьому рівні (або в цій грі);
+  * ''TASK_ID_NOT_FOUND'' - рівня з таким ''id'' немає в цій грі;
+  * ''DUPLICATE_ROW_KEY'', ''DUPLICATE_TASK_ID'' - той самий елемент (рівень) згадано в запиті двічі;
+  * ''DELETE_TARGET_NOT_FOUND'' - видаляти нічого: елемент не знайдено або не названо;
+  * ''LIST_AND_EDIT'' - в одному запиті є і ''codes'', і ''codes_edit'';
+  * ''GAME_STARTED'' - імпорт у вже розпочату гру; знімається полем ''%%"allow_active_game": 1%%'';
+  * ''DELETE_FORBIDDEN'' - ''delete_all_tasks'' у вже розпочатій грі: заборонено навіть із ''allow_active_game''.
+==== Заливка налаштувань гри ====
+В JSON потрібно передати тільки структуру налаштувань гри, як описано на [[uk:authors_main:admin_api:admin_api_json#налаштування_гри|сторінці структури JSON]].
-Для остальных секций (gbonuses, lines), если секция присутствует в JSON - то она полностью заменит существующую. Если отсутствует - то секция остаётся, как была.
+==== Заливка сквозних бонусів ====
+В JSON потрібно передати тільки структуру глобальних бонусів, як описано на [[uk:authors_main:admin_api:admin_api_json#наскрізні_бонуси|сторінці структури JSON]].
-==== Заливка настроек игры ====
+==== Заливка лінійок ====
-В JSON нужно передать только структуру настроек игры, как описано на [[admin_api_json#Настройки игры|странице структуры JSON]].
+В JSON потрібно передати тільки структуру глобальних бонусів, як описано на [[uk:authors_main:admin_api:admin_api_json#лінійки|сторінці структури JSON]].
-==== Заливка сквозных бонусов ====
+===== Використання ШІ (чат-ботів) для створення та редагування рівнів =====
-В JSON нужно передать только структуру глобальных бонусов, как описано на [[admin_api_json#Сквозные бонусы|странице структуры JSON]].
-==== Заливка линеек ====
+Сучасні чат-боти (ChatGPT, Claude, Gemini та ін.) чудово справляються з генерацією та редагуванням рівнів, кодів, підказок та бонусів у форматі JSON для двигуна qeng.org.
-В JSON нужно передать только структуру глобальных бонусов, как описано на [[admin_api_json#Линейки|странице структуры JSON]].
+Готовий системний промпт для налаштування чат-бота ви можете знайти в розділі: [[uk:authors_main:task_editor:ai_authoring|Використання ШІ для створення завдань]].