Player state

Set and save player progress. Player progress is represented by fields that are explicitly set in the control panel.

Player properties

Player properties FREE:

JavaScript

// ID
gp.player.id;
// Score
gp.player.score;
// Name
gp.player.name;
// Avatar link
gp.player.avatar;
// Stub – is the player default or the data in its model differs from the default
gp.player.isStub;
// Player fields
gp.player.fields;

Unity

// ID
GP_Player.GetID();
// Score
GP_Player.GetScore();
// Name
GP_Player.GetName();
// Avatar link
GP_Player.GetAvatarUrl();
// Stub – is the player default or the data in its model differs from the default
GP_Player.IsStub();

Methods for work with the player state FREE:

JavaScript

// Get the value of the key field
gp.player.get('gold');
// Set the value of the key field to value, the value is cast to the type
gp.player.set('class', 'warrior');
// Add the value to the key field
gp.player.add('gold', 50);
// Toggle the value of the key field
gp.player.toggle('vip');
// Check if the key field is present and not empty (not 0, '', false, null, undefined)
gp.player.has('vip');

// Return the player state as an object
gp.player.toJSON();
// Set the state from the object
gp.player.fromJSON({
    name: 'test player',
    score: 4522,
    gold: 100,
    vip: false,
    class: 'warrior',
});

// Reset the player state to default
gp.player.reset();
// Remove the player – reset fields and clear ID
gp.player.remove();

Unity

// Get the value of the key field
GP_Player.GetInt("gold");
// Set the value of the key field to value, the value is cast to the type
GP_Player.Set("gold", 100);
// Add the value to the key field
GP_Player.Add("gold", 10);
// Toggle the value of the key field
GP_Player.Toggle("vip");
// Check if the key field is present and not empty (not 0, '', false, null, undefined)
GP_Player.Has("vip");

// Reset the player state to default
GP_Player.ResetPlayer();
// Remove the player – reset fields and clear ID
GP_Player.Remove();

Player events:

JavaScript

// The player state has changed
gp.player.on('change', () => {});

Unity

//Subscribe to event
private void OnEnable()
{
    GP_Player.OnPlayerChange += OnPlayerChange;
}

//Unsubscribe from event
private void OnDisable()
{
    GP_Player.OnPlayerChange -= OnPlayerChange;
}

//On trigger event
private void OnPlayerChange()
{
    Debug.Log("Player Change");
}

Field Range Limits

Methods for working with player field boundary values, only for fields with specified restrictions (more details) FREE:

JavaScript

// Minimum value of the field key:min
gp.player.getMinValue('energy');
gp.player.get('energy:min'); // equivalent
// Set value
gp.player.set('energy:min', 0);

// Maximum value of the field key:max
gp.player.getMaxValue('energy');
gp.player.get('energy:max'); // equivalent
// Set value
gp.player.set('energy:max', 100);

Unity

// Minimum value of the field key:min
GP_Player.GetMinValue("energy");
GP_Player.GetInt("energy:min"); // equivalent
// Set value
GP_Player.Set("energy:min", 0);

// Maximum value of the field key:max
GP_Player.GetMaxValue("energy");
GP_Player.GetInt("energy:max"); // equivalent
// Set value
GP_Player.Set("energy:max", 100);

Events for boundary values:

JavaScript

// Subscribe to the event of reaching the maximum value
gp.player.on('field:maximum', ({ field }) => {});

// Subscribe to the event of reaching the minimum value
gp.player.on('field:minimum', ({ field }) => {});

Unity

//Subscribe to events
private void OnEnable()
{
    GP_Player.OnFieldMaximum += OnFieldMaximum;
    GP_Player.OnFieldMinimum += OnFieldMinimum;
}

//Unsubscribe from events
private void OnDisable()
{
    GP_Player.OnFieldMaximum -= OnFieldMaximum;
    GP_Player.OnFieldMinimum -= OnFieldMinimum;
}

