Each goal is associated with a hint topic (usually shown as a question, such as "How do I get past the guard?") and an ordered list of hints. The hints are usually ordered from most general to most specific. The idea is to let the player control how big a hint they get; we start with a small nudge and work towards giving away the puzzle completely, so the player can stop as soon as they see something that helps.
At any given time, a goal can be in one of three states:
- Open: this means that the player is (or ought to be) aware of the goal, but the goal hasn't yet been achieved. Determining this awareness is up to the goal. In some cases, a goal is opened as soon as the player has seen a particular object or entered a particular area; in other cases, a goal might be opened by a scripted event, such as a speech by an NPC telling the player they have to accomplish something. A goal could even be opened by viewing a hint for another goal, because that hint could explain a gating goal that the player might not otherwise been able to know about.
- Undiscovered: this means that the player doesn't yet have any reason to know about the goal.
- Closed: this means that the player has accomplished the goal, or in some cases that the goal has become irrelevant.
The hint system only shows goals that are Open. We don't show Closed goals because the player presumably has no need of them any longer; we don't show Undiscovered goals to avoid giving away developments later in the game before they become relevant.
You can use this, for example, to automatically remove the hint from the hint menu after it's been fully displayed. (You might want to do this with a hint for a red herring, for example. After the player has learned that the red herring is a red herring, they probably won't need to see that particular line of hints again, so you can remove the clutter in the menu by closing the hint after it's been fully displayed.) To do this, simply add this to the Goal object:
closeWhenTrue = (goalFullyDisplayed)
Each entry in the list can be a simple (single-quoted) string, or it can be a Hint object. In most cases, a string will do. A Hint object is only needed when displaying the hint has some side effect, such as opening a new Goal.
Note that this should generally NOT be overridden in individual instances; normally, instances would define openWhenTrue instead. However, some games might find that they use the same special condition over and over in many goals, often enough to warrant adding a new openWhenXxx property to Goal. In these cases, you can use 'modify Goal' to override openWhen to add the new condition: simply define openWhen as (inherited || newCondition), where 'newCondition' is the new special condition you want to add.
Sometimes it's more convenient to set a goal's state explicitly from a scripted event; for example, if the goal is associated with a scored achievement, awarding the goal's achievement will set the goal's state to Closed. In these cases, there's no need to use this method, since you're managing the goal's state explicitly. The purpose of this method is to make it easy to catch goal state changes that can be reached by several different routes; in these cases, you can just write a single test for those conditions in this method rather than trying to catch every possible route to the new conditions and writing code in all of those.
The default implementation looks at our openWhenSeen property. If this property is not nil, then we'll check the object referenced in this property; if our current state is Undiscovered, and the object referenced by openWhenSeen has been seen by the player character, then we'll change our state to Open. We'll make the corresponding check for openWhenDescribed.