Документация QSP
Сайт Форум

Эта страница только для чтения. Вы можете посмотреть исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
[[help:classic_qsp|Назад: Классический плеер]]

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

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

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

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

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

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

Изначально **qSpider** разрабатывался для поддержки AeroQSP-игр (так как технология flash прекратила своё существование), однако позже был переориентирован в основном на поддержку классических игр. Возможность запуска игр AeroQSP сохранилась, хотя для их полноценной работы может понадобиться небольшая правка.

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

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

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

Демонстрацию работы плеера можно посмотреть здесь:
    * [[https://qspfoundation.github.io/qspider|https://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 (кликом по странице);
	* Сохранения хранятся в браузере;
	* Можно открывать игры, упакованные в zip-архив или в aqsp-архив;
	* Можно открывать игры в виде текстового файла формата **TXT2GAM** (**QSPS**) (см. ниже раздел "Запуск игр в формате текстовых файлов").

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

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

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

	* возможность открыть QSP-файл или qsps-файл из папки (в отличии от web-версии, где можно открыть только архив);
	* открытие игры через drag-n-drop — перетаскивание файла игры на окно плеера;
	* открытие игры через консоль;
	* загрузка файла конфига из папки с игрой;
	* дополнительная секция в файле конфига для настройки окна 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|списка]] или же расширение хрома [[https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb|"Web Server for Chrome"]].

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

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

==== Установка плеера на 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.
	- Перетащите все распакованные файлы браузерной версии плеера в соответствующее поле на странице (в т.ч. папки "''assets''" и "''game''").
	- Теперь по адресу "''%%https://username.github.io/qspider-game%%''" станет доступна страничка с вашими играми. (Соответственно вместо "username" будет ваш ник на гитхабе, а вместо "qspider-game" — название репозитория, который вы только что создали).

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

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

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

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

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

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

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

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

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

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

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

См. так же информацию в статье [[help:qspider_gamecfg|"Конфигурационный файл"]].

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

	* с https страницы нельзя загрузить http ссылку;
	* у сервера, где находится игра, должны быть настроены [[https://developer.mozilla.org/ru/docs/Web/HTTP/CORS|CORS заголовки]].

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

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

В чём смысл.

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

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

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

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

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

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

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

<sxh html>
https://qspfoundation.github.io/qspider/?config=https://qspfoundation.github.io/qspider/game/game.cfg
</sxh>

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

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

Для того, чтобы иметь возможность писать игры 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+s'' - меню сохранения
	* ''ctrl+o'' - меню загрузки
	* ''f5'' - quicksave (быстрое сохранение)
	* ''f9'' - quickload (быстрая загрузка)

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

==== в QSP-WIKI: ====

	* [[help:qspider_gamecfg|Конфигурационный файл]]
	* [[help:qspider_aeroqsp|Особенности запуска и работы игр AeroQSP на 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://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]]
Документация QSPСайтФорум

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

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

Инструменты страницы

Документация QSP
Сайт Форум
