qSpider версии 0.12.0

qSpider — это QSP-плеер с поддержкой полноценной браузерной HTML-вёрстки, то есть в нём можно использовать такой же HTML-код, как в обычном браузере. Более того существует два варианта плеера: браузерный вариант (запускается непосредственно в браузере, и потому данный вариант можно использовать, например, для публикации игр на QSP в интернете) и десктопный вариант (для стационарных компьютеров, запускается без браузера). Изначально qSpider разрабатывался для поддержки AeroQSP игр (так как технология flash прекратила своё существование), однако позже плеер был переориентирован в основном на поддержку классических игр. Тем не менее возможность запуска игр AeroQSP сохранилась, хотя для их полноценной работы может понадобиться небольшая правка.

Релиз последней версии плеера qSpider вы всегда можете найти по этой ссылке:

https://github.com/qspfoundation/qspider/releases

qSpider использует последнюю версию библиотеки qsplib, а значит игры, написанные на классический плеер с той же версией библиотеки, полностью совместимы с qSpider.

Версия qSpider 0.12.0 использует qsplib версии 5.8.0. О существенных изменениях, произошедших в новой версии библиотеки можно почитать в статье "Что нового в QSP 5.8.0".

Демонстрацию работы плеера можно посмотреть здесь: https://qspfoundation.github.io/qspider/.

Одна из представленных игр была написана для AeroQSP.

Отличия qSpider от Классического плеера

• Полноценная поддержка HTML, как в браузере, в том числе встраивание видео(!);
• Пути к ресурсам (картинкам/аудио файлам) регистрозависимы — то есть, если файл называется 'image.jpg', а в файле игры записано 'Image.jpg' или 'image.JPG', то плеер не сможет показать такую картинку;
• Для проигрывания аудио используются встроенные средства браузера, поэтому рекомендованный формат для плеера — mp3 как самый поддерживаемый (хорошая альтернатива — webm, у него меньше размер при том же качестве, но чуть хуже с поддержкой браузеров);
• Есть возможность пропуска wait (кликом по странице);
• Сохранения хранятся в браузере;
• Можно открывать игры, упакованные в zip-архив или в aqsp-архив.

Обратите внимание: для загрузки архива qsp-файл игры должен находится в корне архива (не в подпапке) и должен быть только один qsp-файл в корне (если используются дополнительные qsp-файлы, то они должны быть расположены в подпапках).

Как уже было отмечено выше, qSpider существует в двух вариантах: десктопный и браузерный (web-версия).

Десктопная версия

Основные отличия desktop-версии от web-версии

• возможность открыть qsp-файл из папки (в отличии от web-версии, где можно открыть только архив);
• открытие игры через drag-n-drop — перетаскивание файла игры на окно плеера;
• открытие игры через консоль (с помощью параметра --file);
• загрузка файла конфига из папки с игрой;
• дополнительная секция в файле конфига для настройки окна desktop-плеера;
• автоматическое обновление desktop-плеера при выходе новой версии.

Установка и запуск

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

• Windows x64
• MacOs
• Linux: deb-пакет, AppImage-пакет

Если в процессе установки на "Windows 7" программа выдаст ошибку похожую на эту:

— попробуйте установить webview2 вручную (скачать можно с этой страницы), а затем вновь запустите установку плеера.

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

Подключение плеера к QGen

Десктопную версию можно подключить к Quest Generator, однако из-за бага в используемой библиотеке сделать плеер напрямую совместимым с QGen не получилось. Пока что для запуска можно использовать простенький bat-файл:

SET QSPIDER=C:\Program Files\qSpider\qSpider.exe
SET DESTPATH=%~f1
start "" "%QSPIDER%" "--file=%DESTPATH%"

Чтобы создать bat-файл откройте блокнот, скопируйте в него данный код и сохраните получившийся файл с расширением ".bat".

Если у вас путь к qSpider отличается от стандартного, нужно поменять значение переменной QSPIDER в указанном коде. Далее нужно прописать путь к bat-файлу в QGen: в меню "Утилиты - Настройки" выбираете вкладку "Пути" и в поле "Путь к плееру" указываете путь до bat-файла.

Браузерная версия, или web-версия

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

Установка и запуск плеера на компьютере

Прежде всего вам необходимо скачать архив с web-версией плеера на компьютер: ссылка на скачивание. Содержимое архива распакуйте в любую папку, эта папка и будет местом расположения плеера.

