§18.26. Printing the locale description of something

1. When it happens. A "locale description" is Inform jargon for the part of a room description which catalogues the visible items in the room. When looking, Inform will normally print the description of the room itself, followed by a locale description for the room. But if the player is in a cage in the room, there will be two locale descriptions: one for the room, then another for the cage. This activity is used to write the locale description for a single domain, and the "something" can be either a room, an enterable container, or an enterable supporter.

2. The default behaviour. Is quite complicated, and is written up in full in the typeset form of the Standard Rules downloadable from the Inform website. Briefly, though: we first run the "choosing notable locale objects" activity to find out what ought to be mentioned here. That assembles a list of things to mention, sorted into priority order. Items with priority 1 go first, then those with priority 2, and so on. The "printing a locale paragraph" activity is run for each, and in practice that usually hands the job over to "writing a paragraph about". Sometimes a paragraph will indeed be written, but not always. Sometimes there is nothing interesting to say, and an item is left until a final, single paragraph which gathers up the leftovers ("You can also see a scarlet fish, a harmonium and a kite here."), the printing of which is done by the "listing nondescript items of" activity. As soon as any item picks up the either/or property "mentioned", by having its name printed, it is struck out so that it will not appear subsequently, whatever its priority.

3. Examples. As general advice: if the effect wanted can be got using "writing a paragraph about" and "listing nondescript items of" alone, use those; if it's necessary to meddle further, use "choosing notable locale objects" and "printing a locale paragraph" to alter the normal processes; use the all-powerful "printing the locale description" activity only when the whole process needs to be altered, not the item-by-item workings.

(a) In the Very Misty Moorlands, nothing on the ground can ordinarily be seen through the swirling mist, so the locale description is suppressed entirely:

paste.png Rule for printing the locale description of the Very Misty Moorlands:
    say "Mist coils around your feet, thick as a blanket. You cannot even see the ground you walk upon." instead.

Report taking something in the Very Misty Moorlands:
    say "You grope blindly in the mist and pick up [the noun]." instead.

(b) Here we take the chance to insert an additional paragraph into the locale description. This does relate to an item which might be described later, but where the player doesn't know that:

paste.png The Horological Workshop is a room. The marble table is fixed in place in the Workshop.

The parcel is a closed opaque container on the marble table. The alarm clock is a device in the parcel. The alarm clock is switched on.

Before printing the locale description of a room (called the locale):
    if the locale encloses the alarm clock and the alarm clock is switched on, say "A faint ticking noise can be heard."


arrow-up.pngStart of Chapter 18: Activities
arrow-left.pngBack to §18.25. Listing nondescript items of something
arrow-right.pngOnward to §18.27. Choosing notable locale objects for something

When it comes time to start manipulating the priorities of items, it is useful to be able to check the table for debugging purposes; the problem is that printing the names of the objects can itself affect the way the room description is generated, foiling our debugging efforts.

What follows is a rule to help with debugging safely, and a sample of how priorities work:

paste.png "Priority Lab"

Section 1 - Procedure

Before printing the locale description (this is the dump locale table rule):
    say "Locale Priority list:";
    repeat through Table of Locale Priorities:
        let the flag be whether or not the notable-object entry is mentioned;
        say "[line break] [notable-object entry]: [locale description priority entry]";
        if the flag is false, now the notable-object entry is not mentioned;
    say line break.

Now, let's look at some items put in a specific order. Things with low priority numbers list towards the beginning; things with high priority numbers list towards the end. (It helps to think of it as though we were making a numbered list of the paragraphs to appear in the description.) Anything numbered 0 doesn't appear at all, and the default priority of an object is 1.

A thing can be early-described, late-described, latest-described, never-described, sightline-described, or ordinarily-described. A thing is usually ordinarily-described.