private void OnFieldMaximum(PlayerFetchFieldsData field)
{
    Debug.Log($"Field {field.name} Maximum");
}
private void OnFieldMinimum(PlayerFetchFieldsData field)
{
    Debug.Log($"Field {field.name} Minimum");
}

Auto-Increment Values

Methods for working with auto-increment variables, only for fields with specified auto-update interval (more details) FREE:

JavaScript

// Value of the field auto-update interval in seconds, key:incrementInterval
gp.player.get('energy:incrementInterval');
// Set value
gp.player.set('energy:incrementInterval', 5 * 60);

// Amount by which the field increases during auto-update, key:incrementValue
gp.player.get('energy:incrementValue');
// Set value
gp.player.set('energy:incrementValue', 5);

// Timestamp of the last auto-update of the field, ISO 8601 string, key:timestamp
gp.player.get('energy:timestamp');
// Set value
gp.player.set('energy:timestamp', '2021-04-27T17:13:02.815Z');

// Remaining time until the next auto-update in seconds, key:secondsLeft
// Read only
gp.player.get('energy:secondsLeft');

// Remaining time until the field reaches its limit in seconds, key:secondsLeftTotal
// Read only
gp.player.get('energy:secondsLeftTotal');

Unity

// Value of the field auto-update interval in seconds, key:incrementInterval
GP_Player.GetInt("energy:incrementInterval");
// Set value
GP_Player.Set("energy:incrementInterval", 5 * 60);

// Amount by which the field increases during auto-update, key:incrementValue
GP_Player.GetInt("energy:incrementValue");
// Set value
GP_Player.Set("energy:incrementValue", 5);

// Timestamp of the last auto-update of the field, ISO 8601 string, key:timestamp
GP_Player.GetString("energy:timestamp");
// Set value
GP_Player.Set("energy:timestamp", "2021-04-27T17:13:02.815Z");

// Remaining time until the next auto-update in seconds, key:secondsLeft
// Read only
GP_Player.GetInt("energy:secondsLeft");

// Remaining time until the field reaches its limit in seconds, key:secondsLeftTotal
// Read only
GP_Player.GetInt("energy:secondsLeftTotal");

Events for auto-updates:

JavaScript

// Subscribe to the event of incrementing the variable
gp.player.on('field:increment', ({ field, oldValue, newValue }) => {});

Unity

//Subscribe to event
private void OnEnable()
{
    GP_Player.OnFieldIncrement += OnFieldIncrement;
}

//Unsubscribe from event
private void OnDisable()
{
    GP_Player.OnFieldIncrement -= OnFieldIncrement;
}

private void OnFieldIncrement(PlayerFetchFieldsData field)
{
    Debug.Log($"Field {field.name} Increment");
}

Player Statistics

FREE

You can retrieve information about the number of days and time spent in the game.

JavaScript

// Number of days in the game
gp.player.stats.activeDays;

// Number of consecutive days in the game
gp.player.stats.activeDaysConsecutive;

// Number of seconds spent in the game today
gp.player.stats.playtimeToday;

// Number of seconds spent in the game overall
gp.player.stats.playtimeAll;

Unity

public void PlayerStats()
{
    // Number of days in the game
    Debug.Log("Active Days:" + GP_Player.GetActiveDays());

    // Number of consecutive days in the game
    Debug.Log("Active Days Consecutive:" + GP_Player.GetActiveDaysConsecutive());

    // Number of seconds spent in the game today
    Debug.Log("Playtime Today:" + GP_Player.GetPlaytimeToday());

    // Number of seconds spent in the game overall
    Debug.Log("Playtime All:" + GP_Player.GetPlaytimeAll());
}

Player fields

Player fields are set in the panel, they describe the player state and store the following properties:

JavaScript

/**
 * Field name translated into current language
 * @type {string}
 */
field.name;

/**
 * Unique field key
 * @type {string}
 */
field.key;

