The Inform 6 Programmer's Guide

Chapter 22: Timers, Daemons, and Scheduling

The standard library provides three complementary mechanisms for executing code at regular intervals or after a delay: daemons, which run every turn until stopped; timers, which count down a specified number of turns and then fire; and the each_turn property, which runs every turn for objects currently in scope. All three are processed during the end-of-turn sequence described in §16, after the player's action has been resolved. This chapter provides a complete reference for all three mechanisms, including the underlying data structures, the turn-end execution order, and the real-time clock used for time-of-day games.

22.1 Overview of Scheduled Events

Interactive fiction proceeds in discrete turns. After each player command is parsed and executed, the library runs a sequence of end-of-turn tasks. Three of those tasks invoke author-supplied code:

Mechanism Property Activation Duration
Daemon daemon StartDaemon(obj) Until StopDaemon(obj)
Timer time_out StartTimer(obj, n) Fires once after n turns
Each-turn each_turn Automatic (in scope) Every turn while in scope

Daemons and timers share a common activation pool, and four library routines manage them. The each_turn property, by contrast, requires no explicit activation - it runs automatically for every object currently in scope.

22.2 The Timer/Daemon Pool

22.2.1 the_timers Array

Daemons and timers are tracked in a single word array called the_timers, declared in parser.h:

#Ifndef MAX_TIMERS;
Constant MAX_TIMERS  32;
#Endif;
Array  the_timers  --> MAX_TIMERS;

Each slot in the_timers holds either 0 (empty), an object reference (for a timer), or an object reference with the high bit set (for a daemon). The global variable active_timers records the high-water mark - the number of slots that have been used, which determines how far the library scans when processing the array.

The maximum number of concurrently active timers and daemons is MAX_TIMERS, which defaults to 32. A game that needs more can define a larger value before including the library:

Constant MAX_TIMERS 64;
Include "Parser";

If a StartDaemon or StartTimer call would exceed the pool size, the library raises runtime error 4, whose message begins "Too many timers/daemons are active simultaneously."

22.2.2 The WORD_HIGHBIT Constant

The pool distinguishes daemons and timers with a single bit. For each daemon entry, the library stores WORD_HIGHBIT + obj rather than obj alone. The constant is platform-specific:

[Z-machine] WORD_HIGHBIT is $8000 (bit 15 of a 16-bit word).

[Glulx] WORD_HIGHBIT is $80000000 (bit 31 of a 32-bit word).

The library tests the_timers-->i & WORD_HIGHBIT (a bitwise AND) to distinguish daemon entries from timer entries, and recovers the object with the_timers-->i & ~WORD_HIGHBIT (masking off the high bit).

22.3 Daemons

A daemon is a background process attached to an object. Once started, the object's daemon property routine is called every turn until the daemon is explicitly stopped. Daemons are useful for continuous processes: a ticking clock, a wandering NPC, a slowly filling room, or any event that recurs indefinitely.

22.3.1 The daemon Property

An object that will use a daemon must provide a daemon property containing a routine:

Object  old_clock "grandfather clock" hallway
  with  name 'grandfather' 'clock' 'old',
        description "A tall grandfather clock with a swinging pendulum.",
        daemon [;
            if (self in location)
                print "^The grandfather clock ticks solemnly.^";
        ];

The daemon property is declared in linklpa.h as a common property. Its default value is 0 (no daemon). The property routine receives no arguments, and its return value is ignored.

22.3.2 StartDaemon(obj)

Activates the daemon for obj. The object is added to the the_timers pool with the WORD_HIGHBIT flag set. If the daemon is already running, the call returns false and does nothing.

[ StartDaemon obj i;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == WORD_HIGHBIT + obj) rfalse;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == 0) jump FoundTSlot3;
    i = active_timers++;
    if (i >= MAX_TIMERS) RunTimeError(4);
  .FoundTSlot3;
    the_timers-->i = WORD_HIGHBIT + obj;
];

The routine first scans for a duplicate entry. If none is found, it searches for an empty slot (a 0 entry). If no empty slot exists, it extends the high-water mark. If that would exceed MAX_TIMERS, runtime error 4 is raised - but note that StartDaemon does not return after the error: execution falls through and still writes the slot. This differs from StartTimer, which does { RunTimeError(4); return; } and aborts on overflow.

Usage:

StartDaemon(old_clock);

22.3.3 StopDaemon(obj)

Deactivates the daemon for obj by clearing its slot in the the_timers array. If the daemon is not currently running, the call returns false.

