Variables and fields

Variables carry text. Fields interpret that text as an entity, a text operation, or a special runtime value. Resolution starts with the trigger run, then checks owner-global state.

Source of truthResolution and field handlers: src/dgscript/dg_variables.c. State operations: src/dgscript/dg_scripts.c.

Substitution syntax

%name%Replace a local, visible owner-global, event, or special variable with its value.
%name.field%Interpret the value and read a field, such as %actor.name%.
%name.field(argument)%Pass a subfield argument, such as %eye.contains('%arg%)%.
%name.field.more%Chain fields when the prior field resolves to an entity or value understood by the next handler.
%%name%%Emit literal percent delimiters through the current substitution pass, enabling controlled indirection in a later pass.

When a name exists in both places, the trigger-local value wins. Owner globals are visible when their context is 0 or matches the script's current context. Missing names normally substitute an empty string, which can silently broaden a condition if it is not guarded.

Live indirect lookup: Dollhouse trigger 11843

eval max %random.21%
set txt[1] PATRIS
set txt[2] PRODITIO
* entries 3 through 20 omitted
set txt[21] RAPIO
set word %%txt[%max%]%%
eval word %word%

The doubled percent signs preserve a reference such as %txt[7]% as text; the later eval resolves it. Use indirection sparingly and keep the index bounded.

Lifetime, scope, and context

Storage	Created by	Lifetime and visibility
Event/local	Event hook, `set`, `eval`, `makeuid`	Lives on this trigger instance during the run, including a wait resume; freed when the run ends.
Owner global	`global <name>`	Stored on the owner's `script_data`; visible in context 0 or the matching current context.
Remote global	`remote <name> <numeric-id>`	Copied to the target entity's `script_data` using the source variable's context.
Staff player variable	`set <player> variable ...`	Written to the player's script globals in context 0.

State operations

set clue candle
global clue

context 118
set stage 2
global stage

set solved 1
remote solved %actor.id%
rdelete solved %actor.id%

A new trigger run resets the owner's current context to 0. context N changes it for subsequent operations. unset first attempts to remove an owner global, then a local variable; rdelete targets another entity.

Remote copies; it does not move

remote finds an existing local or visible global and adds its name, value, and context to the target. The source variable remains. By contrast, global adds the owner-global value and removes the local.

Entity UIDs and numeric IDs

Entity references stored in event variables and returned by many fields use the internal UID marker. Pass those references directly to commands that resolve an entity, such as %send% %actor% or %teleport% %people% 11871.

remote and rdelete parse a positive numeric target ID. Use an entity's .id field, as the live Dollhouse scripts do:

Live persistent player state: trigger 11807

set zn118_a 1
remote zn118_a %actor.id%

Use event variables such as actor, victim, or object when the hook supplies them.
Use makeuid <variable> <numeric-id>, or makeuid <variable> mob|obj|room <name> to resolve a nearby entity for UID-based commands.
Use %entity.id% when an operation explicitly expects the numeric script ID.
Never guess or manually prepend the internal UID marker.

Text fields

When a variable is plain text rather than a resolvable entity, these fields operate on its stored value.

Field	Behavior	Example
strlen	Returns the byte length of the text.	`%arg.strlen%`
toupper	Uppercases the first character only.	`%word.toupper%`
trim	Removes leading and trailing whitespace.	`%arg.trim%`
contains	Case-insensitive substring test; returns `1` or `0`.	`%eye.contains('%arg%)%`
car	Returns the first whitespace-delimited word.	`%arg.car%`
cdr	Returns everything after the first word and following whitespace.	`%arg.cdr%`
charat	Returns the 1-based character at the supplied index, or empty when out of range.	`%word.charat(3)%`
mudcommand	Expands an abbreviated command to the matching canonical game command, or empty when no command matches.	`%cmd.mudcommand%`

`dg_letter` is deprecated

The runtime logs every use. Replace dg_letter out 3 %word% with set out %word.charat(3)%.

Special values and command fields

%self%The current mobile, object, or room UID.
%random.N%A random integer from 1 through positive N; returns 0 for a non-positive bound.
%random.char%A random valid character in the owner's room; mobile owners exclude self and require visibility.
%random.dir%A random direction that has an exit from the owner's room, or empty when none exists.
%time.hour%Current in-game hour. day, month, and year are also available.
%findmob.11870(11830)%Count mobiles with VNUM 11830 in room 11870.
%findobj.11870(11856)%Count matching objects, including objects inside containers, in room 11870.

Names such as send, echo, load, and teleport resolve to owner-specific command strings. They are documented under owner-neutral pseudo-commands.

Character field catalog

These names are handled by the character branch in find_replacement(). Some read values, some take a subfield, and mutators such as skillset should be used only with their expected argument form.

Object field catalog

Object fields expose ownership, containment, location, values, flags, timer state, and object-specific mutation helpers.

Room field catalog

Room fields expose exits, occupants, contents, flags, sector, coordinates, zone identity, weather, and the room's numeric script ID.

Field chains can recurse

A field that returns an entity reference can feed another field, but a scalar such as intelligence or a numeric count cannot become an entity merely because another dot follows it. Keep chains short and inspect empty-result behavior.