Перейти к основному содержимому

Файлы

Обзор​

Вы и ваши игроки можете загружать файлы в облако. Глобальный CDN, сжатие gzip, brotli и кеширование позволят быстро получать файлы. По умолчанию загрузка файлов игроками запрещена. Вы можете включить её с помощью переключателя Разрешать игрокам загружать файлы:

tip

Имейте ввиду, что загрузка файлов дает возможность недобросовестным игрокам загружать запрещенные материалы. Вы всегда можете удалить эти материалы через панель GamePush и в любой момент отключить эту опцию.

Загрузить файл​

Для загрузки файла вам нужно вызвать метод с нужным файлом:

/**
 * @type {File} file - desired file
 */
gp.files.upload({ file: myFile });

Если не передать файл - откроется окно выбора файла с нужным типом файлов, по-умолчанию *.

Затем файл будет загружен на сервер.

// Выбирать файлы любого типа
gp.files.upload();

// Выбирать файлы только .txt или .json
gp.files.upload({ accept: '.txt, .json' });

При загрузке вы можете разметить файл тегами. Дополнительно файлу присваивается тег UGC.

gp.files.upload({
    tags: [
        'replay',
        'level7',
        'valentinesday',
    ]
});

События загрузки

// файл успешно загружен
gp.files.on('upload', (image) => {});
/**
 * Во время загрузки произошла ошибка
* @type {
*     'player_not_found' - аккаунт игрока еще не был создан
*     'project_not_found' - не совпал ID игры или игра не существует
*     'origin_not_allowed' - запрещенный сайт
*     'not_permitted' - запрещено загружать файлы
*     'internal_error' - что-то пошло не так
*      другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:upload', (error) => {});

Загрузить по URL​

Метод аналогичный предыдущему, только вместо файла используется URL. Для загрузки файла вам нужно вызвать метод с нужным URL файла:

/**
 * @type {string} url - нужный URL файла
 */
gp.files.uploadUrl({ url: 'https://mygame.com/myfile.txt' });

Метод по большей части нужен для загрузки файлов через blob.

Игровые движки позволяют сохранять скриншот холста (canvas) и возвращать ссылку на blob или Data URI. Вы можете вставить их в поле URL и загрузить файл на сервер.

// загрузка blob
gp.files.uploadUrl({ url: 'blob:https://example.com/123e4567-e89b-12d3-a456-426614174000' });

// загрузка base64 data URI
gp.files.uploadUrl({ url: 'data:file/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEsAAABLCAYAAAA4...' });

При загрузке вы можете разметить файл тегами. Дополнительно файлу присваивается тег UGC.

gp.files.uploadUrl({
    url: 'https://mygame.com/myfile.txt',
    tags: [
        'replay',
        'level7',
        'valentinesday',
    ]
});

События загрузки

// файл успешно загружен
gp.files.on('upload', (image) => {});

/**
 * Во время загрузки произошла ошибка
* @type {
*     'empty_url' - не указан URL файла
*     'player_not_found' - аккаунт игрока еще не был создан
*     'project_not_found' - не совпал ID игры или игра не существует
*     'origin_not_allowed' - запрещенный сайт
*     'not_permitted' - запрещено загружать файлы
*     'internal_error' - что-то пошло не так
*      другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:upload', (error) => {});

Загрузить контент​

Метод аналогичный предыдущим, только вместо файла или URL используется содержимое. Для загрузки файла вам нужно вызвать метод с нужным содержимым файла и названием файла:

/**
 * @type {string} filename - название файла
 * @type {string} content - содержимое файла
 */
gp.files.uploadContent({
    filename: 'mysave.txt',
    content: 'Hello world!'
});

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

// загрузка json
gp.files.uploadContent({
    filename: 'replay-1771.json',
    content: JSON.stringify({
        teams: [...],
        timeline: [...]
    }),
});

// загрузка сохранения с любым именем файла
gp.files.uploadContent({
    filename: 'mysave.mygmsv',
    content: mygame.save(),
});

При загрузке вы можете разметить файл тегами. Дополнительно файлу присваивается тег UGC.

gp.files.uploadContent({
    url: 'https://mygame.com/myfile.txt',
    tags: [
        'replay',
        'level7',
        'valentinesday',
    ]
});

События загрузки

// файл успешно загружен
gp.files.on('upload', (image) => {});

