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

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


Боковая панель

help:qspider

Назад: Классический плеер

qSpider — плеер с поддержкой HTML

Статья актуализирована для qSpider версии 1.3.1.

Общие сведения

qSpider — это QSP-плеер с поддержкой полноценной браузерной HTML-вёрстки, то есть в нём можно использовать такой же HTML-код, как в обычном браузере.

Обучиться писать HTML-разметку можно, например, здесь:

  • Справочник актуальных HTML-тегов, CSS-свойств, самоучители и прочее: htmlbook.ru

Cуществует два варианта плеера:

  • десктопный вариант (для стационарных компьютеров, запускается без браузера);
  • браузерный вариант (запускается непосредственно в браузере, и потому данный вариант можно использовать, например, для публикации игр на QSP в интернете).

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

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

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

Демонстрацию работы плеера можно посмотреть здесь:

  • Поиграть в QSP-игры без установки плеера: qspfoundation.github.io/qspider. qSpider откроется в браузере и прямо в нём вы сможете просмотреть каталог игр, представленных на сайте qsp.org, добавить любую из них на полку и поиграть.
  • "Вереница миров" — стандалон сборка игры онлайн на плеере qSpider.

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

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

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

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

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

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

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

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

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

У пользователей устаревших операционных систем при установке могут возникнуть ошибки, похожие на эту:

Экран QSP

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

Если ошибка не исправилась, воспользуйтесь браузерной версией плеера.

Запуск плеера из Quest Generator

Десктопный qSpider запускается из Quest Generator точно так же, как и классический плеер. Достаточно прописать путь к qSpider в настройках QGen. Это делается через меню "Утилиты → Настройки" на вкладке "Пути" в поле "Путь к плееру".

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

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

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

  • запуск QSP-файлов и текстовых qsps-файлов с компьютера возможен, но к игре не подключаются ресурсы и файлы конфигурации;
  • игры могут иметь общий файл конфигурации, который загружается из папки "game"; приоритет у индивидуальных файлов конфигураций;
  • можно открыть файл со списком игр или отдельную игру по ссылке (см. раздел "Запуск игр по ссылке").

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

Стандалон-сборка

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

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

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

Более простой способ запустить веб-версию — использовать VS Code с расширением Live Server: * Скачайте и установите бесплатный VS Code.

  • Запустите его по окончании установки.
  • Установите на него расширение Live Server. Для этого:
    • Откройте меню и выберите пункты File → Preferences → Extensions, или нажмите сочетание клавиш Ctrl + Shift + X
    • Слева появится поисковая строка для расширений, введите в неё текст: "Live Server".
    • В списке найденных расширений будет расширение "Live Server", установите его, нажав кнопку Install.
    • Когда расширение установится, в правом нижнем углу VS Code появится кнопка "Go Live"
  • В VS Code откройте папку с распакованной браузерной версией плеера. Меню "File → Open Folder..."
  • Выберите из списка файлов в папке файл index.html.
  • Нажмите кнопку Go Live.

Если вы всё сделали правильно, в браузере откроется qSpider.

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

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

Плеер с полкой игр

Порядок установки веб-версии плеера с полкой игр мало чем отличается от установки стандалон варианта для веб-версии. Единственное отличие заключается в том, что вам нужно скачать архив "qspider-player.zip" с web-версией плеера со страницы релизов.

Далее всё делаем точно так же, как в выше изложенной инструкции.

После запуска сервера в браузере откроется qSpider с полкой игр. Эта версия qSpider ничем не будет отличаться от версии, доступной по ссылке qspfoundation.github.io/qspider.

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

  1. Ознакомьтесь с порядком установки плеера на компьютер. Лучше выделить отдельную папку и распаковать браузерную версию плеера туда. Затем открыть подпапку "game" и добавить в неё свою игру, которую хотите разместить на гитхабе.
  2. Отредактируйте файл "game.cfg" так, чтобы в нём присутствовали все необходимые секции настроек (см. статью "Конфигурационный файл").
  3. Откройте github в браузере, зайдите в свой профиль и создайте новый публичный репозиторий с любым именем, для примера: "qspider-game".
  4. В разделе "Code" нажмите кнопку "Main".
  5. В открывшемся окошке в поле "Find or create branch…" введите название новой ветки "gh-pages", а затем нажмите на кнопку "Create branch: gh-pages from main".
  6. Обязательно переключитесь на ветку "gh-pages", если это не произошло автоматически. Вместо кнопки "main" у вас должна появиться кнопка "gh-pages".
  7. В этом же разделе найдите и нажмите кнопку "Add file" и выберите пункт "Upload files", откроется страница загрузки файлов на github.
  8. Перетащите все распакованные файлы браузерной версии плеера в соответствующее поле на странице. В т.ч. пять папок: "aero", "assets", "game", "locales", "themes".
  9. Теперь по адресу "https://username.github.io/qspider-game" станет доступна страничка с вашей игрой. (Соответственно вместо "username" будет ваш ник на гитхабе, а вместо "qspider-game" — название репозитория, который вы только что создали).

