Add modobj and resetobj statements, and expanded kwrds partition by etc news. Close #42

.gitignore

@@ -18,3 +18,5 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+.obsidian

docs/language/qsp-keywords/index.md

@@ -5,7 +5,7 @@ sidebar_position: 6
 
 # Указатель
 
-:::warning[Внимание!]
+:::warning [Внимание!]
 Вычеркнутые команды не работают в плеерах версии 5.8.0 и выше.
 :::
 
@@ -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)

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 "Пустой квушин"

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
 ```
 
 ## `!` (комментарий)
@@ -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 [$название]
@@ -529,7 +531,7 @@ gosub 'переход', 'локация'
 act 'перейти':
     goto "улица"
 end
-- переход
+-- переход
 ```
 
 Оператор имеет краткую форму `gs`:
@@ -1456,6 +1458,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` — вывод указанного сообщения в диалоговом окне. Общая запись:
@@ -1620,6 +1718,16 @@ play $file, volume
 
 По умолчанию обновление интерфейса происходит 2 раза в секунду (каждые 500 мс). Так же см. оператор [`settimer`](#settimer).
 
+## RESETOBJ
+
+- `RESETOBJ` — сбрасывает отображаемое наименование и иконку предметов с указанным названием до состояния на момент добавления с помощью `ADDOBJ`. Общая запись:
+
+```qsp
+RESETOBJ [$название]
+```
+
+, где `[$название]` — это название предмета, которое было использовано при добавлении предмета в окно предметов с помощью `ADDOBJ`.
+
 ## SAVEGAME
 
 `SAVEGAME` — сохранение состояния игры в указанный файл. Общая запись: