From aebf25b99d39c2a4854ddca346dd4d6a3fe9d37e Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 20:38:21 +0500
Subject: [PATCH 1/7] docs(lang/kwrds/stmts/RU,ENG):add MODOBJ chapter

---
 docs/language/qsp-keywords/index.md           |  2 +
 .../qsp-keywords/qsp-keywords-statements.md   | 96 +++++++++++++++++++
 .../current/language/qsp-keywords/index.md    |  2 +
 .../qsp-keywords/qsp-keywords-statements.md   | 96 +++++++++++++++++++
 4 files changed, 196 insertions(+)

diff --git a/docs/language/qsp-keywords/index.md b/docs/language/qsp-keywords/index.md
index d69a572..1d9b7e5 100644
--- a/docs/language/qsp-keywords/index.md
+++ b/docs/language/qsp-keywords/index.md
@@ -121,6 +121,7 @@ sidebar_position: 6
 - [`$MID`](qsp-keywords-functions.md#mid)
 - [`MIN`](qsp-keywords-functions.md#min)
 - [`MOD`](qsp-keywords-operators.md#mod)
+- [`MODOBJ`](qsp-keywords-statements.md#modobj) - 5.9.4
 - [`MSECSCOUNT`](qsp-keywords-functions.md#msecscount)
 - [`MSG`](qsp-keywords-statements.md#msg)
 - [`NL`](qsp-keywords-statements.md#nl-1)
@@ -147,6 +148,7 @@ sidebar_position: 6
 - [`RAND`](qsp-keywords-functions.md#rand)
 - [`REFINT`](qsp-keywords-statements.md#refint)
 - [`$REPLACE`](qsp-keywords-functions.md#replace)
+- [`RESETOBJ`](qsp-keywords-statements.md#resetobj) - 5.9.4
 - [`RESULT`](qsp-keywords-sys-var.md#result)
 - [`RGB`](qsp-keywords-functions.md#rgb)
 - [`RND`](qsp-keywords-functions.md#rnd)
diff --git a/docs/language/qsp-keywords/qsp-keywords-statements.md b/docs/language/qsp-keywords/qsp-keywords-statements.md
index 4d4595d..6650ee3 100644
--- a/docs/language/qsp-keywords/qsp-keywords-statements.md
+++ b/docs/language/qsp-keywords/qsp-keywords-statements.md
@@ -1456,6 +1456,102 @@ $usr_menu[3] = 'Положить предмет:put_item'
 
 :::
 
+## MODOBJ
+
+`MODOBJ` - замена описания (текста) предмета с указанным названием и его изображения на необходимые. Общая запись:
+
+```qsp
+MODOBJ [$название], [$описание], [$изображение]
+```
+
+, где:
+
+- `[$название]` — это название, которое вы указывали при добавлении предмета в окно предметов (инвентарь) с помощью оператора `ADDOBJ`;
+- `[$описание]` — это текст, который вы хотите увидеть в окне предметов вместо названия;
+- `[$изображение]` — путь к изображению, которое вы хотите увидеть в окне предметов вместо добавленного (или не добавленного) с помощью оператора `ADDOBJ`.
+
+Данная операция позволяет заменить **отображаемое** на экране наименование предмета и его иконку в окне предметов. При этом само название предмета не меняется, то есть `$selobj` продолжает возвращать название предмета, которое было использовано при создании предмета командой `ADDOBJ`. Пример:
+
+```qsp
+addobj "Апельсин" & ! создаём предмет "Апельсин"
+modobj "Апельсин", "Апельсин (1 шт.)" & ! заменяем отображаемое наименование
+! на экране видим "Апельсин (1 шт.)", но когда кликаем по этому предмету:
+*pl $selobj & ! $selobj возвращает "Апельсин"
+```
+
+:::warning [**Обратите внимание!!!**]
+Если вы добавили в окно предметов несколько предметов с одинаковыми названиями, то при использовании `modobj` **отображаемое наименование** поменяется у всех предметов.
+:::
+
+Практический смысл данного оператора становится понятен, если рассмотреть одну из самых распространённых в QSP задач: отображение статуса предмета в инвентаре.
+
+Это может быть "Фонарик" (Фонарик включен/Фонарик выключен), "Фляга для воды" (Фляга полная/Фляга пустая), "Батарейка" (Батарейка заряжена/Батарейка разряжена) и т.п.
+
+До появления оператора `MODOBJ`, чтобы изменить статус предмета, приходилось удалять предмет со старым названием, а затем добавлять в ту же позицию предмет с новым названием:
+
+```qsp
+act "Выключить фонарик":
+  delobj "Фонарик включен"
+  addobj "Фонарик выключен"
+end
+```
+
+Всё довольно просто, но проблема в том, что "Включённый фонарик" мог быть во второй позиции (второй строке списка в окне предметов), а при таком "выключении", "Выключенный фонарик" добавится в последнюю позицию. Т.е. визуально это не выглядит как смена статуса.
+
+Очевидным решением будет "запоминать" позицию предмета, а так же его состояние:
+
+```qsp
+act "Выключить фонарик":
+  if фонарик_включён:
+    delobj "Фонарик включён"
+    if фонарик = 0: фонарик = countobj + 1
+    addobj "Фонарик выключен", "", фонарик
+    фонарик_включён = 0
+  else:
+    *pl "Фонарик уже выключен"
+  end
+end
+act "Включить фонарик":
+  if no фонарик_включён:
+    delobj "Фонарик выключен"
+    if фонарик = 0: фонарик = countobj + 1
+    addobj "Фонарик включён", "", фонарик
+    фонарик_включён = 1
+  else:
+    *pl "Фонарик уже включён"
+  end
+end
+```
+
+Оператор `MODOBJ` позволяет не хранить позицию предметов и не производить поиск предмета с указанным названием в списке. Особенно, если все предметы в игре уникальны.
+
+```qsp
+if no obj('Фонарик'):
+  ! добавляем выключенный фонарик
+  addobj 'Фонарик'
+  modobj 'Фонарик', 'Фонарик выключен'
+  фонарик_включен = 0
+end
+act "Выключить фонарик":
+  if фонарик_включён:
+    modobj 'Фонарик', 'Фонарик выключен'
+    фонарик_включён = 0
+  else:
+    *pl "Фонарик уже выключен"
+  end
+end
+act "Включить фонарик":
+  if no фонарик_включён:
+    modobj 'Фонарик', 'Фонарик включен'
+    фонарик_включён = 1
+  else:
+    *pl "Фонарик уже включён"
+  end
+end
+```
+
+Это не только позволяет сэкономить строки кода, но и число используемых в игре переменных.
+
 ## MSG
 
 `MSG` — вывод указанного сообщения в диалоговом окне. Общая запись:
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
index 4524695..f542684 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
@@ -121,6 +121,7 @@ Crossed out commands do not work in players version 5.8.0 and above.
 - [`$MID`](qsp-keywords-functions.md#mid)
 - [`MIN`](qsp-keywords-functions.md#min)
 - [`MOD`](qsp-keywords-operators.md#mod)
+- [`MODOBJ`](qsp-keywords-statements.md#modobj) - 5.9.4
 - [`MSECSCOUNT`](qsp-keywords-functions.md#msecscount)
 - [`MSG`](qsp-keywords-statements.md#msg)
 - [`NL`](qsp-keywords-statements.md#nl-1)
@@ -147,6 +148,7 @@ Crossed out commands do not work in players version 5.8.0 and above.
 - [`RAND`](qsp-keywords-functions.md#rand)
 - [`REFINT`](qsp-keywords-statements.md#refint)
 - [`$REPLACE`](qsp-keywords-functions.md#replace)
+- [`RESETOBJ`](qsp-keywords-statements.md#resetobj) - 5.9.4
 - [`RESULT`](qsp-keywords-sys-var.md#result)
 - [`RGB`](qsp-keywords-functions.md#rgb)
 - [`RND`](qsp-keywords-functions.md#rnd)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
index eac181b..f23c34d 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
@@ -1455,6 +1455,102 @@ $usr_menu[3] = 'Put item:put_item'
 
 :::
 
+## MODOBJ
+
+`MODOBJ` - замена описания (текста) предмета с указанным названием и его изображения на необходимые. Общая запись:
+
+```qsp
+MODOBJ [$название], [$описание], [$изображение]
+```
+
+, где:
+
+- `[$название]` — это название, которое вы указывали при добавлении предмета в окно предметов (инвентарь) с помощью оператора `ADDOBJ`;
+- `[$описание]` — это текст, который вы хотите увидеть в окне предметов вместо названия;
+- `[$изображение]` — путь к изображению, которое вы хотите увидеть в окне предметов вместо добавленного (или не добавленного) с помощью оператора `ADDOBJ`.
+
+Данная операция позволяет заменить **отображаемое** на экране наименование предмета и его иконку в окне предметов. При этом само название предмета не меняется, то есть `$selobj` продолжает возвращать название предмета, которое было использовано при создании предмета командой `ADDOBJ`. Пример:
+
+```qsp
+addobj "Апельсин" & ! создаём предмет "Апельсин"
+modobj "Апельсин", "Апельсин (1 шт.)" & ! заменяем отображаемое наименование
+! на экране видим "Апельсин (1 шт.)", но когда кликаем по этому предмету:
+*pl $selobj & ! $selobj возвращает "Апельсин"
+```
+
+:::warning [**Обратите внимание!!!**]
+Если вы добавили в окно предметов несколько предметов с одинаковыми названиями, то при использовании `modobj` **отображаемое наименование** поменяется у всех предметов.
+:::
+
+Практический смысл данного оператора становится понятен, если рассмотреть одну из самых распространённых в QSP задач: отображение статуса предмета в инвентаре.
+
+Это может быть "Фонарик" (Фонарик включен/Фонарик выключен), "Фляга для воды" (Фляга полная/Фляга пустая), "Батарейка" (Батарейка заряжена/Батарейка разряжена) и т.п.
+
+До появления оператора `MODOBJ`, чтобы изменить статус предмета, приходилось удалять предмет со старым названием, а затем добавлять в ту же позицию предмет с новым названием:
+
+```qsp
+act "Выключить фонарик":
+  delobj "Фонарик включен"
+  addobj "Фонарик выключен"
+end
+```
+
+Всё довольно просто, но проблема в том, что "Включённый фонарик" мог быть во второй позиции (второй строке списка в окне предметов), а при таком "выключении", "Выключенный фонарик" добавится в последнюю позицию. Т.е. визуально это не выглядит как смена статуса.
+
+Очевидным решением будет "запоминать" позицию предмета, а так же его состояние:
+
+```qsp
+act "Выключить фонарик":
+  if фонарик_включён:
+    delobj "Фонарик включён"
+    if фонарик = 0: фонарик = countobj + 1
+    addobj "Фонарик выключен", "", фонарик
+    фонарик_включён = 0
+  else:
+    *pl "Фонарик уже выключен"
+  end
+end
+act "Включить фонарик":
+  if no фонарик_включён:
+    delobj "Фонарик выключен"
+    if фонарик = 0: фонарик = countobj + 1
+    addobj "Фонарик включён", "", фонарик
+    фонарик_включён = 1
+  else:
+    *pl "Фонарик уже включён"
+  end
+end
+```
+
+Оператор `MODOBJ` позволяет не хранить позицию предметов и не производить поиск предмета с указанным названием в списке. Особенно, если все предметы в игре уникальны.
+
+```qsp
+if no obj('Фонарик'):
+  ! добавляем выключенный фонарик
+  addobj 'Фонарик'
+  modobj 'Фонарик', 'Фонарик выключен'
+  фонарик_включен = 0
+end
+act "Выключить фонарик":
+  if фонарик_включён:
+    modobj 'Фонарик', 'Фонарик выключен'
+    фонарик_включён = 0
+  else:
+    *pl "Фонарик уже выключен"
+  end
+end
+act "Включить фонарик":
+  if no фонарик_включён:
+    modobj 'Фонарик', 'Фонарик включен'
+    фонарик_включён = 1
+  else:
+    *pl "Фонарик уже включён"
+  end
+end
+```
+
+Это не только позволяет сэкономить строки кода, но и число используемых в игре переменных.
+
 ## MSG
 
 `MSG` — displays the specified message in a dialog box. General syntax:

From 59394151e28dc156b803028cb11485de82ff36e2 Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 21:34:46 +0500
Subject: [PATCH 2/7] docs(lang/kwrds/stmts/RU, ENG): add RESETOBJ chapter

---
 .gitignore                                    |   2 +
 .../qsp-keywords/qsp-keywords-statements.md   |  10 ++
 .../qsp-keywords/qsp-keywords-statements.md   | 124 ++++++++++--------
 .../qsp-keywords/qsp-keywords-syntaxems.md    |   2 +-
 4 files changed, 85 insertions(+), 53 deletions(-)

diff --git a/.gitignore b/.gitignore
index b2d6de3..4c28edc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,3 +18,5 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+.obsidian
diff --git a/docs/language/qsp-keywords/qsp-keywords-statements.md b/docs/language/qsp-keywords/qsp-keywords-statements.md
index 6650ee3..af73ce6 100644
--- a/docs/language/qsp-keywords/qsp-keywords-statements.md
+++ b/docs/language/qsp-keywords/qsp-keywords-statements.md
@@ -1716,6 +1716,16 @@ play $file, volume
 
 По умолчанию обновление интерфейса происходит 2 раза в секунду (каждые 500 мс). Так же см. оператор [`settimer`](#settimer).
 
+## RESETOBJ
+
+- `RESETOBJ` — сбрасывает отображаемое наименование и иконку предметов с указанным названием до состояния на момент добавления с помощью `ADDOBJ`. Общая запись:
+
+```qsp
+RESETOBJ [$название]
+```
+
+, где `[$название]` — это название предмета, которое было использовано при добавлении предмета в окно предметов с помощью `ADDOBJ`.
+
 ## SAVEGAME
 
 `SAVEGAME` — сохранение состояния игры в указанный файл. Общая запись:
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
index f23c34d..4df640b 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-statements.md
@@ -1457,99 +1457,105 @@ $usr_menu[3] = 'Put item:put_item'
 
 ## MODOBJ
 
-`MODOBJ` - замена описания (текста) предмета с указанным названием и его изображения на необходимые. Общая запись:
+:::warning [Attention!]
+This chapter is translated by AI.
+:::
+
+`MODOBJ` — replaces the description (text) of an item with the specified name and its image with the ones you need. General syntax:
 
 ```qsp
-MODOBJ [$название], [$описание], [$изображение]
+MODOBJ [$name], [$description], [$image]
 ```
 
-, где:
+, where:
 
-- `[$название]` — это название, которое вы указывали при добавлении предмета в окно предметов (инвентарь) с помощью оператора `ADDOBJ`;
-- `[$описание]` — это текст, который вы хотите увидеть в окне предметов вместо названия;
-- `[$изображение]` — путь к изображению, которое вы хотите увидеть в окне предметов вместо добавленного (или не добавленного) с помощью оператора `ADDOBJ`.
+- `[$name]` is the name you specified when adding the item to the items window (inventory) using the `ADDOBJ` statement;
+- `[$description]` is the text you want to see in the items window instead of the name;
+- `[$image]` is the path to the image you want to see in the items window instead of the one added (or not added) with the `ADDOBJ` statement.
 
-Данная операция позволяет заменить **отображаемое** на экране наименование предмета и его иконку в окне предметов. При этом само название предмета не меняется, то есть `$selobj` продолжает возвращать название предмета, которое было использовано при создании предмета командой `ADDOBJ`. Пример:
+This statement allows you to change the displayed item name on the screen and its icon in the items window. At the same time, the actual item name does not change, so $selobj continues to return the name that was used when creating the item with the ADDOBJ command. Example:
 
 ```qsp
-addobj "Апельсин" & ! создаём предмет "Апельсин"
-modobj "Апельсин", "Апельсин (1 шт.)" & ! заменяем отображаемое наименование
-! на экране видим "Апельсин (1 шт.)", но когда кликаем по этому предмету:
-*pl $selobj & ! $selobj возвращает "Апельсин"
+addobj "Orange" & ! create the "Orange" item
+modobj "Orange", "Orange (1 pc.)" & ! change the displayed name
+! on the screen we see "Orange (1 pc.)", but when we click this item:
+*pl $selobj & ! $selobj returns "Orange"
 ```
 
-:::warning [**Обратите внимание!!!**]
-Если вы добавили в окно предметов несколько предметов с одинаковыми названиями, то при использовании `modobj` **отображаемое наименование** поменяется у всех предметов.
+:::warning [Pay attention!!!]
+
+If you have added several items with the same name to the items window, then when using modobj the displayed name will change for all of them.
+
 :::
 
-Практический смысл данного оператора становится понятен, если рассмотреть одну из самых распространённых в QSP задач: отображение статуса предмета в инвентаре.
+The practical use of this statement becomes clear if we look at one of the most common tasks in QSP: displaying an item status in the inventory.
 
-Это может быть "Фонарик" (Фонарик включен/Фонарик выключен), "Фляга для воды" (Фляга полная/Фляга пустая), "Батарейка" (Батарейка заряжена/Батарейка разряжена) и т.п.
+It can be a "Flashlight" (Flashlight on/Flashlight off), a "Water flask" (Flask full/Flask empty), a "Battery" (Battery charged/Battery discharged), and so on.
 
-До появления оператора `MODOBJ`, чтобы изменить статус предмета, приходилось удалять предмет со старым названием, а затем добавлять в ту же позицию предмет с новым названием:
+Before `MODOBJ` appeared, to change the item status you had to delete the item with the old name and then add an item with the new name in the same position:
 
 ```qsp
-act "Выключить фонарик":
-  delobj "Фонарик включен"
-  addobj "Фонарик выключен"
+act "Turn off the flashlight":
+  delobj "Flashlight on"
+  addobj "Flashlight off"
 end
 ```
 
-Всё довольно просто, но проблема в том, что "Включённый фонарик" мог быть во второй позиции (второй строке списка в окне предметов), а при таком "выключении", "Выключенный фонарик" добавится в последнюю позицию. Т.е. визуально это не выглядит как смена статуса.
+This is quite simple, but the problem is that "Flashlight on" could be in the second position (second line of the list in the items window), and with such a "switching off", "Flashlight off" will be added to the last position. Visually it does not look like a status change.
 
-Очевидным решением будет "запоминать" позицию предмета, а так же его состояние:
+An obvious solution is to "remember" the item position as well as its state:
 
 ```qsp
-act "Выключить фонарик":
-  if фонарик_включён:
-    delobj "Фонарик включён"
-    if фонарик = 0: фонарик = countobj + 1
-    addobj "Фонарик выключен", "", фонарик
-    фонарик_включён = 0
+act "Turn off the flashlight":
+  if flashlight_on:
+    delobj "Flashlight on"
+    if flashlight = 0: flashlight = countobj + 1
+    addobj "Flashlight off", "", flashlight
+    flashlight_on = 0
   else:
-    *pl "Фонарик уже выключен"
+    *pl "The flashlight is already off"
   end
 end
-act "Включить фонарик":
-  if no фонарик_включён:
-    delobj "Фонарик выключен"
-    if фонарик = 0: фонарик = countobj + 1
-    addobj "Фонарик включён", "", фонарик
-    фонарик_включён = 1
+act "Turn on the flashlight":
+  if no flashlight_on:
+    delobj "Flashlight off"
+    if flashlight = 0: flashlight = countobj + 1
+    addobj "Flashlight on", "", flashlight
+    flashlight_on = 1
   else:
-    *pl "Фонарик уже включён"
+    *pl "The flashlight is already on"
   end
 end
 ```
 
-Оператор `MODOBJ` позволяет не хранить позицию предметов и не производить поиск предмета с указанным названием в списке. Особенно, если все предметы в игре уникальны.
+The `MODOBJ` statement allows you not to store item positions and not to search for an item with the specified name in the list, especially if all items in the game are unique.
 
 ```qsp
-if no obj('Фонарик'):
-  ! добавляем выключенный фонарик
-  addobj 'Фонарик'
-  modobj 'Фонарик', 'Фонарик выключен'
-  фонарик_включен = 0
+if no obj('Flashlight'):
+  ! add a switched-off flashlight
+  addobj 'Flashlight'
+  modobj 'Flashlight', 'Flashlight off'
+  flashlight_on = 0
 end
-act "Выключить фонарик":
-  if фонарик_включён:
-    modobj 'Фонарик', 'Фонарик выключен'
-    фонарик_включён = 0
+act "Turn off the flashlight":
+  if flashlight_on:
+    modobj 'Flashlight', 'Flashlight off'
+    flashlight_on = 0
   else:
-    *pl "Фонарик уже выключен"
+    *pl "The flashlight is already off"
   end
 end
-act "Включить фонарик":
-  if no фонарик_включён:
-    modobj 'Фонарик', 'Фонарик включен'
-    фонарик_включён = 1
+act "Turn on the flashlight":
+  if no flashlight_on:
+    modobj 'Flashlight', 'Flashlight on'
+    flashlight_on = 1
   else:
-    *pl "Фонарик уже включён"
+    *pl "The flashlight is already on"
   end
 end
 ```
 
-Это не только позволяет сэкономить строки кода, но и число используемых в игре переменных.
+This not only saves lines of code but also reduces the number of variables used in the game.
 
 ## MSG
 
@@ -1715,6 +1721,20 @@ If the file is already playing, the volume changes without "restarting" it. Mult
 
 By default, interface update occurs 2 times per second (every 500 ms). See also the [`settimer`](#settimer) statement.
 
+## RESETOBJ
+
+:::warning [Attention!]
+This chapter is translated by AI.
+:::
+
+- `RESETOBJ` — resets the displayed name and icon of items with the specified name to the state at the time of addition using `ADDOBJ`. General syntax:
+
+```qsp
+RESETOBJ [$name]
+```
+
+, where `[$name]` is the item name that was used when adding the item to the items window using `ADDOBJ`.
+
 ## SAVEGAME
 
 `SAVEGAME` — saving game state to the specified file. General syntax:
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
index 54d1858..ef49f6d 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
@@ -455,7 +455,7 @@ end
 Implicit location-function calling replaces both `gosub` and `func`, therefore:
 
 1. if your location-function returns a result, implicit calling of such a location will work exactly the same as explicit calling through `func`;
-2. if the location-function doesn't return a result, then when using it with the **[implicit operator](qsp-keywords-statements.md#implicit-operator)** it will work like explicit calling through `gosub`.
+2. if the location-function doesn't return a result, then when using it with the **[implicit statement](qsp-keywords-statements.md#implicit-statement)** it will work like explicit calling through `gosub`.
 
 :::
 

From 6c50311455fdf40672c395c905f3513209c78d9d Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 22:57:10 +0500
Subject: [PATCH 3/7] docs(lang/kwrds/sntxm/RU, ENG): extract @@ syntax sugar

---
 docs/language/qsp-keywords/index.md           |  2 +-
 .../qsp-keywords/qsp-keywords-statements.md   | 10 ++--
 .../qsp-keywords/qsp-keywords-syntaxems.md    | 31 +++++++---
 .../current/language/qsp-keywords/index.md    |  2 +-
 .../qsp-keywords/qsp-keywords-syntaxems.md    | 59 ++++++++++++-------
 5 files changed, 69 insertions(+), 35 deletions(-)

diff --git a/docs/language/qsp-keywords/index.md b/docs/language/qsp-keywords/index.md
index 1d9b7e5..6eaf3e7 100644
--- a/docs/language/qsp-keywords/index.md
+++ b/docs/language/qsp-keywords/index.md
@@ -5,7 +5,7 @@ sidebar_position: 6
 
 # Указатель
 
-:::warning[Внимание!]
+:::warning [Внимание!]
 Вычеркнутые команды не работают в плеерах версии 5.8.0 и выше.
 :::
 
diff --git a/docs/language/qsp-keywords/qsp-keywords-statements.md b/docs/language/qsp-keywords/qsp-keywords-statements.md
index af73ce6..5a9cda7 100644
--- a/docs/language/qsp-keywords/qsp-keywords-statements.md
+++ b/docs/language/qsp-keywords/qsp-keywords-statements.md
@@ -26,12 +26,12 @@ $curloc
 $func('foo')
 $func('foo')
 $curloc
-- start
+-- start
 
 # foo
 ! это код локации-функции
 local i = 0
-- foo
+-- foo
 ```
 
 В данном случае локация-функция `foo` ничего не возвращает, поэтому на экране мы увидим две строки со словом "start", между которыми не будет пустых строк, так как неявный оператор в строках с `$func` на локации `start` будет просто проигнорирован. Сравните с:
@@ -43,12 +43,12 @@ local i = 0
 *pl $func('foo')
 *pl $func('foo')
 *pl $curloc
-- start
+-- start
 
 # foo
 ! это код локации-функции
 local i=0
-- foo
+-- foo
 ```
 
 ## `!` (комментарий)
@@ -529,7 +529,7 @@ gosub 'переход', 'локация'
 act 'перейти':
     goto "улица"
 end
-- переход
+-- переход
 ```
 
 Оператор имеет краткую форму `gs`:
diff --git a/docs/language/qsp-keywords/qsp-keywords-syntaxems.md b/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
index 2fd7a82..b981dbf 100644
--- a/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
+++ b/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
@@ -400,15 +400,28 @@ health = 150
 
 ## Символ "Коммерческое эт" `@`
 
-Символ "Коммерческое эт" `@` используется для организации неявного вызова локаций-функций, упрощая запись и заменяя собой оператор `gosub` или функию `func`. Общая запись:
+Символ "Коммерческое эт" `@` используется для организации неявного вызова локаций-функций, упрощая запись и заменяя собой функию `func` или оператор `gosub`.
+
+Общая запись для замены `func`:
 
 ```qsp
 @[$локация]([аргумент 0], [аргумент 1], ... , [аргумент 18])
 ```
 
+Общая запись для замены `gosub`:
+
+```qsp
+@@[$локация] [аргумент 0], [аргумент 1], ... , [аргумент 18]
+@@[$локация]([аргумент 0], [аргумент 1], ... , [аргумент 18])
+```
+
 , где `[$локация]` — это название локации, код которой мы хотим выполнить без непосредственного перехода на неё. Аргументы `[аргумент 0]`, `[аргумент 1]` и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные `args[0]`, `args[1]`, и т.д. соответственно. После обработки локации предыдущие значения `args` восстанавливаются. Использование аргументов не обязательно, в этом случае скобки можно опускать.
 
-При обращении к локации с помощью `@` базовое описание локации добавляется к текущему описанию, базовые действия добавляются к текущим действиям, и происходит выполнение операторов в поле "Выполнить при посещении", затем возврат на исходную строку (продолжение выполнения кода после команды с `@`).
+:::danger [Внимание!]
+пробел после названия локации `[$локация]`, перед скобкой, ставить нельзя! Иначе плеер воспримет это как передачу одного аргумента типа *кортеж*.
+:::
+
+При обращении к локации с помощью `@` (или `@@`) базовое описание локации добавляется к текущему описанию, базовые действия добавляются к текущим действиям, и происходит выполнение операторов в поле "Выполнить при посещении", затем возврат на исходную строку (продолжается выполнение кода после команды с `@` или `@@`).
 
 Название локации при неявном вызове не должно содержать специальных символов, иначе это может привести к неработоспособности кода. Можно использовать буквы, цифры, символ подчёркивания и точку.
 
@@ -426,7 +439,7 @@ health = 150
 
 ```qsp
 ! это код вызова локации "переход"
-@переход('локация')
+@@переход('локация')
 
 ! а это код самой локации "переход"
 # переход
@@ -435,7 +448,7 @@ health = 150
 act 'перейти':
     goto "улица"
 end
-- переход
+-- переход
 ```
 
 ```qsp
@@ -445,20 +458,24 @@ end
 loop while args[0] > 0 step args[0] -= 1:
     result += args[0]
 end
-- summ
+-- summ
 
 ! пример вызова локации "summ", как функции
 *pl @summ(19) & ! выведет на экран 190
 ```
 
-:::warning[Обратите внимание!]
-Неявный вызов локации-функции заменяет и `gosub`, и `func`, поэтому:
+:::warning [Обратите внимание!]
+Неявный вызов локации-функции c помощью `@` заменяет `func`, однако:
 
 1. если ваша локация-функция возвращает результат, неявный вызов такой локации будет работать точно так же, как явный вызов через `func`;
 2. если же локация-функция не возвращает результат, то при использовании её с **[неявным оператором](qsp-keywords-statements.md#неявный-оператор)** она будет работать, как явный вызов через `gosub`.
 
 :::
 
+:::warning [Кроме того:]
+Дублированный символ "коммерческое эт" `@@` используется только для неявного вызова `gosub`. Т.е. при таком вызове локация никогда не будет возвращать результат.
+:::
+
 ## Символ "Знак доллара" `$`
 
 Выступает, как префикс типа для именования переменных и функций строкового типа. Его обязательно нужно указывать, если вы хотите присвоить переменной строковое значение:
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
index f542684..2172e55 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
@@ -9,7 +9,7 @@ sidebar_position: 6
 Crossed out commands do not work in players version 5.8.0 and above.
 :::
 
-- [Implicit statement](qsp-keywords-statements#implicit-operator)
+- [Implicit statement](qsp-keywords-statements#implicit-statement)
 - [`!` (comment)](qsp-keywords-statements.md#-comment)
 - [`!` (not equal)](qsp-keywords-operators.md#-not-equal-1)
 - [`&` (concatenation)](qsp-keywords-operators.md#-concatenation)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
index ef49f6d..86432e9 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-syntaxems.md
@@ -398,65 +398,82 @@ Apostrophes can also be used for writing multi-line comments:
 '
 ```
 
-## Commercial "At" Symbol `@`
+## The "Commercial at" symbol `@`
 
-The commercial "at" symbol `@` is used to organize implicit calling of location-functions, simplifying syntax and replacing the `gosub` operator or `func` function. General syntax:
+The "Commercial at" symbol `@` is used to organize implicit calling of location-functions, simplifying the notation and replacing the `func` function or the `gosub` statement.
+
+General syntax for replacing `func`:
 
 ```qsp
 @[$location]([argument 0], [argument 1], ... , [argument 18])
 ```
 
-where `[$location]` is the name of the location whose code we want to execute without directly going to it. Arguments `[argument 0]`, `[argument 1]`, etc. can be used on this location, their values are automatically placed in variables `args[0]`, `args[1]`, etc. respectively. After processing the location, previous `args` values are restored. Using arguments is not mandatory; in this case, brackets can be omitted.
+General syntax for replacing `gosub`:
 
-When accessing a location using `@`, the base description of the location is added to the current description, base actions are added to current actions, and operators in the "Execute on visit" field are executed, then return to the original line (continuing code execution after the command with `@`).
+```qsp
+@@[$location] [argument 0], [argument 1], ... , [argument 18]
+@@[$location]([argument 0], [argument 1], ... , [argument 18])
+```
 
-The location name in implicit calling should not contain special characters, otherwise this may lead to non-functional code. You can use letters, numbers, underscores, and periods.
+where `[$location]` is the name of the location whose code we want to execute without directly going to it. Arguments `[argument 0]`, `[argument 1]`, etc. can be used on this location, their values are automatically placed in variables `args[0]`, `args[1]`, etc. respectively. After processing the location, the previous values of `args` are restored. Using arguments is optional, in which case the parentheses can be omitted.
+
+:::danger [Attention!]
+Do not put a space after the location name `[$location]`, before the parenthesis! Otherwise, the player will interpret this as passing a single argument of type *tuple*.
+:::
+
+When accessing a location using `@` (or `@@`), the base description of the location is added to the current description, base actions are added to the current actions, and the statements in the "Execute on visit" field are executed, then return to the original line (code execution continues after the command with `@` or `@@`).
+
+The location name in an implicit call should not contain special characters, otherwise this may lead to code malfunction. You can use letters, numbers, underscore, and period.
 
 Examples:
 
 ```qsp
-!processing location "move". The args[] array is empty.
+! processing the "move" location. The args[] array is empty.
 @move()
 
-!processing location "move" with passing 3 parameters.
+! processing the "move" location with 3 parameters passed.
 ! $args[0] = $var (value), args[1] = 2,
-! $args[2] = "data". Note the '$' symbols.
+! $args[2] = "data". Pay attention to the '$' symbols.
 @move($var, 2, 'data')
 ```
 
 ```qsp
-! this is the code for calling location "transition"
-@transition('location')
+! this is the code for calling the "transition" location
+@@transition('location')
 
-! and this is the code of the location "transition" itself
+! and this is the code of the "transition" location itself
 # transition
-*pl $args[0]  & ! the text 'location' will be displayed on screen
+*pl $args[0]  & ! the text 'location' will be displayed on the screen
 ! a new action will appear in the actions window:
 act 'go':
     goto "street"
 end
-- transition
+-- transition
 ```
 
 ```qsp
-! location code for a function that gets the sum of a series of numbers from one to the specified value
+! code of the location for a function that gets the sum of a series of numbers from one to the specified value
 # summ
 ! args[0] will contain the number we specify as [argument 0]
 loop while args[0] > 0 step args[0] -= 1:
     result += args[0]
 end
-- summ
+-- summ
 
-! example of calling location "summ" as a function
-*pl @summ(19) & ! will display 190 on screen
+! example of calling the "summ" location as a function
+*pl @summ(19) & ! will display 190 on the screen
 ```
 
-:::warning[Note!]
-Implicit location-function calling replaces both `gosub` and `func`, therefore:
+:::warning [Pay attention!]
+An implicit call to a location-function using `@` replaces `func`, however:
 
-1. if your location-function returns a result, implicit calling of such a location will work exactly the same as explicit calling through `func`;
-2. if the location-function doesn't return a result, then when using it with the **[implicit statement](qsp-keywords-statements.md#implicit-statement)** it will work like explicit calling through `gosub`.
+1. if your location-function returns a result, an implicit call to such a location will work exactly the same as an explicit call via `func`;
+2. if the location-function does not return a result, then when using it with an **[implicit statement](qsp-keywords-statements.md#implicit-statement)** it will work as an explicit call via `gosub`.
+
+:::
 
+:::warning [Also:]
+The duplicated "commercial at" symbol `@@` is used only for implicit calls to `gosub`. I.e., with such a call, the location will never return a result.
 :::
 
 ## Dollar Sign Symbol `$`

From 5e043ee9892043461fa6493efeda35b2dc50e5c6 Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 23:11:27 +0500
Subject: [PATCH 4/7] docs(lang/kwrds/sntxm/RU): extract brackets and parens
 synthsugar

---
 .../qsp-keywords/qsp-keywords-syntaxems.md    | 30 +++++++++++++++++--
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/language/qsp-keywords/qsp-keywords-syntaxems.md b/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
index b981dbf..4fb7f4e 100644
--- a/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
+++ b/docs/language/qsp-keywords/qsp-keywords-syntaxems.md
@@ -232,14 +232,14 @@ gosub "add_object", "Апельсин", 2, "Еда", 37
     gosub("add_object", "Рек", rand(23, 45), "Артефакт", max(36, 67, 90, a))
     ```
 
-3. Если нужно организовать кортеж значений:
+3. Если нужно организовать кортеж:
 
     ```qsp
     %tuple = (123, 234, 'string')
     %mass[23] = ('Петров', 'Пётр', 'Петрович')
     ```
 
-:::warning[Рекомендация!]
+:::warning [Рекомендация!]
 Для организации кортежей рекомендуется использовать квадратные скобки.
 
 ```qsp
@@ -249,6 +249,18 @@ gosub "add_object", "Апельсин", 2, "Еда", 37
 
 :::
 
+Начиная с плееров версии 5.9.4 в скобках допустимы переносы на новую строку, что не будет разрывать выражение:
+
+```qsp
+*pl (
+	45 +
+	68 +
+	73
+)/3
+```
+
+Однако использовать комментарии внутри круглых скобок нельзя!
+
 ## Квадратные скобки `[]`
 
 Квадратные скобки `[]` в QSP используются для указания индекса ячейки массива:
@@ -297,6 +309,18 @@ $mass[]
 %mass[23] = ['Петров', 'Пётр', 'Петрович']
 ```
 
+Начиная с плееров версии 5.9.4 в скобках допустимы переносы на новую строку, что не будет разрывать выражение:
+
+```qsp
+%mass[23] = [
+	'Петров',
+	'Пётр',
+	'Петрович'
+]
+```
+
+Однако использовать комментарии в квадратных скобках нельзя.
+
 ## Фигурные скобки `{}`
 
 Фигурные скобки `{}` в QSP выступают как спецсимволы, отмечающие начало и конец строковых значений. Иными словами, по наличию таких скобок плеер может понять, где начинается и где кончается строковое значение:
@@ -334,7 +358,7 @@ dynamic {
 }
 ```
 
-Допустимо вложение любого количества фигурных скобок друг в друга.
+Допустимо вложение любого количества фигурных скобок друг в друга. Однако каждая открытая фигурная скобка должна быть закрыта.
 
 ## Кавычка `"`
 

From c3e4d761cc0f3137cc28fb40cb9e6370f8b5d8f1 Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 23:24:11 +0500
Subject: [PATCH 5/7] docs(kwrds/stmts,oprtrs/RU): expanded DELOBJ and OBJ
 description

---
 .../qsp-keywords/qsp-keywords-operators.md     | 18 ++++++++++--------
 .../qsp-keywords/qsp-keywords-statements.md    | 16 +++++++++-------
 2 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/docs/language/qsp-keywords/qsp-keywords-operators.md b/docs/language/qsp-keywords/qsp-keywords-operators.md
index f7549de..a2acf40 100644
--- a/docs/language/qsp-keywords/qsp-keywords-operators.md
+++ b/docs/language/qsp-keywords/qsp-keywords-operators.md
@@ -1204,29 +1204,31 @@ no (5 = 3) & ! вернёт 1 (правда)
 
 ## OBJ
 
-`OBJ` — операция проверяет наличие предмета в инвентаре и возвращает `1`, если предмет есть, и — `0`, если предмета нет. Общая запись:
+`OBJ` — операция проверяет наличие предметов с указанным названием в инвентаре и возвращает число этих предметов. Если предметов нет, функция возвращает `0`. Общая запись:
 
 ```qsp
 OBJ([$название])
 ```
 
-, где `[$название]` — название предмета, наличие которого необходимо проверить в окне предметов. Выражение верно, если предмет добавлен в окно предметов.
+, где `[$название]` — название предметов в окне предметов, число которых необходимо получить.
 
 Примеры:
 
 ```qsp
-! проверяет, добавлен ли в окно предметов предмет "Отвёртка"
-obj("Отвёртка") & ! если предмет есть, возвращает 1
+addobj "Отвёртка"
+addobj "Отвёртка"
+obj("Отвёртка") & ! вернёт 2
 
-! в зависимости от наличия того или иного предмета
-! выводится то или иное действие
-if obj("Полный кувшин") = 1:
+obj("Гаечный ключ") & ! вернёт 0
+
+! с помощью данной операции можно проверять наличие предмета:
+if obj("Полный кувшин"):
     act "Опустошить кувшин":
         delobj "Полный кувшин"
         addobj "Пустой квушин"
         goto $curloc
     end
-elseif obj("Пустой кувшин") = 1:
+elseif obj("Пустой кувшин"):
     act "Наполнить кувшин":
         addobj "Полный кувшин"
         delobj "Пустой квушин"
diff --git a/docs/language/qsp-keywords/qsp-keywords-statements.md b/docs/language/qsp-keywords/qsp-keywords-statements.md
index 5a9cda7..2dc0aa4 100644
--- a/docs/language/qsp-keywords/qsp-keywords-statements.md
+++ b/docs/language/qsp-keywords/qsp-keywords-statements.md
@@ -359,7 +359,7 @@ delact 'Идти вперед'
 delact $selact
 ```
 
-:::warning[Устаревшая форма записи:]
+:::warning [Устаревшая форма записи:]
 
 ```qsp
 DEL ACT [$название]
@@ -374,23 +374,25 @@ DEL ACT [$название]
 `DELOBJ` — удаление предмета из инвентаря по названию (если такой предмет существует). Общая запись:
 
 ```qsp
-DELOBJ [$название]
+DELOBJ [$название], [#количество]
 ```
 
-, где `[$название]` — название предмета, который хотим удалить.
+, где:
+- `[$название]` — название предмета, который хотим удалить;
+- `[#количество]` — число предметов с одинаковыми названиями, которые нужно удалить.
 
-Если в инвентаре присутствуют одинаковые предметы, команда удалит самый верхний с указанным индексом.
+Если в инвентаре присутствуют одинаковые предметы, команда удалит самые верхние.
 
 Примеры:
 
 ```qsp
-! удаляем предмет с конкретным названием
-delobj "Отвёртка"
+! удаляем первые три предмета с конкретным названием
+delobj "Отвёртка", 3
 ! удаляем выделенный предмет
 delobj $selobj
 ```
 
-:::warning[Устаревшая форма записи:]
+:::warning [Устаревшая форма записи:]
 
 ```qsp
 DEL OBJ [$название]

From 670514c13c0cb303e892b644fde1e6d263f6342a Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 23:28:14 +0500
Subject: [PATCH 6/7] docs(kwrds/sysvar/RU): expanded ARGS of hyperlink uses

---
 docs/language/qsp-keywords/qsp-keywords-sys-var.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/language/qsp-keywords/qsp-keywords-sys-var.md b/docs/language/qsp-keywords/qsp-keywords-sys-var.md
index a097748..297091d 100644
--- a/docs/language/qsp-keywords/qsp-keywords-sys-var.md
+++ b/docs/language/qsp-keywords/qsp-keywords-sys-var.md
@@ -284,16 +284,16 @@ gosub "локация_2", 34
 
 * код локаций
 * код, передаваемый `dynamic`/`dyneval`
-* код в гиперссылках
 * код в циклах
+* код в гиперссылках
 * код действий
 
-В первых трёх случаях для каждой отдельной сессии таких блоков кода плеер будет создавать собственный массив `args`.
+В первых двух случаях для каждой отдельной сессии таких блоков кода плеер будет создавать собственный массив `args`.
 
 **Однако:**
 
 * в циклах будет использоваться массив `args`, созданный в блоке кода, из которого цикл был вызван.
-* в действиях будет использоваться массив `args`, созданный на локации, на которую был осуществлён переход с помощью  операторов `goto` или `xgoto`.
+* в действиях и гиперссылках будет использоваться массив `args`, созданный на локации, на которую был осуществлён переход с помощью  операторов `goto` или `xgoto`.
 
 ## BCOLOR
 

From 26ca04ab94959530c536ea85d7e4d9cb066cd317 Mon Sep 17 00:00:00 2001
From: aleksversus <aleksversus@mail.ru>
Date: Thu, 19 Feb 2026 23:38:34 +0500
Subject: [PATCH 7/7] fix(kwrds/pointer, functions): rong anchor in links

---
 .../current/language/qsp-keywords/index.md                      | 2 +-
 .../current/language/qsp-keywords/qsp-keywords-functions.md     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
index 2172e55..f52591a 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/index.md
@@ -21,7 +21,7 @@ Crossed out commands do not work in players version 5.8.0 and above.
 - [`{}` (Curly braces)](qsp-keywords-syntaxems.md#curly-braces-)
 - [`()` (round brackets)](qsp-keywords-syntaxems.md#round-brackets-)
 - [`[]` (square brackets)](qsp-keywords-syntaxems.md#square-brackets-)
-- [`@` (commercial "at")](qsp-keywords-syntaxems#commercial-at-symbol-) - 5.8.0
+- [`@` (commercial "at")](qsp-keywords-syntaxems#the-commercial-at-symbol-) - 5.8.0
 - [`$` (dollar sign)](qsp-keywords-syntaxems#dollar-sign-symbol-)
 - [`%` (percent sign)](qsp-keywords-syntaxems#percent-sign-symbol-) - 5.9.0
 - [`*`](qsp-keywords-operators.md#-multiplication)
diff --git a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-functions.md b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-functions.md
index 2a27e9e..845f45b 100644
--- a/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-functions.md
+++ b/i18n/en/docusaurus-plugin-content-docs/current/language/qsp-keywords/qsp-keywords-functions.md
@@ -211,7 +211,7 @@ $name_loc = "summ"
 *pl func($name_loc, 23) & ! will output 276 to screen
 ```
 
-Also see ["Implicit `FUNC` function call"](qsp-keywords-syntaxems#commercial-at-symbol-).
+Also see ["Implicit `FUNC` function call"](qsp-keywords-syntaxems#the-commercial-at-symbol-).
 
 ## `$GETOBJ`