Tutorial explaining how to use the AdventureJS scorecard.

tutorial, scorecard

Goals, Hints, and Scores:Scorecards

Example Output Methods Properties Variables Point Properties

Scorecards are a system for creating and awarding points, updating a player's score, printing score update messages, and setting the score in the status bar. Points aren't managed automatically - it's up to authors to define them and determine when they're awarded. Authors can call game.scorecard.awardPoint("my point") from any code block to award points. Point objectss can be organized into groups, which may award additional points when all of their children are completed. The first thing an author needs to do is create a set of points via shorthand or longhand methods. A player might see something like the following in response to typing points:

Example Output

> score You've earned 4 out of 10 points.

You opened the window.
You entered the library.
You unlocked the desk drawer.
You found Raggedy Ann.

Methods

MyGame.scorecard.set({}) {Object} an object containing point definitions MyGame.goalcard Use this to add point data to the scorecard.

Expand for example

MyGame.scorecard.set({
  points: {
    "open window": 1,
    "take ann": 1,
    "open library door": 1,
    "open top drawer": 1,
    "open chest": 1,
    "take andy": 1,
    "pin ann": 1,
  },
});

MyGame.scorecard.awardPoint("my point", false) {String} key {Boolean} recurse - whether to award nested points (default is true) Boolean Use this to mark a point as awarded.

Expand for example

MyGame.createAsset({
  class: "Lantern",
  name: "brass lamp",
  doActivate:
  {
    MyGame.scorecard.awardPoint("turn on lamp");
  },
  doMoveThisToThat:
  {
    "MyHero": function()
    {
      MyGame.scorecard.awardPoint("get lamp");
    },
  },
});

MyGame.scorecard.clearPoint("my point") {String} key Boolean Use this to clear an awarded point.
Expand for example
```
MyGame.scorecard.clearPoint({"my point"});
```
Private-ish Methods

The following methods are not technically private, as AdventureJS has no private functions. We point these out because, while authors shouldn't need to call them directly, we can imagine situations where authors might want to.

MyGame.scorecard.createPoint() {} Object point Used to add a new point to the scorecard with default values. This is handled automatically when using scorecard.set(). Authors shouldn't need to call this directly, but can.
Expand for example
```
MyGame.scorecard.createPoint();
```

MyGame.scorecard.updateScore() {} Boolean Used to update the score display. Authors don't necessarily need to call this directly, but can.
Expand for example
```
MyGame.scorecard.updateScore();
```

Properties

In addition to the methods listed above, scorecards have several configurable properties that authors can set with MyGame.scorecard.set({}).

MyGame.scorecard.award_text {String|Array|Function} Use to set the content of score update messages. award_text is subject to StringArrayFunction.
Expand for example
```
MyGame.scorecard.set({

  // simple generic example
  award_text: `{Our} score went up! `,

  // using scorecard variables
  award_text: function(){
    return `Dude, you totally just got ${this.diff} points! 
      Only ${this.total - this.newscore} points to go!`;
  },

});
```
Several scorecard values are available when using a function for award_text.
- this.score – the old score before adding the current point.
- this.newscore – the new score after adding the current point.
- this.diff – the difference between the old and new scores.
- this.total – the total of all points available in the game.
You can use them in a function like this.
```
MyGame.scorecard.set({
  award_text: function(){
    return `Dude, you totally just earned 
      ${this.diff} points out of ${this.total}!`;
  },
});
```

MyGame.scorecard.score_format {Function} Use to set the format of the score status on the status bar. The default is score/total but you can customize this any way you like, even to the point of not using numerical values.
Expand for example

Several scorecard values are available when using a function for score_format.
- this.score – the old score before adding the current point.
- this.newscore – the new score after adding the current point.
- this.diff – the difference between the old and new scores.
- this.total – the total of all points available in the game.
You can use them in a function like this.
```
MyGame.scorecard.set({
  score_format: function()
  {
    return `${this.score} / ${this.total}`;
  }
});

MyGame.scorecard.set({
  score_format: function()
  {
    return `Score: ${this.score} out of ${this.total}`;
  }
});

MyGame.scorecard.set({
  score_format: function()
  {
    return `${this.total - this.newscore} 
      points to go before you can die.`;
  }
});
```
You're not limited to numerical values. Call custom functions to build dynamic strings.
```
MyGame.scorecard.set({
  score_format: function()
  {
    return `Current mood: ${MyGame.getMood()}`;
  }

});

MyGame.scorecard.set({
  score_format: function()
  {
    return `Current danger level: 
      ${MyGame.getVar("danger_level")}`;
  }

});
```

MyGame.scorecard.summarize_updates {Boolean} In cases where a player earns multiple points in one turn, this setting determines whether the game prints individual score message or one summarized message.
Expand for example
```
MyGame.scorecard.set({
  summarize_updates: true,
});
        
```

