Skip to main content

Files

Overview

You and your players can upload files to the cloud. Global CDN, gzip, brotli compression and caching will allow you to get files fastly. By default, file uploads by players are disabled. You can enable it with the Allow players to upload files switch:

tip

Please be aware that downloading files allows unscrupulous players to upload prohibited materials. You can always remove these materials through the GamePush panel and disable this option at any time.

Upload file

+1 Request

To upload a file, you need to call the method with the desired file:

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

If you do not specify a file, a file selection window will open with the desired file type, by default *.

The file will then be uploaded to the server.

// Select files of any type
gp.files.upload();

// Select only .txt or .json files
gp.files.upload({ accept: '.txt, .json' });

When uploading, you can tag the file. Additionally, the file is assigned the UGC tag.

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

Upload events

// File uploaded successfully
gp.files.on('upload', (image) => {});

/**
* An error occurred while uploading
* @type {
* 'player_not_found' - player account has not been created yet
* 'project_not_found' - did not match the game ID or the game does not exist
* 'origin_not_allowed' - forbidden origin
* 'not_permitted' - it is forbidden to upload files
* 'internal_error' - something went wrong
* other - any error not related to the service
* }
*/
gp.files.on('error:upload', (error) => {});

Upload by URL

+1 Request

The method is similar to the previous one, only a URL is used instead of a file. To upload an file, you need to call the method with the desired file URL:

/**
* @type {string} url - desired file URL
*/
gp.files.uploadUrl({ url: 'https://mygame.com/myfile.txt' });

The method is mostly needed to upload screenshots and graphics via blob and Base64 Data URI.

Game engines allow you to save a screenshot of the canvas and return a blob link or Data URI. You can paste them into the url field and upload the file to the server.

// upload blob
gp.files.uploadUrl({ url: 'blob:https://example.com/123e4567-e89b-12d3-a456-426614174000' });

// upload base64 data URI
gp.files.uploadUrl({ url: 'data:file/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEsAAABLCAYAAAA4...' });

When uploading, you can tag the file. Additionally, the file is assigned the UGC tag.

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

Upload events

// File uploaded successfully
gp.files.on('upload', (image) => {});

/**
* An error occurred while uploading
* @type {
* 'empty_url' - no file URL specified
* 'player_not_found' - player account has not been created yet
* 'project_not_found' - did not match the game ID or the game does not exist
* 'origin_not_allowed' - forbidden origin
* 'not_permitted' - it is forbidden to upload files
* 'internal_error' - something went wrong
* other - any error not related to the service
* }
*/
gp.files.on('error:upload', (error) => {});

Upload content

+1 Request

The method is similar to the previous ones, only the content is used instead of a file or URL. To upload a file, you need to call the method with the desired file content and file name:

/**
* @type {string} filename - file name
* @type {string} content - file content
*/
gp.files.uploadContent({
filename: 'mysave.txt',
content: 'Hello world!'
});

The method is mostly needed to load saves, replays or other data in .txt or .json format.

// upload json
gp.files.uploadContent({
filename: 'replay-1771.json',
content: JSON.stringify({
teams: [...],
timeline: [...]
}),
});

// upload gamesave with any file name
gp.files.uploadContent({
filename: 'mysave.mygmsv',
content: mygame.save(),
});

When uploading, you can tag the file. Additionally, the file is assigned the UGC tag.

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

Upload events

// File uploaded successfully
gp.files.on('upload', (image) => {});

/**
* An error occurred while uploading
* @type {
* 'empty_filename' - file name not specified
* 'empty_content' - no file content specified
* 'player_not_found' - player account has not been created yet
* 'project_not_found' - did not match the game ID or the game does not exist
* 'origin_not_allowed' - forbidden origin
* 'not_permitted' - it is forbidden to upload files
* 'internal_error' - something went wrong
* other - any error not related to the service
* }
*/
gp.files.on('error:upload', (error) => {});

Load content

FREE

You can load the content of any file from the link in text format:

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

Load events

// content received successfully
gp.files.on('loadContent', (text) => {});

/**
* An error occurred while receiving
* @type {any error not related to the service}
*/
gp.files.on('error:loadContent', (error) => {});

Choose file

FREE

You can ask the player to choose a file without uploading it to the server. For example, to open a local save, load file content or other mechanics. The method will return the file and a temporary blob link to it.

gp.files.chooseFile();

// with a certain file type
const result = await gp.files.chooseFile('.txt, .mp4');

const {
/**
* File
* @type {File}
*/
file,
/**
* Temporary link to a file
* (only available from the current browser)
* @type {string}
*/
tempUrl
} = result;

Later you can upload this link or file to the server:

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

// file
gp.files.upload({ file });
// temporary link
gp.files.uploadUrl({ url: tempUrl });

File choosing events:

// File choosed
gp.files.on('choose', (result) => {});

/**
* An error occurred during choosing
* @type {
* 'cancelled' - the file picker window has been closed
* other - any error not related to the service
* }
*/
gp.files.on('error:choose', (error) => {});

Fetch files

+1 Request

Fetch files sorted by newest:

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

const {
/**
* Files array
* @type {FileInfo[]}
*/
items,
/**
* Check to see if you can upload more
* @type {boolean}
*/
canLoadMore
} = result;

Fetch files from a special collection by tag. The set of tags searches through AND: if you specify the tags replay and valentinesday - files that have both of these tags will be found:

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

Fetch files created by a specific player:

// own files
gp.files.fetch({ playerId: gp.player.id });

// another player
gp.files.fetch({ playerId: 16977410 });

Fetch a certain number of files at a time with the desired offset:

// First 100 files
gp.files.fetch({
limit: 100,
offset: 0,
});

// Files 101 to 200
gp.files.fetch({
limit: 100,
offset: 100,
});

Fetch events

// Successful fetch
gp.files.on('fetch', (result) => {});

/**
* Error while fetching
* @type {
* 'player_not_found' - player account has not been created yet
* 'project_not_found' - did not match the game ID or the game does not exist
* 'origin_not_allowed' - forbidden origin
* 'internal_error' - something went wrong
* other - any error not related to the service
* }
*/
gp.files.on('error:fetch', (error) => {});

Fetch more

+1 Request

Fetch the following batch of files with the desired settings:

// default behavior
const result = await gp.files.fetchMore();

const {
/**
* Files array
* @type {FileInfo[]}
*/
items,
/**
* Check to see if you can upload more
* @type {boolean}
*/
canLoadMore
} = result;

// next batch with replay tag,
// only uploaded by my player,
// load 10 items
gp.files.fetchMore({
tags: ['replay'],
playerId: gp.player.id,
limit: 10
});

Fetch events

// Successful fetch
gp.files.on('fetchMore', (result) => {});

/**
* Error while fetching
* @type {
* 'player_not_found' - player account has not been created yet
* 'project_not_found' - did not match the game ID or the game does not exist
* 'origin_not_allowed' - forbidden origin
* 'internal_error' - something went wrong
* other - any error not related to the service
* }
*/
gp.files.on('error:fetchMore', (error) => {});

File fileds

/**
* File ID
* @type {string}
*/
file.id

/**
* ID of the Player who posted the file or 0
* @type {number}
*/
file.playerId

/**
* File name with extension
* @type {string}
*/
file.name

/**
* Link
* @type {string}
*/
file.src

/**
* File size, Byte
* @type {number}
*/
file.size

/**
* Tags array
* @type {string[]}
*/
file.tags

Stay in Touch

Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.

GamePush Community Telegram: @gs_community.

For your suggestions e-mail: [email protected]

We Wish you Success!