Trigger types

Trigger flags are owner-specific event subscriptions. Their Numeric Arg, Arguments string, injected variables, and return handling change with the event hook.

Source of truthNames: src/constants.c. Flag definitions: src/dgscript/dg_scripts.h. Runtime semantics: src/dgscript/dg_triggers.c.

How to read the reference

The columns below describe what TRIGEDIT calls Numeric Arg and Arguments. A dash means the hook does not use that field for its primary behavior. Event variables exist only for a run started by that hook.

Numeric Arg is overloaded

It is commonly a 1-100 chance, but it can be a minimum bribe amount, hit-point threshold, exact game hour, speech match mode, or object command location bitmask. Always interpret it by trigger type.

Chance percentThe code rolls rand_number(1, 100) and runs when the roll is at or below the value.
Game hourExact equality with time_info.hours, not a chance.
Location maskObject Command uses bits: worn 1, inventory 2, room 4; add values to enable more than one.
Global flagIts own Numeric Arg is unused. On mobiles and rooms it allows Random and Time checks in empty zones; Object Global is explicitly unused.

Mobile trigger types

Mobile triggers run with a character as %self%. After core DG commands, unmatched lines can use the mobile script command table or the normal character command interpreter.

Type	Numeric Arg	Arguments	Event variables	Runtime behavior

Object trigger types

Object triggers run with an object as %self%. Get, Drop, Give, Wear, Remove, and Consume return a value to action code; a false result can prevent the action.

Type	Numeric Arg	Arguments	Event variables	Runtime behavior

Object Leave scope

The hook scans objects in the room being left. It does not scan the actor's inventory or equipment in this implementation.

Room trigger types

Room triggers run with a room as %self%. They are the natural owner for location-wide observation and can coordinate other owners through UIDs, hidden commands, and global variables.

Type	Numeric Arg	Arguments	Event variables	Runtime behavior

Command, speech, and act matching

Command prefix matching

The Arguments string is compared with the start of the command word, without case sensitivity. An asterisk matches any command. That means ex can catch examine, but the script should still verify %cmd.mudcommand% and its arguments before consuming the command.

Live gate from Dollhouse trigger 11843

if %cmd.mudcommand% == examine
  if walls /= %arg%
    * matching body omitted here
  else
    return 0
  end
end

Speech and Act matching

With Numeric Arg 0, the hook performs a case-insensitive substring search. With a nonzero Numeric Arg, it uses word-list or phrase matching against the Arguments text. Use the mode intentionally: substring matching is broad and can fire inside a longer word.

Direction values

Enter/Greet receive the direction from which the actor arrived, while Leave receives the direction being taken. When no valid direction exists, hooks that supply the value use none.

Return values are part of the hook contract

The driver starts with a true result and return N changes it with integer parsing. The caller decides whether that value matters.

Hook family	Effect of return
Mobile Receive	The result can accept or reject the object transfer.
Mobile Damage	No explicit return preserves the original pending damage. An explicit `-1` cancels, `0` produces a miss, and a positive integer replaces the pending amount. A driver error preserves the original; values below `-1` are rejected and cancel.
Object actions	Get, Drop, Give, Wear, Remove, and Consume return into action code and can veto the action.
Arrival hooks	In the standard movement path, Mobile Entry, Mobile Greet/Greet-All, and Room Enter can return false and send the mover back.
Leave and Door hooks	Callers combine trigger results to decide whether movement or the door action continues.
Cast hooks	Room, object, and mobile Cast run before `call_magic()`; a false result cancels the spell.
Command hooks	A true result reports that the command trigger handled the command; `return 0` lets non-matching paths fall through.
Mobile Death	When there is a killer, a false result suppresses the default death cry; it does not cancel the death.
Other notifications	The body still runs, but the caller may ignore the integer result.

Damage is synchronous and pre-mitigation

Damage runs only for positive attempts routed through damage() against an uncharmed NPC. It does not observe misses, direct DG damage commands, direct hit-point mutation, protected attempts rejected earlier, or an instance already running or waiting. The first eligible attached trigger whose chance succeeds owns the hit. A wait cannot postpone the decision: without an earlier explicit return, the original pending amount is used, and a return after resume cannot revise completed combat. Later defenses, reductions, redirects, and the combat cap can still change final hit-point loss.

Damage supplies %actor%, %victim%, %damage%, legacy %attacktype%, and stable metadata pairs: %attackid%/%attackname%, %damagetype%/%damagetypename%, and %attackmodeid%/%attackmode%. Physical attacks remain UNDEFINED in the legacy variable; use %attackname% for them.

Multiple flags require compatible semantics

A single prototype can carry more than one trigger flag, but Numeric Arg and Arguments are shared fields. Combine flags only when one configuration makes sense for every selected hook.