The Inform 6 Programmer's Guide

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:

  1. An action number - a compile-time constant written ##ActionName. The compiler assigns these automatically.
  2. An action routine - a function named ActionNameSub that implements the default behavior.
  3. A grammar pattern (optional) - one or more grammar lines in a Verb directive 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 → Give and ShowR → Show: GiveR and ShowR are actions in their own right, with GiveRSub and ShowRSub routines, that a grammar line can name directly. The library swaps noun and second and changes the action to Give or Show. (The standard library's own grammar takes a different route: * creature held -> Give reverse keeps the action Give and sets a flag that makes the parser swap the two parameters as it builds them - see §20.6.)
  • Tell redirect: NPC, TELL ME ABOUT X (an order to the NPC) becomes ASK NPC ABOUT X, with the player as the actor.
  • AskFor redirect: ASK NPC FOR X becomes an order to the NPC to GIVE X TO ME.
! In parser.h, the transformation looks like this (simplified):
if (action == ##GiveR or ##ShowR) {
    ! Swap noun and second
    i = inputobjs-->2; inputobjs-->2 = inputobjs-->3;
    inputobjs-->3 = i;
    if (action == ##GiveR) action = ##Give;
    else                   action = ##Show;
}

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:

  1. Calls player.orders - if it returns true, the order is handled.
  2. Calls actor.orders - if it returns true, the NPC handles it.
  3. Falls back to RunLife(actor, ##Order) for old-style life property 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.

  1. GamePreRoutine() - a game-wide hook. If the game defines this entry-point routine and it returns true, it blocks the action.
  2. LibraryExtensions.RunWhile(ext_gamepreroutine) - extensions get a chance to intercept the action.
  3. player.orders - the player object's orders property is checked (this handles some special cases).
  4. Scope search for react_before - every object in scope that has a react_before property gets a chance to react. If any returns true, the action is blocked.
  5. location.before - the current room's before property is called. Return true to block the action.
  6. inp1.before (i.e. noun.before) - the first object's before property is called. Return true to 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:

  1. Scope search for react_after - every object in scope with a react_after property is checked.
  2. location.after - the current room's after property.
  3. inp1.after (i.e. noun.after) - the first object's after property.
  4. GamePostRoutine() - a game-wide post-hook.
  5. 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.

  1. AdvanceWorldClock() - increment turns and advance the clock.
  2. RunTimersAndDaemons() - fire all active timers and daemons.
  3. RunEachTurnProperties() - call each_turn on relevant objects.
  4. TimePasses() - game entry point for end-of-turn processing. If it returns false (or is undefined), LibraryExtensions.RunAll(ext_timepasses) runs as part of the same step; deadflag is tested only once both have run.
  5. AdjustLight() - recalculate light and darkness.
  6. 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 their tall/wide variants PlacesTall/PlacesWide and ObjectsTall/ObjectsWide) are real meta actions with PlacesSub/ObjectsSub routines and places/objects grammar. Only when the game defines the NO_PLACES constant are the grammar and Sub routines omitted and Places/Objects instead 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).