search

AleksVersus / JAD_for_QSP

QSP-package for Sublime Text
3 stars 1 forks source link

readme

QSP-Package для Sublime Text

Пакет QSP для редактора Sublime Text включает в себя подсветку синтаксиса для языка QSP, встроенный билдер, собирающий и запускающий QSP-игры из файлов-исходников, а так же наборы сниппетов, инструментов работы с проектом и другие элементы, облегчающие разработку игр на QSP.

[!tips] Подсказка. Если вы не имели дела с Sublime Text, есть краткая пошаговая инструкция по первому запуску игры с нуля: Краткая инструкция по установке пакета QSP для Sublime Text

Преимущества Sublime Text в сравнении с QuestGenerator 4.0.0

Всем новичкам в разработке игр на QSP я предлагаю начинать с Quest Generator, так как он удобен, прост и интуитивно понятен. Пишешь локации, нажатием на кнопку запускаешь игру — тестируешь.

Тем же, кому не достаёт возможностей в Quest Generator, предлагаю воспользоваться более удобным и функциональным редактором Sublime Text.

Вот какие преимущества даёт Sublime Text с установленным в него пакетом QSP:

  1. Исходники. Разработка игры ведётся исключительно в текстовых файлах (исходниках) формата TXT2GAM (QSPS), что позволяет:
    • Использовать системы контроля версий типа GIT на всех этапах разработки, а значит фиксировать и отслеживать все изменения, вносимые в игру и быстрее находить ошибки.
    • Вести совместную разработку игры с использованием общего репозитория на ресурсах типа GitHub.
    • Проводить поиск по отдельным папкам, файлам, или по всему проекту.
  2. Удобная модульная разработка: то есть вы можете разбивать игру на сколь угодно большое число частей и подчастей, организовывать эти части по папкам, вкладывая папки друг в друга, или даже хранить некоторые части игры отдельно, а в нужный момент билдер сам соберёт все нужные вам файлы ".qsp" и запустит игру в плеере по нажатию пары клавиш.
  3. Один редактор — много плееров. Вы можете завести несколько файлов проекта, каждый из которых будет ориентирован на сборку и запуск игры в определённом плеере, что позволит вам разрабатывать игру сразу под несколько плееров.
  4. Работа с файлами ресурсов. Sublime Text из коробки умеет подсвечивать CSS, HTML и JavaScript-файлы, что позволяет работать с этими файлами в том же редакторе, в котором вы работаете над основной частью игры.
  5. Расширения. Вы можете настроить редактор под себя, создавая собственные сниппеты, устанавливая различные вспомогательные плагины и т.д. Например, вы можете установить в Sublime Text проверку орфографии, или Emmet, облегчающий работу с HTML.
  6. Подсветка кода. Умеет очень многое:
    • Поскольку текст между локациями не попадает в финальную версию игры, он подсвечивается как комментарий.
    • Распознавание начала и конца локации и соответственно подсветка этих элементов.
    • Подсветка, которую умеет Quest Generator:
      • Подсветка сложных многострочных комментариев.
      • Подсветка строковых констант.
      • Подсветка числовых констант, системных переменных, операторов и функций.
      • Подсветка меток на локации
    • Подсветка вложенных выражений (подвыражений) в строках.
    • Подсветка основных синтаксических ошибок:
      • Лишний $ перед именами числовых системных переменных или функций.
      • Отсутствие $ перед именами текстовых системных переменных и функций.
      • Звёздочка * перед именем операторов, кроме *pl, *p, *nl, *clr.
      • Неверное число операндов у операций типа +, -, *, <, > и т.д.
      • Подсветка неправильных имён переменных типа 123build.
      • Разрыв строки кода внутри вложенного выражения.
      • Подсветка лишнего end, а так же else и elseif вне конструкций условий.
      • Подсветка неправильной записи else и elseif в многострочном условии.
      • Незакрытый многострочный act, loop или if вызывает подсветку элемента "конец локации" или фигурной скобки, как ошибки.
      • Неправильно поставленная запятая.
      • Неверная запись оператора local или set.
      • Унарный минус перед текстовой переменной.
    • Подсветка HTML-кода в строках и фигурных скобках при вставке тегов <qhtml>, </qhtml>.
    • Подсветка конструкций неявного вызова, а так же подсветка ошибочной записи таких конструкций.
    • Подсветка команд препроцессора
    • Подсветка операторов многострочных конструкций act, if, else, elseif, loop, end. Правильная подсветка end loop, end act, end if - такие сочетания подсвечиваются, как отдельное ключевое слово.
  7. Автоподстановка. Когда вы начинаете вводить ключевое слово, или уже вводившуюся ранее переменную, появляется список со словами автоподстановки. Если вы используете неявный вызов функции, редактор предложит варианты уже созданных вами локаций, начинающихся с той же буквы.
  8. Предупреждения. Редактор предупредит вас:
    • если вы укажете для локации название, которое уже существует в проекте
    • если вы укажете метку, которая уже присутствует в файле

