Различия

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

--- help:txt2gam [2024/11/09 03:04]
byte [Формат TXT2GAM (QSPS)]
+++ help:txt2gam [2026/02/14 17:34] (текущий)
aleks_versus [Дополнительная информация и полезные ссылки:]
@@ Строка 3: / Строка 3: @@
 ====== TXT2GAM. Краткое руководство ======
-Утилита "**TXT2GAM**" ("''txt2gam.exe''") предназначена для конвертирования текстовых файлов, написанных в специальном формате, в файлы QSP-игр "''.qsp''". Таким образом вы можете создавать игры в обычном текстовом редакторе, а затем конвертировать их в приемлемые для плееров файлы.
+Утилита "**TXT2GAM**" ("''txt2gam.exe''") предназначена для конвертирования текстовых файлов, написанных в специальном формате, в файлы QSP-игр "''.qsp''". Таким образом вы можете создавать игры в обычном текстовом редакторе, а затем конвертировать их в обычные игры.
-[[https://qsp.org/attachments/txt2gam011.zip|Скачать утилиту для Windows]]
+	* [[https://qsp.org/attachments/txt2gam011.zip|Скачать утилиту для Windows]]
-[[help:txt2gam_linux|Сборка TXT2GAM на Linux]]
+	* [[help:txt2gam_linux|Сборка TXT2GAM на Linux]]
 ===== Формат TXT2GAM (QSPS) =====
@@ Строка 15: / Строка 15: @@
 Использовать qsps-файлы предпочтительнее по трём причинам:
 	* воспроизведение таких файлов поддерживается плеером **[[help:qspider|qSpider]]**;
-	* расширение для **[[https://github.com/gretmn102/QSP-VSCode/blob/master/README.md|MS Visual Studio Cod]]e** поддерживает подсветку синтаксиса qsps-файлов;
+	* расширение для **[[https://github.com/gretmn102/QSP-VSCode/blob/master/README.md|MS Visual Studio Code]]** поддерживает подсветку синтаксиса qsps-файлов;
 	* в **[[https://github.com/AleksVersus/JAD_for_QSP|пакете для Sublime Text]]** встроена подсветка синтаксиса qsps-файлов.
 Как было отмечено выше, файлы в формате **TXT2GAM** — это обычные текстовые файлы, в которых мы размещаем код QSP, при этом данный код нужно записывать по определённым правилам.
-Начало локации отмечается символом **''#''** (решётка/диез), после которого должен стоять пробел и название локации. Например так:
+==== Начало и конец локации ====
+Начало локации отмечается символом ''**#**'' (решётка/диез), после которого должен стоять пробел и название локации. Например так:
 <sxh qsp>
@@ Строка 26: / Строка 28: @@
 </sxh>
-Конец локации обозначается строкой **''--''** (2 дефиса) в отдельной строке. После этого в той же строке могут идти любые символы, например, снова название локации:
+Конец локации обозначается двумя символами "дефис" ''--'' в отдельной строке. После этого в той же строке могут идти любые символы, например, снова название локации:
 <sxh qsp>
@@ Строка 42: / Строка 44: @@
 end
 -- (конец локации)
 # next
 $s='Это последняя локация примера.'
@@ Строка 55: / Строка 57: @@
 Между локациями в таком файле может быть записан любой текст, он не попадёт в конечный файл игры. Поэтому вы можете помещать туда различные комментарии, команды препроцессора и другой сопроводительный текст.
-Отнеситесь внимательно к строке завершения локации **''--''** в начале отдельно стоящей строки.
+Поскольку концом локации считается строка, начинающаяся с ''--'', будьте внимательны при написании игры.
-Записанная в поле "Выполнить при посещении" редактора **Quest Generator**, она будет частью локации в итоговой игре, однако если эту строку записать в файле формата **TXT2GAM**, конвертер посчитает её окончанием локации, и все последующие строки вплоть до начала следующей локации будут проигнорированы.
+Так как, если вы пишете код в **Quest Generator**, такая строка, записанная в коде локации, хотя и будет вызывать ошибку, но всё же не сломает локацию. Однако, если вы сконвертируете игру с подобной ошибкой в qsps, а затем — обратно в игру, весь код локации после такой ошибочной строки потеряется.
 <sxh qsp>
+# начало
 # начало
 "Какой-то код. Много-много кода
@@ Строка 65: / Строка 69: @@
 "А вот этот код не попадёт в локацию"
 -- начало (хотим, чтобы конец локации был здесь)
 # локация 2
 ! какой-то код
@@ Строка 71: / Строка 75: @@
 </sxh>
-Если не закрыть локацию строкой, начинающейся с **''--''**, новую локацию открыть будет нельзя, а значит строка, начинающаяся с символа **''#''** может вызвать ошибку "Неизвестное действие" в конечной игре:
+Если не закрыть локацию строкой, начинающейся с ''**--**'', новую локацию открыть будет нельзя, а значит строка, начинающаяся с символа ''**#**'' может вызвать ошибку "Неизвестное действие" в конечной игре:
 <sxh qsp>
@@ Строка 78: / Строка 82: @@
 # локация 2
 "Забыли закрыть локацию перед открытием новой"
--- локация 2
+- локация 2
 </sxh>
-Внимание! Для формата **TXT2GAM** не предусмотрено редактирование базового описания и базовых действий. Поэтому при экспорте игры из **Quest Generator** в формат **TXT2GAM** будьте внимательны: все базовые описания и базовые действия будут экспортированы в основной код локаций. Если впоследствии вы импортируете игру обратно из TXT2GAM-файла в **Quest Generator**, то поля "Описание" и "Базовые действия" во всех локациях окажутся пустыми.
+==== Базовое описание и базовые действия ====
+Если в **Quest Generator** вы использовали не только поле "Выполнить при посещении", но так же поля "Базовое описание" и "Базовые действия", содержимое этих полей при экспорте игры в формат **TXT2GAM** будет сконвертировано в обычный код QSP, но размещённый между комментариями ''! BASE'' и ''! END BASE'' в самом начале кода локации. При этом:
+	* Каждое действие из поля "Базовые действия" преобразуется в многострочное действие, как если бы оно было записано в поле "Выполнить при посещении".
+	* Весь текст из поля "Базовое описание" будет строкой для оператора "''*P''".
+Вот как это может выглядеть:
+<sxh qsp>
+# Начало
+! BASE
+*P 'Укузя 1.2
+Привет! Вашему вниманию предоставляется небольшой квест про Укузю. Кто она такая, неизвестно.
+Если Вы прошли первую часть игры, то можно загрузиться.'
+ACT 'Начать!':
+   gosub 'menu'
+   goto 'norka'
+END
+ACT 'Проект':
+   goto 'proect'
+END
+ACT 'Загрузить':
+   goto 'saves'
+END
+! END BASE
+Fcolor = RGB(248,194,240)
+Bcolor = RGB(1,0,0)
+if nach = 0: msg 'Совет: Разверните окно на весь экран' & nach=1
+-- Начало ---------------------------------
+</sxh>
+Как видите, в базовом описании был текст из нескольких строк, а в базовых действиях было создано три действия. Всё это сконвертировалось в обычный QSP-код, заключённый между комментариями ''! BASE'' и ''! END BASE''.
+Далее для удобства мы этот код с комментариями будем называть //Базовым блоком//.
+При конвертировании из формата **TXT2GAM** обратно в игру, происходит обратный процесс.
+Если в коде локации присутствовал //Базовый блок// (комментарии ''! BASE'' и ''! END BASE'', между которыми вы разместили код QSP), код этого блока будет преобразован в базовое описание и базовые действия локации в конечной игре.
+Однако, тут есть нюанс.
+Конвертер распознаёт только действия и оператор ''*P'', добавленные в //Базовый блок//. То есть все остальные операторы и выражения будут проигнорированы.
+Более того, будут проигнорированы все строки для оператора ''*P'', заключённые не в кавычки, а так же все действия, названия которых не заключены в кавычки, или формируются динамическим способом.
+Вот наглядный пример:
+<sxh qsp>
+! BASE
+*PL "Этот текст не попадёт в Базовое описание, потому что используется неверный оператор."
+*P {Оператор верный, но текст записан в фигурных скобках.}
+*P "А этот текст попадёт в Базовое описание."
+ACT $action_name:
+   ! Это действие не попадёт в Базовые действия, потому что
+   ! его название указано не константой
+END
+! END BASE
+</sxh>
+Если в файле формата **TXT2GAM** в коде локации вы создали несколько //Базовых блоков//, то — при конвертировании — в Базовое описание и Базовые действия будут добавлены только текст и действия из первого //Базового блока//.
 ===== Использование утилиты TXT2GAM =====
@@ Строка 121: / Строка 189: @@
 </sxh>
-Если указать ключ ''**a**'', исходный файл будет обрабатываться как ANSI-файл (кодировка **CP1251**). По умолчанию используется Unicode (**UTF-8**, **UCS-2 LE** / **UTF-16 LE**):
+Если указать ключ ''**u**'', исходный файл будет обрабатываться как Unicode-файл (кодировка **UCS-2 LE** / **UTF-16 LE**):
 <sxh>
-txt2gam.exe game.txt myCoolGame.qsp a
+txt2gam.exe game.txt myCoolGame.qsp u
 </sxh>
@@ Строка 141: / Строка 209: @@
 	* ''a'', ''A'' — режим ANSI. По умолчанию утилита работает в режиме Unicode (**UTF-8**, **UCS-2** / **UTF-16**).
 	* ''o'', ''O'' — сохранить игру в старом формате ("''.gam''"). По умолчанию используется новый формат ("''.qsp''").
-	* ''s[string]'', ''S[string]'' — вместо ''[string]'' нужно указать строку, с которой начинаются ваши локации. Т.е. это строка, которую вы можете использовать вместо ''**#**'', если это необходимо.
+	* ''s[string]'', ''S[string]'' — вместо ''[string]'' нужно указать строку, с которой начинаются ваши локации. Т.е. это строка, которую вы можете использовать вместо ''#'', если это необходимо.
-	* ''e[string]'', ''E[string]'' — вместо ''[string]'' нужно указать строку, которой будет отмечаться конец локации. Т.е. это строка, которую вы можете использовать вместо ''**--**'', если это необходимо.
+	* ''e[string]'', ''E[string]'' — вместо ''[string]'' нужно указать строку, которой будет отмечаться конец локации. Т.е. это строка, которую вы можете использовать вместо ''--'', если это необходимо.
 	* ''p[pass]'', ''P[pass]'' — вместо ''[pass]'' укажите пароль, который хотите установить на игру. По умолчанию ''**NO**''. Если пароль содержит пробелы, заключите его в кавычки.
-	* ''t'', ''T'' — извлечь строки из текста.
+	* ''c'', ''C'' — конвертировать текстовый файл в игру (режим по умолчанию).
+	* ''d'', ''D'' — конвертировать игру в текстовый файл формата **TXT2GAM**.
+	* ''t'', ''T'' — извлечь строки из текста.
 	* ''q'', ''Q'' - извлечь строки кода (между "{" и "}") из текста.
@@ Строка 152: / Строка 222: @@
 txt2gam.exe file.txt gamefile.qsp pMyPassword
 txt2gam.exe file.txt gamefile.qsp
-txt2gam.exe file.txt gamefile.qsp u
+txt2gam.exe file.txt gamefile.qsp a
+txt2gam.exe gamefile.qsp file.txt d pMyPassword
 txt2gam.exe file.txt gamefile.qsp o pMyPassword
 txt2gam.exe file.txt gamefile.qsp o e@ pMyPassword
@@ Строка 163: / Строка 234: @@
 </sxh>
-===== Подключение утилиты к текстовому редактору =====
-При разработке игр в текстовом редакторе, очень полезным может оказаться создание специального действия / кнопки для автоматической компиляции файла в "''.qsp''" и запуска плеера сразу с редактируемым файлом.
-То есть пишете текст игры в редакторе, нажимаете некое сочетание клавиш и получаете запущенную в плеере игру.
-Данное руководство, на примере **[[http://www.emeditor.com|EmEditor]]**а , описывает, как это сделать.
-Для начала, создайте папку (допустим, "''D:\Games\QSP''"), распаковав в неё базовый архив плеера ("''qspgui.exe''" + все **DLL**ки) и архив утилиты **TXT2GAM**.
-Далее, создайте в этой папке (рядом с "''qspgui.exe''", "''txt2gam.exe''") файл "''start.bat''" со следующим содержимым:
-<sxh>
-txt2gam %1 %2
-start qspgui %2
-</sxh>
-Теперь нужно в редакторе добавить действие/кнопку, при нажатии на которую будет запущен файл "''start.bat''" с двумя аргументами - указанием исходного TXT-файла и конечного "''.qsp''"-файла.
-	- Запустите EmEditor, выберите в меню **Tools / External Tools / Customize Tools...**
-	- В появившемся окошке нажмите кнопку **New**.
-	- В поле **Title** впишите название действия (например, "QSP").
-	- В поле **Command** строку ''D:\Games\QSP\start.bat''
-	- В поле **Arguments** строку ''"$(Path)" "$(Dir)\$(Filename).gam"'' (сохраняя кавычки)
-	- В поле **Initial Directory** строчку ''D:\Games\QSP''
-	- Затем поставьте флажок напротив **Save File**, и нажмите **OK**.
-	- На панели инструментов появится новая кнопка с подписью "QSP", при нажатии на которую будут произведены требуемые действия.
-Теперь нужно назначить сочетание клавиш для кнопки.
-	- Выберите пункт меню **Help / Keyboard Map...**. В категории **External Tools** найдите пункт **QSP** (обычно, в самом низу) и щелкните по нему 2 раза.
-	- Установите курсор в поле **Press New Shortcut Key** и нажмите желаемое сочетание клавиш (к примеру, F1). Станет доступной кнопка **Assign**. Нажимаем.
-	- Далее жмём **OK** и пишем игры в формате TXT2GAM :-)
-Чтобы установить пароль на файл, создаваемый утилитой TXT2GAM, замените в файле **''start.bat''** строчку
-<sxh>
-txt2gam.exe %1 %2
-</sxh>
-на
-<sxh>
-txt2gam.exe %1 %2 pMyPassword
-</sxh>
-где ''MyPassword'' - устанавливаемый пароль. Для задания паролей с пробелами, строчка ''pMyPassword'' должна быть указана в кавычках:
-<sxh>
-txt2gam.exe %1 %2 "pMy Pass word"
-</sxh>
 ===== Дополнительная информация и полезные ссылки: =====
 	- В настоящий момент общепринятым расширением для текстовых файлов формата **TXT2GAM** можно считать "''.qsps''". "Просто потому что" (с) [[https://github.com/gretmn102/QSP-VSCode#допустим-я-хочу-попробовать|Pseudopod]].
+	- Есть готовая [[help:txt2gam_emeditor|инструкция]] по подключению утилиты **TXT2GAM** к редактору **EmEditor**.
 	- Существует утилита **qsp2txt** для конвертирования игр в обратную сторону — из файлов игр "''.qsp''" в текстовые файлы формата **TXT2GAM**. Исходная ссылка утеряна, можно скачать в [[https://mega.nz/folder/jXwXlSRJ#TF7P-soOJOWIC8MrBA-L1A|архиве программ QSP от Aleks Versus]].
 	- Существовали разные [[https://qsp.org/index.php?option=com_agora&task=topic&id=686&Itemid=57|подсветки синтаксиса для **Notepad++** и **AkelPad**]], но были утеряны.
@@ Строка 227: / Строка 249: @@
 [[help:analyzer|Вперёд: Анализатор кода]]

Документация QSPСайтФорум

Инструменты пользователя

Инструменты сайта

Различия

Инструменты страницы

Документация QSP
Сайт Форум