MyGame.scorecard.noscore {String|Array|Function} Use this to customize the message that prints if the player types points before earning any points. noscore is subject to StringArrayFunction.
Expand for example
```
MyGame.scorecard.set({
  noscore: `{We've} earned nothing. Nothing! `,
});
        
```

MyGame.scorecard.overview {String|Array|Function} Use this to customize the overview message that prints if the player types points. overview has access to scorecard vars this.score, this.newscore, this.diff, and this.total. overview is subject to StringArrayFunction.
Expand for example
```
MyGame.scorecard.set({
  overview: `{We've} earned ${this.score} out of ${this.total} points.`,
});
        
```

Variables

Scorecards have several variable properties that can be used when customizing award_text and score_format.

MyGame.scorecard.score {String} The score before changes are applied by the current turn.

Expand for example

MyGame.scorecard.set({
  award_text: function()
  {
    return `${this.score} plus ${this.diff} equals ${this.newscore}. Way to go, dude! Only ${this.total - this.newscore} more points to go.`;
  }
});

MyGame.scorecard.newscore {String} The score with changes applied by the current turn.

Expand for example

MyGame.scorecard.set({
  score_format: function()
  {
    return `${this.newscore} / ${this.total}`;
  }
});

MyGame.scorecard.diff {String} The difference between score and newscore.

Expand for example

MyGame.scorecard.set({
  award_text: function(){
    return `Dude, you totally just earned ${this.diff} points!`
  },
});

MyGame.scorecard.total {String} The total of points available in the game.

Expand for example

MyGame.scorecard.set({
  score_format: function()
  {
    return `${this.newscore} / ${this.total}`;
  }
});

Point properties

In addition to the scorecard's configurable options, individual points can be further customized to return distinct messages. At minimum, a point only needs a name and a value, but authors can customize the message that is printed when that particular point is awarded, how the point is presented in a list of completed points when a player types score, whether the point is a bonus point, and optional custom code to be called when the point is awarded. Authors can use these properties to exercise granular control over score output.

MyGame.scorecard.points["my point"].value {Int} A numeric value.

Expand for example

MyGame.scorecard.set({
  points: {
    "unlock spellbook": {
      value: 1,
    },
  },
});

MyGame.scorecard.points["my point"].award_text {String|Array|Function} An optional string, array or function to be called when the point is awarded.

Expand for example

MyGame.scorecard.set({
  points: {
    "unlock spellbook": {
      value: 1,
      award_text: "[ ** {We} unlock the spellbook for a point! ** ]",
    },
  },
});

MyGame.scorecard.points["my point"].complete_text {String|Array|Function} An optional string, array or function to use when printing the score event in lists, such as when the player inputs score.

Expand for example

MyGame.scorecard.set({
  points: {
    "unlock spellbook": {
      value: 1,
      award_text: "[ ** {We} unlock the spellbook for a point! ** ]",
      complete_text: "{We} unlocked the spellbook. ",
    },
  },
});

MyGame.scorecard.points["my point"].bonus {Boolean} A boolean, true or false, to indicate whether this point is a bonus point. Bonus points are not included in the available points count, allow for scores like 110 out of 100.
Expand for example
```
MyGame.scorecard.set({
  points: {
    "unlock spellbook": {
      value: 1,
      award_text: "[ ** {We} unlock the spellbook for a point! ** ]",
      complete_text: "{We} unlocked the spellbook. ",
      bonus: true,
    },
  },
});
```

MyGame.scorecard.points["my point"].action {Function} An optional function to be called when the point is awarded.

Expand for example

MyGame.scorecard.set({
  points: {
    "unlock spellbook": {
      value: 1,
      award_text: "[ ** {We} unlock the spellbook for a point! ** ]",
      complete_text: "{We} unlocked the spellbook. ",
      bonus: true,
      action: function(){
        // custom code here
      },
    },
  },
});

Private-ish Properties

The following properties are not technically private, as AdventureJS has no private properties. We point these out because, while authors shouldn't need to access them directly, we can imagine situations where authors might want to.

MyGame.scorecard.points["my point"].awarded {Boolean} A boolean, true or false, to indicate whether this point has been awarded. Normally, authors would call game.scorecard.awardPoint("my point") or game.scorecard.clearPoint("my point") to set or unset this value. Though authors can set it directly, be aware that changes made this way won't be reflected in save game states, so be careful when setting it manually.
Expand for example
```
MyGame.scorecard.points["my point"].awarded = true;
```

MyGame.scorecard.points["my point"].recorded {Boolean} A boolean, true or false, to indicate whether this point has been recorded. This is used for tracking whether awarded points have been written to the saved game state. Though authors can set it directly, be aware that changes made this way won't be reflected in save game states, so be careful when setting it manually.
Expand for example
```
MyGame.scorecard.points["my point"].recorded = true;
```

Goals, Hints, and Scores:Scorecards

Example Output

Methods

Private-ish Methods

Properties

Variables

Point properties

Private-ish Properties