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

Файлы

Обзор

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

tip

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

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

+1 Request

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

/**
* @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

+1 Request

Метод аналогичный предыдущему, только вместо файла используется 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) => {});

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

+1 Request

Метод аналогичный предыдущим, только вместо файла или 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) => {});

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

FREE

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

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

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

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

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

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

Выбрать файл

FREE

Вы можете предолжить игроку выбрать файл без загрузки на сервер. Например для открыть локальное сохранение, загрузить контент файла или другие механики. Метод вернет файл и временную 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) => {});

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

+1 Request

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

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) => {});

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

+1 Request

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

// поведение по умолчанию
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]

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