Untitled

📰Getting Started | ⭐**Updates |** 📝 Guides | 🔢 API | ❓FAQ

Guides Overview

The score API allows users to define different score types, update scores, as well as define their visual characteristics.

const score = require('score-preview');

Creating a Score

Every score object is created with a descriptor. The user can choose to specify an Element that added scores will spawn around. Creating a score without attaching it to an Element makes it appears direclty in front of the user. It also possible to specify the location of the score when configuring it.

// attached to an element
var coinsScore = score.create(this, 'coins');

// directly in front of the user
var points = score.create('points');

Configuring a Score.

Each parameter of the score can be controlled through calling a method of the score. These functions can be chained. All of the parameters are optional.

// declares a score object.
var coinsScore = score.create(this, 'coins');

// sets initial score to be 10. The default is 0.
coinsScore.score(10);

// sets the color of margin score display to be red. the default is col4(1,1,1,1).
coinsScore.color(col(1,0,0,1));

// sets margin score display font size to be 90. The default is 60.
coinsScore.fontSize(90);

// sets score display offset.
// When there is an element attached, this is the local offset.
// When there is none attached, this is the global offset.
coinsScore.offset(vec3(3,3,0));

// sets duration of margin score display to be 2 seconds. Default is 1 second.
coinsScore.duration(2);

// sets duration of margin score display's fade in/fade out to be 1 second. The default value is 0.5 second.
coinsScore.fadeDuration(1);

// spawns the marginal scores at a random location within the specified range. Default is 0.
coinsScore.randomPosRange(1);

// defines the string fromatting of the spawned visualization. [score] will be replaced with the marginal score
// if marginal score is 2, the visualization spawned is 'You received 2 points!'
coinsScore.scoreFormat('You received [score] points!');

// mutes sound fx.
coinsScore.mute(true);

// sets the vine that displays the updated total score
coinsScore.setDisplayVine(this.parent.findOne('..coins-score'));

Adding Points

Scores can be directly added to the Score object declared. They can also be added through the score manager.

// create a score object that will display in front of the user.
var coinsScore = score.create('coins');

// add 2 points
coinsScore.award(2);

// add 2 more points, with an offset.
coinsScore.award(2, vec3(0, 1, 1));

// add 3 more from the module, using the category.
score.award('coins', 3);

Access and Modify Score Parameters

The score manager has reference to all created scores. All score information can be accessed and modified through the manager.

var coinsScore = score.getType('coins');
coinsScore.score(10)
    .fontSize(100)
    .color(col(0,0,0,1))
    .offset(vec3(1,2,3))
    .duration(3)
    .fadeDuration(0.7)
    .randomPosRange(1.5)
    .scoreFormat('+ {score} pts')
    .mute(true)
    .setDisplayVine(this.findOne('..coins-score'));

Messages on Score Change

A local message score-increase is dispatched whenever a score increases. A local message score-decrease is dispatched whenever a score decreases. Each of these messages include two payloads: the first one is the type name of the increased/decreased score, and the second one is the marginal score.

const MSG_SCORE_INCREASE = 'score-increase';

function enter() {
  scoreManager.on(MSG_SCORE_INCREASE, onIncrease);
}

function onIncrease(type, margin) {
if (type == 'coins') {
    log.info("Coins increased by " + margin);
  }
}

function exit() {
  scoreManager.off(MSG_SCORE_INCREASE, onIncrease);
}

Module Events

Module Methods

create(name)

create(element, name)

Creates a score object with the specified name and optional Element. If a score object with the same name exists, it is replaced.

award(name, points, [offset])

Awards (or subtracts) points for a category and displays them to the user.

awardHidden(name, points)

Awards (or subtracts) points for a category without displaying to the user.

getType(name)

Fetches the ScoreElement for an existing score ID.

clearScore(name)

Sets the value for the given score ID to 0.

clearAll()

Resets all score values to 0.

ScoreElement Methods

award(value, [offset])

Awards or subtracts points and displays to the user.

awardWithoutVisualization(value)

Awards or subtract points without displaying them to the user.

clearScore()

Resets the score to 0.

getName()

score(score)

Sets the score value.

getScore()

Fetches the current score.

fontSize(size)

Sets the font size for the score display.

getFontSize()

Fetches the font size of the score display.

color(color)

Sets the font color of the score display.

getColor()

Fetches the color of the score display.

offset(offset)

Sets the relative position of where score displays should be spawned.

getOffset()

Fetches the relative position of where score displays should be spawned.

setDisplayVine(vine)

Sets a custom Vine to use to display scores.

getDisplayVine()

Fetches the element with a Vine that is used to display scores.

duration(dur)

Sets the amount of time, in seconds, a score should display before fading.

getDuration()

Fetches the amount of time, in seconds, a score should display before fading.

fadeDuration(fade)

Untitled