/**
 * Field type
 * @type {'stats' | 'data' | 'flag' | 'service' | 'accounts'}
 * stats — numeric fields
 * data — string fields
 * flags — boolean fields
 * service – ID, test, active, remote, etc.
 * accounts — vkId, yandexId, okId, etc.
 */
field.type;

/**
 * Important field for the player
 * If you need to decide who will be left, you can display these fields
 * @type {boolean}
 */
field.important;

/**
 * Player's public field
 * will be visible to all players when searching for players
 * @type {boolean}
 */
field.public;

/**
 * Default field value
 * @type {string | number | boolean}
 */
field.default;

/**
 * Possible variants of values for the fields
 * If they are not specified, then the field takes any value
 * @type {ModelFieldVariant[]}
 */
field.variants;

/**
 * Limits for the field,
 * Can be empty
 * @type {FieldLimits | null}
 */
field.limits;

/**
 * Auto-increment interval,
 * Can be empty
 * @type {IntervalIncrement | null}
 */
field.intervalIncrement;

Unity

public class PlayerFetchFieldsData
{
    //Field name translated into current language
    public string name;
    //Unique field key
    public string key;

    /**
    * Field type
    * stats — numeric fields
    * data — string fields
    * flags — boolean fields
    * service – ID, test, active, remote, etc.
    * accounts — vkId, yandexId, okId, etc.
    */
    public string type;
    // Default field value
    public string defaultValue; // string | bool | number
    /**
    * Important field for the player
    * If you need to decide who will be left, you can display these fields
    */
    public bool important;
    /**
    * Public field of the player
    * will be visible to all players when searching for players
    */
    public bool public;
    /**
    * Possible values for the field,
    * if not specified, the field accepts any value
    */
    public Variants[] variants;
    /**
    * Limits for the field,
    * Can be empty
    */
    public FieldLimits limits;

    /**
    * Auto-increment interval,
    * Can be empty
    */
    public IntervalIncrement intervalIncrement;
}

Field variants can also be set in the panel. Variant properties:

JavaScript

/**
 * Variant name translated into current language
 * @type {string}
 */
fieldVariant.name;

/**
 * Unique value of the variant
 * @type {string | number | boolean}
 */
fieldVariant.value;

Unity

public class Variants
{
    //Variant name translated into current language
    public string name;
    //Unique value of the variant
    public string value; // string | number
}

Field limits can be set in the panel. Field limit properties:

JavaScript

/**
 * Lower limit of the field
 * @type {number}
 */
limit.min;

/**
 * Upper limit of the field
 * @type {number}
 */
limit.max;

/**
 * Can the field be manually set above the maximum limit
 * @type {boolean}
 */
limit.couldGoOverLimit;

Unity

public class Limits
{
    // Lower limit of the field
    public number min;
    // Upper limit of the field
    public number max;
    // Can the field be manually set above the maximum limit
    public number max;
}

Auto-increment interval of the field can be set in the panel. Properties of the auto-increment interval of the field:

JavaScript

/**
 * Increment interval, seconds
 * @type {number}
 */
intervalIncrement.interval;

/**
 * Value to increment
 * @type {number}
 */
intervalIncrement.increment;

Unity

public class IntervalIncrement
{
    // Increment interval, seconds
    public number interval;
    // Value to increment
    public number increment;
}

The list of fields is available directly in the player model FREE:

JavaScript

gp.player.fields;

Unity

Get by GP_Player.FetchFields()

Methods for work with fields FREE:

JavaScript

// Get the field by key
gp.player.getField('gold');
// Get the translated field name by key
gp.player.getFieldName('score');
// Get the translated name of the field variant by the key and its value
gp.player.getFieldVariantName('rank', 2);

Unity

// Get the translated field name by key
GP_Player.GetFieldName("score");
// Get the translated name of the field variant by the key and its value
GP_Player.GetFieldVariantName("class", "mage");

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!