Формат исходных файлов

Ещё на заре появления QSP была создана утилита TXT2GAM, которая позволяет разрабатывать игру в виде текстового файла (исходника) в любом текстовом редакторе, а потом конвертировать исходник в готовый файл игры.

Вкратце. Файлы формата TXT2GAM (исходники) — это обычные текстовые файлы, в которых код QSP записывается по определённым правилам. В данном руководстве данный формат будет называться форматом qsps по названию уже общепринятого расширения для подобных текстовых файлов ".qsps". Однако файлы формата qsps могут иметь любое иное расширение: ".txt", ".start" и т.п.

В таких файлах нет возможности работать с базовым описанием и базовыми действиями локации, а только лишь с кодом поля "Выполнить при посещении", если работу в текстовом редакторе сравнивать с работой в Quest Generator.

Типичный файл формата qsps выглядит так:

# start
!^ в строчке выше записана метка начала локации.
! она состоит из символа решётки и названия локации.
! название можно отделять, а можно не отделять пробелом от решётки

*pl "Здесь вы видите код локации, соответствующий коду
из поля Выполнить при посещении Quest Generator'а."

! последняя строчка, это метка окончания локации
! она должна начинаться с символа - , за которым
! может находиться любой текст. Обычно это снова
! название локации, или сочетание доп символов и
! названия локации 
- start

Весь текст между локациями не попадает в игру

# вторая локация
*pl "

    В одном qsps-файле можно размещать несколько локаций,
    если это необходимо

"
--- вторая локация ---------------------------------

Более подробно о том, как пишутся игры на QSP в формате TXT2GAM, вы можете узнать из уроков от ELMORTEM: "Пишем QSP-игру в текстовом редакторе".

Кодировка

Непосредственно сами файлы QSP (".qsp") имеют кодировку utf-16le, тогда как билдер работает исключительно с файлами в кодировке utf-8 (без BOM-символов). Чтобы билдер собирал игру правильно, исключительно важно, чтобы все qsps-файлы вашего проекта имели кодировку utf-8. Будьте аккуратны при использовании спецсимволов, проверяйте соответствие в исходном и конечном файле.

Установка пакета QSP для Sublime Text

  1. Прежде всего у вас должен быть установлен Sublime Text, желательно Sublime Text 4. Скачать его можно отсюда https://www.sublimetext.com/download.

Установка для пользователей Windows

Данная инструкция ориентирована на пользователей, которые скачают последний релиз со страницы релизов: . Установка из исходников будет немного отличаться.

  1. Скачайте установочный файл из последнего релиза. Файл будет называться "install.QSP.sublime-package.XX.exe", где XX — номер версии.
  2. Запустите установочный файл и следуйте инструкциям — пакет установится автоматически.
  3. При желании скачайте и распакуйте в отдельную папку архив "manual and examples.zip", в котором содержится текущая инструкция и различные примеры проектов.

Установка из исходников

  1. Скачайте архив "QSP.sublime-package.src.zip" из последнего релиза.
  2. Откройте Sublime Text и откройте папку с установленными пакетами: пункты меню Preferences → Browse Packages...
  3. В открытую папку извлеките из архива "QSP.sublime-package.src.zip" папку "QSP". При необходимости замените файлы.

Перезагрузите Sublime Text после установки пакета!

Удаление пакета QSP из Sublime Text

  1. Откройте Sublime Text и откройте папку с установленными пакетами: пункты меню Preferences → Browse Packages...

для пользователей Windows

  1. Откройте папку QSP и запустите программу unins000.exe
  2. Следуйте инструкциям.
  3. Если папка QSP не удалится, или удалится не полностью, её можно удалить вручную.

для пользователей, устанавливавших из исходников

  1. Удалите папку QSP

[!warning] Важно! Перезагрузите Sublime Text после удаления пакета!

Состав пакета QSP для Sublime Text

QSP-Builder

QSP-Builder (далее QBST, билдер) — это встроенный в пакет QSP плагин, который:

  1. собирает из разрозненных файлов формата qsps один цельный файл игры в формате qsps;
  2. конвертирует полученный qsps-файл в файл игры в формате ".qsp" (QSP-файл);
  3. запускает указанный файл игры в стандартном или выбранном плеере QSP.

Возникающие при сборке ошибки выводятся в консоль. Консоль открывается сочетанием клавиш Ctrl + ~.

