It doesnât help that the various (spatial) relations arenât completely defined together in any one place in the documentation.
There are 5 mutually-exclusive basic spatial relations between objects:
support- applicable only to supporters supporting things
containment- applicable only to rooms or containers containing things, or regions containing rooms or other regions
wearing- applicable only to people wearing things
carrying- applicable only to people carrying things
incorporation-applicable to any thing incorporating any thing
(incorporation is usually asserted by phrases or conditions such as âA is a part of Bâ or âif A is a part of Bâ although âB incorporates Aâ or âA is incorporated by Bâ are equivalent ways to express the same relation).
All these basic spatial relations describe only direct spatial relationships- so (counter-intuitively) if for example A contains B, which contains C, then A does NOT contain C; similarly if A carries B, which supports C, then A does NOT carry C.
There are two shorthand spatial relations (possession and holding) that combine basic direct spatial relationships:
A person has something if he/she/it (directly) wears or carries that something. Note that the built-in verb for the possession relation is âto haveâ not âto possessâ. Note that you canât assert âJohn has the teapotâ, because Inform is unwilling to decide whether that implies that the teapot should be carried or worn.
A thing or room holds (or is the holder of) something if he/she/it (directly) supports, contains, wears, carries or incorporates that something. âTo holdâ is somewhat complicated because (unlike âto haveâ) it can be used in a narrower sense as an assertion (âJohn holds the teapotâ) in which case it means the same as âto carryâ and therefore applies only to people. However, used as a condition (if the tray holds the teapot) it can apply to any thing or room, as a shorthand for any of the basic direct spatial relations. A person can therefore hold something in three different ways- by carrying, wearing or incorporating it. A container can hold something in two ways- by containing or incorporating it. A supporter can also hold something in two ways- by supporting or incorporating it. Rooms and regions can hold something only by containing it (rooms and regions cannot incorporate things). Finally, a thing that is not a supporter, container, region, room or person can hold something only by incorporating it.
As an additional complication, although a region cannot hold a room it can hold one or more regions. Conversely, by a special rule a region can contain a room, this being the only situation where an object contains something without holding it. It follows that a room can be both contained and regionally contained by a region- indeed, if it is contained by a region, it must also be regionally contained by it (see below).
In addition to the direct basic spatial relationships there are some indirect spatial relationships:
enclosure applicable to a room or thing directly or indirectly holding a thing or to a region directly or indirectly holding a region
room-containment applicable to a room directly or indirectly holding a thing
regional-containment applicable to a region directly or indirectly regional-containing a room, or a thing enclosed by that room, or a backdrop
Because the first two of these indirect spatial relationships never specify exactly where and how the contents are held, they canât be used in assertions. You canât for example write âNow John encloses the teapotâ.
Room-containment also has no specific built-in verb. It usually appears in source as conditions like âif the Kitchen is the location of the teapotâ. You can define a verb if you like: âThe verb to locate means the room-containment relation. The verb to be located in means the reversed room-containment relationâ, after which you can write the equivalent condition âif the Kitchen locates the teapotâ or âif the teapot is located in the Kitchenâ although âif the Kitchen encloses the teapotâ or âif the teapot is enclosed by the Kitchenâ would do just as well. Note that âif the teapot is in the Kitchenâ always implies direct containment, not room-containment, so you must use âthe location ofâ or âenclosesâ or a specifically-defined verb like âlocatesâ if you want to include things indirectly contained or held by a room.
Regional-containment similarly has no built-in verb. It usually appears in source as conditions like âif the teapot is in the Mansionâ (where the Mansion is a region) or if, rarely, this leads to ambiguity as to whether âif the teapot is inâŚâ is implying containment or regional-containment- âif the teapot is regionally in an-object-that-variesâ, for example- since âan-object-that-variesâ (as an object variable) could conceivably be at various times a region, a room or a thing. The important point here is that if the Inform compiler can determine at the time of compilation that the putative âcontaining objectâ is definitely a region, it will apply a test of regional-containment rather than a test of containment. Note that the compiler can sometimes even work out that a variable must be a region, if you have created a global variable as âa region that variesâ or created a local variable to be a region with, for example, âlet my_putative_container be the Mansionâ. Conversely, the compiler cannot know whether a global variable declared to be an âobject that variesâ is currently a region or not. If the putative âcontaining objectâ is definitely a room or container, or if it might conceivably be any of a region, room or container because it is an âobject that variesâ, then the compiler will apply a test of containment.
The best relation to use in determining whether a region is directly located within another region is, counter-intuitively and despite the suggestion of the I7 documentation, not regional-containment or containment but holding. âif Region A is regionally in Region Bâ always returns false. âIf Region A is in Region Bâ or âif Region A contains Region Bâ will also return false, because (as explained above) these phrases are interpreted by the compiler as testing regional-containment. Thus, although regions holding other regions also do contain them, itâs not straightforward to test a region for containment. Use âif Region A holds region Bâ or âif Region A is the holder of Region Bâ or âif Region B is held by Region Aâ. Enclosure can be used to include indirect holding between regions, e.g. âif Region A encloses Region Bâ.
small print As noted above, it is possible to force the test of a region for containment by putting the holding region into âan object that variesâ, (or an object variable in a loop- e.g. repeat with obj_putative_container running through objectsâŚ). This can cause confusion, if you were expecting âinâ or âcontainsâ to test for regional-containment in these situations. It is also possible to force the test of a region for containment by invoking the relation explicitly in phrases such as âif the Mansion is the region which relates to the East Wing by the containment relationâ or âthe list of regions that the Mansion relates to by the containment relationâ. See §13.13 in the documentation. Generally itâs just easier to use âIf the Mansion holdsâŚâ.
Importantly, since regions cannot hold rooms, and enclosure depends on direct or indirect holding, the âcascade of enclosureâ is broken between regions and rooms, so rooms or any of their contents are never enclosed by a region. Regional containment provides the indirect relation between regions and rooms or their contents.
Although assertions locating regions within regions (âthe East Wing is in the Mansionâ or equivalently and pedantically âthe East Wing is regionally in the Mansionâ) might appear to be asserting regional containment, in fact they create the containing and holding relations. Regions can never regionally-contain other regions. Consequently, such assertions imply a direct relation: (âthe East Wing is regionally in the Mansionâ implies that the Mansion directly holds and contains the East Wing) and they can therefore only be used to place a region (or a room- see below) within a region. In the above example, the East Wing must therefore be either a room or a region, not a container or some other thing or object. In the case of locating rooms in a region, either the regional containment or containment relation can be asserted (âthe East Wing contains the Kitchenâ (containment), or âthe Kitchen is contained by the East Wingâ (containment), or âthe Kitchen is in the East Wingâ (could imply either containment or regional containment), or âthe Kitchen is regionally in the East Wingâ (regional containment) and in either case both containment and regional containment relations are created. Assertions like this canât be made in play- ânow the East Wing is regionally in the Mansionâ, ânow the Kitchen is in the East Wingâ, or ânow the East Wing contains the Kitchenâ are all disallowed, as are phrases such as âmove the Kitchen to the East Wingâ, which produce a runtime error.
The explicit uses of room-containment and regional-containment in source are limited. The I6 routine [LocationOf] is used both to define âthe location ofâ and the room containment relation (should a verb such as âto room-containâ be defined for it in source)- but in practice âthe location of an-objectâ is generally used and room-containment is left redundant. Regional-containment exists as a means both to assert the relationships of regions and rooms and to allow phrases like âif the teapot is in the Mansionâ- regions can never enclose or hold things they regionally contain- so âif the Mansion encloses the teapotâ will never be true- assuming the Mansion is a region and the teapot a thing- and âthe holder of a-roomâ is always nothing. Note also that thereâs no directly equivalent built-in phrase âthe region of an-objectâ, perhaps because unlike rooms which cannot (in the Inform sense) contain rooms, large regions can encompass one or more smaller regions, so there is not necessarily a unique answer to âwhat region is this object within?â. However, every room provides a âmap regionâ property that gives the âlowest-levelâ region (if any) that regionally contains and contains it. So âthe map region of the location of a-thingâ is available. Note that as mentioned above, the map region of a room contains and regionally-contains but does not hold that room.
To summarise the complicated potential spatial relations of regions, they can:
containâ , hold and/or enclose other regions
contain roomsÇ
regionally-contain backdrops, or rooms, or things enclosed by those rooms
â but see notes above about testing for containment of regions
Ç Note that this appears to contradict the Inform 6 Designerâs Manual 4 (DM4) which states in â§24 The World Model Describedâ that âA room is (never) containedâ- but this is due to a difference in terminology: the corresponding âlawâ, which holds equally true in Inform 7, would be âA room is (never) heldâ.
Small-print (1) doors âthe location ofâ a two-way door is usually the one out of the two rooms it links that was first mentioned in the source text, this being defined by Inform as the âfront sideâ of the door. The exception to this is if the player is in the room on the âback sideâ of the door, in which case that becomes temporarily the location of the door. The room that contains the door defaults to its âfront sideâ but subsequently, becomes the room holding the most-recently-player-facing side of the door, (which may therefore be either the front side or the back side of the door). The location of a door also usually therefore contains that door (which therefore is in that location). However, the room which is the âother sideâ of the door, being the one not most-recently-player-facing, does not hold or contain it and the door therefore is not in that room. See the Addendum for why this is so. However, a paradoxical situation can arise if the door ends up either through code (e.g. ânow the oak door is in the Libraryâ, or through automatic repositioning via the wanderings of the player, in the room that is the âback sideâ of the door when the player is not also in that room. In this instance the location of the door will default back to being reported as the âfront sideâ, but the âback sideâ rather than the âfront sideâ will still contain and hold it. Furthermore, by a special rule a two-way door is always enclosed by the rooms to both front and back. The paradox created is that the door is enclosed by one room which neither room-contains or contains or holds it, or indeed satisfies any of the basic spatial relations with it. This is the only situation in which an object encloses something it does not (directly or indirectly) hold. One-way doors are simply always contained, enclosed and held by the one room they lead from.
Small-print (2) - Backdrops are equally complicated. The I7 documentation states that a backdrop has no location and is enclosed and contained by nothing, but this is not quite true. When play begins a backdrop is contained, held but not enclosed by the room it is first declared to be found in and that room is also its location. Backdrops are the only objects not to be enclosed by a thing that holds them. If a backdrop is first declared to be found in several rooms within a single sentence, or to be found in a region, its location is the first of those rooms to be mentioned (in the source text generally, that is- not the first to be mentioned in the sentence declaring where the backdrop is to be found). Once play is underway, the location of a backdrop becomes the last room the player occupied where the backdrop was to be found- unless or until the places where the backdrop is to be found are changed and updated, or it is moved off-stage. See the Addendum for why this is so. Strangely, there is no simple condition in I7 that tests whether a backdrop will be found in a particular room when the player is not presently there. It can if required be provided by this simple example of I6 hackery-
To decide whether (B - a backdrop) is found in (R - a room): (- (BackdropLocation( {B}, {R} )) -);
Also, if a backdrop is found in one or more of the rooms regionally contained by a region, the regional-containment relation applies and the condition âif a-backdrop is regionally in a-regionâ is true- even if neither the current location of the player or the current location of the backdrop is. In this instance, the regionally of regionally in is required, not optional.
Inform also defines a number of what might be termed âcalculatedâ spatial relations, which can be tested for in conditions but not asserted:
adjacency applicable to a room which âis adjacent toâ a room
visibility applicable to a thing which âcan be seen byâ a thing
touchability applicable to a thing which âcan be touched byâ a thing
concealment applicable to a thing which âis concealed byâ a thing that holds it
These relations are determined by (sometimes complex) rules that are in part dependent on the simpler spatial relations described above (or in the case of adjacency, the various mapping relations) and they cannot therefore be simply asserted to be true or false. To make them so, the simpler spatial relations or other elements of the world state must be manipulated and/or the relevant rules must be written or altered.
As a useful shorthand, an âadjacent roomâ means one adjacent to the location of the player; a âtouchable thingâ means one the player can touch ; a âvisible thingâ means one the player can see â although the last of these, confusingly, has a subtly different meaning in the context of defining new actions:
The meaning of âvisible thingâ in Inform Many action definitions are akin to Watching is an action applying to one visible thing.
The choice of the word âvisibleâ in action definitions to distinguish objects anywhere in the universe that the player is allowed to refer to (by way of contrast to those that are merely touchable, or actually carried), is one of the more confusing syntax features of Inform, as in this special context âvisibleâ can sometimes include things which the player cannot see. This is compounded by the parallel existence of a visibility relation that also makes use of the adjective âvisibleâ and which has a meaning that is both subtly different and more conventional. Any object, whether conventionally visible or not, that is brought âinto scopeâ, as Inform puts it, is a âvisible thingâ in the context of action definitions. If this were not the case, the player would not ordinarily (but see discussion of âany (description of objects)â below) be able to invoke actions involving objects that are not physically enclosed by the same room as the player, the latter representing the absolute limits of conventional visibility.
Likewise the use of the word âthingâ in action definitions to mean âobjectâ- when elsewhere âthingâ means a subgroup of objects that, in the basic world model, are not rooms, directions or regions (see the Kinds tab in the Index of the Inform documentation).
In summary, in the context of action definitions, and action definitions alone, âvisible thingâ actually means âany object the player is allowed to refer toâ. or, in more technical Inform-speak, âany object in scopeâ
Objects that âcan be seen by the playerâ (and which therefore satisfy the âvisibility relationâ and can be referred to in descriptions and conditions as âvisibleâ objects) are usually âin scopeâ and vice versa, but there are multiple exceptions- for example in the dark, the playerâs possessions are in scope but not visible.
Note that the use of the qualifier âanyâ applied to objects (or descriptions of objects) appearing in tokens of grammar lines, e.g. â[any door] or [any closed container]â, allows them to override the requirement for âvisible thingsâ to be in scope (or, looked at another way, brings said objects into scope for that particular action). 'Understand âopen [any closed container] as remote openingâ thereby allows the âremote openingâ action to be invoked on any closed container, in-or-out-of-play, anywhere in the game universe, whether in scope or not. Possibly more usefully, [any room], [any adjacent room] etc. therefore allow the player to invoke actions referring to rooms, which are never ordinarily in scope and thus are not ordinarily âvisible thingsâ.
Note also that âin playâ has a technical meaning in Inform as an adjective that can be applied to objects, which is that the object in question is enclosed by a room. Even objects that by this definition are âout of playâ, such as directions, or other objects created âoff-stageâ or âremoved from playâ to ânowhereâ may be considered âvisible thingsâ in the context of action definitions if the scoping rules decide that they are nevertheless âin scopeâ. An âout of playâ object can also be said to âbe nowhereâ and an âin play objectâ to âbe somewhereâ.
Adjacency A room is adjacent to another room if it is possible to move directly from one to the other either by a mapped direction or through a door (even if the door is currently closed and locked). Although the documentation states that adjacency applies only to two rooms, possibly as a bug it also sometimes applies to a room and a door, but that fact probably shouldnât be relied upon.
Concealment The definition of concealment (as an adjective) is that a thing is concealed if its holder conceals it. The relation of concealment is governed by the verbs â concealsâ or âis concealed byâ through the activity âdeciding the concealed possessionsâ, which by default is an empty rulebook, meaning that nothing is concealed. New rules written regarding certain things (such as âMr Darcyâ), or things grouped under a description (such as âa personâ), or even the all-encompassing âsomethingâ, can decide according to any criteria they choose that they conceal any other given thing. The potentially concealed thing under consideration when the activity is run is called âthe particular possessionâ. An example rule might begin Rule for deciding the concealed possessions of a person who is wearing a cloak:
Anomalous treatment of concealment invoked by adjective vs. verb If a question regarding concealment is phrased using âconcealedâ as an adjective e.g. âif the pistol is concealedâ or âa list of concealed things in the locationâ the âdeciding the concealed possessionsâ activity is called regarding the holder of e.g. the pistol, or the holder of each of the things in the location in turn, so that only rules in the activity rulebook matching the holder (in the first example, if the holder of the pistol wears a cloak) will be considered. However, if the question is phrased as a condition regarding described or specified âconcealer(s)â and with âconcealâ as a verb, e.g. âif Mr Darcy conceals the pistolâ or âif the pistol is concealed by a womanâ âthereby invoking the concealment relation directly- the activity is called (in the first example) regarding Mr Darcy- and if Mr Darcy is wearing a cloak, the above rule will be considered whether or not Mr Darcy holds the pistol. If the rule itself does not question whether or not Mr Darcy is actually the holder of the particular possession (the pistol), it may in theory decide he is concealing a pistol that is not even in the same room.
The simplest way round this potential anomaly is either to always work with the âconcealedâ adjective, or to ensure that rules for deciding the concealed possessions of something can only report a positive decision if the âparticular possessionâ is actually held by the âconcealerâ under consideration. A good way to enforce this restriction is to include it in the opening declaration of the rule, e.g. âRule for deciding the concealed possessions of a person (called the concealer) who holds the particular possession when the concealer is wearing a cloak:â
Indirect concealment Note that Informâs default strict definition of concealment can be counter-intuitive with regard to indirectly held things- it only allows something to conceal things it directly holds: a person carrying a bag can never conceal something that is inside the bag, even if the bag is itself concealed. If this is undesirable, with a little rewording, this can be changed so that indirectly held things can also be concealed e.g.
Rule for deciding the concealed possessions of a person (called the concealer) who encloses the particular possession when the concealer is wearing a cloak:
Definition: a thing is concealed if something which encloses it conceals it or something which encloses it is concealed.
Useful undocumented phrases. There also exist a number of useful built-in but undocumented phrases that work with spatial relations, although they donât define new relations:
the component parts core of (an object) is the enclosing object (thing, container, supporter or person) most closely related to it solely through direct or indirect incorporation- in other words, the object it is ultimately directly or indirectly a part of. For example, if a button is part of a control panel, which is part of a remote control, which is in a drawer, which is itself part of a cabinet, which is part of a bookcase in the Library, the component parts core of the button would be the remote control. The component parts core of the drawer is the bookcase. The idea here is that parts of things are considered to be represented by the whole and here the button is ultimately a part of the remote control. The component parts core of an object which is not a part of anything is itself. The component parts core of nothing is nothing.
the not-counting-parts holder of (a thing) (note the hyphens) is the object (thing, container, supporter, person or room) most closely related to it through direct or indirect holding, but skipping over any intervening things related by incorporation. In other words, the not-counting-parts holder of a thing is the component parts core of the holder of its component parts core. Again, the idea is that parts of things are considered to be represented by the whole. In the above example, the not-counting-parts holder of the button is the bookcase. The button is ultimately a part of the remote control, which is held by the drawer which is ultimately part of the bookcase. If nothing holds the component parts core of something, the not-counting-parts holder of it is nothing.
the common ancestor of (one object) with (another object) (note âwithâ not âandâ) is the object (room or thing or region) most closely related through holding to both items. For example, if a hat is worn by a cat, which is in a cage, which is part of a display case, which is on the bookcase described in the previous paragraph, which is in the Library, the common ancestor of the hat and the button will be the bookcase. If a display is part of the remote control, the common ancestor of the button with the display will be the remote control. The common ancestor of the hat and the cage is the cage. If there is no common ancestor, because for example they are things are in different rooms, or one or the other is off-stage, the common ancestor is nothing. The common ancestor of something with nothing is nothing. The common ancestor of something with itself is itself.
Note that because there is no holding relation between rooms and regions, a region cannot be the common ancestor of a room or anything enclosed by a room- a region can only be the common ancestor of two regions.
The visibility-holder of (an object) If the object is a closed, opaque container then its visibility-holder is nothing. Otherwise, it is the not-counting-parts holder of the object. The idea is that starting from the standpoint of a given object, one can move up through the hierarchy of visibility-holders until reaching one whose visibility-holder is nothing. That final visibility-holder provides the outer limit of visibility (called the visibility ceiling) from the standpoint of the original given object, which will be either the location or a closed, opaque container enclosing the original given object. The visibility-holder of nothing is nothing.
This idea is used by the Standard Rules when determining what of her surroundings the player can see- usually in preparation for printing locale descriptions- using the phrase âCalculate visibility ceiling at low levelâ in which case the âoriginal given objectâ is the player and the results are stored in a variable called âvisibility ceiling calculatedâ. Also, the number of steps taken to get from the player to the âvisibility ceiling calculatedâ is stored in the variable âvisibility ceiling count calculatedâ. In the case of the player being directly held by a lighted location, the visibility ceiling calculated is the location and the visibility ceiling count calculated will be 1. If the player is on a table inside an open cage in the location, visibility ceiling calculated is the location and the visibility ceiling count calculated will be 3. If the player is standing holding a light source on a chair inside a closed, opaque cupboard in the location, visibility ceiling calculated is the cupboard and the visibility ceiling count calculated will be 2. If the player gets down off the chair, visibility ceiling calculated is the cupboard and the visibility ceiling count calculated will be 1. If the player then opens the cupboard, the visibility ceiling calculated is the location and the visibility ceiling count calculated will be 2. In the special case of the player being in darkness, the visibility ceiling calculated is the darkness object and the visibility ceiling count calculated is 0.
The touchability ceiling of (an object) is the enclosing object (room, supporter, container or person) most distantly related through touchability. This is calculated in a similar way to the visibility ceiling (see previous paragraph) except via a hierarchy of not-counting-parts holders that the âreaching outsideâ rulebook decides can be reached out through. By default, only reaching out of closed containers is disallowed by this rulebook, so the touchability ceiling will usually be either the location or the first closed container encountered in moving up through the hierarchy. The touchability ceiling of something whose component parts core (see above) is held by nothing (i.e. is off-stage) is its component parts core. Similarly, if the last object encountered in the hierarchy is not a room but nevertheless is held by nothing (i.e. it is off-stage) that object is the touchability ceiling. The touchability ceiling of nothing is nothing.
See also Addendum belowâŚ