Achievement

An Achievement is an object used to award points in the score. For most purposes, an achievement can be described simply by a string, but the Achievement object provides more flexibility in describing combined scores when a set of similar achievements are to be grouped.

There are two ways to use the scoring system.

1. You can use a mix of string names and Achievement objects for scoring items; each time you award a scoring item, you call the function addToScore() to specify the achievement (by name or by Achievement object) and the number of points to award. You can also call the method addToScoreOnce() on an Achievement object to award the scoring item, ensuring that the item is only awarded once in the entire game (saving you the trouble of checking to see if the event that triggered the scoring item has happened before already in the same game). If you do this, you MUST set the property gameMain.maxScore to reflect the maximum score possible in the game.

2. You can use EXCLUSIVELY Achievement objects to represents scoring items, and give each Achievement object a 'points' property indicating the number of points it's worth. To award a scoring item, you call the method awardPoints() on an Achievement object. If you use this style of scoring, the library AUTOMATICALLY computes the gameMain.maxScore value, by adding up the 'points' values of all of the Achievement objects in the game. For this to work properly, you have to obey the following rules:

- use ONLY Achievement objects (never strings) to award points;
- set the 'points' property of each Achievement to its score;
- define Achievement objects statically only (never use 'new' to
create an Achievement dynamically)
- if an Achievement can be awarded more than once, you must override
its 'maxPoints' property to reflect the total number of points it
will be worth when it is awarded the maximum number of times;
- always award an Achievement through its awardPoints() or
awardPointsOnce() method;
- there exists at least one solution of the game in which every
Achievement object is awarded

class Achievement : object

Describe the achievement - this must display a string explaining the reason the points associated with this achievement were awarded.

Note that this description can make use of the scoreCount information to show different descriptions depending on how many times the item has scored. For example, an achievement for finding various treasure items might want to display "finding a treasure" if only one treasure was found and "finding five treasures" if five were found.

In some cases, it might be desirable to keep track of additional custom information, and use that information in generating the description. For example, the game might keep a list of treasures found with the achievement, adding to the list each time the achievement is scored, and displaying the contents of the list when the description is shown.

Add this achievement to the score one time only, awarding the given number of points. This can be used to score an achievement without separately tracking whether or not the achievement has been accomplished previously. If the achievement has already been scored before, this will do nothing at all; otherwise, it'll score the achievement with the given number of points. Returns true if we do award the points, nil if not (because we've awarded them before).