Порядок работы с проектом игры на QSP

  1. Проект организуется по папкам. В корневой папке проекта должен лежать файл "qsp-project.json", который и содержит в себе инструкции по сборке проекта (см. раздел qsp-project.json).
  2. Все рабочие файлы проекта пишутся в формате qsps и сохраняются с расширением ".qsps". В качестве исключения можно указывать иные расширения, но в таком случае необходимо будет указывать пути до конкретных файлов (см. раздел "qsp-project.json").
    Sublime Text по умолчанию работает с файлами кодировки UTF-8, поэтому и билдер написан под данную кодировку. Если кодировка в конечном файле игры нарушена, значит вы работаете с исходниками в кодировке отличной от UTF-8, смените кодировку исходников на UTF-8.
  3. После редактирования и сохранения файлов можно выбрать один из режимов сборки:
    • "QSP - qsp-build" — собрать файлы согласно инструкции и сконвертировать в ".qsp", по умолчанию сочетание клавиш ["ctrl+alt+q"].
    • "QSP - qsp-run" — запустить стартовый файл, указанный в проекте "qsp-project.json", в плеере. По умолчанию сочетание клавиш ["ctrl+alt+s"].
    • "QSP" — собрать файлы согласно инструкции и запустить стартовый файл в плеере, по умолчанию сочетание клавиш ["ctrl+f5"].

Для примера рассмотрим проект моей игры "fantastic battles", которую я писал в Quest Generator.

В этом проекте пришлось разбить игру на отдельные модули для удобства разработки, и всего таких модулей получилось четыре:

Каждый из этих файлов может содержать множество локаций, поэтому для самих файлов ведутся файлы ".qproj", которые содержат псевдопапки. Например, в "fb_v.0.2.qsp" локации разбиты на псевдопапки:

Работая в редакторе типа Sublime Text, я могу не только разбить данный файл игры на отдельные файлы и разместить их по папкам, но каждую локацию писать в отдельном файле. Я могу создавать подпапки и т.д., а потом собирать те же четыре файла из разрозненных qsps-файлов.

В данном случае я бы выделил отдельную папку под каждый модуль, в том числе — под основной файл игры. Допустим так:

Необходимо отметить, что при сборке конечного файла из таких разрозненных файлов, к конечному файлу добавляются сначала локации из файлов, которые лежат в папках верхних уровней, затем файлы из папок нижних уровней. Таким образом локация из файла "start.qsps" окажется в самом верху списка локаций при создании файла ".qsp". Это особенно важно учитывать, если вы пользуетесь возможностями препроцессора.

qsp-project.json

Пример с комментариями представлен в файле "[disdocs]\example.json" (см. на гитхабе).

Как видно из расширения, проект представляет собой JSON-файл. Это значит, что вся его структура состоит из JSON-объектов (в Python - это словари) и JSON-массивов (в Python - это списки). Немного более подробно о файлах формата JSON Вы можете прочитать здесь: https://www.hostinger.ru/rukovodstva/chto-takoe-json. Пока же для краткости скажем, что JSON-объекты записываются в фигурных скобках и состоят из элементов вида ключ-значение, разделённых запятыми. Между ключом и значением обязательно ставится двоеточие, за последним элементом ни в коем случае нельзя ставить запятую. Ключ — всегда записывается с использованием кавычек, то есть это всегда строка. JSON-массивы записываются в квадратных скобках, в которых через запятую перечисляются значения. За последним значением ни в коем случае не ставится запятая. Значениями могут быть числа, строки, другие объекты и массивы.

В данном случае корневым элементом является объект, в котором присутствуют восемь элементов:

"project":[],
"start":"startgame.qsp",
"converter":"C:\\Program Files\\QSP\\txt2gam.exe",
"player":"C:\\Program Files\\QSP\\qsp580\\qspgui.exe",
"save_temp_file": true,
"preprocessor":"Off",
"assets":[],
"scans":{}

Обязательно нужно указать элементы "project" и "start". Если по пути "C:\Program Files\QSP\qsp580\qspgui.exe" не расположен плеер, нужно так же указать элемент "player". Остальные элементы указывать не обязательно.

project

Значением элемента "project" является массив однотипных объектов ("билдов"), в которых присутствуют следующие элементы:

"module": "output_file.qsp",
"files": [],
"folders": [],

Элемент "module" содержит путь к конечному файлу ".qsp", который мы хотим получить.

Элементы "files" и "folders" содержат массивы однотипных объектов. И в том и в другом случае объекты содержат элементы "path", однако для "files" каждый элемент "path" содержит путь к конкретному файлу, из которого мы должны получить локации, а для "folders" каждый элемент "path" содержит путь к папке, и уже из этих папок выбираются файлы ".qsps".

"files": [
    {"path":"D:\\my\\projects\\01_меню.qsp-txt"},
    {"path":"game.qsp-txt"}
],
"folders": [
    {"path": "."},
    {"path": "D:\\my\\projects\\Вопросы"},
    {"path": "projects\\Вопросы"}
]

Из элементов "files" или "folders" должен присутствовать хотя бы один. Элемент "build" указывать обязательно. Элемент "postprocessors" можно не указывать.

start

Значением элемента "start" является путь к файлу, который необходимо запускать в плеере после билда. Это не обязательно должен быть один из собранных файлов, т.е. указать можно абсолютно любой файл ".qsp".

"start": "startgame.qsp"
converter

Значением элемента "converter" является путь к утилите, конвертирующей файлы формата qsps в файлы ".qsp". В QBSP уже встроен собственный конвертер, поэтому данный элемент можно не использовать.