Из-за ограничений безопасности плеер нельзя запустить просто открыв файл "index.html" в браузере.

Поэтому для запуска необходим локально запущенный сервер — можно использовать один из списка или же расширение хрома "Web Server for Chrome".

Дальнейшие инструкции ориентированы на использование расширения:

• устанавливаем "Web Server for Chrome"
• в адресной строке в хроме пишем "chrome://apps/" и выбираем в списке "Web Server";
• в открывшемся попапе выбираем папку, в которую распаковали плеер и запускаем сервер;
• там же в попапе будет ссылка на запуск сервера в окне браузера.

Установка плеера на github

1. Ознакомьтесь с порядком установки плеера на компьютер. Лучше выделить отдельную папку и распаковать браузерную версию плеера туда. Затем открыть подпапку "game" и удалить из неё ненужные файлы игр, и добавить свои, которые хотите разместить на гитхабе (см. раздел "добавление и удаление игр из списка".
2. Отредактируйте файл "game.cfg" так, чтобы в нём присутствовали все секции на каждую из размещаемых игр (см. раздел "Конфигурационный файл").
3. Откройте github в браузере, зайдите в свой профиль и создайте новый публичный репозиторий с именем "username.github.io" (внимание! Это важно! Впоследствии репозиторий нужно будет переименовать, но пока что он должен называться так), где "username" — это ваш логин (ник) на github.
4. В разделе "Code" репозитория нажмите кнопку "Add file" и выберите пункт "Upload files", откроется страница загрузки файлов на github.
5. Перетащите все распакованные файлы браузерной версии плеера в соответствующее поле на странице (в т.ч. папки "assets" и "game").
6. Теперь по адресу "https://username.github.io" станет доступна страничка с вашими играми, однако таким образом в одном аккаунте сможет существовать лишь одна подобная страница. Нужно переименовать созданный репозиторий, чтобы в дальнейшем вы смогли добавлять в аккаунт и другие репозитории с подобными страницами. Зайдите в созданный репозиторий на github, найдите раздел "settings", подраздел "general". В поле "Repository name" введите новое имя репозитория, например "mygame", нажмите кнопку "rename", и таким образом страница с игрой станет доступна по адресу "https://username.github.io/mygame" (соответственно вместо "username" будет ваш ник на гитхабе, а вместо "mygame" — название репозитория, которое вы только что ввели).

Добавление и удаление игр из списка

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

Демонстрационные игры лежат в подпапке "game", там же лежит конфигурационный файл "game.cfg"

Для добавления своей игры в список, нужно разместить игру в папке "game" одним из следующих способов:

• скопировать zip-архив с упакованной в него игрой в папку "game"
• скопировать папку с игрой в папку "game"
• если ваша игра имеет формат игры для AeroQSP, скопировать файл ".aqsp" вашей игры в папку "game"

Чтобы игра отобразилась в списке, необходимо отредактировать файл "game.cfg". Конфигурация каждой игры в файле начинается с заголовка секции [[game]], далее перечисляется несколько параметров:

• id — уникальный идентификатор игры (используется для сохранений);
• title — название игры (будет показано в заголовке плеера);
• description — необязательное краткое описание игры, аннотация;
• file — путь к файлу с игрой относительно файла "game.cfg", или внешняя ссылка (например file = "qspfoundation.github.io/qspider/game/skazka/skazka.qsp";
• mode — если ваша игра написана для AeroQSP, данному параметру назначается значение "aero".

Таким образом вам нужно добавить в файл "game.cfg" новую секцию для вашей игры примерно такого содержания:

[[game]]
id="уникальный-идентификатор-может-быть-и-просто-числом"
title="Название игры, отображаемое в виде заголовка на странице"
description="""Краткое описание игры, которое будет отображаться на странице со списком игр. Аннотация."""
file="путь к файлу игры/mygame.qsp"

Если вы убрали демонстрационные игры из папки "game", не забудьте удалить соответствующие секции из файла "game.cfg".

См. так же информацию в разделе "Конфигурационный файл"

Обратите внимание! Если вы указываете путь к внешнему файлу игры, нужно помнить о ряде ограничений, накладываемых браузером:

• с https страницы нельзя загрузить http ссылку;
• у сервера, где находится игра, должны быть настроены CORS заголовки.

Конфигурационный файл

Конфигурационный файл "game.cfg" определяет поведение плеера во время запуска той или иной игры. Данный файл размещается рядом с файлом ".qsp" запускаемой игры. Если игра упакована в архив ".zip" или ".aqsp", конфигурационный файл так же должен быть упакован в тот же самый архив рядом с файлом ".qsp" самого верхнего уровня. Для web-версии плеера можно написать один конфигурационный файл для всех игр и разместить его в папке "game", при этом конфигурационные файлы, которые находятся рядом с файлами игр, будут иметь приоритет над общим.

Конфигурационный файл (конфиг, конфиг-файл) состоит из секций, каждая из которых описывает одну игру. Таким образом в конфиге должна быть хотя бы одна секция, описывающая игру. Для десктопной версии плеера в конфиге указывается только одна секция игры.

Секция, описывающая игру, начинается с заголовка [[game]] и заканчивается там, где начинается следующая секция, описывающая игру, либо с концом файла. Заголовок секции пишется отдельной строкой. Структура конфиг-файла для трёх игр в браузерной версии плеера может выглядеть примерно так:

[[game]]
id = "7466df3b-4236-4668-b0df-2a70477da67b"
title = "Сказочка на ночь"
description = """описание первой игры"""
file = "skazka/skazka.qsp"

[[game]]
id = "30c8aebe-1690-4e6d-8b42-47c4be381748"
title = "Куртуазная Баллада"
description = """описание второй игры"""
file = "ballad/ballad.zip"

[[game]]
id = "c2cb4b5b-6a1c-482e-bb47-9ef207fb0dcd"
mode = "aero"
title = "Город туманов"
description = """описание третьей игры"""
file = "cityofmists.aqsp"

Как видно из приведённого примера, следом за заголовком секции идёт ряд параметров. Сначала записывается название параметра (ключ), затем ставится знак равенства, а после в кавычках указывается значение параметра. Если значение пишется в несколько строк, оно помещается в тройные кавычки.

Для описания игры используются следующие параметры, ключи:

• id — уникальный идентификатор игры (используется для сохранений, поэтому технически можно использовать любой набор символов, однако лучше сгенерировать собственный уникальный айди по образцу из примера, воспользовавшись онлайн-генератором https://www.uuidgenerator.net);
• title — название игры (будет показано в заголовке плеера и на вкладке браузера);
• description — необязательное краткое описание игры, аннотация;
• file — путь к файлу с игрой относительно файла "game.cfg", или внешняя ссылка (например file = "qspfoundation.github.io/qspider/game/skazka/skazka.qsp", для браузерной версии;
• mode — если ваша игра написана для AeroQSP, данному параметру назначается значение "aero".

Для десктопной версии плеера все параметры, кроме "id", не обязательны. Тем не менее рекомендуется их проставлять для удобства чтения конфигурационного файла. Для игр, написанных для AeroQSP, параметр "mode" обязателен.

Далее каждая секция игры может содержать подсекции, расширяющие возможности управления плеером и игрой.

Назначение горячих клавиш [game.hotkeys]

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

[game.hotkeys]
i = "Инвентарь"
"ctrl+shift+m" = "карта"
"up up down down left right left right b a" = "konami"

Для одиночного нажатия клавиш в качестве ключа указывается её обозначение:

i="Инвентарь"

Для того, чтобы указать одновременное нажатие нескольких клавиш, их обозначения перечисляются через "+" (плюс):

"ctrl+shift+m" = "карта"

Для того, чтобы задействовать последовательное нажатие клавиш, их обозначения перечисляются через пробел:

"up up down down left right left right b a" = "konami"

Можно использовать следующие обозначения:

Клавиши-модификаторы

• shift
• ctrl
• alt
• meta — для поддержки на macOs лучше использовать этот модификатор вместо ctrl

Специальные клавиши

• backspace
• tab
• enter
• capslock
• esc
• space
• pageup
• pagedown
• end
• home
• left
• up
• right
• down
• ins
• del
• plus
• f1 - f19

Остальные клавиши можно определять просто по имени a, $, *, или =.

Подключение дополнительных ресурсов [game.resources]

Есть возможность подключить к каждой отдельной игре дополнительные ресурсы. Например, собственные css-файлы, скрипты, шрифты и т.д. Для этого в секции игры нужно создать подсекцию с заголовком [game.resources]. Пример:

[game.resources]
styles = [
  "https://fonts.googleapis.com/css?family=Sofia",
  "styles.css"
]
scripts = [
  "script.js"
]
fonts = [
  ["Shelter", "fonts/shelter.woff2"]
]
icon = "icon.png"

Для подключения css-файлов используем ключ "styles", значением которого выступает список ссылок на необходимые нам файлы css. Это могут быть как внешние ссылки, так и пути относительно файла "game.cfg".

Список обязательно помещается в квадратные скобки! Его элементы разделяются запятыми. Отступы между элементами и скобками ни на что не влияют. За последним значением списка нельзя ставить запятую. Пример:

styles = ["skins/game.css","lewis.css"]

К основным элементам интерфейса добавлен атрибут data-qsp (например, data-qsp="main", data-qsp="actions" и т.д.), который позволит вам стилизовать данные элементы, или взаимодействовать с ними через скрипты.

Для подключения JavaScript используется ключ "scripts". Его значением так же выступает список ссылок на нужные скрипты. Поскольку нет возможности автоматически удалить JS код из памяти (при переключении на другую игру, например) — это надо делать вручную. Подробнее об этом можно почитать в статье Werewolf'а, посвящённой выходу qSpider 0.10.0.

Пример подключения скриптов:

scripts=["skins/js/game.js","skins/js/QspLibBrowserTest.js"]

Ключ "fonts" предназначен для подключения шрифтов к игре. Его значением является список, элементами которого являются другие списки — каждый такой отвечает за подключение одного шрифта. Пример подключения:

fonts=[
    ["GoodVibesPro","skins/fonts/good-vibes-pro.woff2"],
    ["AstronBold","skins/fonts/astron-bold.woff2"]
]

Как видите, в данном примере подключаются два шрифта. Здесь "GoodVibesPro" и "AstronBold" — это имена шрифтов, которые вы можете использовать при стилизации текста в вашей игре. Вы можете сами назначать эти имена. Вторым элементом для каждого из шрифтов указывается путь к конкретному файлу шрифта. Рекомендуемый формат — woff2, он поддерживается всеми современными браузерами. В сети полно онлайн конверторов из ttf в woff2.

Если у шрифта есть Bold, Italic и BoldItalic варианты в отдельных файлах, то подключение может выглядеть так:

fonts = [
  ["Shelter", "fonts/shelter.woff2"],
  ["Shelter", "fonts/shelter-bold.woff2", "bold"],
  ["Shelter", "fonts/shelter-italic.woff2", "normal", "italic"],
  ["Shelter", "fonts/shelter-bold-italic.woff2", "bold", "italic"]
]

Параметр "icon" дает возможность заменить иконку во вкладке браузера, так называемый "favicon". По умолчанию там находится логотип QSP. Пример использования:

icon="skins/gfx/doctor.png"

Поддержка игр AeroQSP [game.aero]

Как было сказано выше, для того, чтобы запускать AeroQSP-игру, нужно в секции игры выставить параметр "mode":

mode="aero"

Так же, если используется размер игры, отличающийся от дефолтного 800х600, необходимо добавить секцию [game.aero] с размерами:

[game.aero]
width = 504
height = 680

Смотрите так же раздел "Особенности работы игр AeroQSP на qSpider"

Настройка окна desktop-плеера [game.window]

Вы можете настраивать окно плеера в десктопной версии. Для этого в основной секции игры нужно объявить подсекцию с заголовком [game.window], и проставить необходимые параметры:

[game.window]
width = 1280
height = 960
resizable = true
minWidth = 1024
minHeight = 768

• width и height задают размер окна при старте игры;
• minWidth и minHeight дают возможность задать минимально возможные размеры, если игрок попытается изменить размеры окна;
• resizable — позволяет запретить изменения размера в принципе (автоматически включается в aero режиме).

Пример файла "game.cfg" для отдельной игры

[[game]]
id = "50458ae2-c07d-ca43-4a81-7bf480eedcf6"
title = "Вереница миров, или Выводы из закона Мёрфи"
description = """В Лаборатории Мерфи опять неприятности. Похищен опытный образец бета-аннигилятора, и похититель скрылся в Веренице Миров - сложной системе межпространственных порталов. Кому предстоит расхлёбывать это дельце? Ну конечно же вам, майор!"""
file = "merphy_law.qn.qsp"

[game.hotkeys]
b = "back.varriors"
"ctrl+shift+m"="карта"
"up up down down left right left right" = "konami"

[game.resources]
styles = ["skins/qspidergame.css"]
fonts=[
    ["GoodVibesPro","skins/fonts/good-vibes-pro.woff2"],
    ["AstronBold","skins/fonts/astron-bold.woff2"]
]
icon="skins/gfx/doctor.png"

[game.window]
width = 1280
height = 720
resizable = true
minWidth = 848
minHeight = 480

Особенности работы игр AeroQSP на qSpider

HTML-движок в флеш версии AeroQSP достаточно специфичен и не всегда совпадает с тем, как работает браузер, поэтому при запуске AeroQSP-игр на qSpider будут наблюдаться некоторые отличия в поведении игр.

Вот список особенностей и отличий:

• несколько игр использовали синтаксис, который поменялся в 5.8.0 (порядок аргументов в INSTR, ARRCOMP, ARRPOS), и в qSpider эти игры будут выдавать ошибку о несовпадении типов данных;
• в AeroQSP шрифты подключались в формате swf, использовать такой формат больше нет возможности, поэтому если игра использует нестандартные шрифты — их необходимо будет подключать через файл конфига в секции game.resources;
• в qSpider не поддерживаются эффекты pixels, h_blinds и v_blinds, остальные эффекты могут немного отличаться от того, как работала флеш-версия;
• не поддерживается переменная SCROLL_SPEED (впрочем, скорее всего нет игр, в которых она бы использовалась);
• обработка клика в флеше отличается от браузера — если на блоке нет обработчика, то он не перехватывает клик, даже если размещен поверх другого. В ряде игр это привело к тому, что неспрятанные панельки (пустые и не видимые) в qSpider блокируют клики по линкам под ними. Пример — игра "Новогодние сказки", где кнопка "Играть" почти полностью перекрыта пустой на этот момент панелькой действий. Лечится небольшими изменениями игры — отключением неиспользуемых панелей.
• в флеше тег center внутри таблиц растягивает таблицу на всю ширину, при этом еще размеры ячеек без явно указанной ширины в этом случае считаются не как в браузере. Чаще всего это заметно в действиях — для форматирования по умолчанию используется таблица, и если в названии действия использовать тег center, то в флеш-версии текст будет посередине панели, а в qSpider — нет. Лечится добавлением width=100% в такую таблицу. Не было возможности сделать это на уровне плеера, поскольку в ряде игр это ломало отображение.

Пример подключения

Для подключения AeroQSP игры через конфиг — необходимо в основной секции добавить mode="aero", и если используется размер экрана игры, отличающийся от дефолтного 800х600, — добавить секцию с размерами:

[[game]]
id = "c2cb4b5b-6a1c-482e-bb47-9ef207fb0dcd"
title = "Чашка кофе"
mode = "aero"
file = "aero_coffee.aqsp"

[game.aero]
width = 504
height = 680

При этом можно использовать как aqsp-архив, так и распаковать его и прописать ссылку на qsp-файл в папке.

Важное примечание от Werewolf'а:

Я не собираюсь развивать и поддерживать (кроме багфиксов) формат AeroQSP, поэтому не советую начинать новые игры с его использованием.

Заключение

Werewolf продолжает развивать и модернизировать qSpider, добавляя в него всё новые и новые возможности. Ждите обновлений, проводите побольше тестов свежих версий плеера и пишите побольше игр.

Обо всех ошибках и странностях в поведении при работе плеера просьба сообщать прямо на канал #qsp_dev на сервере интерактивной литературы в дискорде.

Данная статья собрана из статей, написанных Werewolf''ом для ifhub.club:

• qSpider - плеер для запуска QSP игр в браузере
• qSpider HotKeys - горячие клавиши
• qSpider 0.9.0 - список игр в конфиге
• qSpider 0.9.1 - загрузка игр из zip
• qSpider 0.10.0 - подключение дополнительных ресурсов
• qSpider 0.11.0 - поддержка игр в AeroQSP-формате
• qSpider 0.12.0 - полноценная desktop-версия

Post Scriptum

Данную статью вы можете найти так же и на других ресурсах:

• мой_сайт/qSpider 0.12.0
• medium/qSpider 0.12.0
• vk.com/qSpider 0.12.0