Some objects, such as a pair of shoes or a flight of stairs could be regarded as either singular or plural and referred to as either 'it' or 'them'. Set ambiguouslyPlural to true for such objects.

Disambiguation prompt grouping. When the parser generates a disambiguation question ("Which did you mean, the red book, or the blue book?"), it'll group the objects in the list by common disambigGroup values. The group is just an arbitrary value that keeps like objects together in the list. You can use a string, a class, or whatever you like for this, as long as grouped objects have the same value in common. We give this property a default value of 0 so that the disambigOrder will work by default without the need to specify a disambigGroup.

Do we want to test for phrase matches when disambiguating? We'll assume that by default we do since the same reasons for wanting the phrase match are likely to apply when disambiguating, and that we'll use the same set of phrases. This can be overridden to supply a different set of phrases or none.

The object's disambiguation name. This is a more detailed version of the name, for situations where the short name is ambiguous. For example, the parser displays this name in "Which do you mean" questions when it would help tell two of the listed objects apart.

By default, this is the same as the short name. It's uncommon to override this, since short names are typically already detailed enough for most purposes. Every so often, though, you'll want to keep the short name very terse, so you'll leave out some distinguishing detail that it *could* have had. In such cases, you can add the distinguishing detail here, so that it's displayed only when it's really needed.

Disambiguation prompt sorting. This gives the display order of this item within its disambiguation group, if it has one. The parser sorts objects within each group in ascending order of this value when generating the object list for a disambiguation question. This is simply an integer; the default is 1 for every object, which makes the ordering arbitrary.

This property is useful for grouped objects with a natural ordering, such as items with sequential labels of some sort (numbers, letters, etc). You can use this property to ensure that lists of these items will be displayed in the natural order: "button 1, button 2, or button 3?" or "the door on the left, the door in the middle, or the door on the right?"

Can I be distinguished in parser messages by my contents? If so, we can be distinguished (in parser messages) from similar objects by our contents, or lack thereof: "bucket of water" vs "empty bucket". If this is true, our nominalContents property determines the contents we display for this.

The object's grammatical gender(s). This information is used to determine which pronouns can match the object as an antecedent, which pronouns should represent it in output, and (for some languages) which articles and other gender-agreement words should be used in conjunction with the object name in output.

The default is neuter. Use isHim and isHer to give an object masculine and/or feminine gender. Use isIt to explicitly give an object neuter gender. By default, we infer isIt from isHim and isHer: we assume the object is neuter if it's not masculine or feminine.

Languages that have grammatical gender will almost certainly want to parse articles in the 'vocab' property to make it more convenient to encode each object's gender. For example, a French implementation could parse 'le' or 'la' at the start of a vocab string and set isHim and isHer accordingly.

The English library sets isHim and isHer if 'him' and 'her' (respectively) are found in the object's pronoun list. (This is the most convenient way to represent gender via the vocab string in English, since English doesn't have gendered articles.)

Note that we define the genders as three separate properties, so the genders are NOT mutually exclusive - an object can be a "him", a "her", and an "it" at the same time. This is because a single object can have multiple grammatical genders in some languages. In English, for example, an animal can be referred to as gendered (matching its physical gender) or neuter; and a few inanimate objects have a sort of optional, idiomatic gender, such as referring to a ship or country as "her".

Some languages might need additional genders. When needed, LMentionable should simply define suitable additional properties.

In most gendered languages, the grammatical gender is an attribute of the noun, not of the object. In particular, if an object has two nouns in its vocabulary, the two nouns might be of different genders. The language module might therefore limit the use of isIt et al to the gender of the object's name string as it appears in output (e.g., for selecting an article when showing the name in a list, or selecting a pronoun to represent the object), and use a completely different scheme to tag the gender of individual vocabulary words. One approach would be to use separate mNoun and fNoun token properties (and more if needed) to distinguish the gender of individual nouns in the dictionary.

The object's name is a mass noun. A mass noun is a word that has singular form but represents an indeterminate quantity or group of something, such as "sand" or "furniture".