"converter": "C:\\Program Files\\QSP\\txt2gam.exe"

Чтобы указать для конвертера дополнительные параметры, используйте подобны формат записи:

"converter": ["C:\\Program Files\\QSP\\txt2gam.exe", "-pMyPass -u"]
player

Значением элемента "player" является путь к плееру, в котором необходимо запустить игру (например, после сборки).

"player": "C:\\Program Files\\QSP\\Quest Navigator\\QuestNavigator.exe"
save_temp_file

Элемент "save_temp_file" разрешает оставлять промежуточные файлы после сборки (т.е. рядом с каждым собранным файлом ".qsp" будет лежать его исходник в формате qsps с раширением ".txt"). Ему можно назначать значения true и false. Значением по умолчанию является false.

"save_temp_file": true
preprocessor

Элемент "preprocessor" позволяет включать и выключать препроцессор при сборке файлов. Подробнее см. раздел Препроцессор. Ему можно назначать значения "On", "Off" и "Hard-off". Значением по умолчанию является "Off".

"preprocessor": "On"
assets

Данный элемент позволяет копировать различные ресурсы из разных источников в папку с билдом игры. Например, удобнее вести css-файлы рядом с исходниками игры, и запускать билд горячими клавишами, при этом нужно, чтобы свежие файлы css при сборке подтягивались в папку с готовой игрой. Вот для таких случаев и предназначен данный параметр.

Значением элемента "assets" является массив однотипных объектов ("ресурсов"), в которых присутствуют следующие элементы:

"output": "..\\[output]\\assets",
"files": [],
"folders": [],

Элемент "output" содержит путь к папке, в который мы хотим разместить перечисленные ресурсы.

Элементы "files" и "folders" содержат массивы однотипных объектов. И в том и в другом случае объекты содержат элементы "path", значениями которых являются пути к файлам и папкам, которые мы хотим скопировать. Пути нужно прописывать относительно файла "qsp-project.json".

"folders": [
    {"path": ".\\assets\\css"},
    {"path": ".\\assets\\img"}
],
"files": [
    {"path": ".\\assets\\css_1\\extras.css"}
]

При отсутствии элементов "files" и/или "folders" и элемента "output" копирование файлов производиться не будет.

[!danger] Внимание!!! Папки и файлы перезаписываются полностью! Будьте аккуратны и всегда сохраняйте резервные копии всех файлов.

[!warning] Учтите Если вы используете большое количество ресурсов в своей игре, копировать постоянно все не имеет смысла. Используйте ключ "output" при первом копировании, затем замените его на "output_" для тех папок и файлов, которые не требуется постоянно перезаписывать. Оставьте полное копирование только для тех ресурсов, с которыми работает постоянно.

scans

Элемент "scans" должен содержать объект, состоящий из трёх элементов: "location", "files", "folders". Из элементов "files" и "folders" должен присутствовать хотя бы один элемент.

"scans": {
    "location": "prv_file",
    "folders": [],
    "files": []
}

При наличии данного элемента в первый создаваемый "билд" будет встроена локация-функция, сгенерированная автоматически. Во время генерации в эту локацию будут прописаны пути ко всем существующим файлам, перечисленным в элементе "files", и ко всем файлам, которые находятся в папках, перечисленных в элементе "folders". Таким образом данная локация позволит проверять наличие того или иного файла прямо из кода вашей игры. Механизм, обеспечивающий проверку, уже встроен в эту локацию, и возвращает 1, если файл существует, и 0 — если файл не существует.

[!warning] Обратите внимание, В файле "qsp-project.json" все пути указываются относительно его расположения, но в генерируемой локации все пути будут сгенерированы относительно файла, прописанного в элементе "start".

[!warning] Так же обратите внимание, Что локация будет добавлена к первому собираемому модулю. Если это будет не модуль, прописанный в элементе "start", локация будет недоступна без подключения соответствующего модуля.

Пример проверки пути в QSP версии 5.8.0 и выше:

if @prv_file('res\img\ico\p.gif'):
    "Файл существует"
else:
    "Файл не существует"
end

Пути

Элементы "start","module", "path" и другие должны содержать абсолютные или относительные пути к файлам или папкам.

Относительные пути обсчитываются относительно расположения файла "qsp-project.json" и записываются по следующим правилам:

  1. Разделителем между папками/файлами в пути выступает обратный слэш, однако он должен быть проэкранирован дублированием: "lib\\easy.dialog\\mod.qsp"
  2. Путь не должен начинаться с разделителя (двойной обратный слэш):
    • так писать можно: "lib\\easy.dialog\\mod.qsp"
    • так писать нельзя: "\\lib\\easy.dialog\\mod.qsp"
  3. Указание на текущую папку (в которой лежит "qsp-project.json") производится через точку: "." - текущая папка
  4. Допускается указание текущей папки через точку и относительный путь от этой папки: ".\\lib" — вложенная в текущую папку папка "lib". Равносильно такой записи: "lib"
  5. Используя две точки можно указать папку выше текущей: ".." — папка, в которую вложена текущая
  6. Можно указывать папки на несколько уровней вверх, указывая через двойной бэкслэш две точки для каждого уровня:
    • "..\\.." — на два уровня выше текущей
    • "..\\..\\.." — на три уровня выше текущей
  7. Можно так же указывать папки относительно папок, расположенных выше текущей:
    • "..\\export" — папка "export", размещённая в одном каталоге с текущей.
    • "..\\..\\project\\other_game\\lib" — два уровня вверх, и от этой папки в "project\other_game\lib".

