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
ss.player.id;
// Score
ss.player.score;
// Name
ss.player.name;
// Avatar link
ss.player.avatar;
// Stub – is the player default or the data in its model differs from the default
ss.player.isStub;
// Player fields
ss.player.fields;

Unity

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

Methods for work with the player state FREE:

JavaScript

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

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

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

Unity

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

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

Player events:

JavaScript

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

Unity

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

//Unsubscribe from event
private void OnDisable()
{
    SS_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
ss.player.getMinValue('energy');
ss.player.get('energy:min'); // equivalent
// Set value
ss.player.set('energy:min', 0);

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

Unity

// Example will be added soon

Events for boundary values:

JavaScript

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

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

Unity

// Example will be added soon

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
ss.player.get('energy:incrementInterval');
// Set value
ss.player.set('energy:incrementInterval', 5 * 60);

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

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

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

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

Unity

// Example will be added soon

Events for auto-updates:

JavaScript

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

Unity

// Example will be added soon

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
ss.player.stats.activeDays;

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

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

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

Unity

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

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

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

    // Number of seconds spent in the game overall
    Debug.Log("Playtime All:" + SS_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

ss.player.fields;

Unity

Get by SS_Player.FetchFields()

Methods for work with fields FREE:

JavaScript

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

Unity

Not implemented

Stay in Touch

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

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!