[ StopDaemon obj i;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == WORD_HIGHBIT + obj) jump FoundTSlot4;
    rfalse;
  .FoundTSlot4;
    the_timers-->i = 0;
];

Usage:

StopDaemon(old_clock);

22.3.4 Daemon Example

A wandering NPC that moves to a random adjacent room each turn:

Object  guard "palace guard" throne_room
  with  name 'palace' 'guard',
        description "A stern-looking guard in ceremonial armor.",
        daemon [ dest;
            dest = random(parent(self).n_to, parent(self).s_to,
                          parent(self).e_to, parent(self).w_to);
            while (dest == 0 or nothing)
                dest = random(parent(self).n_to, parent(self).s_to,
                              parent(self).e_to, parent(self).w_to);
            move self to dest;
            if (dest == location)
                print "^The palace guard marches in.^";
            if (parent(self) == location && dest ~= location)
                print "^The palace guard marches away.^";
        ],
  has   animate;

! In Initialise():
[ Initialise;
    location = throne_room;
    StartDaemon(guard);
];

22.4 Timers

A timer is a countdown attached to an object. When started, the object's time_left property is set to a count. Each turn, the library decrements time_left by one. When it reaches zero, the object's time_out property routine is called, and the timer is automatically removed from the pool.

22.4.1 Timer Properties

Two properties govern timers:

  • time_left - a numeric property that holds the number of turns remaining. The library decrements it each turn. The object must provide this property (the library checks with .&time_left); if it does not, runtime error 5 is raised.

  • time_out - a property routine (declared as additive) that is called when time_left reaches zero. This is the timer's "fire" event.

Object  bomb "ticking bomb" cellar
  with  name 'ticking' 'bomb',
        description [;
            print "A bomb with a fuse. ";
            if (self.time_left > 0)
                print "It will go off in ", self.time_left, " turns.^";
            else
                "It looks inert.";
        ],
        time_left 0,
        time_out [;
            deadflag = 1;
            "^The bomb explodes with a deafening roar!";
        ];

22.4.2 StartTimer(obj, turns)

Activates a timer on obj, setting its time_left property to turns. The object is added to the the_timers pool. If the timer is already running, the call returns false and does nothing.

[ StartTimer obj timer i;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == obj) rfalse;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == 0) jump FoundTSlot;
    i = active_timers++;
    if (i >= MAX_TIMERS) { RunTimeError(4); return; }
  .FoundTSlot;
    if (obj.&time_left == 0) { RunTimeError(5, obj, time_left); return; }
    the_timers-->i = obj; obj.time_left = timer;
];

The routine validates that obj provides a time_left property by checking obj.&time_left. If the object lacks this property, it raises runtime error 5 and does not start the timer.

Usage:

StartTimer(bomb, 10);   ! Bomb explodes in 10 turns

22.4.3 StopTimer(obj)

Deactivates the timer for obj, clears its slot in the_timers, and resets time_left to zero. If the timer is not running, the call returns false.

[ StopTimer obj i;
    for (i=0 : i<active_timers : i++)
        if (the_timers-->i == obj) jump FoundTSlot2;
    rfalse;
  .FoundTSlot2;
    if (obj.&time_left == 0) { RunTimeError(5, obj, time_left); return; }
    the_timers-->i = 0; obj.time_left = 0;
];

Usage:

! Player defuses the bomb:
before [;
    Disarm:
        if (noun == bomb && bomb.time_left > 0) {
            StopTimer(bomb);
            "You carefully cut the fuse. The bomb is disarmed.";
        }
],

22.4.4 Restarting a Timer

Because StartTimer returns false if the timer is already running, you can't restart a timer without stopping it first. To reset a running timer to a new countdown:

StopTimer(bomb);
StartTimer(bomb, 5);   ! Reset to 5 turns

Alternatively, you can directly modify the time_left property of a running timer without stopping and restarting it:

bomb.time_left = 5;    ! Reset countdown without removing from pool

This works because the library decrements time_left each turn; it does not read the value from the pool.

22.4.5 Timer Example

A lantern with limited fuel:

Object  lantern "brass lantern" startroom
  with  name 'brass' 'lantern' 'lamp',
        description "A well-polished brass lantern.",
        time_left 0,
        time_out [;
            give self ~light;
            give self ~on;
            StopDaemon(self);
            if (self in location || IndirectlyContains(player, self))
                "^Your lantern flickers and goes out!";
        ],
        before [;
            SwitchOn:
                StartTimer(self, 200);  ! 200 turns of fuel
                give self light;
            SwitchOff:
                StopTimer(self);
                give self ~light;
        ],
  has   switchable;

