+# This YAML file gets processed into a collection of data structures and
+# variable initializers describing Colossal Cave. It replaces an ad-hoc
+# text database shipped with Adventure versions up to 2.5. The format
+# change enabled a lot of use of symbolic names where there were previously
+# inscrutable numeric literals.
+#
+# We define a bunch of YAML structures:
+#
+# hints: Each item contains a hint number (add 10 to get cond bit),
+# the number of turns he must be at the right loc(s) before
+# triggering the hint, the points deducted for taking the hint, the
+# message number (section 6) of the question, and the message
+# number of the hint. These values are stashed in the "hints"
+# array.
+#
+# locations: Each item contains a long and short description. Some
+# short descriptions are empty. Order of these locations is significant;
+# see the macros OUTSID and INDEEP. Location conditions can be read
+# as follows:
+# LIT Light
+# OILY If FLUID flag is on: true for oil, false for water
+# FLUID Liquid asset
+# NOARRR Pirate doesn't go here unless following player
+# NOBACK Cannot use "back" to move away
+# HCAVE Trying to get into cave
+# HBIRD Trying to catch bird
+# HSNAKE Trying to deal with snake
+# HMAZE Lost in maze
+# HDARK Pondering dark room
+# HWITT At Witt's End
+# HCLIFF Cliff with urn
+# HWOODS Lost in forest
+# HOGRE Trying to deal with ogre
+# HJADE Found all treasures except jade
+#
+# arbitrary_messages: These are arguments to rspeak(). Some spans of
+# these messages need to be kept adjacent and ordered (for now).
+# To see which, grep for rspeak() calls containing expressions with
+# arithmetic. Eventually, these will be pulled out into more appropriate
+# data structures. Then ordering can be dropped, and gaps removed.
+#
+# classes: Each item contains a point threshold and a message
+# describing a classification of player. Point thresholds must be
+# in ascending order. The scoring code selects the appropriate
+# message, where each message is considered to apply to players
+# whose scores are higher than the previous N but not higher than
+# this N. Note that these scores probably change with every
+# modification (and particularly expansion) of the program.
+#
+# turn_thresholds: Each item contains a number and a message
+# berating the player for taking so many turns. When the turn count
+# matches one of the thresholds, the corresponding message is shown.
+# Order doesn't matter; the logic simply tests every threshold on
+# the assumption that turn counts never decrease nor skip values.
+#
+# objects: Each item contains a description for use in the inventory command
+# and one or more messages describing the object in different states.
+# If the inventory desription begins with "*" the object is dungeon
+# furniture that cannot be taken or carried.
+#
+# obituaries: Death messages and reincarnation queries. Order is
+# significant, they're used in succession as the player racks up
+# deaths.
+#
+# These correspond to sections 1, 2, 5, 6, 10, 11, and 14 in the old
+# adventure.text format. Sections 3, 4, 7, 8, and 9 haven't moved yet.
+# Section 12 was obsolete.
+
+# FIXME: Hint texts shouldn't be in arbitrary_messages, but inlined here
+hints:
+ - hint: &grate
+ number: 1
+ turns: 4
+ penalty: 2
+ question: ENTRY_QUERY
+ hint: HARD_GRATE
+ - hint: &bird
+ number: 2
+ turns: 5
+ penalty: 2
+ question: BIRD_QUERY
+ hint: SKITTISH_BIRD
+ - hint: &snake
+ number: 3
+ turns: 8
+ penalty: 2
+ question: SNAKE_QUERY
+ hint: SNAKE_HINT
+ - hint: &maze
+ number: 4
+ turns: 75
+ penalty: 4
+ question: MAZE_HELP
+ hint: DROP_THINGS
+ - hint: &dark
+ number: 5
+ turns: 25
+ penalty: 5
+ question: PLOVER_QUERY
+ hint: EXPLORE_HINT
+ - hint: &witt
+ number: 6
+ turns: 20
+ penalty: 3
+ question: HELP_LEAVING
+ hint: NOGO_WEST
+ - hint: &cliff
+ number: 7
+ turns: 8
+ penalty: 2
+ question: WONDERING_QUERY
+ hint: ADVANCED_SECTION
+ - hint: &forest
+ number: 8
+ turns: 25
+ penalty: 2
+ question: FOREST_QUERY
+ hint: GO_EAST
+ - hint: &ogre
+ number: 9
+ turns: 10
+ penalty: 4
+ question: OGRE_QUERY
+ hint: OGRE_CLUE
+ - hint: &jade
+ number: 10
+ turns: 1
+ penalty: 4
+ question: MISSING_ONE
+ hint: NO_LOCATE
+