Пример проекта

В папке "[disdocs]\example_project" есть пример разобранного проекта. Почти все локации разнесены по отдельным файлам и разбросаны в разные папки по функционалу и тематике. Если считать "[disdocs]\example_project" за корень, то в корне размещён, помимо остальных папок, файл "qsp-project.json", который и определяет порядок сборки основного файла игры и файлов модулей.

Попробуйте сделать билд этого проекта, если сомневаетесь, что правильно поняли, как работает билдер. При сборке данного проекта в папке "[disdocs]\example_game" будут созданы основной файл игры "game.sam.qsp" и файлы различных модулей. Не забудьте прописать свой путь к плееру для правильного запуска. Если Вы используете режим Build and Run, файл "game.sam.qsp" будет запущен в плеере.

Проект адаптирован под плеер версии 5.8.0. В более старых версиях работать не будет. В 5.8.0 могут присутствовать ошибки в логике некоторых алгоритмов. Пока что я этим проектом не занимаюсь. Возможно, в будущем переведу его на новую версию движка и это будет полноценная демка.

Порядок сборки и запуска

Для удобства определены три режима работы QBST:

У каждого из режимов есть свои особенности.

"Build and Run" отличается тем, что в этом режиме обязательно собираются заново все файлы ".qsp", определённые инструкциями "qsp-project.json", затем, если в инструкциях неверно указан, или не указан, файл ".qsp", который следует запустить (элемент "start"), запускается самый первый определённый инструкциями собранный файл ".qsp".

"Build" отличается тем, что в этом режиме происходит новая сборка всех файлов ".qsp", определённых инструкциями "qsp-project.json", и больше ничего.

"Run" — в этом режиме не производится новая сборка файлов ".qsp", но запускается в плеере тот файл ".qsp", который указан в "qsp-project.json" в элементе "start", либо, если файл указан неверно или не указан совсем, любой выбранный файл ".qsp" и открытый во вкладке Sublime Text.

Сборка с помощью конвертера qsps_to_qsp или внешнего конвертера

Конвертер qsps_to_qsp является составной частью плагина, но начиная с версии 0.15 пакета QSP на Windows по умолчанию используется сторонний конвертер QGC, ускоряющий сборку проекта в несколько раз, особенно при больших объёмах исходных файлов.

Если вы хотите, чтобы ваша игра собиралась средствами встроенного конвертера qsps_to_qsp, укажите его в элементе "converter" файла "qsp-project.json":

"converter": "qsps_to_qsp"

Если указать в этом элементе путь к другой программе конвертеру (внешний конвертер), порядок сборки будет таким же.

При сборке содержимое файлов формата qsps добавляется в результирующий файл в следующем порядке:

  1. Файлы, перечисленные в массиве элемента "files", по порядку. Таким образом самыми первыми в файле ".qsp" оказываются локации из самого первого файла в элементе "files". Данной особенностью можно воспользоваться, если вам нужно строго определить первую локацию в игре, но порядок остальных вас не волнует. Просто выносите эту локацию в отдельный текстовый файл, а расширение ставите ".txt", или например ".start", затем указываете путь к файлу самым первым в массиве элемента "files".
  2. Файлы ".qsps", содержащиеся в папках, перечисленных в массиве элемента "folders" по порядку, независимо от уровня вложенности. Т.е. если у нас перечислены по порядку папки "1", "2" и "3", то сначала в результирующий файл добавятся локации из папки "1" и всех её вложенных папок, затем из папки "2" и всех её вложенных папок, затем из папки "3" и всех её вложенных папок. При этом первыми всегда добавляются файлы самого верхнего уровня, а потом с более глубоких уровней вложенности. Это особенно важно учитывать, если Вы используете препроцессор.
  3. Перед конвертированием, если включена обработка препроцессором, данные будут дополнительно обработаны встроенным в билдер препроцессором.
Сборка с помощью QSP Game Converter

Начиная с версии 0.15 пакета QSP для Sublime Text на Windows по умолчанию используется сторонний конвертер QGC, ускоряющий сборку проекта в несколько раз, особенно при больших объёмах исходных файлов. При сборке проекта с помощью QGC результат будет отличаться от описанного в разделе выше.

Если для отдельного модуля перечислены файлы в элементе "files", то самой первой локацией в модуле окажется локация первейшего из перечисленных файлов.