22.5 The each_turn Property

The each_turn property provides a simpler form of per-turn processing that does not require explicit activation or deactivation. Every turn, the library calls the each_turn routine of every object currently in scope (see §23 for the full definition of scope). If the object is out of scope - for example, in a different room - its each_turn routine is not called.

22.5.1 Declaration

The each_turn property is declared additive in linklpa.h, meaning that when a class defines each_turn and an instance also defines it, both routines run. The property can be either a routine or a string:

Object  dripping_tap "dripping tap" bathroom
  with  name 'dripping' 'tap' 'faucet',
        each_turn [;
            if (random(3) == 1)
                "^Drip... drip... drip...";
        ];

If each_turn is a string, the string is printed (with a newline) each turn.

22.5.2 Scope Dependency

The crucial distinction between each_turn and daemons is scope dependency. A daemon runs every turn regardless of where the object is in the game world. An each_turn routine runs only when the object is in the player's scope - typically, when the object is in the same room as the player (or in a transparent or open container accessible from the player's location).

This makes each_turn ideal for ambient effects: sounds, smells, and visual descriptions that should occur only when the player is present. Use daemons for processes that must continue regardless of the player's location.

22.5.3 Execution Order

The each_turn routines are called by RunEachTurnProperties(), which uses the scope mechanism with EACH_TURN_REASON to iterate over all in-scope objects. The scope-scanning algorithm (see §23.1) determines the order by traversing the object tree depth-first, starting from the player's location and the player's inventory. Within a single container, children are processed in the order of the object tree's sibling chain (from child following sibling links), not in object-number order (see §23.1.4).

22.5.4 each_turn on Rooms

The player's current location (i.e., the room object) can also have an each_turn property. The library calls the location's each_turn routine each turn, just as it would for any other in-scope object. This provides a convenient way to implement per-room ambient effects:

Object  forest "Dark Forest"
  with  description "Tall pines block most of the light.",
        each_turn [;
            switch (random(4)) {
                1: "^An owl hoots in the distance.";
                2: "^A branch snaps somewhere nearby.";
                3: "^The wind whispers through the trees.";
            }
        ],
  has   light;

22.6 The End-of-Turn Sequence

After the player's action has been fully processed (including before, the action routine, and after - see §18), the library executes the end-of-turn sequence. This is defined as a property of the InformLibrary object in parser.h:

end_turn_sequence [;
    AdvanceWorldClock();        if (deadflag) return;
    RunTimersAndDaemons();      if (deadflag) return;
    RunEachTurnProperties();    if (deadflag) return;
    if (TimePasses() == 0)
        LibraryExtensions.RunAll(ext_timepasses);
                                if (deadflag) return;
    AdjustLight();              if (deadflag) return;
    NoteObjectAcquisitions();
],

The six steps, in order:

22.6.1 Step 1: AdvanceWorldClock()

Increments the turn counter and, for time-of-day games, advances the game clock (the_time) by the configured rate. See §22.7 for details on the time-of-day system.

22.6.2 Step 2: RunTimersAndDaemons()

Scans the the_timers array from slot 0 to active_timers - 1. For each non-zero entry:

  • If the entry has WORD_HIGHBIT set, it is a daemon. The library calls RunRoutines(obj, daemon), which invokes the object's daemon property routine.

  • Otherwise, it is a timer. The library checks obj.time_left first: if it is already zero, the timer fires - the library stops it (via StopTimer) and calls RunRoutines(obj, time_out). Otherwise it decrements obj.time_left by one. (Note the order: the zero check precedes the decrement, so a timer whose time_left is already zero fires at the next check rather than being treated as inactive.)

If any daemon or timer sets deadflag to a non-zero value, the sequence aborts immediately and the death/victory sequence begins.

Processing order: Timers and daemons are processed in the order they appear in the the_timers array, which corresponds to the order in which they were started (subject to slot reuse when earlier slots are freed by stopping).

22.6.3 Step 3: RunEachTurnProperties()

Calls the each_turn property of every object currently in scope, using the scope mechanism with EACH_TURN_REASON. This routine invokes DoScopeAction for each in-scope object, which in turn calls PrintOrRun(obj, each_turn) if the property exists.

If any each_turn routine sets deadflag, the sequence aborts.

22.6.4 Step 4: TimePasses()

