Mob Program Reference

Overview

Mob programs (mob_progs) allow non-player characters to react to in-game events through a small scripting language interpreted by the MUD engine. Each program is stored in an MPROG_DATA structure linking to the next program and containing its trigger type, argument list, and command list.

Data Structures

MPROG_DATA stores next, type, arglist, and comlist fields.
MPROG_ACT_LIST queues pending triggers with fields for the triggering character, object, and data pointer.
MPROG_CAN_SEE caches visibility checks to temporarily override sight rules.

Trigger Types

Programs use bit flags to declare which events they handle:

Flag	Purpose
`ACT_PROG`	reacts to `act()` messages
`SPEECH_PROG`	triggered by player speech
`RAND_PROG`	random chance every pulse
`FIGHT_PROG`	during combat rounds
`DEATH_PROG`	upon mob death
`HITPRCNT_PROG`	when hit points fall below a percentage
`ENTRY_PROG`	when a player enters the room
`GREET_PROG`	greets a player in the same room
`ALL_GREET_PROG`	greets every player
`GIVE_PROG`	when given an object
`BRIBE_PROG`	when bribed with gold

Programs defined in external files use IN_FILE_PROG to indicate that additional scripts are included from other files.

Program Files

A mob_prog file contains one or more program blocks:

>trigger_type argument~
commands...
~
|  (end of file)

Each block starts with > followed by the textual trigger name (e.g., greet_prog) and an argument list terminated by ~. The command list follows and is also terminated by ~. The file ends with a line containing |.

To attach a program to a mobile, area files use the M directive followed by the mob vnum and the program filename. During boot, load_mobprogs loads the file and sets the mob's progtypes flags.

Variable Expansion

Within commands, $ codes are replaced with context-specific values:

Code	Meaning
`$i` / `$I`	mob's name / short description
`$n` / `$N`	actor's name / short description
`$t` / `$T`	secondary target's name / short description (character)
`$r` / `$R`	random character in room name / short description
`$e` `$m` `$s`	actor pronouns
`$E` `$M` `$S`	target pronouns
`$j` `$k` `$l`	mob pronouns
`$J` `$K` `$L`	random character pronouns
`$o` / `$O`	object name / short description
`$p` / `$P`	secondary object name / short description
`$a` / `$A`	article for object / secondary object
`$$`	a literal dollar sign

Gotcha: Using $t when the secondary target is an object may crash the engine; act() assumes $t refers to a character.

Control Flow

Scripts support structured control flow:

if <check> ... endif — conditional execution
or — additional condition in the same if
else — alternate branch
break — aborts the current block

String comparisons accept operators ==, !=, / (contains), and !/ (does not contain). Numeric comparisons accept ==, !=, >, <, >=, <=, &, and |.

If Checks

The if statement evaluates a variety of checks. Arguments typically reference one of the $ variables (e.g., $n). All checks return boolean values or compare against an operator and value.

Check	Description
`rand(n)`	true `n%` of the time
`ispc($x)` / `isnpc($x)`	whether the referenced character is a player or mob
`isgood($x)`	alignment > 750
`isfight($x)`	character currently fighting
`isimmort($x)`	character has immortal level
`ischarmed($x)`	affected by charm
`isfollow($x)`	has a master in same room
`isaffected($x) & flag`	affected_by bitmask
`hitprcnt($x) < n`	hit points percentage comparison
`inroom($x) == vnum`	room vnum comparison
`sex($x) == n`	sex (0 neutral,1 male,2 female)
`position($x) == n`	position constant
`level($x) >= n`	trust level
`align($x) < n`	alignment value
`class($x) == n`	class index
`race($x) == name`	race check
`goldamt($x) > n`	gold carried
`objtype($o) == n`	object type number
`objval0-3($o) == n`	object `value[]` fields
`number($x) == vnum`	vnum for mobs/objects
`name($x) / 'text'`	string comparisons on names
`tribe($x) == 'name'`	tribe name
`isleader($x)`	character has leader flag
`isntpet($x)`	character is not flagged as a pet
`mobhere(vnum[,room])`	mob with vnum present here or in room
`objhere(vnum\|name)`	object present in room
`hasobj(vnum)`	actor carries object vnum

Execution

mprog_driver processes each command, temporarily overrides visibility with MOBcansee, and resets the global MOBtrigger flag after each act() to prevent recursive triggers. Random variables $r/$R select a random visible player in the room.

Writing Mob Programs

Create a file under area/MOBProgs following the block format shown above.
Use $ variables and if checks as needed to craft responses.
Add an entry in the area file's MOBPROGS section: M <mob_vnum> <filename>
Reboot or reload the area to activate the script.

Example:

>greet_prog 100~
if ispc($n)
  say Hello, $n!
endif
~
|

Debugging

Use the mpstat command to list programs attached to a mob and verify triggers and arguments.