In English, mass nouns use "some" as the indefinite article rather than "a" (some sand, not a sand). Their plural usage tends to differ from regular nouns, in that they already carry a sense of plurality; if you have two distinct piles of sand, the two together are usually still just "sand", not "two sands".

When a mass noun is awkward as an object's name, you can often make it into a regular noun by naming its overall form. "Sand" is a mass noun, but recasting it as "pile of sand" makes it an ordinary noun. (The generic way to do this for a homogeneous substance is to add "quantity of".)

A single-quoted string, or a list of single-quoted strings containing exact phrases (i.e. sequences of words) that must be matched by the player input if any of the words in the phrase matches appear in the player input. Note that words defined here should also be defined in the vocab property; the purpose of the matchPhrases property is to limit matches. Note also that object will be matched if any of the phrases in the list is matched.

If failing to match any of the match phrases (when the player's input includes at least one word used in any of them) excludes a match, then return nil

The object's short name, for display in lists and announcements. By default, this is automatically derived from 'vocab', so you usually don't have to set it directly. If you define a non-nil 'name' value manually, though, it takes precedence (i.e., the library won't replace it with the name implied by 'vocab').

My nominal contents is the special contents item we can use in naming the object. This is useful for containers whose identities come primarily from their contents, such as a vessel for liquids or a box of loose files. Returns an object that qualifies the name: a "water" object for BOX OF WATER, a "files" object for BOX OF FILES. Nil means that the object isn't named by its contents.

Note that this is always a single object (or nil), not the whole list of contents. We can only be named by one content object. (So you can't have a "box of books and papers" by having separate nominal contents objects for the books and the papers; although you could fake it by creating a "books and papers" object.)

The grammatical person of narration relative to this object. Use 1 for first person ("I am in a cave"), 2 for second person ("You are in a cave"), and 3 for third person ("Bob is in a cave").

Usually, every object in the game will be in the third person - *except* the player character object, which is usually in the second person. The library doesn't care which person you use for the player character, though - you're free to use first or third person if you prefer. First-person and third-person IF are relatively uncommon, but not unheard of.

This property is used for verb agreement when library messages are generated. This ensures that library messages adapt to the correct narrative person of the story automatically. To write a first-person game, you don't have to replace all of the default messages, but simply set person=1 in your PC object.

The object's name's grammatical number. This specifies singular or plural usage for the object's name when it appears in generated messages. By default, an object has singular usage, so it'll appear as (for example) "an orange". Some objects have names with plural usage, either because they're words that always appear in the plural (such as "scissors"), or because the game object represents a group of items that are too numerous and unimportant to the game to actually implement as separate Thing objects. For example, the books in a library might be implemented collectively as a single "books" object.

The English library sets this to true if 'them' is listed as a pronoun for the object in the 'vocab' property.

Is this object's short name a proper name? A proper name is the name of a person, place, or other unique entity with its own name.

This property controls how the library shows the object's name in generated messages. In English, for example, articles (a, the) aren't used with a proper name.

The English library tries to infer whether the object has a proper name based on the 'vocab' string: if all the words in the short name are capitalized, we'll consider it a proper name. This rule of thumb doesn't always apply, though, so you can override it: simply set 'proper' explicitly in an individual object, and the setting will take precedence over whatever the name's capitalization would otherwise imply. (Other languages might have different rules for inferring 'proper', and some might not be able to infer it at all.)

The object's name is "qualified" grammatically, meaning that it can't be combined with articles (a, the) or possessives. Proper names are considered to be qualified, but it's possible for a name to be qualified but not proper, such as a name that incorporates a possessive.

My room title. This is displayed as the start of the room headline, which is the first line of the room description when 'self' is the outermost visible container of the point-of-view actor. The headline is also conventionally shown on the status line whenever the player is in the location.

The room title essentially serves as a label for the room on the player's mental and/or paper map of the game's geography. It's usually something short and pithy that sums up the room's essence, function, or appearance, and is usually written in title case: Ice Cave, Bank Lobby, Front of House, Transporter Room 3, etc.

The room headline sometimes adds more status information to the title, such as the point-of-view actor's direct container when the actor is inside an intermediate container within the room, such as a chair.

the State objects applying to this object

'vocab' is a string that we use to initialize the object's short name, dictionary words, grammatical gender, and grammatical number (singular/plural). This is designed to make it as convenient as possible to describe the object's name and grammatical behavior for input and output purposes.

The syntax is language-specific - see initVocab() for details.

Vocabulary word list. This is a vector of VocabWord objects that we build in initVocab(), giving the individual words that this object uses for its noun phrase vocabulary.

On dynamically creating a new object, do the automatic vocabulary and short name initialization.

The filterResolveList method allows this object to remove itself or other objects from the list of resolved objects.

np is the noun phrase, so np.matches gives the current list of matches, and np.matches[i].obj gives the ith object match. To change the list of matches, manipulate the np.matches list.

cmd is the command object, so that cmd.action gives the action about to be executed.

mode is the match mode.

By default we do nothing here.

Match the object to a noun phrase in the player's input. If the given token list is a valid name for this object, we return a combination of MatchXxx flag values describing the match. If the token list isn't a valid name for this object, we return 0.

By default, we call simpleMatchName(), which matches the name if all of the words in the token list are in the object's vocabulary list, regardless of word order.

In most cases, an unordered word match works just fine. The obvious drawback with this approach is that it's far too generous at matching nonsense phrases to object names - DUSTY OLD SPELL BOOK and BOOK DUSTY SPELL OLD are treated the same. In most cases, users won't enter nonsense phrases like that anyway, so they'll probably never notice that we accept them. If they enter something like that intentionally, we can plead Garbage In/Garbage Out: a user who willfully types a nonsense command has only himself to blame for a nonsense reply.

Occasionally, though, there are reasons to be pickier. When these come up, you can override matchName() to be as picky as you like.

The most common situation where pickiness is called for is when two objects happen to share some of the same vocabulary words, but certain words orderings clearly refer to only one or the other. With the unordered approach, this can be a nuisance for the player because it can trigger disambiguation questions that seem unnecessary. Overriding matchName() to be picky about word order for those specific objects can often fix this. In this implementation the matchPhrases property can be used for this purpose.

Another example is ensuring the user knows the correct full name of an object as part of a puzzle: you can override matchName() to make sure the user doesn't accidentally stumble on the object by using one of its vocabulary words to refer to something else nearby. Another example is matching words that aren't in the vocabulary list, such as a game object that represents a group of apparent objects that have a whole range of labels ("post office box 123", say).

Match a name against a list of tokens entered by the player. phrases is the list of match phrases defined on the object (either for initial matching or for disambiguation) and excludes should be true or nil depending on whether failure to match phrases should exclude a match overall.

Match the object to a noun phrase in *disambiguation* input. This checks words in the player's reply to a "Which one did you mean...?" question from the parser. When the player replies to this kind of question, they usually don't respond with the full name, but with just an adjective or two.

Now, you might think we should handle these replies by just appending them to the original noun phrase in the input. But we can't just do that: matchName() *could* care about the order of the words in the noun phrase, so we can't just assume that we can stick them in somewhere and still have a valid name for the object. So, instead of doing that, we call this routine with the phrase from the player's answer to the "Which one" question. Since this routine knows that the new words aren't part of the original phrase, it can deal with them as it sees fit with respect to word order.

The default here, of course, is to do the same thing as the default matchName(): we simply call simpleMatchName() to match the input to the object vocabulary, ignoring word order. This will usually work even when matchName() is overridden to care about word order, since the added words here are just serving to distinguish one object from another.

If we have any phraseMatches defined, check whether we fail to match any of them. This will be the case if we find a phraseMatch containing one of our tokens but not the rest in the right order.

Simple implementation of matchName(), which simply checks to see if all of the tokens are associated with the object. The "simple" aspect is that we don't pay any attention to the order of the words - we simply check that they're all in the object's vocabulary list, in any order.