DESCRIBED Inconsistencies in DARK_LOCATION and Unlit Locations

[tajmone]

At some point after the v2.0.0 release, we need to check whether the described attribute is being handled correctly with dark locations (both unlit normal locations and DARK_LOCATION instance):

• When the dark_loc_des is shown instead of the location's DESCRIPTION, is the described attribute for the location being increased? It shouldn't, for the look command didn't result in a real description in this case.
• In DARK_LOCATIONs, when the automatic LOOK is executed by the light_on EVENT or by the ENTERED clause for NPCs, is the described attribute for the location being increased, as it should?

NOTE — I've already verified that some of the above are not handling the described attribute correctly, for example the ENTERED clause doesn't increase it when executing a LOOK. So this is Issue is being labeled as a BUG from the onset.

These aspects of described are not covered anywhere in the StdLib Manual, nor in the library sources' comments.

These aspects should be covered in:

• [ ] Test Suite — we must add extensive tests to uncover the current behavior of the described attribute in the above mentioned circumstances, and if found to behave inconsistently:
  • [ ] StdLib Sources — amend the Library to enforce consistency by ensuring that the described counter is:
    • [ ] Not incremented only when dark_loc_des is shown.
    • [ ] Duly incremented whenever a LOOK statement is triggered by the library (e.g. an entering NPC bringing light to the location)
• [ ] StdLib Design Documentation — which should provide clear guidelines on the design goals of described, how the Library implements its details and edge-cases, and provide guidelines for authors wishing to extend the StdLib with custom verbs and code, in order to ensure they honor the intended goal of the described attribute without breaking its design.
• [ ] StdLib Manual — it should mention how described is handled in dark locations, and provide basic reminders for authors who add custom verbs that might (or should) affect the described counter.

[tajmone]

A Few Random Thoughts on This Problem

Fixing this is going to be a challenging task!

Right now, the library increments described every time:

• The 'look' verb is executed.
• The hero enters a location.

... regardless of whether the location is lit or dark.

The feature has a faulty design, because the library should ensure that only real descriptions of the location are counted, not when the dark_loc_desc is shown — otherwise a description intended only for the first time visualization might be skipped altogether due to darkness descriptions moving the described counter beyond its visualization range.

Ideally, the incrementation of described should be moved from the 'look' VERB and the ENTERED clause and placed directly into the DESCRIPTION CHECKs of location and DARK_LOCATION, ensuring that it's incremented only when the location is lit. But that's an extremely unsafe approach, as mentioned in The ALAN Manual on DESCRIPTION:

The Description should not change any game state since it might not always be executed depending on the settings of Visits. In particular, the Description clause of a location should not move the hero; this might lead to a recursive loop of descriptions. This might instead be managed by the Entered clause.

Another obstacle to making this feature straight is the need to check if a location is also a DARK_LOCATION instance — something that can't always be done easily, since branching instructions in ALAN don't support NOT IsA, and in some contexts it's not possible (or at least, not easy) to exploit an Else of an IsA DARK_LOCATION, because of the need of providing a statement that does nothing in the Then block (see alan-if/alan#14 for more details on this).

The mechanism for deciding on whether to increase described or not, will largely depend on whether the location is also a DARK_LOCATION or not.

To complicate things, for DARK_LOCATIONs there are the background EVENTs that might change its lit status at every turn, so relying on the location's lit status might turn out to be no trustworthy, since EVENTs might rectify it after the 'look' verb or the ENTERED clause have executed.

All the above need to be kept in mind before attempting a solution to the problem; and, of course, ample testing is necessary.

In theory, the problem could be approached "reversely," by decreasing described if necessary — i.e. to operate the various checks after the current mechanism, and fix the value in dark locations. Although this would allow moving the solution to other parts of the code, I doubt it would lead to an elegant solution at all.

[AnssiR66]

Would the following work:

ADD TO EVERY LOCATION HAS visited 0.
HAS described 0.

ENTERED
     IF CURRENT ACTOR = hero
        THEN 
            INCREASE visited OF THIS.
                            IF THIS IS lit
                                THEN    
            INCREASE described OF THIS.
                             END IF.        
            -- The "described" attribute increases also after LOOK (see 'verbs.i').
     END IF.

END ADD TO.

(and similarly in the 'look' verb?) Or am I overlooking something here?

[tajmone]

Probably it won't work on DARK_LOCATIONs, because they might be lit at the beginning of the turn, but later on (during the same turn) become unlit if no lit lightsources are present. The problem is that the darkness handling EVENTs will occur after the VERBs and ENTERED execution, and that's not something that can be changed (i.e. player commands are always executed before EVENTs, SCRIPTs and RULEs, so the flanked expression approach doesn't apply in this context).

This is going to take some time, and lot's of tests. I propose to post-pone it after the mid-Nov 2.2.0 release, since we're tight on time. Also, Thomas has started to work on implementing the NOT IsA <someclass> conditional expression, which is going to make these changes much easier on our side; so it might be worth waiting for that feature to be added to a Beta ALAN release (which is unlikely to become available before the new year).

[AnssiR66]

OK, we can do as you suggest.