Если файлы в элементе "files" не перечислены, однако перечислены папки в элементе "folders", самым первым станет файл (и соответствующая локация) на верхнем уровне первейшей папки, или в первейшей из вложенных папок (см. пункт 2 в разделе выше).

Все остальные локации будут отсортированы конвертером по алфавиту.

Упрощённый запуск

Упрощённый запуск — это запуск игры без "qsp-project.json", а вернее "qsp-project.json" при этом будет создан автоматически. Для такого запуска необходимо, чтобы плеер лежал по адресу "C:\Program Files\QSP\qsp580\qspgui.exe".

Тогда, если исходник игры ".qsps" лежит не в папке с проектом другой игры, он будет запущен, как самостоятельная игра.

Подобный запуск удобен, когда вам нужно быстро протестировать небольшой фрагмент кода, а создавать целый проект под это нет смысла: вы можете просто написать исходник, сохранить его вне любого проекта игры, и запустить одним из вышеперечисленных способов.

Ошибки

Начиная с версии 0.10 некритические ошибки выводятся в консоль Sublime Text.

Ошибки в консоли могут иметь следующий вид, что значит, что ошибка в работе самого плагина, или в написанном исходнике игры:

Traceback (most recent call last):
  File "D:\my\GameDev\QuestSoftPlayer\projects\JAD\QBST\main.py", line 72, in <module>
    qsp.constructFile(build_files,exit_txt)
  File "D:\my\GameDev\QuestSoftPlayer\projects\JAD\QBST\function.py", line 44, in constructFile
    file.write(text)
  File "C:\Program Files\Python39\lib\encodings\cp1251.py", line 19, in encode
    return codecs.charmap_encode(input,self.errors,encoding_table)[0]
UnicodeEncodeError: 'charmap' codec can't encode character '\u2191' in position 29347: character maps to <undefined>

В данном случае ошибка показывает, что имеются проблемы с декодированием. Сообщайте о подобных ошибках письмом на почту aleksversus@mail.ru.

[!warning] ВНИМАНИЕ!!! Если вы столкнулись с тем, что билдер собирает вашу игру не полностью (т.е. некоторые локации не попадают в итоговую версию игры), выставьте параметр "save_temp_file" в значение "True" и посмотрите в промежуточном текстовом файле, какая локация последней попадает в итоговую версию. Где-то с 99% вероятностью следующая за ней локация написана неправильно (например, не закрыта кавычка или фигурная скобка), исправьте эту локацию в исходниках и затем снова запустите билд. Скрипт, равно как и утилита TXT2GAM, конвертирует игру любого объёма, хоть тысяча локаций, хоть тридцать тысяч, если они написаны соответственно формату qsps.

Препроцессор

Препроцессор - это набор команд предобработки исходного текста программы перед компиляцией. В нашем случае, до того, как мы сконвертируем файлы проекта в конечные файлы ".qsp", мы можем исключить из этих файлов некоторые строки, или рекомбинировать их.

Препроцессор написан с нуля, поэтому будут баги и логические ошибки в работе команд. Я ни разу не пользовался сторонними препроцессорами, поэтому могу изобрести велосипед там, где все гоняют на Kawasaki z900. Будьте аккуратны и делайте побольше коммитов.

При препроцессинге билдер работает в несколько раз медленнее.

Команды (директивы, инструкции)

Для удобства в препроцессор встроены два уровня инструкций: непосредственно команды препроцессора и специальные комментарии.

Специальные комментарии (спецкомментарии):

Команды препроцессора:

Некоторые синтаксические правила
  1. Все команды препроцессора являются комментариями QSP, и записываются как комментарии, то есть начиная с символа !.
  2. Команды препроцессора всегда записываются в одну строку, без отступов от начала строки!
  3. Все команды, имена меток, значения и т.д. пишутся в нижнем регистре.
  4. Имена меток и их значения необходимо писать без пробелов, двоеточий и любых видов кавычек. Лучше избегать спецсимволов.
  5. Использовать имена and, or, not для меток запрещено.
  6. Допустимо объявлять метку без указания значения: !@pp:var(layer) — объявляет метку layer.
  7. Специальные комментарии !@ и !@< должны быть однострочными! Хотя и могут размещаться в строке с другими операторами.
Некоторые особенности работы препроцессора
  1. При препроцессинге все команды препроцессора удаляются из конечного файла.
  2. Команды препроцессора будут выполняться даже в том случае, если они размещены внутри строковых значений QSP, если записаны согласно требованиям синтаксических правил: 
    *pl "Текстовое значение, разбитое на несколько строк