Calls the game author's TimePasses() entry point, if defined (see §24.16). If TimePasses() returns false (or is not defined), the library also calls any registered library extension routines. This entry point is the last opportunity for per-turn processing before the library adjusts lighting.

22.6.5 Step 5: AdjustLight()

Recalculates whether the player's location is lit or dark, and transitions between light and darkness as necessary. See §23.2 for details on the light-propagation algorithm.

22.6.6 Step 6: NoteObjectAcquisitions()

Sets the moved attribute on any objects in the player's possession that have not yet been marked as moved. For each such object that also carries the scored attribute, OBJECT_SCORE is added to both score and things_score - this is how the library awards points the first time a treasure is picked up.

22.6.7 deadflag Checks

The first five steps are each followed by a check of the global variable deadflag; the final step, NoteObjectAcquisitions(), has none, since no later step remains to skip. When a check finds deadflag non-zero (indicating the player has died, won, or reached another terminal state), the remaining steps are skipped, and the library proceeds to the death/victory sequence.

22.7 The Time-of-Day System

The library includes a time-of-day clock for games that track the passage of hours and minutes rather than (or in addition to) a simple turn counter. This is primarily used for displaying the time on the status line.

22.7.1 Enabling the Clock

To enable the time-of-day display, the source file must include:

Statusline time;

This causes the status line to display the current time instead of the score and turn count. Three global variables control the clock:

Variable Purpose
the_time Current time in minutes since midnight (0-1439).
time_rate Minutes advanced per turn (positive or negative).
time_step Internal fractional accumulator (negative rates).

22.7.2 SetTime(time, rate)

Initializes the game clock. time is the starting time in minutes since midnight (e.g., 540 for 9:00 AM). rate is the number of minutes that pass per turn.

[ Initialise;
    location = bedroom;
    SetTime(9*60, 1);   ! Start at 9:00 AM, 1 minute per turn
];

If rate is positive, the clock advances by rate minutes every turn. If rate is negative, the clock advances by 1 minute every |rate| turns - useful for slower-paced games.

The implementation in parser.h:

[ SetTime t s;
    the_time = t; time_rate = s; time_step = 0;
    if (s < 0) time_step = 0-s;
];

22.7.3 Clock Advancement

Each turn, AdvanceWorldClock() advances the clock according to time_rate:

  • If time_rate >= 0: the_time is incremented by time_rate minutes. If the_time reaches or exceeds 1440 (midnight), it wraps around. (When time_rate is zero, the clock does not advance automatically, but the game can still modify the_time directly or call SetTime.)

  • If time_rate < 0: the internal time_step counter is decremented. When time_step reaches zero, the_time is incremented by 1 minute and time_step is reset to |time_rate|. This effectively advances the clock by one minute every |time_rate| turns.

  • If time_rate == 0: this falls into the >= 0 branch above, so zero is added, and the clock does not advance. The game can still modify the_time directly or call SetTime.

22.7.4 Displaying the Time

When Statusline time is in effect, DisplayStatus() loads the current hour and minute into sline1 and sline2. This runs on every platform:

sline1 = the_time / 60;
sline2 = the_time % 60;

How those values are then drawn and formatted depends on the platform and, on the Z-machine, the story-file version:

[Z-machine] In Version 3, the interpreter draws the status line in hardware; the library supplies only the hour and minute values, and the interpreter formats them (12-hour versus 24-hour display is interpreter-dependent). In Version 4 and later, the library draws the status line itself in DrawStatusLine(), printing the time by calling LanguageTimeOfDay(sline1, sline2). (Version 6 provides its own DrawStatusLine that does not use LanguageTimeOfDay.)

[Glulx] The library always draws the status line in DrawStatusLine(), printing the time with the same LanguageTimeOfDay(sline1, sline2) call.

LanguageTimeOfDay formats the time in 12-hour form with an "am" or "pm" suffix (for example, "9:05 AM"); it is defined in the language-definition file english.h.

22.7.5 Real-Time Events

[Z-machine] The Z-machine specification (versions 4+) supports a real-time input feature. The interpreter can interrupt keyboard input after a specified number of tenths of a second and call a callback routine. This is implemented with the timed variant of the read (or aread) opcode:

@aread buffer parse time routine -> result;

Here time is the timeout in tenths of a second and routine is a packed address of a routine to call when the timeout expires. If the routine returns true, input is terminated as if the player had pressed Enter.

