Script Law

Otherwise known as the SpecProc handbook. Where immortals learn how to attach, edit, and reason about Beanshell scripts on rooms, objects, mobiles, and items in Nilgiri.

If you come from stock Diku / Circle: Neo does not ship builder dg_scripts or a MUDL interpreter. Live world scripts are Beanshell (bsh) stored on SpecProc rows in the world H2 database. You build the room/item/npc prototype first (Creation Law), create a named SpecProc, then attach the name on the prototype. Topic pages below hold the full walkthroughs and examples.

Two layers exist: DB Beanshell SpecProcs you edit in-game, and hard-coded Java specials under net.nilgiri.mud.spec (for example MobileMayor, RoomPrayForItems, SpellSunbeam) for behavior that belongs in compiled code.

Two immortal faces for scripts:

'''@proc''' — create/rename/edit/delete named SpecProcs for the world (item, npc, room, spell). Creator command set.
'''script''' — list or rewrite the SpecProc whose name matches a player (usually your own). Immortals edit their own; implementors may name another player as a third token.
See: Code Law — why Beanshell was chosen
See: Creation Law — build the prototype before attaching a proc

@proc is gated by Immortality.creatorCheck (same as building). script is also in the creator set; non-implementors may only edit the script named for themselves. Scripts persist in world tables (spec_mobile, spec_room, spec_item, spell procs) and reload on boot via SpecProc*.init().

> @proc npc new thanksgiving
Okay.
> @proc npc script thanksgiving
(writer opens — paste Beanshell, then finish)
> index proc_npc thanksgiving
>

Personal writer: script (mobile|item|room) (list|write) [player].

See: Mobiles, Rooms, Objects, Items — full attach + edit sessions

SpecProcs run with a var context. Branch on var.STATE (from Constant):

Constant	Value	Typical meaning
`STATE_SCRIPT`	0	Periodic / script pulse (mobile `mobact`, room `roomact`, …)
`STATE_INTERPRETER`	-1	Before / during command interpretation involving the entity
`STATE_COMBAT`	-2	Combat tick involvement
`STATE_POST_INTERPRETER`	-3	After a command (give, say, social reactions, …)
`STATE_ENTER`	-4	Entry into a room (room procs)
`STATE_MOVE_TO`	-5	Movement toward / into
`STATE_UPDATE`	-6	Periodic room update

Returning Boolean.TRUE can block the triggering command for interpreter-style calls; false / null allows normal processing. Keep scripts cheap — see mobile CPU-filter caveat on Script mobiles.

Each func binds var (event context) and util (ScriptTool: roll, chance, limit, …). Shell methods live on var.mobile / var.room / var.item. Prefer @proc … examine <name> on a live proc before inventing new calls.

See children for shell API patterns proven in world scripts.

Immortal/creator only. @proc … delete removes the DB row — detach prototypes first. Eval errors can echo to the owning immortal when the proc name matches a player. No separate “script reload” beyond saving the proc and pointing the prototype at the name; boot reloads from H2. Shared Beanshell interpreter — do not leave leftover globals.

Room @proc, ENTER/UPDATE triggers, room shell helpers.