!@pp:if(layer):exclude
Данные строки будут исключены из конечного файла,
если метка layer была определена.
!@pp:endif
А эта строка останется в конечном файле"
  3. Специальные комментарии не будут обрабатываться, если они размещены внутри кавычек или фигурных скобок.
  4. Специальные комментарии будут обрабатываться даже если они идут в конце обычных комментариев. Чтобы отключить обработку спецкомментария в обычном комментарии, спецкомментарий можно расположить внутри кавычек или фигурных скобок.
  5. Все метки и их значения являются глобальными для всего проекта! Будьте внимательны при организации препроцессинга.
  6. НЕ ПОДДЕРЖИВАЕТСЯ ВЛОЖЕННОСТЬ УСЛОВИЙ. Не рекомендуется, но возможно комбинировать условия, используя ключевые слова and и not: 
    !@pp:if(layer and quest_navigator):include
"Если метки layer и quest_navigator определены, данная строка останется в конечном файле"
!@pp:endif
  7. Заранее определены метки "True" и "False", для которых установлены соответствующие булевые значения. Таким образом допустимо использовать команды if(build_em!=True) или if(build_em==False).
Включение препроцессора
  1. Включить препроцессор сразу для всего проекта можно, указав в "qsp-project.json" значение (режим "On"): 
    "preprocessor":"On",

    При этом абсолютно все файлы будут подвергаться препроцессингу, в т.ч. исходники модулей. Всё, что собирается проектом, будет обработано перед сборкой. Исключение составляют файлы, для которых препроцессинг отключается командой !@pp:off.

  2. Включить препроцессор только для одного файла можно командой: 
    !@pp:on

    Эту команду необходимо указать первой или второй строкой в обрабатываемом файле. Если препроцессор выключен выставлением режима "Hard-off", данная команда работать не будет.

Выключение препроцессора
  1. Для всего проекта можно использовать значение в "qsp-project.json" (режим "Off"): 
    "preprocessor":"Off",

    Данное значение является значением по умолчанию, поэтому его можно не указывать. При этом файлы, поставленные в обработку командой !@pp:on, всё равно будут обрабатываться препроцессором.

  2. Другое значение, полностью исключающее препроцессинг проекта (режим "Hard-off"): 
    "preprocessor":"Hard-off",

    Данное значение отключает препроцесинг абсолютно для всех файлов, даже если в файлах проставлены команды !@pp:on. В этом режиме у пользователей Windows сборка будет осуществляться с помощью конвертера "QGC.exe", что значительно ускорит получение конечного файла игры и запуск в плеере. Строго рекомендуется выставить данное значение, если пользуетесь Windows и ваша игра находится на стадии разработки.

  3. Из препроцессинга в режиме "`On" исключаются файлы, содержащие команду: 
    !@pp:off

    Эту команду необходимо указать первой или второй строкой в обрабатываемом файле.

Примеры

Подробный пример смотрите в файле "[disdocs]/example_project/[pp-test]/pptest.qsps".

!@pp:on
!@pp:var(layer=1)
# start
"Текст, который мы увидим на локации."
!@pp:if(layer==1):include
"Этот текст будет включён в конечный файл" & !@ а этот комментарий будет удалён
"Этот текст будет удалён" & !@< вместе с комментарием, потому что препроцессор работает
!@pp:endif
!@pp:if(layer==1):exclude
"Этот текст будет исключён из конечного файла" & ! и комментарий тоже
!@pp:endif
- start
!@pp:on
!@pp:var(layer=0)
# start
"Текст, который мы увидим на локации."
!@pp:if(layer==1):include
"Этот текст не будет включён в конечный файл"
!@pp:endif
!@pp:if(layer==1):exclude
"Этот текст не будет исключён из конечного файла" & ! и комментарий тоже
name=123 & !@< а вот эта строка кода будет удалена
!@pp:endif
- start

Подсветка синтаксиса QSP

Если Вы установили пакет QSP согласно инструкции, значит у вас уже установлена и работает подсветка кода QSP.

Автоматическое включение подсветки QSP-кода

Подсветка автоматически включается для файлов с расширениями ".qsps", ".qsp-txt", или ".txt-qsp". Если Вам нужно чтобы подсветка QSP-кода автоматически включалась для файлов с другими расширениями, пропишите в начале таких файлов строку:

QSP-Game

После слова Game можно поставить пробел и добавить ещё какой либо текст, например название игры или модуля.

Сниппеты

Сниппеты — это стандартные фрагменты кода, которые можно вставить, набрав ключевое слово, или часть строки кода, и нажав клавишу Tab. Переключаться между полями вставленного фрагмента также можно с помощью клавиши Tab.

Вот какие сниппеты вы можете использовать:

Сниппеты с привязкой к клавишам. Выделяем текст и нажимаем клавиши:

От себя могу порекомендовать сначала писать разметку в HTML-файле и затем переносить её в QSP. Это будет намного удобнее, к тому же почти все плагины, не будут действовать в QSP-коде.

Сочетания клавиш

Вспомогательные скрипты

Вспомогательные скрипты при установленном пакете QSP доступны из основного меню Sublime Text.

Откройте Tools → QSP tools для доступа к вспомогательным скриптам. Здесь вам доступны:

Автоподстановка

Другие фишки

Совместная разработка и контроль версий

