Различия

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

--- help:txt2gam [2017/09/12 19:40]
aleks_versus
+++ help:txt2gam [2026/02/14 17:34] (текущий)
aleks_versus [Дополнительная информация и полезные ссылки:]
@@ Строка 1: / Строка 1: @@
-Работа с утилитой TXT2GAM
+[[help:debugger|Назад: Отладчик]]
-Top Previous Next
+====== TXT2GAM. Краткое руководство ======
-Программа "TXT2GAM" (''"txt2gam.exe"'') предназначена для создания игр под платформу QSP в обычном текстовом редакторе.
+Утилита "**TXT2GAM**" ("''txt2gam.exe''") предназначена для конвертирования текстовых файлов, написанных в специальном формате, в файлы QSP-игр "''.qsp''". Таким образом вы можете создавать игры в обычном текстовом редакторе, а затем конвертировать их в обычные игры.
-Формат файла, обрабатываемого утилитой, представлен ниже.
+	* [[https://qsp.org/attachments/txt2gam011.zip|Скачать утилиту для Windows]]
+	* [[help:txt2gam_linux|Сборка TXT2GAM на Linux]]
+===== Формат TXT2GAM (QSPS) =====
-Начало локации обозначается символом "#", после которого пишут название локации. Затем, построчно, необходимые операторы, а заканчивается локация символом "-" (с новой строки), после которого может идти всё, что угодно (в том числе ничего). Следующая локация опять начинается с символа "#" и т.д.
+Формат **TXT2GAM** так же называется форматом **QSPS**, а текстовые файлы, записанные в этом формате и имеющие расширение "''.qsps''", называются qsps-файлами.
-Пример исходного файла:
+Использовать qsps-файлы предпочтительнее по трём причинам:
+	* воспроизведение таких файлов поддерживается плеером **[[help:qspider|qSpider]]**;
+	* расширение для **[[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-файлов.
-<sxh qsp>#Начало
+Как было отмечено выше, файлы в формате **TXT2GAM** — это обычные текстовые файлы, в которых мы размещаем код QSP, при этом данный код нужно записывать по определённым правилам.
-'It''s only test of new utility.'
+==== Начало и конец локации ====
-'That is all.'
+Начало локации отмечается символом ''**#**'' (решётка/диез), после которого должен стоять пробел и название локации. Например так:
-act 'Далее':
+<sxh qsp>
+# начало
+</sxh>
-goto 'next'
+Конец локации обозначается двумя символами "дефис" ''--'' в отдельной строке. После этого в той же строке могут идти любые символы, например, снова название локации:
+<sxh qsp>
+-- начало
+</sxh>
+Между началом и концом локации записывается обычный код QSP, как если бы вы его писали в поле "**Выполнить при посещении**" редактора **Quest Generator**. Вот пример кода в формате **TXT2GAM** с двумя локациями:
+<sxh qsp>
+# Начало
+'It''s only test of new utility.'
+'That is all.'
+act 'Далее':
+   goto 'next'
 end
+-- (конец локации)
+# next
+$s='Это последняя локация примера.'
+loop local i = 1 while i<=len($s) step i += 1:
+   *p $mid($s,i,1)
+   wait 200
+end
+*nl & 'Это всё.'
+--
+</sxh>
-- (конец локации)
+Между локациями в таком файле может быть записан любой текст, он не попадёт в конечный файл игры. Поэтому вы можете помещать туда различные комментарии, команды препроцессора и другой сопроводительный текст.
+Поскольку концом локации считается строка, начинающаяся с ''--'', будьте внимательны при написании игры.
+Так как, если вы пишете код в **Quest Generator**, такая строка, записанная в коде локации, хотя и будет вызывать ошибку, но всё же не сломает локацию. Однако, если вы сконвертируете игру с подобной ошибкой в qsps, а затем — обратно в игру, весь код локации после такой ошибочной строки потеряется.
-#next
+<sxh qsp>
+# начало
+# начало
+"Какой-то код. Много-много кода
+Этот код попадёт в локацию"
+--
+"А вот этот код не попадёт в локацию"
+-- начало (хотим, чтобы конец локации был здесь)
+# локация 2
+! какой-то код
+-- локация 2
+</sxh>
-$s='Это последняя локация примера.'
+Если не закрыть локацию строкой, начинающейся с ''**--**'', новую локацию открыть будет нельзя, а значит строка, начинающаяся с символа ''**#**'' может вызвать ошибку "Неизвестное действие" в конечной игре:
-i=1
+<sxh qsp>
+# начало
+"Выводим текст"
+# локация 2
+"Забыли закрыть локацию перед открытием новой"
+- локация 2
+</sxh>
-:loop
+==== Базовое описание и базовые действия ====
-if i<=len($s):
+Если в **Quest Generator** вы использовали не только поле "Выполнить при посещении", но так же поля "Базовое описание" и "Базовые действия", содержимое этих полей при экспорте игры в формат **TXT2GAM** будет сконвертировано в обычный код QSP, но размещённый между комментариями ''! BASE'' и ''! END BASE'' в самом начале кода локации. При этом:
-*p mid($s,i,1)
+	* Каждое действие из поля "Базовые действия" преобразуется в многострочное действие, как если бы оно было записано в поле "Выполнить при посещении".
+	* Весь текст из поля "Базовое описание" будет строкой для оператора "''*P''".
-wait 200
+Вот как это может выглядеть:
-i=i+1
+<sxh qsp>
+# Начало
+! BASE
+*P 'Укузя 1.2
-jump 'loop'
+Привет! Вашему вниманию предоставляется небольшой квест про Укузю. Кто она такая, неизвестно.
-end
+Если Вы прошли первую часть игры, то можно загрузиться.'
+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
-*nl & 'Это всё.'
+-- Начало ---------------------------------
+</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 =====
+**TXT2GAM** — это консольная утилита, т.е. она запускается командами из консоли, например из командной строки Windows.
+(Ознакомиться с основными командами командной строки вы можете в обучающей статье [[https://sonikelf.ru/vvodnaya-statya-po-rabote-v-konsoli-chto-takoe-konsol-komandy-konsoli-i-prochee-takoe-raznoe-cmd/|"Что такое консоль, команды и прочее такое разное — CMD"]]).
+Пример работы с утилитой:
+<sxh>
+txt2gam.exe game.txt game.qsp
+</sxh>
+Здесь: "''game.txt''" — исходный файл вашей игры, написанный в формате **TXT2GAM**; "''game.qsp''" — конечный файл, в котором будет сохранена ваша игра.
+Предположим, вы написали игру в текстовом редакторе, и теперь она у вас лежит в виде файла "''game.txt''" на диске "''D:''" в папке "''QSP\Games\myCoolGame''".
+Для удобства скопируйте утилиту **TXT2GAM** (т.е. файл "''txt2gam.exe''") в папку с игрой. Теперь для конвертирования игры вам нужно сделать следующее:
+	- Откройте консоль
+	- Перейдите на диск "''D:''", введя команду ''**D:**'' в командной строке и нажав клавишу "Enter".
+	- Перейдите в папку с вашей игрой с помощью команды **cd**. В нашем примере это делается так ''**cd "QSP\Games\myCoolGame"**''
+	- Запустите утилиту **TXT2GAM**, указав в качестве параметров сначала исходный файл вашей игры (т.е. "''game.txt''"), а затем название файла, который хотите получить, например "''myCoolGame.qsp''":
+<sxh>
+	txt2gam.exe game.txt myCoolGame.qsp
+</sxh>
+Утилита поддерживает полные пути к файлам, поэтому вы можете использовать одну утилиту для конвертирования разных игр:
+<sxh>
+txt2gam.exe "D:\QSP\Games\myCoolGame\game.txt" "D:\QSP\releases\myCoolGame\myCoolGame.qsp"
+</sxh>
+Для получения дополнительной информации об утилите, запустите её в консоли без параметров:
+<sxh>
+txt2gam.exe
+</sxh>
+Если указать ключ ''**u**'', исходный файл будет обрабатываться как Unicode-файл (кодировка **UCS-2 LE** / **UTF-16 LE**):
+<sxh>
+txt2gam.exe game.txt myCoolGame.qsp u
+</sxh>
+===== Дополнительные возможности утилиты =====
--</sxh>
+==== Использование ====
+Общий вид команды для консоли:
-Пример запуска утилиты:
+<sxh>
+txt2gam [txt file] [output file] [options]
+</sxh>
+==== Опции. [Options] ====
+	* ''a'', ''A'' — режим ANSI. По умолчанию утилита работает в режиме Unicode (**UTF-8**, **UCS-2** / **UTF-16**).
+	* ''o'', ''O'' — сохранить игру в старом формате ("''.gam''"). По умолчанию используется новый формат ("''.qsp''").
+	* ''s[string]'', ''S[string]'' — вместо ''[string]'' нужно указать строку, с которой начинаются ваши локации. Т.е. это строка, которую вы можете использовать вместо ''#'', если это необходимо.
+	* ''e[string]'', ''E[string]'' — вместо ''[string]'' нужно указать строку, которой будет отмечаться конец локации. Т.е. это строка, которую вы можете использовать вместо ''--'', если это необходимо.
+	* ''p[pass]'', ''P[pass]'' — вместо ''[pass]'' укажите пароль, который хотите установить на игру. По умолчанию ''**NO**''. Если пароль содержит пробелы, заключите его в кавычки.
+	* ''c'', ''C'' — конвертировать текстовый файл в игру (режим по умолчанию).
+	* ''d'', ''D'' — конвертировать игру в текстовый файл формата **TXT2GAM**.
+	* ''t'', ''T'' — извлечь строки из текста.
+	* ''q'', ''Q'' - извлечь строки кода (между "{" и "}") из текста.
-''txt2gam.exe game.txt game.gam''
+==== Примеры вызова: ====
+<sxh>
+txt2gam.exe file.txt gamefile.qsp pMyPassword
+txt2gam.exe file.txt gamefile.qsp
+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
+txt2gam.exe file.txt gamefile.qsp u o p"My Password"
+txt2gam.exe file.txt gamefile.qsp o
+txt2gam.exe file.txt gamefile.qsp o e@
+txt2gam.exe file.txt gamefile.qsp s@ e~
+txt2gam.exe file.txt gamefile.qsp s@ e~ o
+txt2gam.exe file.txt gamefile.qsp t u
+</sxh>
-Здесь: "game.txt" - имя исходного файла, "game.gam" - имя файла, в котором будет сохранена игра.
+===== Дополнительная информация и полезные ссылки: =====
+	- В настоящий момент общепринятым расширением для текстовых файлов формата **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**]], но были утеряны.
+	- Подсветка синтаксиса для Sublime Text входит в **[[https://github.com/AleksVersus/JAD_for_QSP|пакет QSP для Sublime Text]]**. В этот же пакет встроен плагин с конвертерами qsps и QSP-файлов в любую сторону.
+	- Существует подсветка для [[https://qsp.org/components/com_agora/img/members/20/notepad-qsp.zip|Notepad++ от Олегуса]]. С этой подсветкой ассоциируются текстовые файлы с расширением "''.tqsp''", однако вы можете отредактировать файл подсветки, указав нужное вам расширение.
+	- Werewolf разработал утилиту для конвертирования QSP-файла в текстовый формат (аналог **qsp2txt**), которая работает онлайн: [[https://codepen.io/srg-kostyrko/full/QWqdwxv|https://codepen.io/srg-kostyrko/full/QWqdwxv]]. Так же он разработал специальные пакеты для конвертирования файлов в любую сторону: [[https://github.com/QSPFoundation/converters|https://github.com/QSPFoundation/converters]].
+	- Существует учебник по написанию игр на QSP, если вы начинаете сразу с работы в текстовом редакторе: [[help:txt2gam_manual|Пишем QSP-игру в текстовом редакторе]].
+	- Можно дополнительно обрабатывать qsps-файлы специальными программами перед тем, как конвертировать в файл игры QSP. Эти программы называются препроцессорами. В 2010 году NTROPY написал статью на эту тему: [[help:txt2gam_preprocessor|"Препроцессор при использовании TXT2GAM"]]
-PS:
+[[help:analyzer|Вперёд: Анализатор кода]]
-  - Между локациями может находиться любой текст, не начинающийся с символа "#". В результирующем файле данный текст присутствовать не будет.
-  - При указании параметра "u" в командной строке, исходный файл будет обрабатываться как Unicode-файл (кодировка UCS-2 LE / UTF-16 LE).
-  - Для получения дополнительной информации об утилите, запустите её в консоли без параметров.

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

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

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

Различия

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

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