Runtime architecture

Data model

script_data.types is the OR of attached trigger flags. Event hooks use it as a fast owner-level check before walking the trigger list.

From flat file to live instance

parse_trigger() reads the attach type, ASCII flag bitvector, Numeric Arg, Arguments, and tilde-terminated command body. It tokenizes the body into a linked command list and registers the prototype in trig_index.

World entity prototypes keep only attached trigger VNUMs. When a mobile, object, or room script is instantiated, read_trigger() allocates a trig_data copy, duplicates mutable strings, shares the prototype command-list pointer, and add_trigger() adds it to the owner's script_data.

Game code calls typed event hooks

DG Scripts does not infer most events. Game systems explicitly call functions such as command_mtrigger(), get_otrigger(), enter_wtrigger(), and damage_mtrigger(). Each hook:

1. Checks that the owner has a script and the relevant flag in its aggregate type bitvector.
2. Walks attached trigger instances and skips any instance already running.
3. Tests chance, match text, threshold, time, direction, visibility, or location mask.
4. Adds event-local variables such as actor, object, cmd, or direction.
5. Calls script_driver() with owner address, instance, owner type, and TRIG_NEW.
6. Consumes or ignores the returned integer according to the hook contract.

The main heartbeat calls script_trigger_check() every PULSE_DG_SCRIPT for periodic checks; Time triggers also compare the in-game hour.

Mobile Damage is a specialized synchronous hook in the combat path. Deflective-screen and artifact reductions can occur before it; most defenses, reductions, redirects, the combat cap, hit-point subtraction, and death handling occur after it. The hook also records whether the driver executed an explicit return or yielded, allowing no-return and pre-return waits to preserve the incoming pending damage without changing the default behavior of other trigger families.

The script driver

script_driver() rejects or attempts to recover an out-of-range incoming owner type before interpreting the owner pointer. A separate actual-type-versus-trigger-flags diagnostic is compiled only under SCRIPT_DEBUG. The driver then enforces recursion depth, initializes new-run state, and walks command nodes until completion, wait, halt, owner purge, or error.

Control lines are recognized before normal variable substitution so block navigation can evaluate only the necessary conditions. Other lines pass through var_subst(), then through the core command chain. Remaining lines go to:

• script_command_interpreter()Mobile DG commands, then the normal character interpreter if unmatched.
• obj_command_interpreter()Object DG command table only.
• wld_command_interpreter()Room DG command table only.

At normal completion the driver frees the trigger's local variable list, clears current state and depth, and returns the current integer result.

Variable resolution

find_replacement() looks for a matching trigger local first, then an owner global whose context is 0 or the current context. If the value resolves to a character, object, or room UID, the corresponding field branch handles it. Otherwise text processing and special names provide additional fields.

%actor.name%
    |
    +-- local variable actor = internal character UID
    +-- resolve UID through the character lookup table
    +-- character field "name"
    +-- copy replacement into the command buffer

Subfields inside parentheses are themselves passed through var_subst(). Chained fields can recurse when an earlier field returns another meaningful value. The output buffer is bounded by the command input size.

Character and object UIDs are maintained in a lookup table initialized by the DG subsystem. Room IDs use the room VNUM plus ROOM_ID_BASE.

Wait events and resumption

process_wait() converts pulses, real seconds, in-game hours, or a clock target into an event delay. It records the next command in curr_state, creates a wait_event_data record, and returns from the driver without final cleanup.

When the event fires, the runtime verifies that the stored owner pointer still appears in the relevant character, object, or room collection, then invokes the driver with TRIG_RESTART. Execution resumes from curr_state, retaining the trigger instance's locals and control depth.

Persistence boundaries

Source map

• src/dgscript/dg_scripts.hFlags, runtime structures, limits, macros, and public DG API.
• src/dgscript/dg_db_scripts.cTrigger parsing, instance copying, and attachment loading.
• src/dgscript/dg_triggers.cTyped game-event hooks and injected event variables.
• src/dgscript/dg_scripts.cDriver, control flow, state commands, UIDs, stats, attach/detach, and waits.
• src/dgscript/dg_variables.cSubstitution, entity fields, text fields, special values, and pseudo-commands.
• src/dgscript/dg_misc.cdg_cast and dg_affect.
• src/dgscript/dg_mobcmd.cMobile DG command implementations; table registration is in src/interpreter.c.
• src/dgscript/dg_objcmd.cObject command implementations and table.
• src/dgscript/dg_wldcmd.cRoom command implementations and table.
• src/dgscript/dg_olc.cTRIGEDIT, disk save, and shared attachment menu.
• src/dgscript/dg_event.cEvent integration used by trigger waits.
• src/constants.cBuilder-facing mobile, object, and room trigger type names.