Для более точных сведений о совместной разработке, вам необходимо ознакомиться с системами Git, github, и иными, более подробно. Здесь приводятся лишь основные моменты, с которых могут начать новички.

Контроль версий

Для контроля версий разрабатываемой игры необходимо установить на своём компьютере Git. Нижеследующие пункты взяты из инструкции https://htmlacademy.ru/blog/boost/frontend/git-console и ориентированы на пользователей Windows:

  1. Скачиваем установщик со страницы https://git-scm.com/download/win
  2. Устанавливаем программу, и при установке можем отметить или снять пункты "Windows Explorer integration":
    • "Git Bash Here" — пункт контекстного меню, который запустит косноль git bash в указанной папке
    • "Git GUI Here" — пункт контекстного меню, который запустит git с графическим интерфейсом в указанной папке
  3. Ещё при установке можно выбрать редактор по умолчанию. Я выбирал Sublime Text, и если вы уже установили Sublime Text и теперь впервые устанавливаете Git, то так же выбирайте его. Остальные пункты можно оставить без изменения.
  4. После установки Git можете добавить user.name и user.email для всех своих проектов через командную строку Windows или Git CMD, хотя в принципе это не обязательно. См. https://htmlacademy.ru/blog/boost/frontend/git-console

  5. Для пробы можете создать новый репозиторий. Для этого:

    • создайте любую пустую папку. Например, я храню все проекты на диске D: в папке "projects", поэтому для нового репозитория я создал папку "new_rep" ("D:\projects\new_rep").

    • откройте командную строку Windows или Git CMD и перейдите в указанный каталог с помощью команды "cd": cd "D:\projects\new_rep"

    • инициализируйте создание нового репозитория (данная команда создаст репозиторий, даже если в папке уже есть содержимое): git init

Собственно это всё, что нужно для контроля версий. В интернете есть много информации о работе с Git, и в принципе, если вам удобно вести контроль версий, используя консоль, то вам будет достаточно Git Bash. Кое-кому удобен даже Git GUI. Однако...

Sublime Merge

...если вы откроете один из файлов вашего проекта (репозитория) в Sublime Text, то в строке состояния вы увидите особую отметку, которая показывает число изменённых файлов проекта. Если вы добавите новый файл в тестовый репозиторий "new_rep", то эта отметка будет выглядеть, как "master|1|" — то есть 1 изменение в master-ветке проекта.

master-1

Дело в том, что Sublime Text автоматически подхватывает списки изменений из Git (условно говоря). Если вы щёлкнете по отметке об изменениях, Sublime Text предложит вам скачать Sublime Merge. Обязательно скачайте и установите, так как Sublime Merge в совокупности с Sublime Text является более удобным Git-клиентом.

По сути Git-клиент — это приложение, которое взаимодействует с системой Git, чтобы обеспечивать вам наглядное и удобное управление вашими репозиториями. Это что-то вроде внешнего GUI для Git.

Любое, или все изменения, можно закоммитить (зафиксировать в истории изменений), используя Sublime Merge. Для этого отмечаете нужные файлы и изменения в них, вводите текст коммита и нажимаете кнопку "Commit". Если вы ещё не указывали "user.name" и "user.email", Sublime Merge предложит вам сделать это.

Совместная разработка

Теперь, когда у вас есть все инструменты для контроля версий, осталось организовать совместную разработку. Я предлагаю воспользоваться системой github, как наиболее удобным для новичков хранилищем репозиториев.

Всем разработчикам придётся зарегистрировать по одному аккаунту на github. Один из разработчиков должен создать репозиторий для совместной разработки игры. При этом можно выбрать опцию "Private" (репозиторий будет доступен для просмотра вам и выбранным людям) или "Public" (репозиторий смогут просматривать все).

Разработчик, создавший репозиторий, должен выслать приглашения остальным разработчикам. Это делается в разделе GitHub "Settings" — "Manage Access"

Когда у всех разработчиков появляется доступ к репозиторию, каждому нужно зайти в Sublime Merge открыть меню "File" - "Clone Repository", откроется вкладка, в которой нужно указать URL репозитория и другие параметры доступа, например SSH-ключ.

Заключение

Данное руководство будет пополняться подробностями по мере возникновения вопросов.

Если у вас есть, что спросить, пишите на aleksversus@mail.ru, помогу чем смогу, а ваши вопросы помогут улучшить текст данного руководства.

Пишите обязательно, если у вас есть советы или замечания по работе пакета, и в частности билдера, по наполнению данного руководства и иные.

P.S.:

Видео о работе с JAD: Работа с JAD

Расширение Псевдопода для VS Code: QSP + VS Code QSP Game Converter от Alex (studentik), используемый как основной конвертер в пакете QSP: QGC

Новые версии плеера:

Поблагодарите отца-основателя платформы Байта: https://qsp.org/index.php?option=com_comprofiler&Itemid=20&user=66

Донаты

Донаты на развитие проекта и канала на ютубе: