[[help:classic_qsp|Назад: Классический плеер]]

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

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

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

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

Обучиться писать HTML-разметку можно, например, здесь:
  * [[https://htmlacademy.ru|htmlacademy.ru]].
  * Справочник актуальных HTML-тегов, CSS-свойств, самоучители и прочее: [[http://htmlbook.ru|htmlbook.ru]]

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

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

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

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

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

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

  * Поиграть в QSP-игры без установки плеера: **[[https://qspfoundation.github.io/qspider/|qspfoundation.github.io/qspider]]**. **qSpider** откроется в браузере и прямо в нём вы сможете просмотреть каталог игр, представленных на сайте qsp.org, добавить любую из них на полку и поиграть.
  * **[[https://aleksversus.github.io/merphy_law/|"Вереница миров"]]** — стандалон сборка игры онлайн на плеере **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-плеера при выходе новой версии.

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

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

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

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

[[https://i.ibb.co/8z8MHyp/image.png|{{https://i.ibb.co/8z8MHyp/image.png?500|Экран QSP}}]]

В этом случае попробуйте установить webview2 вручную (скачать можно с [[https://developer.microsoft.com/en-us/microsoft-edge/webview2/|этой страницы]]), а затем вновь запустите установку плеера.

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

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

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

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

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

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

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

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

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

Прежде всего вам необходимо скачать архив "''qspider-player-standalone.zip''" с web-версией плеера со [[https://github.com/qspfoundation/qspider/releases|страницы релизов]]. Содержимое архива распакуйте в любую папку, эта папка и будет местом расположения плеера.

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

Поэтому для запуска необходим локально запущенный сервер — можно использовать один из [[https://gist.github.com/willurd/5720255|списка]].

Более простой способ запустить веб-версию — использовать VS Code с расширением Live Server: * Скачайте и установите бесплатный [[https://code.visualstudio.com|VS Code]].
  * Запустите его по окончании установки.
  * Установите на него расширение [[https://github.com/ritwickdey/vscode-live-server-plus-plus|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-версией плеера со [[https://github.com/qspfoundation/qspider/releases|страницы релизов]].

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

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

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

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

Есть видео на тему: [[https://www.youtube.com/watch?v=bEjRzTDsPp4&t=3029s|Размещение игры онлайн с использованием GitHub]], однако там создание страницы производится другим способом, без создания ветки "gh-pages".

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

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

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

В чём смысл.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  * Игра обязательно должна быть написана в формате **[[help:txt2gam|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: ====

  * [[help:qspider_gamecfg|Конфигурационный файл]]
  * [[help:qspider_aeroqsp|Особенности запуска и работы игр AeroQSP на qSpider]]
  * [[help:qspider_interface|Взаимодействие с интерфейсом]]
  * [[help:qspider_themes|Темы оформления]]
  * [[help:qspider_spectags|Специальные теги]]
  * [[help:qspider_inclib|Встроенная библиотека]]
  * [[help:qspider_standalone|Стандалон-сборка игры на qSpider]]

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

  * [[https://ifhub.club/2020/10/11/qspider-pleer-dlya-zapuska-qsp-igr-v-brauzere.html|qSpider - плеер для запуска QSP игр в браузере]]
  * [[https://ifhub.club/2020/10/11/qspider-hotkeys.html|qSpider HotKeys - горячие клавиши]]
  * [[https://ifhub.club/2020/10/18/qspider-090.html|qSpider 0.9.0 - список игр в конфиге]]
  * [[https://ifhub.club/2020/11/01/qspider-091.html|qSpider 0.9.1 - загрузка игр из zip]]
  * [[https://ifhub.club/2021/05/23/qspider-0100.html|qSpider 0.10.0 - подключение дополнительных ресурсов]]
  * [[https://ifhub.club/2021/10/22/qspider-0110.html|qSpider 0.11.0 - поддержка игр в AeroQSP-формате]]
  * [[https://ifhub.club/2022/02/06/qspider-0120.html|qSpider 0.12.0 - полноценная desktop-версия]]
  * [[https://ifhub.club/2022/10/05/qspider-0130.html|qSpider 0.13.0]]
  * [[https://ifhub.club/2024/01/03/qspider-100.html|qSpider 1.0.0 — Полка игр и Каталог]]
  * [[https://ifhub.club/2024/01/10/qspider-101.html|qSpider 1.0.1]]
  * [[https://ifhub.club/2024/02/11/qspider-110.html|qSpider 1.1.0 — Стандалон]]
  * [[https://ifhub.club/2024/07/15/qspider-120.html|qSpider 1.2.0 — китайский язык]]
  * [[https://ifhub.club/2024/09/29/qspider-130.html|qSpider 1.3.0 — переход на библиотеку QSP 5.9.0]]

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

  * [[https://qsp.org/index.php?option=com_agora&task=topic&id=1291&Itemid=57|Обсуждение плеера на форуме QSP.org]]
  * [[https://vk.com/@qsplayer-qspider-v-0120-svodnaya-statya|Сводная статья по версии 0.12.0 в вк]]

[[help:qgen|Вперёд: Quest Generator]]