Chapter 18: Actions and the Action Processing Pipeline
Every command the player types - and every command issued by game code - ultimately becomes an action. Actions are the central mechanism by which the game world changes. This chapter describes how actions are defined, how the library processes them from raw parser output to final result, and how game authors can intercept, modify, or initiate actions at every stage of the pipeline.
18.1 What Is an Action?
An action is a named game-world event. When the player types TAKE LAMP, the
parser identifies the verb and the object, then triggers the Take action with
lamp as the noun. The library dispatches the action to a routine called
TakeSub, which carries out the effect.
Every action has three components:
- An action number - a compile-time constant written
##ActionName. The compiler assigns these automatically. - An action routine - a function named
ActionNameSubthat implements the default behavior. - A grammar pattern (optional) - one or more grammar lines in a
Verbdirective that tell the parser how to recognize the action from player input.
When an action fires, the library sets several global variables that describe it:
| Variable | Purpose |
|---|---|
action |
The action number (e.g. ##Take). |
noun |
The first object, or a numeric value, or 0. |
second |
The second object, or a numeric value, or 0. |
inp1 |
Like noun, but 1 when the value is a number. |
inp2 |
Like second, but 1 when the value is a number. |
actor |
The person performing the action (usually player). |
meta |
True if the action is a meta-action (see §18.5). |
The distinction between noun/second and inp1/inp2 matters when the
parser reads a numeric value: noun holds the number itself, while inp1 is
set to 1 to indicate "this is a number, not an object." For object references,
noun and inp1 hold the same value.
! Testing what action is being performed:
before [;
Take:
if (noun == golden_idol)
"You hesitate - the idol looks trapped.";
Lock, Unlock:
"This object has no keyhole.";
],
18.2 The Full Processing Sequence
When the player types a command and presses Enter, a precisely ordered sequence
of events occurs. Understanding this sequence is essential for writing correct
before and after handlers.
Step 1: Parsing
The parser reads the input, matches it against grammar lines, and resolves noun
phrases to objects. On success, it sets action, noun, second, and related
variables. (§19 covers parsing in detail.)
Step 2: Action Transformations
Before dispatching, the library applies several transformations to normalize reversed and redirected actions:
GiveR→GiveandShowR→Show:GiveRandShowRare actions in their own right, withGiveRSubandShowRSubroutines, that a grammar line can name directly. The library swapsnounandsecondand changes the action toGiveorShow. (The standard library's own grammar takes a different route:* creature held -> Give reversekeeps the actionGiveand sets a flag that makes the parser swap the two parameters as it builds them - see §20.6.)Tellredirect:NPC, TELL ME ABOUT X(an order to the NPC) becomesASK NPC ABOUT X, with the player as the actor.AskForredirect:ASK NPC FOR Xbecomes an order to the NPC toGIVE X TO ME.
! In parser.h, the transformation looks like this (simplified):
if (action == or ) {
! Swap noun and second
i = inputobjs-->2; inputobjs-->2 = inputobjs-->3;
inputobjs-->3 = i;
if (action == ) action = ;
else action = ;
}
Step 3: NPC Orders
If actor is not the player (e.g. the command was TROLL, TAKE SWORD), the
library routes the action through actor_act() instead of the normal pipeline.
This routine:
- Calls
player.orders- if it returns true, the order is handled. - Calls
actor.orders- if it returns true, the NPC handles it. - Falls back to
RunLife(actor, ##Order)for old-stylelifeproperty handling.
If none of these handle the order, the library prints a refusal message.
Step 4: begin_action()
For player actions (or actions invoked from code), the library calls
begin_action(). This is the heart of the pipeline. begin_action() itself
performs just two of the three sub-steps below - BeforeRoutines() (4a) and
then, if the action was not blocked, ActionPrimitive() (4b). The third
sub-step, AfterRoutines() (4c), is not called by begin_action();
instead, those action routines (ActionNameSub) that offer an after stage
call it for themselves, typically just before printing their default success
message, as explained in 4c.
4a. BeforeRoutines()
The library calls the following handlers in order. If any handler returns
true, the action is blocked - ActionPrimitive() is never called, and no
after processing occurs.
GamePreRoutine()- a game-wide hook. If the game defines this entry-point routine and it returnstrue, it blocks the action.LibraryExtensions.RunWhile(ext_gamepreroutine)- extensions get a chance to intercept the action.player.orders- the player object'sordersproperty is checked (this handles some special cases).- Scope search for
react_before- every object in scope that has areact_beforeproperty gets a chance to react. If any returnstrue, the action is blocked. location.before- the current room'sbeforeproperty is called. Returntrueto block the action.inp1.before(i.e.noun.before) - the first object'sbeforeproperty is called. Returntrueto block the action.
! Simplified from parser.h:
[ BeforeRoutines rv;
if (GamePreRoutine()) rtrue;
rv = LibraryExtensions.RunWhile(ext_gamepreroutine, 0);
if (rv) rtrue;
if (RunRoutines(player, orders)) rtrue;
scope_reason = REACT_BEFORE_REASON;
parser_one = 0;
SearchScope(ScopeCeiling(player), player, 0);
scope_reason = PARSING_REASON;
if (parser_one) rtrue;
if (location && RunRoutines(location, before)) rtrue;
if (inp1 > 1 && RunRoutines(inp1, before)) rtrue;
rfalse;
];
4b. ActionPrimitive()
If no before handler blocked the action, the library dispatches to the action
routine (ActionNameSub) via a lookup in the actions table. ActionPrimitive()
has one definition per VM:
[Z-machine]
[ ActionPrimitive; (#actions_table-->action)(); ];
[Glulx]
[ ActionPrimitive; (#actions_table-->(action+1))(); ];- Glulx indexes the table with an offset of one.
The action routine carries out the default behavior - printing messages, moving objects, changing attributes, and so on.
4c. AfterRoutines()
Unlike the previous two sub-steps, AfterRoutines() is invoked from inside
the action routine itself, not from begin_action(). A typical
ActionNameSub carries out its effect, then calls AfterRoutines() before
printing its default success message; if AfterRoutines() returns true, the
routine suppresses that message (the action has already occurred). The handlers
run in this order:
- Scope search for
react_after- every object in scope with areact_afterproperty is checked. location.after- the current room'safterproperty.inp1.after(i.e.noun.after) - the first object'safterproperty.GamePostRoutine()- a game-wide post-hook.LibraryExtensions.RunWhile(ext_gamepostroutine)- extensions get a final chance to react.
! Simplified from parser.h:
[ AfterRoutines rv;
scope_reason = REACT_AFTER_REASON;
parser_one = 0;
SearchScope(ScopeCeiling(player), player, 0);
scope_reason = PARSING_REASON;
if (parser_one) rtrue;
if (location && RunRoutines(location, after)) rtrue;
if (inp1 > 1 && RunRoutines(inp1, after)) rtrue;
rv = GamePostRoutine();
if (rv == false)
rv = LibraryExtensions.RunWhile(ext_gamepostroutine, false);
return rv;
];
Step 5: End-of-Turn Sequence
For non-meta actions only, the library runs the end-of-turn sequence after
action processing completes. At each stage, if deadflag becomes non-zero (the
player has died or won), the sequence halts.
AdvanceWorldClock()- incrementturnsand advance the clock.RunTimersAndDaemons()- fire all active timers and daemons.RunEachTurnProperties()- calleach_turnon relevant objects.TimePasses()- game entry point for end-of-turn processing. If it returnsfalse(or is undefined),LibraryExtensions.RunAll(ext_timepasses)runs as part of the same step;deadflagis tested only once both have run.AdjustLight()- recalculate light and darkness.NoteObjectAcquisitions()- track newly acquired objects for scoring.
18.3 Before and After Processing
The before and after properties are the primary way game authors customize
action behavior. Both are additive properties (default NULL), meaning
inherited values from class definitions are combined rather than replaced - a
class hierarchy can layer multiple handlers, and an instance inherits all of
them and can add its own.
Blocking with before
A before handler receives the action in the global variable action and can
test it with a switch statement or action-name labels. Returning true blocks
the action entirely - the action routine is never called.
Object rusty_gate "rusty gate" garden
with name 'rusty' 'gate' 'iron',
before [;
Open:
if (self hasnt general) {
give self general;
"The gate screeches as you force it open
for the first time.";
}
Push, Pull:
"The gate won't budge that way.";
],
has door openable locked;
When the handler prints a string (which implicitly returns true), the action
is blocked, and no default message is printed.
Suppressing messages with after
An after handler runs after the action has taken effect. Returning true
tells the library to suppress its default success message, allowing the game to
substitute a custom one.
Object diamond "diamond" cave
with name 'diamond' 'gem' 'stone',
after [;
Take:
"You carefully pocket the diamond,
your hands trembling.";
Drop:
"The diamond clatters on the stone floor.";
],
has scored;
Room-Level Handling
The room's before and after properties handle actions that occur within the
room, regardless of which object is involved:
Object library "Library"
with description "Walls of books surround you.",
before [;
Take:
if (noun == rare_book)
"The librarian glares at you warningly.";
],
after [;
Drop:
"It thuds onto the library carpet.";
],
has light;
Scope-Wide Reactions
The react_before and react_after properties let an object react to any
action that occurs while it is in scope - even actions directed at other
objects. Unlike before and after they are not additive (default 0). A
react_before handler returning true blocks the action; a react_after
handler returning true suppresses the default success message:
Object guard "burly guard" throne_room
with name 'burly' 'guard',
react_before [;
Take:
if (noun == crown)
"~Hands off the crown!~ bellows the guard.";
],
has animate;
18.4 The life and orders Properties
The life property is called on animate objects when certain actions target
them directly. It works like before - it too is additive (default
NULL) - but is specific to person-oriented actions. The library calls
RunLife(object, ##Action) from inside the relevant action routines. (For
conversation actions, talkable objects also qualify; see §17.12.5.)
Actions that trigger life:
| Action | Called on | Typical use |
|---|---|---|
##Give |
second |
NPC receives an object |
##Show |
second |
NPC is shown an object |
##Ask |
noun |
NPC is asked about a topic |
##Tell |
noun |
NPC is told about a topic |
##Answer |
second |
NPC hears speech |
##Attack |
noun |
NPC is attacked |
##Kiss |
noun |
NPC is kissed |
##WakeOther |
noun |
NPC is woken up |
##ThrowAt |
second |
Something is thrown at NPC |
##Order |
actor |
NPC receives a command |
Object wizard "old wizard" tower
with name 'old' 'wizard' 'mage',
life [;
Give:
if (noun == spellbook) {
remove spellbook;
"~Ah, my spellbook! Thank you!~
The wizard smiles warmly.";
}
"~I have no use for that,~ he says.";
Ask:
if (second == 'dragon' or 'beast')
"~The dragon? It lurks in the eastern caves.~";
"The wizard shrugs.";
Attack:
"The wizard vanishes in a puff of smoke!";
default:
rfalse; ! Let the library handle it
],
has animate;
If life returns true, the action is considered handled. If it returns
false, the library falls through to its default response.
The orders Property
The orders property handles commands given to this object as an NPC (for
example, "robot, take the spanner"). Additive. It receives the player's
command with action set to the requested action and noun/second set
appropriately; if it returns true, the command is considered handled. Orders
are routed through the pipeline's NPC-orders step (§18.2, Step 3), which
consults player.orders, then actor.orders, then falls back to life with
##Order. See §17.12.4 for a worked example.
Object butler "butler" dining_room
with name 'butler',
orders [;
Give: "~Very good, sir.~ The butler accepts ", (the) noun, ".";
default: "~I'm afraid I can't do that, sir.~";
],
description "An impeccably dressed butler.",
has animate male proper;
18.5 Meta vs Non-Meta Actions
Meta actions are out-of-world commands that do not consume a game turn. They
do not trigger before/after processing or the end-of-turn sequence (no
timers, daemons, or each_turn routines fire).
Meta actions are defined with the Verb meta directive:
Verb meta 'score'
* -> Score;
Verb meta 'save'
* -> Save;
Inside begin_action(), the library checks the meta flag. When it is set,
BeforeRoutines() is skipped entirely and the action routine is called
directly. After the routine returns, the library skips AfterRoutines() and
end-of-turn processing.
The standard library defines these meta actions:
| Action | Verb words |
|---|---|
LMode1 |
brief |
LMode2 |
verbose, long |
LMode3 |
superbrief, short |
LModeNormal |
normal |
NotifyOn / NotifyOff |
notify |
Pronouns |
pronouns, nouns |
Quit |
quit, q, die |
Restart |
restart |
Restore |
restore |
Save |
save |
Score |
score |
FullScore |
fullscore, full |
ScriptOn / ScriptOff |
script, transcript, noscript, unscript |
CommandsOn / CommandsOff / CommandsRead |
recording, replay |
Verify |
verify |
Version |
version |
Places / PlacesTall / PlacesWide |
places, places tall, places wide (real meta actions by default; see note) |
Objects / ObjectsTall / ObjectsWide |
objects, objects tall, objects wide (real meta actions by default; see note) |
Note -
Places/Objects: By default, these (together with theirtall/widevariantsPlacesTall/PlacesWideandObjectsTall/ObjectsWide) are real meta actions withPlacesSub/ObjectsSubroutines andplaces/objectsgrammar. Only when the game defines theNO_PLACESconstant are the grammar andSubroutines omitted andPlaces/Objectsinstead declared as fake actions (see §18.6). The two configurations are mutually exclusive: an action is either the real meta verb or the fake action, never both.
Debug-mode meta actions (compiled only with DEBUG) include trace, actions,
routines, timers, changes, showobj, showverb, showdict, scope,
goto, gonear, abstract, purloin, tree, and glklist (Glulx only).
18.6 Fake Actions
A fake action has an action number but no grammar and no Sub routine. Fake
actions are declared with Fake_Action:
Fake_Action LetGo;
Fake_Action Receive;
Fake_Action ThrownAt;
The library uses fake actions internally to signal special situations via
before and after handlers. The game author can test for them exactly like
real actions:
before [;
Receive:
if (noun == something_heavy)
"The shelf can't support that much weight.";
LetGo:
"You can't remove items from the display case.";
],
The standard library declares these fake actions in parser.h:
| Fake action | Purpose |
|---|---|
LetGo |
An object is being removed from a container or a supporter. Sent to the container/supporter's before. |
Receive |
An object is being placed in a container or on a supporter. Sent to the container/supporter's before. |
ThrownAt |
An object has been thrown at this object. |
Order |
An NPC is being given an order. Sent to life. |
TheSame |
Disambiguation: the parser is comparing two objects. Sent to parse_name. |
PluralFound |
Signals that parse_name matched a plural word. |
ListMiscellany |
Internal: library message selection for object lists. |
Miscellany |
Internal: general library messages. |
RunTimeError |
Internal: run-time error messages. |
Prompt |
The library is about to print the command prompt. |
NotUnderstood |
The parser could not understand the command (sent to NPC orders). |
Going |
Sent to the destination room's before (via GoSub) just before the move; sent to the previous room's after once the player has arrived. The departure room itself receives the ordinary ##Go action. |
Places |
Fake action only when NO_PLACES is defined; otherwise places is a real meta action (see §18.5). |
Objects |
Fake action only when NO_PLACES is defined; otherwise objects is a real meta action (see §18.5). |
18.7 Calling Actions from Code
Game code can trigger actions directly using angle-bracket notation. This is essential for redirecting actions, implementing complex behaviors, and creating cause-and-effect chains.
Basic Forms
<Look>; ! Perform Look with no objects
<Examine mirror>; ! Perform Examine on the mirror
<PutOn ball table>; ! Perform PutOn with ball and table
Each of these calls begin_action(), running the full pipeline including
before and after handlers.
Return-True Form
Double angle brackets perform the action and return true. This is commonly
used inside before handlers to redirect one action to another:
before [;
Push:
<<Pull self>>; ! Redirect Push to Pull and block
];
The <<...>> form is equivalent to <...>; rtrue;.
Directed Actions
An action can be directed at a specific actor by adding the actor after a comma:
<Give sword player, troll>; ! The troll gives the sword to the player
<Take lamp, servant>; ! Order the servant to take the lamp
Summary of Syntax
| Syntax | Effect |
|---|---|
<Action> |
Perform action, no objects |
<Action noun> |
Perform action with first object |
<Action noun second> |
Perform action with both objects |
<<Action>> |
Perform action and return true |
<<Action noun>> |
Perform with noun and return true |
<<Action noun second>> |
Perform with both and return true |
<Action noun, actor> |
Directed at actor |
<Action noun second, actor> |
Both objects, directed at actor |
Practical Examples
! A button that triggers a Look when pushed:
Object red_button "red button" control_room
with name 'red' 'button',
before [;
Push:
print "Click! The lights flicker.^";
<Look>; ! Re-describe the room
rtrue; ! Block the default Push message
],
has scenery;
! A magic mirror that redirects Examine to Search:
Object magic_mirror "mirror" hallway
with name 'magic' 'mirror',
before [;
Examine:
<<Search self>>;
];
18.8 Action Groups
The library organizes actions into three groups by nature. The grouping depends
on how the action is declared in grammar.h.
Group 1: Standard Actions
These are the regular, in-world actions that advance the game clock. They go
through the full processing pipeline including before/after handlers and
end-of-turn processing. Examples: Take, Drop, Look, Go, Open,
Examine.
Group 2: Meta Actions
Out-of-world commands declared with Verb meta. They do not consume a game turn
and bypass before/after processing. Examples: Score, Save, Quit,
Version.
Group 3: Debug Actions
Available only when the game is compiled with the DEBUG flag. These are always
meta actions. Examples: XPurloin, XAbstract, XTree, Goto, GoNear,
Scope, TraceOn.
18.9 Complete Action Listing
§ 18.2- § 18.8 describe the action-processing model, the standard/meta/fake
distinctions, and the action groups. The complete catalog of every action - with
its verb words, noun patterns, Sub routine, and meta/fake classification - is
in Appendix A (the full grammar, §A.3-§A.5) and Appendix H (the
standard-actions reference).