Goal

A Goal represents an open task: something that the player is trying to achieve. A Goal is an abstract object, not part of the simulated world of the game.

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.

class Goal : MenuTopicItem HintMenuObject HintOpener

Has this goal been fully displayed? The hint system automatically sets this to true when the last item in our hint list is displayed.

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)

The list of hints for this topic. This should be ordered from most general to most specific; we offer the hints in the order they appear in this list, so the earlier hints should give away as little as possible, while the later hints should get progressively closer to just outright giving away the answer.

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.

Check our menu state and update it if necessary. Each time our parent menu is about to display, it'll call this on its sub-items to let them update their current states. This method can promote the state to Open or Closed if the necessary conditions for the goal have been met.

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.