/**
 * Во время загрузки произошла ошибка
* @type {
*     'empty_filename' - не указано имя файла
*     'empty_content' - не указан контент файла
*     'player_not_found' - аккаунт игрока еще не был создан
*     'project_not_found' - не совпал ID игры или игра не существует
*     'origin_not_allowed' - запрещенный сайт
*     'not_permitted' - запрещено загружать файлы
*     'internal_error' - что-то пошло не так
*      другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:upload', (error) => {});

Получить контент​

Вы можете скачать контент любого файла по ссылке в текстовом формате:

const content = await gp.files.loadContent('https://mygame.com/myfile.json');

События получения

// контент успешно получен
gp.files.on('loadContent', (text) => {});

// Во время получения произошла ошибка
// @type {любая ошибка не связанная с сервисом}

gp.files.on('error:loadContent', (error) => {});

Выбрать файл​

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

gp.files.chooseFile();

// с определенным типом
const result = await gp.files.chooseFile('.txt, .mp4');

const {
    /**
     * Файл
     * @type {File}
     */
    file,
    /**
     * Временная ссылка на файл
     * (доступна только с текущего браузера)
     * @type {string}
     */
    tempUrl
} = result;

В последствии вы можете загрузить эту ссылку или файл на сервер:

const { file, tempUrl } = await gp.files.chooseFile();

// файл
gp.files.upload({ file });
// временная ссылка
gp.files.uploadUrl({ url: tempUrl });

События выбора файла:

// Файл выбран
gp.files.on('choose', (result) => {});

/**
* Во время выбора возникла ошибка
* @type {
* 'cancelled' - окно выбора было закрыто
* другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:choose', (error) => {});

Получение файлов​

Получить файлы отсортированные по новизне:

const result = await gp.files.fetch();

const {
    /**
     * Массив файлов
     * @type {FileInfo[]}
     */
    items,
    /**
     * Проверка на возможность подгрузить еще
     * @type {boolean}
     */
    canLoadMore
} = result;

Получить файлы из специальной коллекции по тегу. Набор тегов ищет через AND: если указать теги replay и valentinesday - будут найдены файлы у которых есть оба этих тега:

gp.files.fetch({
    tags: ['replay', 'valentinesday']
});

Получить файлы созданные определенным игроком:

// собственные файлы
gp.files.fetch({ playerId: gp.player.id });

// другой игрок
gp.files.fetch({ playerId: 16977410 });

Получить определенное количество файлов за раз с нужным смещением:

// Первые 100 файлов
gp.files.fetch({
    limit: 100,
    offset: 0,
});

// Файлы со 101 по 200
gp.files.fetch({
    limit: 100,
    offset: 100,
});

События получения файлов

// Успешное получение
gp.files.on('fetch', (result) => {});

/**
* Ошибка при получении
* @type {
*     'player_not_found' - аккаунт игрока еще не был создан
*     'project_not_found' - не совпал ID игры или игра не существует
*     'origin_not_allowed' - запрещенный сайт
*     'internal_error' - что-то пошло не так
*      другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:fetch', (error) => {});

Подгрузить еще​

Загрузить следующую партию файлов с нужными настройками:

// поведение по умолчанию
const result = await gp.files.fetchMore();

const {
    /**
     * Массив файлов
     * @type {FileInfo[]}
     */
    items,
    /**
     * Проверка на возможность подгрузить еще
     * @type {boolean}
     */
    canLoadMore
} = result;

// следующая партия с тегом replay,
// только загруженных моим игроком,
// загружать по 10 штук
gp.files.fetchMore({
    tags: ['replay'],
    playerId: gp.player.id,
    limit: 10
});

События подгрузки

// Успешная подгрузка
gp.files.on('fetchMore', (result) => {});

/**
* Ошибка при подгрузке
* @type {
*     'player_not_found' - аккаунт игрока еще не был создан
*     'project_not_found' - не совпал ID игры или игра не существует
*     'origin_not_allowed' - запрещенный сайт
*     'internal_error' - что-то пошло не так
*      другое - любая ошибка не связанная с сервисом
* }
*/
gp.files.on('error:fetchMore', (error) => {});

Поля файла​

/**
* ID файла
* @type {string}
*/
file.id

/**
* ID Игрока, опубликовавшего файл или 0
* @type {number}
*/
file.playerId

/**
* Имя файла с расширением
* @type {string}
*/
file.name

/**
* Ссылка
* @type {string}
*/
file.src

/**
* Размер файла, Байт
* @type {number}
*/
file.size

/**
* Массив тегов
* @type {string[]}
*/
file.tags

Оставайтесь на связи​

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!