infocom/compilers/inform5/library/contributions/adhints/adhints.txt

[Last revision: January 31, 1996, AdHints v0.9]

REQUIREMENTS:
Library 5/12 (or later)
Inform 5.5 (or later)
NewMenu.h to replace DoMenu and LowKeyMenu

USING THE ADHINTS LIBRARY IN INFORM:

In practice, one declares a series of objects, all contained within an
object called Hints, with the name of the puzzle in short_name, a property
called 'the_hints' which contains one or more strings to act as the
(consecutive) hints, and a hint_check routine to set general and solved
based on the status of the game. 

All adaptive hint examples are for the demonstration game BALANCES.  The
adaptive hints are contained in a file called ah_bal.h and three lines
were added before the line Include "Grammar"; 

They are:
Constant SHOWSOLVEDTAG;
Include "AdHints";
Include "ah_bal";

[In addition, to allow the menus to change dynamically and otherwise
 perform properly, you need to include NewMenu.h:

before including Parser:
  Replace Low_KeyMenu;
  Replace DoMenu;

then before including AdHints.h:
  Include "NewMenu";

otherwise there will be some undefined symbol problems. ]

A sample would be:

Object  Cottage_Puzzle "Cottage Puzzle" Hints
 has    general
 class  HintClass
 with   short_name "What to do in the Cottage",
        the_hints "Maybe you should look around some."
                  "Perhaps you should even try looking at objects in the room."
                  "In fact, the furniture might be a good place to start \
                   looking.",
        hint_check [;
            if (h_box has moved) give self solved;
        ];

Notice that it starts with general (which means that it is available to the 
player from the very beginning), and that as soon as the h_box has been 
moved, it is solved.

It is probably a good idea to point out that the hint_check routine is 
run in an AfterPrompt() routine within AdHints.h, so special precautions 
should probably be taken if you define your own AfterPrompt() (for boxed 
quotations, for example).

A more complicated hint structure might be:

Object  Box_Puzzle "Box Puzzle" Hints
 class  HintClass
 with   short_name "What to do with the box",
        the_hints "Hmmm, I wonder if there isn't a useful ability to unlock \
                   things."
                  "Of course, you might try looking at your spellbook."
                  "(The next hint is explicit)"
                  "Maybe the REZROV spell would be useful.",
        hint_check [;
            if (h_box has moved) give self general;
            if (h_box hasnt locked) give self solved;
        ];

Notice that the hint_check routine causes the hint to be available after
h_box has been moved, and as soon as it is unlocked, the puzzle is
considered solved. 


THE INTERFACE:

AdHints implements several new verbs (some of which are available only 
for debugging):
GENERAL:
  Hint, Hints -- goes into the hints system
  Hints off   -- disables hints for the remainder of the game
  Hints on    -- parity routine, doesn't actually re-enable the hints
  Review      -- looks at past hints
DEBUGGING:
  Puzzles     -- lists all puzzles under the Hints object
  AllHints    -- shows every single hint

If the player uses 'Hints off', the hints will be unavailable for the
remainder of the game *regardless* of the use of 'Hints on'.  This is
preserved over saved games since the state is saved in a global variable
called AH_hints_available.  Set this to 1 if you need to re-enable hints
for some reason (for instance, in an AMUSING routine). 

CUSTOMIZING:
    The easiest way to customize the behavior of the adaptive hints system
is to define one or more constants/variables.  The 'correct' way to define
them are: 

Constant variablename;
(e.g.  Constant GIVEHINTSONCE;  )

The variables are:

GIVEHINTSONCE: This causes a hint to be given by the hint verb only once. 
This is a particular nuisance (from the player's perspective) if
NOHINTREVIEW is also defined, since the hints will be given but a single
time and be utterly unretrievable afterwards. 

NOHINTREVIEW: This disables the Review verb.  It does not disable the
ReviewSub() routine, so the programmer may call it up (say, at the end of
the game) somewhere else in the code. 

REVIEWGIVENONLY: The default behavior is for Review to display any hints
which have been given and any hints for puzzles which have been solved. 
Defining this causes Review to display only those hints which were
actually given. 

SHOWSOLVEDTAG: If defined, this causes the string "(solved)" to appear
after any hint title in the Review menu if the puzzle has been solved. 

HINTDEBUG: This causes extra internal information to be displayed and
allows access to debugging verbs.  Probably not useful unless you are
hacking at the actual hints system. 

HINTDEBUGVERBS: This causes the debugging verbs to be available without
having all the debugging and tracing information displayed. 

NOTE: The defines modify the behavior at compile-time! That means that
(for instance) the "(solved)" tag either appears or doesn't. This may
change in future versions if interest is expressed, but it doesn't seem
worth the space trade-off, in my opinion. 


INSIDE THE ADAPTIVE HINTS:
    The source code can, of course, be examined.  The brief overview is
that there is an AfterPrompt() routine which executes AH_UpdateHints() in
order to run hint_check on each hint object each turn.  If you define your
own AfterPrompt(), call it AfterPrompt2 and make certain it is defined
before including AdHints.h. 
    Each hint should be declared as being of class HintClass (although
that does practically nothing as of yet -- this will probably change as
the system improves) to pick up appropriate defaults. 

COMMENTS:
    I have tried to make a general, useful adaptive hints module, and I
think I have succeeded to a certain extent.  However, I'm sure I missed
some things, and I would appreciate comments, criticisms, corrections,
suggestions, bug fixes, bug reports, and anything else which might improve
the module.  Yes, it's pretty large, but it's a pretty large task that's
being done.  I'm not 100% sure of my paging code, but it survived my
testing, and I'm sure the source code could be a little more elegant, and
I'd like to not have to replace the DoMenu stuff, so I have submitted my
minor corrections to Parser.h. 
    Commentary of any sort should be mailed to mike@lawlib.wm.edu and the
'correct' home site is: 

    ftp://skaro.lawlib.wm.edu/pub/users/mike/inform-stuff/adhints/

    After a first round of review, barring extremely major complications,
AdHints.h will be uploaded to ftp.gmd.de as a 1.0 release. 

SPECIAL NOTE:
    To allow use in the 1996 IF Competition without waiting for me to 
finish up the last couple of things I want, I am releasing 0.92 to 
FTP.GMD.DE for that specific and express purpose.