#@x
A couple of utility macros we use internally for turning macro values into strings. STRINGIZE(x) expands any macros in its argument and then turns the result into a single-quoted string, which can then be used in regular program text or in directives that evaluate constant expressions, such as #if. (STRINGIZE is the real macro; _STRINGIZE is needed to force expansion of any macros in the argument, which is required because of the weird ANSI C expansion-order rules, and which works because of same.)

#@x
A couple of utility macros we use internally for turning macro values into strings. STRINGIZE(x) expands any macros in its argument and then turns the result into a single-quoted string, which can then be used in regular program text or in directives that evaluate constant expressions, such as #if. (STRINGIZE is the real macro; _STRINGIZE is needed to force expansion of any macros in the argument, which is required because of the weird ANSI C expansion-order rules, and which works because of same.)

throw new AbortActionSignal()
a concise macro to throw an Abort signal

throw new AbortImplicitSignal()
a concise macro to throw an AbortImplicitSignal

0x0001 /* plain text hyperlink (no underline/color) */
aHref() flags

{ \
preCond { return preCond##obj##Action; } \
verify() { verify##obj##Action; } \
remap() { return remap##obj##Action; } \
check() { check##obj##Action; } \
action() { action##obj##Action; } \
report() { report##obj##Action; } \
}
Treat an object definition as equivalent to another object definition. These can be used immediately after a dobjFor() or iobjFor() to treat the first action as though it were the second. So, if the player types "search box", and we want to treat the direct object the same as for "look in box", we could make this definition for the box:

dobjFor(Search) asDobjFor(LookIn)

Note that no semicolon is needed after this definition, and that this definition is completely in lieu of a regular property set for the object action.

In general, a mapping should NOT change the role of an object: dobjFor(X) should not usually be mapped using asIobjFor(Y), and iobjFor(X) shouldn't be mapped using asDobjFor(Y). The problem with changing the role is that the handler routines often assume that the object is actually in the role for which the handler was written; a verify handler might refer to '{dobj}' in generating a message, for example, so reversing the roles would give the wrong object in the role.

Role reversals should always be avoided, but can be used if necessary under conditions where all of the code involved in the TARGET of the mapping can be carefully controlled to ensure that it doesn't make assumptions about object roles, but only references 'self'. Reversing roles in a mapping should never be attempted in general-purpose library code, because code based on the library could override the target of the role-reversing mapping, and the override could fail to observe the restrictions on object role references.

Note that role reversals can almost always be handled with other mechanisms that handle reversals cleanly. Always consider Doer.doInstead() first when confronted with a situation that seems to call for a role-reversing asObjFor() mapping, as doInstead() specifically allows for object role changes.

{ \
preCond { return preCond##obj##Action; } \
verify() { verify##obj##Action; } \
remap() { return remap##obj##Action(); } \
check() { check##obj##Action; } \
action() { } \
}
Define mappings of everything except the action. This can be used in cases where we want to pick up the verification, preconditions, and check routines from another handler, but not the action. This is often useful for two-object verbs where the action processing is entirely provided by one or the other object, so applying it to both would be redundant.

1
Communication Link Types

AudioLink means audio communication only is available VideoLink means both audio and visual links are available.

checkFeelMsg
Define some synonyms for potentially confusing property names

name: ##baseClass \
baseActionClass = name
Define an action OBJECT with the given name inheriting from the given base class, for use with the Mercury parser.

DefineAction(name, IAction)
Define a concrete IAction, given the root name for the action. We'll automatically generate a class with name XxxAction.

DefineAction(name, SystemAction)
Define a "system" action. System actions are meta-game commands, such as SAVE and QUIT, that generally operate the user interface and are not part of the game world.

DefineTActionSub(name, TAction)
Define a concrete TAction, given the root name for the action. We'll automatically generate a class with name XxxAction, a verProp with name verXxx, a checkProp with name checkXxx, and an actionProp with name actionDobjXxx.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
remapDobjProp = &remapDobj##name \
preCondDobjProp = &preCondDobj##name \
checkDobjProp = &checkDobj##name \
actionDobjProp = &actionDobj##name \
reportDobjProp = &reportDobj##name \

Define a concrete TAction with a specific base class.

DefineTIAActionSub(name, TIAAction)
The following macros relating to the TIAAction class are only relevant when the TIAAction extension is used. The macros are nevertheless included here for convenience when using the TIAAction extension.

Define a concrete TIAAction, given the root name for the action. We'll automatically generate a class with name XxxAction, a verDobjProp with name verDobjXxx, a verIobjProp with name verIobjxxx, a checkDobjProp with name checkDobjXxx, a checkIobjProp with name checkIobjXxx, an actionDobjProp with name actionDobjXxx, and an actionIobjProp with name actionIobjXxx.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
verIobjProp = &verifyIobj##name \
verAobjProp = &verifyAobj##name \
remapDobjProp = &remapDobj##name \
remapIobjProp = &remapIobj##name \
remapAobjProp = &remapAobj##name \
preCondDobjProp = &preCondDobj##name \
preCondIobjProp = &preCondIobj##name \
preCondAobjProp = &preCondAobj##name \
checkDobjProp = &checkDobj##name \
checkIobjProp = &checkIobj##name \
checkAobjProp = &checkAobj##name \
actionDobjProp = &actionDobj##name \
actionIobjProp = &actionIobj##name \
actionAobjProp = &actionAobj##name \
reportDobjProp = &reportDobj##name \
reportIobjProp = &reportIobj##name \
reportAobjProp = &reportAobj##name \

Define a concrete TIAction with a specific base class.

DefineTIActionSub(name, TIAction)
Define a concrete TIAction, given the root name for the action. We'll automatically generate a class with name XxxAction, a verDobjProp with name verDobjXxx, a verIobjProp with name verIobjxxx, a checkDobjProp with name checkDobjXxx, a checkIobjProp with name checkIobjXxx, an actionDobjProp with name actionDobjXxx, and an actionIobjProp with name actionIobjXxx.

DefineAction(name, cls) \
verDobjProp = &verifyDobj##name \
verIobjProp = &verifyIobj##name \
remapDobjProp = &remapDobj##name \
remapIobjProp = &remapIobj##name \
preCondDobjProp = &preCondDobj##name \
preCondIobjProp = &preCondIobj##name \
checkDobjProp = &checkDobj##name \
checkIobjProp = &checkIobj##name \
actionDobjProp = &actionDobj##name \
actionIobjProp = &actionIobj##name \
reportDobjProp = &reportDobj##name \
reportIobjProp = &reportIobj##name \

Define a concrete TIAction with a specific base class.

sig##Signal: Signal \
name = #@nam\
handleProp = &handle_##sig
Definitions for the Signals Extension

message(#@id, txt, ##args)
DMsg() - default English library message cover macro.

Whenever the library displays a message, it uses the DMsg() macro. The arguments are a message ID, and the default English message text to display. The message ID is a string that identifies the message; this is used to look for overriding customizations of the message. Refer to the CustomMessages class for information on customizing the standard library messages.

In our approach, the library defines the default English text of the messages in-line, directly in the code. On the surface, this is contrary to standard practices in most modern programming projects, which strive to make translations easier by separating the message text from the program code, gathering all of the text into a central message file that can be replaced for each language. Despite appearances, we're accomplishing the same thing - but in our system, we have the advantage that we *also* define the default English message text in-line as part of the code it applies to. This makes it easier to read the code by keeping a message and its full context in one place; this way you don't have to shuttle between the code and message file.

Here's how we accomplish the message separation required for translations, and also for games that wish to customize the library defaults. The DMsg() macro requires both the default English message text *and* an ID key for the message. The message display function receives both. The display function proceeds to look up the ID key in a translation table; if it finds an entry, it uses the version of the message in the translation table instead of the English default passed in via DMsg(). A language module can provide a message table that defines the language translations, and a game can provide a table that further customizes the library messages to fit its narrative style.

There's one additional element. Translators and game authors need to be able to see all of the messages in one place, so they can create their tables. We would seem to lack that central list of English messages. Fortunately, by using a standard macro for each message, we can extract a comprehensive English message list automatically via a special tool. We use this as part of the library release process to create the English message file for reference.

Note that the macro expansion includes the default English text only in English builds. It omits the text in non-English builds. This is to save space - we assume that the English messages will all be overridden anyway by each translated library version, so there's no point in including their text in the final compiled program.

nounList->dobjMatch
Also add a couple of synonyms familiar froma adv3

throw new ExitSignal()
a concise macro to throw an ExitSignal

throw new ExitActionSignal()
a concise macro to throw an ExitActionSignal

throw new ExitCommandLineSignal()
Terminate execution of the command line. This aborts the current command, including any remaining object iterations for the current action, and discards anything else on the command line.

(libGlobal.curAction)
the Action object of the command being executed

(gAction != nil \
&& (action#foreach/gAction.ofKind(action)/||/))
is the current global action ANY of the specified actions?

(gAction != nil && gAction.ofKind(action))
Determine if the current global action is the specified action. Only the action prefix is needed - so use "Take" rather than "TakeAction" here.

This tests to see if the current global action is an instance of the given action class - we test that it's an instance rather than the action class itself because the parser creates an instance of the action when it matches the action's syntax.

(nilToList(gCommand.action.actionList))
the list of objects involved in the action just completed

(object: Thing \
{ \
plural = (gAction.reportList.length > 1 || \
gAction.reportList[1].plural); \
isIt = (gAction.reportList.length == 1 ? \
gAction.reportList[1].isIt : nil);\
isHim = (gAction.reportList.length == 1 ? \
gAction.reportList[1].isHim : nil);\
isHer = (gAction.reportList.length == 1 ? \
gAction.reportList[1].isHer : nil);\
name = gActionListStr; \
qualified = true; \
} )
an object that is singular or plural according to whether gActionList represents a single object of a plurality of objects, and which picks up the correct gender if there is only a single object.

makeListStr(gCommand.action.reportList, &theName)
a displaying string version of the above

(libGlobal.curActor)
the actor performing the current command

(gCommand == nil || gCommand.verbProd == nil ? [] \
: gCommand.verbProd.tokenList.mapAll({t: getTokVal(t)}))
Get the command tokens for the current command.

(gAction.curDobj)
For convenience, define some macros that return the current direct and indirect objects from the current action. The library only uses direct and indirect objects, so games that define additional command objects will have to add their own similar macros for those.

(libGlobal.exitListerObj)
the exit lister object - if the exits module isn't included in the game, this will be nil

(libGlobal.extraHintManagerObj)
the extra hint manager object - if the hints module isn't included in the game, this will be nil

(libGlobal.hintManagerObj)
the hint manager object - if the hints module isn't included in the game, this will be nil

(getActor.informedAbout(key))
has a topic key been revealed to an NPC through <.inform>?

(libGlobal.lastAction)
The previous action and command

(libGlobal.libMessageObj)
The current library messages object. This is the source object for messages that don't logically relate to the actor carrying out the comamand. It's mostly used for meta-command replies, and for text fragments that are used to construct descriptions.

This message object isn't generally used for parser messages or action replies - most of those come from the objects given by the current actor's getParserMessageObj() or getActionMessageObj(), respectively.

By default, this is set to libMessages. The library never changes this itself, but a game can change this if it wants to switch to a new set of messages during a game. (If you don't need to change messages during a game, but simply want to customize some of the default messages, you don't need to set this variable - you can simply use 'modify libMessages' instead. This variable is designed for cases where you want to *dynamically* change the standard messages during the game.)

(gPlayerChar.location)
get the player character's location

(gAction.setMessageParams(var#foreach/#@var, var/,/))
Some message processors add their own special parameters to messages, because they want to use expansion parameters (in the "{the dobj/him}" format) outside of the set of objects directly involved in the command.

The Action method setMessageParam() lets you define such a parameter, but for convenience, we define this macro for setting one or more parameters whose names exactly match their local variable names. In other words, if you call this macro like this:

gMessageParams(obj, cont)

then you'll get one parameter with the text name 'obj' whose expansion will be the value of the local variable obj, and another with text name 'cont' whose expansion is the value of the local variable cont.

doInstead(Go, dirn##Dir)
Convenience macros for synthesizing travel in a given compass direction

(libGlobal.playerChar)
get the current player character Actor object

(libGlobal.setRevealed(key))
reveal a topic key, as though through <.reveal>

(libGlobal.revealedNameTab[key] != nil)
has a topic key been revealed through <.reveal>?

(gPlayerChar.getOutermostRoom)
get the player character's current room (which may or may not be the same as his/her location)

(gPlayerChar.setKnowsAbout(obj))
mark a Topic/Thing as known/seen by the player character

(gAction != nil && gAction.ofKind(Travel) && gAction.direction == dirn ## Dir)
is the current action a Travel action going dirn

(libGlobal.totalTurns)
get the current turn count

(gCommand.getCommandPhrase())
Get the command phrase for the current command.

(gCommand == nil || gCommand.verbProd == nil ? '' \
: getTokVal(gCommand.verbProd.tokenList[1]))
Get the first word the player entered for the current command.

gAction.verifyList
Macros for use in verify routines, returning various kinds of verify results

if (DebugCtl.enabled[#@key]) { code; } else { }
Debugging. When we compile in development mode, we'll include a number of functions and methods that display information for debugging purposes. We omit these in release builds to keep the compiled file size smaller, and to avoid making it too easy for end users to snoop around in the program internals.

gAction.addVerifyResult(new VerifyResult(40, msg, nil, self))
IllogicalAlready doesn't do anything different from IllogicalNow in adv3Lite, but is supplied so that game authors familiar with adv3 can use it without getting a compilation error. It may also be slightly useful for documentary purposes to clarify why a verify routine in game code is ruling out an action.

1
Define convenient named constants for use with ConvAgendaItem

isEdible
The library uses isEdible rather than isEatable, since edible is the more natural word to use, but strict consistency might have dictated isEatable, so we make it an effective synonym in case some game authors use it.

isDrinkable
Conversely, authors alive to the Latin root of edible might try the latinate isPotable instead of isDrinable.

1
The indices for the key values used to navigate menus, which are held in the keyList array of MenuItems.

0x0002
matched an adjective (the phrase contains at least one adjective)

0x1000
all words were matched WITHOUT character approximations (such as matching 'a' to 'a-umlaut')

0x2000
all words were matched WITHOUT truncation

0x0004
matched a noun (the phrase contains at least one noun word)

0x0FFF
mask to select only the part-of-speech flags

0x0010
matched a phrase

0x0008
matched a plural (the phrase contains at least one plural word)

0x0001
matched a preposition (the phrase contains at least one preposition)

0xF000
mask to select only the match-strength flags

0x0001
matched a weak token (which we'll treat as equivalent to matchimg a preposition).

inputManager.pauseForMore()
Define some macros to give abbreviated synonyms to inputManager method

#@id, txt
Msg() - define a custom message to override a library message. 'id' is the message ID, which is the same ID used for the DMsg() message that you wish to override. Do NOT use quotes around the ID - just enter it as though it were a variable name. 'txt' is the message text, as a single-quoted string.

This is used in CustomMessages objects to define message overrides. See CustomMessages for full details.

return null
Convenient abbreviations for rules that want to allow their RuleBook to continue processing more rules.

0x0002
This object was chosen arbitrarily from a larger set, because the noun phrase construction says we should do so. This flag is set when the noun phrase is something TAKE A BOOK or TAKE ANY OF THE BOOKS.

0x0008
We selected an object as a default. This is set when the player leaves out a noun phrase, but we can guess what was probably meant based on context: e.g., ASK ABOUT THE HOUSE is probably directed to Bob if Bob is the only person nearby.

0x0001
The noun phrase required disambiguation, because more than one object was in scope that matched the noun phrase. We were able to figure out which one(s) the player meant from context, without having to ask the player for help.

For example, there are two doors in the room, one open and one closed. The player types OPEN DOOR. It's fairly obvious that they must be talking about the closed door. So, we choose that object and set the Disambig flag.

(Note that this flag specifically does NOT mean that we had to ask the user for help with the dreaded "Which do you mean..." question. It's kind of the opposite: it means that we had a noun phrase that was initially ambiguous, but that we managed to disambiguate it on our own. When we get the user involved, there's ambiguity *before* we ask the question, but the user's response removes the ambiguity by telling us exactly which alternative they intended. This flag indicates that we made an educated guess about what the user must have intended, without asking. The flag lets the parser tell the player about the guess, which is desirable because the guess is sometimes wrong.

0x0004
The noun phrase that we matched was a manifestly plural construction, such as TAKE ALL or TAKE THE BOOKS.

0x1000
This object was set internally by the program; it did not come from parsing any player input. This generally means that the whole command was constructed by the program, to handle an event or other internal processing, rather than by parsing player input.

(gameMain.usePastTense = (val))
Set the current narrative tense. Use val = true for past and val = nil for present.

singleNoun->dobjMatch
Verb rule noun phrase macros. These are convenience macros for specifying the most common noun phrase slots in the grammar templates for verb rules.

return stopValue;
Definitions for the rules.t extension

(gameMain.usePastTense ? (pastVal) : (presVal))
Shorthand macro for selecting one of two values depending on the current narrative tense.

grammar predicate(tag):
The VerbRule macro starts the definition of a verb grammar rule. The tag is just an identifying name for the rule, so that you can refer to it with 'replace' or 'modify'.

(withTense(nil, (callback)))
Temporarily override the current narrative tense and invoke a callback function.

Enums for Goals in the Hint system

Enums for Footnotes

enums for different types of lock:

Large - the object is large enough that its details can be sensed from a distance or through an obscuring medium.

Definitions for the relations.t extension

Medium - the object can be sensed at a distance or when obscured, but not in any detail. Most objects fall into this category. Note that things that are parts of large objects should normally be medium.

Null value to return from Rules that don't stop a RuleBook from continuing to consider rules.

A special role for the "other" object of a two-object command. This can be used in certain contexts (such as remapTo) where a particular object role is implied by the context, and where the action involved has exactly two objects; OtherObject in such contexts means DirectObject when the implied role is IndirectObject, and vice versa.

reading a response to a prompt for a missing literal phrase

reading a response to a prompt for a missing object phrase

reading a normal command line

reading a response to an interactive disambiguation prompt

reading an unknown word response, to check for an "oops" command

Small - the object cannot be sensed at a distance at all. This is appropriate for detailed parts of medium-class objects.

+points? "desc";
An achievement defines its descriptive text. It can also optionally define the number of points it awards.

"topicResponse" | [eventList];
AltTopics just specify the response text or list

[eventTime];
Template for ClockEvent

[eventList];
templates for EventLists

+hintDelay? "hintText" | [eventList];
A Template to facilitate the definition of ExtraHints. We can define it here and not in a header file since ExtraHints are only defined in this

"desc";
Template for Footnotes

->closeWhenAchieved? 'title' 'heading'? [menuContents];
templates for hint system objects

'title' 'heading'?;
some templates for defining menu items

"topicResponse" | [eventList];
miscellanous topics just specify the response text or list

+matchScore? 'qtype' @matchObj | [matchObj] | 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above

+matchScore? 'qtype' @matchObj | [matchObj] 'matchPattern' "topicResponse" | [eventList] ?;
we can also include *both* the match object/list *and* pattern

+matchScore? 'qtype' @matchObj | [matchObj] 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above

<> mentionA;
String templates for room descriptions etc.

<> takeTime;
String Templates for Objective Time module

'tagName' 'openText'? 'closeText'?;
Templates for style tags

->destination;
Definitions for the SymConn Extension

'testName' [testList] @location? [testHolding]?;
Templates for use with test sequences

'vocab' @location? "desc"?;
Object definition templates

+matchScore? @matchObj | [matchObj] | 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above

+matchScore? @matchObj | [matchObj] 'matchPattern' "topicResponse" | [eventList] ?;
we can also include *both* the match object/list *and* pattern

+matchScore? @matchObj | [matchObj] 'matchPattern' [firstEvents] [eventList];
a ShuffledEventList version of the above