The standard library does not provide a high-level interface for real-time input; using it requires direct assembly language. A game that wants a timer to fire every 5 seconds during input would embed a @aread call with time set to 50 (50 tenths of a second = 5 seconds).

[Glulx] Glulx provides timer events through the Glk timer mechanism. The game calls glk_request_timer_events(milliseconds) to start receiving evtype_Timer events at the specified interval, and glk_request_timer_events(0) to stop. Timer events are received through glk_select() and can be handled in the game's event loop.

22.8 Interactions Between Mechanisms

22.8.1 Daemons vs. Timers

A single object can have both a daemon and a timer active at the same time. They occupy separate slots in the the_timers array (distinguished by WORD_HIGHBIT). The daemon runs every turn; the timer counts down independently. When the timer fires, the daemon continues unless you explicitly stop it.

22.8.2 Daemons vs. each_turn

An object can have both a daemon property and an each_turn property. The daemon runs every turn regardless of scope; each_turn runs only when the object is in scope. Both can be active at the same time. The daemon is processed in step 2 of the end-of-turn sequence; each_turn is processed in step 3.

A common pattern is to use a daemon for global bookkeeping and each_turn for player-visible effects:

Object  volcano "Mount Doom" landscape
  with  daemon [;
            self.pressure = self.pressure + random(3);
            if (self.pressure > 100) {
                deadflag = 1;
                "^The volcano erupts catastrophically!";
            }
        ],
        each_turn [;
            if (self.pressure > 80)
                "^The ground trembles beneath your feet.";
            if (self.pressure > 50)
                "^You hear a distant rumbling from the volcano.";
        ],
        pressure 0;

22.8.3 Stopping a Timer from Its Own time_out

It is safe for a time_out routine to call StartTimer on itself to create a repeating timer:

time_out [;
    print "^The church bells chime the hour.^";
    StartTimer(self, 60);   ! Chime again in 60 turns
],

The library clears the timer slot before calling time_out, so StartTimer finds the slot empty and reuses it.

22.8.4 Stopping a Daemon from Its Own daemon Routine

It is safe for a daemon routine to call StopDaemon(self). The library does not re-process the cleared slot in the same turn.

22.9 Debugging Timers and Daemons

22.9.1 The TIMERS (or DAEMONS) Debug Verb

When the game is compiled in debug mode (-D), the player can type TIMERS (or its synonym DAEMONS) to turn on the timer/daemon listing; the library replies "[Timers listing on.]" (TIMERS OFF or DAEMONS OFF turns it off again). While the listing is on, the library prints one line for each active pool entry each turn, giving the object's short name followed by either "daemon" or "timer with N turns to go":

grandfather clock: daemon
ticking bomb: timer with 7 turns to go

22.9.2 Inspecting the Pool

In debug mode, the the_timers array can be inspected directly. Each slot contains either 0 (empty), a bare object number (timer), or WORD_HIGHBIT + object_number (daemon).

22.9.3 Common Pitfalls

  • Forgetting time_left: If an object is used with StartTimer but does not provide a time_left property, the library raises runtime error 5. Always include time_left 0 in the object definition.

  • Exceeding MAX_TIMERS: If more than MAX_TIMERS daemons and timers are active simultaneously, StartDaemon or StartTimer raises runtime error 4. If needed, increase MAX_TIMERS before including the library.

  • Pool fragmentation: Stopping and starting many timers/daemons can leave empty slots in the middle of the array. The library handles this correctly (it scans for empty slots when starting a new entry), but active_timers only grows; it never shrinks. This means the scan range may exceed the number of active entries. In practice, this is harmless, as scanning 32 slots is negligible.

  • Order dependence: If two daemons interact (e.g., one sets a variable that another reads), their execution order depends on their order in the the_timers array, which is the order in which they were started. Relying on this order is fragile; use explicit state management instead.

22.10 Summary of Routines and Properties

Routine / Property Purpose
StartDaemon(obj) Activate daemon for obj
StopDaemon(obj) Deactivate daemon for obj
StartTimer(obj, turns) Start countdown timer on obj
StopTimer(obj) Cancel countdown timer on obj
SetTime(time, rate) Set game clock and advance rate
daemon property Routine called every turn while active
time_out property Routine called when timer reaches zero
time_left property Turns remaining on active timer
each_turn property Routine called every turn while in scope
the_timers array Pool of active timers and daemons
active_timers global High-water mark of pool usage
MAX_TIMERS constant Maximum pool size (default 32)
the_time global Game clock in minutes since midnight
time_rate global Clock advance rate (minutes/turn)