Customize Output:Scorecard

Scorecards offer methods for creating scored events, updating a player's score, printing score update messages, and setting the score in the status bar. Following is a list of scorecard methods and properties that an author can set.

Methods

• scorecard.createEvent(): add a new scoring event to the scorecard.
• scorecard.completeEvent(): mark a scoring event as completed.
• scorecard.updateScore(): used by the parser to update the score display. Authors don't necessarily need to call this manually, but can.

Properties

• scorecard.score_message: can be used to set the content of score update messages.
• scorecard.score_format: can be used to set the format of the score status on the status bar. The default is score/total.
• scorecard.summarize_updates: in cases where a player completes multiple score events in one turn, can be used to set the game to print one summarized message instead of the default behavior, which is to print separate score messages for each event.

Variables

• scorecard.score: the score before changes are applied by the current turn.
• scorecard.newscore: the score with changes applied by the current turn.
• scorecard.diff: the difference between score and newscore.
• scorecard.total: the total of points available in the game.

Finally, a score event can be set with just a numeric value, or with an object containing several optional properties.

• scorecard.event.points: a numeric value.
• scorecard.event.message: a string, array or function.
• scorecard.event.complete: a boolean, true or false.
• scorecard.event.recorded: a boolean, true or false.
• scorecard.event.bonus: a boolean, true or false.

MyGame.scorecard.set({
  
  // Use the score_events property to set score events for a game. 
  // Any number of events is accepted.
  // Event names are strings that can be set to any text.
  // Event points are integers that can be set to any value,
  // or can be objects that contain deeper properties.
  score_events: {

    // these items are set with a simple numerical point value
    "get lamp": 1,
    "turn on lamp": 1,
    "get sword": 1,
    "kill orc": 1,
    "get key": 1,
    "unlock chest": 1,
    "get treasure": 1,

    // Point values can be negative as well.
    "lose five points": points: -5, 

    // To set properties aside from points, move points into the object.
    // You can customize the score message for individual score 
    // events by setting score_events.item.message to a string 
    // or array or function.
    "eat treasure": { 
      points: 1, 
      message: "[ ** Whoa! Who thought THAT would work? ** ]" 
    },

    // You can assign "bonus" points that aren't 
    // counted in the total, allowing players to earn a 
    // score beyond the max, such as 110/100.
    "eat treasure": { 
      points: 1, 
      bonus: true 
    },

    // Points can be preset, allowing you to start the game 
    // with some points already set. 
    "preset points": { 
      points: 5, 
      complete: true, // this must be true
      recorded: true  // this must be true
    },

  },

  // The summarize_updates property determines how score updates 
  // are printed when multiple score events occur in the same turn. 
  // The default value is false. If set to true, when multiple score 
  // events occur in a turn, only one score update will be printed 
  // showing the cumulative score change.
  summarize_updates: false,
  
});

Once a scorecard is initialized, score events can be completed with a call from any code block using the scorecard.completeEvent() function. If a previously completed event is called again, it will be ignored, so there is no danger of repeating events.

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

The default score message out of the box looks like this: `[ ** Your score went up by 1 point ** ]`. Authors can change this with the scorecard.score_message property.

MyGame.scorecard.set({

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

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

Use scorecard.score_format to change the format of the score as it appears in a game's status bar. By default, score is formatted in the status bar as score/total. scorecard.score_format has access to the scorecard variables this.score, this.newscore, this.diff and this.total.

MyGame.scorecard.set({

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

  // Technically you don't even need to use numbered scores. You could, 
  // if you wanted, set scores as text that includes placeholders, like so:
  score_format: function()
  {
    return `Current danger level: ${MyGame.getVar("danger_level")}`;
  }
  
});