After choosing notable locale objects (this is the apply early and late description rule):
    repeat with item running through early-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 1; [list before everything else -- this would work with any number lower than 5 and higher than 0]
    repeat with item running through late-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 10; [list after everything else -- this would work with any number larger than 5]
    repeat with item running through never-described things:
        set the locale priority of the item to 0; [don't list at all]
    continue the activity.

An important cautionary note: priorities are only honored if the objects are going to get their own paragraphs (with "writing a paragraph about..." or because they have initial appearances). Priorities do not affect the order in which items appear in the final "You can see..." list, except that items with priority 0 or lower are omitted. (If we want to order the items in that list, we may want to resort to the Complex Listing extension by Emily Short.)

There are further refinements available to us: for instance, we could make some things that are only visible if the player is raised above ground level.

After choosing notable locale objects (this is the sightline-described things are visible from supporters rule):
    if the player is not on a supporter:
        repeat with item running through sightline-described things:
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 0; [remove objects that can only be seen from higher objects.]
    continue the activity.

It may also be useful to know about the "parameter-object", which refers to the thing whose contents we are currently describing: the standard rules consider how to describe the contents of the location and then also check the contents of any supporter or container the player may be inside, so in the first case "parameter-object" would be the location, and then in the second the supporter in question.

In practice this is rarely useful, but should we need to change priorities in the case of both player and object being inside a particular container, we might make use of it, for instance:

A thing can be tasteful or icky. A thing is usually tasteful.

After choosing notable locale objects (this is the icky things next to players rule):
    if the player is on the parameter-object:
        repeat with item running through icky things :
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 10; [remove objects that can only be seen from higher objects.]
    continue the activity.

The other thing to note is that by default that final collection of generic objects ("You can also see...") appears at the end, regardless of the priority of everything else. If we really wanted to, though, we could force something to appear even after that paragraph, by adding a new listing rule to the locale description rules:

After choosing notable locale objects (this is the latest-described items priority rule):
    repeat with item running through latest-described things:
        if the item is a notable-object listed in the Table of Locale Priorities:
            now the item is mentioned;
            now the item is marked for late listing.

The late listing rule is listed after the you-can-also-see rule in the for printing the locale description rules.

A thing can be marked for late listing. A thing is usually not marked for late listing.

This is the late listing rule:
    if something is marked for late listing:
        say "Oh! And also [a list of things which are marked for late listing].";
        now everything is not marked for late listing;
    continue the activity.

Section 2 - Scenario

The Priority Lab is a room. The early bird, the worm, the leaf, the unseen object, the pebble, the twig, and the late edition are things in the Priority Lab.

The early bird is early-described. The late edition is late-described. The unseen object is never-described.

The worm is icky.

The high window is in Priority Lab. It is sightline-described and fixed in place. The initial appearance of the high window is "There's a tiny high window up near the ceiling that you can't see unless you're on top of something."

In order for the priorities we just set to be interesting, let's give out some initial appearances and writing a paragraph rules:

The initial appearance of the worm is "A worm inches along the ground."
The initial appearance of the late edition is "Finally, the late edition lies at your feet."

Rule for writing a paragraph about the early bird when the early bird is in a room: say "The early bird always appears first, and here it is."
Rule for writing a paragraph about the leaf: say "Look, there's [a leaf][unless the leaf is in the location] on [the holder of the leaf][end if]!"
Rule for writing a paragraph about an icky thing (called icky item) which is on something which supports the player: say "Ew, [an icky item] is right next to you."

This procedure also means (as you can test by experiment) that after the late edition has been picked up and dropped again, it lists in no special order in the "you can see..." paragraph (since initial appearances only print when the object has not yet been moved).

The afterthought is a thing in the Priority Lab. It is latest-described.

The bar stool is an enterable supporter in Priority Lab.

Test me with "get leaf / drop leaf / look / x unseen object / get pebble / look / get twig / look / get afterthought / look / drop twig / look / get late edition / look / drop late edition / sit on bar stool / look / get all / put all on stool / look".

*ExamplePriority Lab
A debugging rule useful for checking the priorities of objects about to be listed.

When it comes time to start manipulating the priorities of items, it is useful to be able to check the table for debugging purposes; the problem is that printing the names of the objects can itself affect the way the room description is generated, foiling our debugging efforts.

What follows is a rule to help with debugging safely, and a sample of how priorities work:

paste.png "Priority Lab"

Section 1 - Procedure

Before printing the locale description (this is the dump locale table rule):
    say "Locale Priority list:";
    repeat through Table of Locale Priorities:
        let the flag be whether or not the notable-object entry is mentioned;
        say "[line break] [notable-object entry]: [locale description priority entry]";
        if the flag is false, now the notable-object entry is not mentioned;
    say line break.

Now, let's look at some items put in a specific order. Things with low priority numbers list towards the beginning; things with high priority numbers list towards the end. (It helps to think of it as though we were making a numbered list of the paragraphs to appear in the description.) Anything numbered 0 doesn't appear at all, and the default priority of an object is 1.

A thing can be early-described, late-described, latest-described, never-described, sightline-described, or ordinarily-described. A thing is usually ordinarily-described.

After choosing notable locale objects (this is the apply early and late description rule):
    repeat with item running through early-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 1; [list before everything else -- this would work with any number lower than 5 and higher than 0]
    repeat with item running through late-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 10; [list after everything else -- this would work with any number larger than 5]
    repeat with item running through never-described things:
        set the locale priority of the item to 0; [don't list at all]
    continue the activity.

An important cautionary note: priorities are only honored if the objects are going to get their own paragraphs (with "writing a paragraph about..." or because they have initial appearances). Priorities do not affect the order in which items appear in the final "You can see..." list, except that items with priority 0 or lower are omitted. (If we want to order the items in that list, we may want to resort to the Complex Listing extension by Emily Short.)

There are further refinements available to us: for instance, we could make some things that are only visible if the player is raised above ground level.

After choosing notable locale objects (this is the sightline-described things are visible from supporters rule):
    if the player is not on a supporter:
        repeat with item running through sightline-described things:
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 0; [remove objects that can only be seen from higher objects.]
    continue the activity.

It may also be useful to know about the "parameter-object", which refers to the thing whose contents we are currently describing: the standard rules consider how to describe the contents of the location and then also check the contents of any supporter or container the player may be inside, so in the first case "parameter-object" would be the location, and then in the second the supporter in question.

In practice this is rarely useful, but should we need to change priorities in the case of both player and object being inside a particular container, we might make use of it, for instance:

A thing can be tasteful or icky. A thing is usually tasteful.

After choosing notable locale objects (this is the icky things next to players rule):
    if the player is on the parameter-object:
        repeat with item running through icky things :
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 10; [remove objects that can only be seen from higher objects.]
    continue the activity.

The other thing to note is that by default that final collection of generic objects ("You can also see...") appears at the end, regardless of the priority of everything else. If we really wanted to, though, we could force something to appear even after that paragraph, by adding a new listing rule to the locale description rules:

After choosing notable locale objects (this is the latest-described items priority rule):
    repeat with item running through latest-described things:
        if the item is a notable-object listed in the Table of Locale Priorities:
            now the item is mentioned;
            now the item is marked for late listing.

The late listing rule is listed after the you-can-also-see rule in the for printing the locale description rules.

A thing can be marked for late listing. A thing is usually not marked for late listing.

This is the late listing rule:
    if something is marked for late listing:
        say "Oh! And also [a list of things which are marked for late listing].";
        now everything is not marked for late listing;
    continue the activity.

Section 2 - Scenario

The Priority Lab is a room. The early bird, the worm, the leaf, the unseen object, the pebble, the twig, and the late edition are things in the Priority Lab.

The early bird is early-described. The late edition is late-described. The unseen object is never-described.

The worm is icky.

The high window is in Priority Lab. It is sightline-described and fixed in place. The initial appearance of the high window is "There's a tiny high window up near the ceiling that you can't see unless you're on top of something."

In order for the priorities we just set to be interesting, let's give out some initial appearances and writing a paragraph rules:

The initial appearance of the worm is "A worm inches along the ground."
The initial appearance of the late edition is "Finally, the late edition lies at your feet."

Rule for writing a paragraph about the early bird when the early bird is in a room: say "The early bird always appears first, and here it is."
Rule for writing a paragraph about the leaf: say "Look, there's [a leaf][unless the leaf is in the location] on [the holder of the leaf][end if]!"
Rule for writing a paragraph about an icky thing (called icky item) which is on something which supports the player: say "Ew, [an icky item] is right next to you."

This procedure also means (as you can test by experiment) that after the late edition has been picked up and dropped again, it lists in no special order in the "you can see..." paragraph (since initial appearances only print when the object has not yet been moved).

The afterthought is a thing in the Priority Lab. It is latest-described.

The bar stool is an enterable supporter in Priority Lab.

Test me with "get leaf / drop leaf / look / x unseen object / get pebble / look / get twig / look / get afterthought / look / drop twig / look / get late edition / look / drop late edition / sit on bar stool / look / get all / put all on stool / look".

When it comes time to start manipulating the priorities of items, it is useful to be able to check the table for debugging purposes; the problem is that printing the names of the objects can itself affect the way the room description is generated, foiling our debugging efforts.

What follows is a rule to help with debugging safely, and a sample of how priorities work:

paste.png "Priority Lab"

Section 1 - Procedure

Before printing the locale description (this is the dump locale table rule):
    say "Locale Priority list:";
    repeat through Table of Locale Priorities:
        let the flag be whether or not the notable-object entry is mentioned;
        say "[line break] [notable-object entry]: [locale description priority entry]";
        if the flag is false, now the notable-object entry is not mentioned;
    say line break.

Now, let's look at some items put in a specific order. Things with low priority numbers list towards the beginning; things with high priority numbers list towards the end. (It helps to think of it as though we were making a numbered list of the paragraphs to appear in the description.) Anything numbered 0 doesn't appear at all, and the default priority of an object is 1.

A thing can be early-described, late-described, latest-described, never-described, sightline-described, or ordinarily-described. A thing is usually ordinarily-described.

After choosing notable locale objects (this is the apply early and late description rule):
    repeat with item running through early-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 1; [list before everything else -- this would work with any number lower than 5 and higher than 0]
    repeat with item running through late-described things:
        if there is a notable-object of item in the Table of Locale Priorities:
            set the locale priority of the item to 10; [list after everything else -- this would work with any number larger than 5]
    repeat with item running through never-described things:
        set the locale priority of the item to 0; [don't list at all]
    continue the activity.

An important cautionary note: priorities are only honored if the objects are going to get their own paragraphs (with "writing a paragraph about..." or because they have initial appearances). Priorities do not affect the order in which items appear in the final "You can see..." list, except that items with priority 0 or lower are omitted. (If we want to order the items in that list, we may want to resort to the Complex Listing extension by Emily Short.)

There are further refinements available to us: for instance, we could make some things that are only visible if the player is raised above ground level.

After choosing notable locale objects (this is the sightline-described things are visible from supporters rule):
    if the player is not on a supporter:
        repeat with item running through sightline-described things:
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 0; [remove objects that can only be seen from higher objects.]
    continue the activity.

It may also be useful to know about the "parameter-object", which refers to the thing whose contents we are currently describing: the standard rules consider how to describe the contents of the location and then also check the contents of any supporter or container the player may be inside, so in the first case "parameter-object" would be the location, and then in the second the supporter in question.

In practice this is rarely useful, but should we need to change priorities in the case of both player and object being inside a particular container, we might make use of it, for instance:

A thing can be tasteful or icky. A thing is usually tasteful.

After choosing notable locale objects (this is the icky things next to players rule):
    if the player is on the parameter-object:
        repeat with item running through icky things :
            if there is a notable-object of item in the Table of Locale Priorities:
                set the locale priority of the item to 10; [remove objects that can only be seen from higher objects.]
    continue the activity.

The other thing to note is that by default that final collection of generic objects ("You can also see...") appears at the end, regardless of the priority of everything else. If we really wanted to, though, we could force something to appear even after that paragraph, by adding a new listing rule to the locale description rules:

After choosing notable locale objects (this is the latest-described items priority rule):
    repeat with item running through latest-described things:
        if the item is a notable-object listed in the Table of Locale Priorities:
            now the item is mentioned;
            now the item is marked for late listing.

The late listing rule is listed after the you-can-also-see rule in the for printing the locale description rules.

A thing can be marked for late listing. A thing is usually not marked for late listing.

This is the late listing rule:
    if something is marked for late listing:
        say "Oh! And also [a list of things which are marked for late listing].";
        now everything is not marked for late listing;
    continue the activity.

Section 2 - Scenario

The Priority Lab is a room. The early bird, the worm, the leaf, the unseen object, the pebble, the twig, and the late edition are things in the Priority Lab.

The early bird is early-described. The late edition is late-described. The unseen object is never-described.

The worm is icky.

The high window is in Priority Lab. It is sightline-described and fixed in place. The initial appearance of the high window is "There's a tiny high window up near the ceiling that you can't see unless you're on top of something."

In order for the priorities we just set to be interesting, let's give out some initial appearances and writing a paragraph rules:

The initial appearance of the worm is "A worm inches along the ground."
The initial appearance of the late edition is "Finally, the late edition lies at your feet."

Rule for writing a paragraph about the early bird when the early bird is in a room: say "The early bird always appears first, and here it is."
Rule for writing a paragraph about the leaf: say "Look, there's [a leaf][unless the leaf is in the location] on [the holder of the leaf][end if]!"
Rule for writing a paragraph about an icky thing (called icky item) which is on something which supports the player: say "Ew, [an icky item] is right next to you."

This procedure also means (as you can test by experiment) that after the late edition has been picked up and dropped again, it lists in no special order in the "you can see..." paragraph (since initial appearances only print when the object has not yet been moved).

The afterthought is a thing in the Priority Lab. It is latest-described.

The bar stool is an enterable supporter in Priority Lab.

Test me with "get leaf / drop leaf / look / x unseen object / get pebble / look / get twig / look / get afterthought / look / drop twig / look / get late edition / look / drop late edition / sit on bar stool / look / get all / put all on stool / look".