[[help:debugger|Назад: Отладчик]]

====== TXT2GAM. Краткое руководство ======

Утилита "**TXT2GAM**" ("''txt2gam.exe''") предназначена для конвертирования текстовых файлов, написанных в специальном формате, в файлы QSP-игр "''.qsp''". Таким образом вы можете создавать игры в обычном текстовом редакторе, а затем конвертировать их в приемлемые для плееров файлы.

[[https://github.com/QSPFoundation/txt2gam/releases|Скачать утилиту для Windows/Linux/MacOS]]
===== Формат TXT2GAM (QSPS) =====

Формат **TXT2GAM** так же называется форматом **QSPS**, а текстовые файлы, записанные в этом формате и имеющие расширение "''.qsps''", называются qsps-файлами.

Использовать qsps-файлы предпочтительнее по трём причинам:
	* воспроизведение таких файлов поддерживается плеером **[[help:qspider|qSpider]]**;
	* расширение для **[[https://github.com/gretmn102/QSP-VSCode/blob/master/README.md|MS Visual Studio Cod]]e** поддерживает подсветку синтаксиса qsps-файлов;
	* в **[[https://github.com/AleksVersus/JAD_for_QSP|пакете для Sublime Text]]** встроена подсветка синтаксиса qsps-файлов.

Как было отмечено выше, файлы в формате **TXT2GAM** — это обычные текстовые файлы, в которых мы размещаем код QSP, при этом данный код нужно записывать по определённым правилам.

Начало локации отмечается символом **''#''** (решётка/диез), после которого должен стоять пробел и название локации. Например так:

<sxh qsp>
# начало
</sxh>

Конец локации обозначается строкой **''%%--%%''** (2 дефиса) в отдельной строке. После этого в той же строке могут идти любые символы, например, снова название локации:

<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**, она будет частью локации в итоговой игре, однако если эту строку записать в файле формата **TXT2GAM**, конвертер посчитает её окончанием локации, и все последующие строки вплоть до начала следующей локации будут проигнорированы.

<sxh qsp>
# начало
"Какой-то код. Много-много кода
Этот код попадёт в локацию"
--
"А вот этот код не попадёт в локацию"
-- начало (хотим, чтобы конец локации был здесь)

# локация 2
! какой-то код
-- локация 2
</sxh>

Если не закрыть локацию строкой, начинающейся с **''%%--%%''**, новую локацию открыть будет нельзя, а значит строка, начинающаяся с символа **''#''** может вызвать ошибку "Неизвестное действие" в конечной игре:

<sxh qsp>
# начало
"Выводим текст"
# локация 2
"Забыли закрыть локацию перед открытием новой"
-- локация 2
</sxh>

Внимание! Для формата **TXT2GAM** не предусмотрено редактирование базового описания и базовых действий. Поэтому при экспорте игры из **Quest Generator** в формат **TXT2GAM** будьте внимательны: все базовые описания и базовые действия будут экспортированы в основной код локаций. Если впоследствии вы импортируете игру обратно из TXT2GAM-файла в **Quest Generator**, то поля "Описание" и "Базовые действия" во всех локациях окажутся пустыми.

===== Использование утилиты 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>

Если указать ключ ''**a**'', исходный файл будет обрабатываться как ANSI-файл (кодировка **CP1251**). По умолчанию используется Unicode (**UTF-8**, **UCS-2 LE** / **UTF-16 LE**):

<sxh>
txt2gam.exe game.txt myCoolGame.qsp a
</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**''. Если пароль содержит пробелы, заключите его в кавычки.
	* ''t'', ''T'' — извлечь строки из текста.
	* ''q'', ''Q'' - извлечь строки кода (между "{" и "}") из текста.

==== Примеры вызова: ====

<sxh>
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 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>

===== Подключение утилиты к текстовому редактору =====

При разработке игр в текстовом редакторе, очень полезным может оказаться создание специального действия / кнопки для автоматической компиляции файла в "''.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]].
	- Существует утилита **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"]]

[[help:analyzer|Вперёд: Анализатор кода]]