Есть видео на тему: Размещение игры онлайн с использованием GitHub, однако там создание страницы производится другим способом, без создания ветки "gh-pages".

Запуск игр по ссылке

ВНИМАНИЕ!!! Возможность запуска игр по ссылке ограничена — на сервере, на котором лежит игра, должна быть включена поддержка CORS.

Важно! Запускать сторонние игры может только версия плеера со встроенным каталогом игр.

В чём смысл.

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

Например, qSpider у нас установлен по адресу "https://qspfoundation.github.io/qspider", а игра лежит по адресу "https://aleksversus.github.io/merphy_law/game/merphy_law.qsp".

Мы можем ввести в адресную строку, или вставить в атрибут href гиперссылки следующий адрес, и он откроет нашу игру в указанном "плеере" qSpider:

https://qspfoundation.github.io/qspider/?game=https://aleksversus.github.io/merphy_law/game/merphy_law.qsp

При этом игра будет загружена на полку игр.

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

Таким же образом можно загружать игры целым пакетом, сославшись на один конфигурационный файл (конфиг), в котором описаны сразу несколько игр:

https://qspfoundation.github.io/qspider/?config=https://aleksversus.github.io/QSP-storage/game/game.cfg

После загрузки всех игр на полку, самая первая игра в конфиге будет запущена автоматически.

А ещё можно упаковать несколько игр в zip-архив, поместить в корень архива конфигурационный файл, и сделать ссылку на архив — все игры из архива тоже будут загружены на полку.

Запуск игр из каталога по ссылке

Игру, опубликованную в каталоге игр qsp.org, можно запускать по прямой ссылке. Она автоматически добавится на полку и запустится. Чтобы получить такую ссылку:

  • откройте страницу с игрой на сайте qsp.org
  • скопируйте адрес из адресной строки. Должно получиться что-то вроде этого:
    https://qsp.org/index.php?option=com_sobi2&sobi2Task=sobi2Details&catid=6&sobi2Id=84&Itemid=55
  • Найдите в этом адресе часть, начинающуюся с sobi2Id. Число после знака равенства является идентификатором игры в каталоге. Например, для ссылки выше это число 84.
  • Теперь возьмите полную ссылку к онлайн-версии плеера, и укажите через вопросительный знак параметр catalogId и идентификатор игры в каталоге. Получится вот такая ссылка:
    https://qspfoundation.github.io/qspider/?catalogId=84

Запуск игр в формате текстовых файлов

Для того, чтобы писать игры QSP в текстовом редакторе, был разработан специальный формат для текстовых файлов под названием TXT2GAM. Ещё его можно называть "формат QSPS" по названию общепринятого расширения ".qsps", которое таким файлам назначается. Подробное описание формата вы найдёте в статье "TXT2GAM. Краткое руководство".

Обычно игры, написанные в этом формате, требуется сконвертировать в файл игр QSP с помощью специальной утилиты TXT2GAM. Однако qSpider позволяет запускать такие игры прямо из qsps-файлов, не конвертируя их.

Требования к играм, написанным в виде текстовых файлов:

  • Игра обязательно должна быть написана в формате TXT2GAM (QSPS);
  • Файл должен иметь расширение ".qsps";
  • Файл должен быть сохранён в кодировке utf-8 (рекомендуется), или utf-16le.

Quest Generator позволяет экспортировать игру в qsps-файл именно в кодировке utf-16le, однако предпочтительнее использовать кодировку utf-8, поскольку в этом случае файл будет гораздо меньше по объёму.

Стандартные горячие клавиши

  • ctrl+r - перезапуск игры (Заново)
  • ctrl+s - меню сохранения
  • ctrl+o - меню загрузки
  • f5 - quicksave (быстрое сохранение)
  • f9 - quickload (быстрая загрузка)
  • PageUp - увеличить громкость
  • PageDown - уменьшить громкость
  • Home - выключить звук
  • End - включить звук
  • Space - единственное действие
  • 1 ... 9 - действия с 1 по 9 по порядку.

Список полезных ссылок о qSpider

в QSP-WIKI:

на IFHUB (краткая история версий)

Другие ссылки

help/qspider.txt · Последние изменения: 2024/10/15 10:08 — aleks_versus