Page locked

This page is currently locked for editing by another user. You have to wait until this user finishes editing or the lock expires.
Currently locked by: 216.73.216.245
Lock expires at: 2026/09/24 02:06 (11 min)
This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 ([[creationlaw|Creation Law]]), create a named SpecProc, then attach the name on the prototype. Topic pages below hold the full walkthroughs and examples.

===== What scripting is here =====
 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: [[codelaw|Code Law]] — why Beanshell was chosen
  * See: [[creationlaw|Creation Law]] — build the prototype before attaching a proc

===== Who may script =====
 ''@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'' and personal ''script'' (overview) =====
<code mud>
> @proc npc new thanksgiving
Okay.
> @proc npc script thanksgiving
(writer opens — paste Beanshell, then finish)
> index proc_npc thanksgiving
>
</code>

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

  * See: [[scriptmobiles|Mobiles]], [[scriptrooms|Rooms]], [[scriptobjects|Objects]], [[scriptitems|Items]] — full attach + edit sessions

===== Event triggers (STATE_*) =====
 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 [[scriptmobiles|Script mobiles]].

===== ''var'' and ''util'' (overview) =====
 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.

===== Safety =====
 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.

===== Rooms =====
 Room ''@proc'', ENTER/UPDATE triggers, room shell helpers.
  * See: [[scriptrooms|Rooms]]

===== Objects =====
 ''@proc item'', ''@item proc'', object-proc workflow with Creation cross-links.
  * See: [[scriptobjects|Objects]]

===== Items =====
 Item shell APIs (''isWeapon'', ''purge'', ''createMobile'', …), patterns.
  * See: [[scriptitems|Items]]

===== Mobiles =====
 Full mobile scripting, worked examples (''babybunny'', ''thanksgiving'', ''quest_cursor''), starter stub.
  * See: [[scriptmobiles|Mobiles]]

===== Zones =====
 Zones have **no** SpecProc table — scripts live on what the zone places.
  * See: [[scriptzones|Zones]]

===== Related =====
  * [[creationlaw|Creation Law]] — prototypes, zones, load/create/purge
  * [[codelaw|Code Law]] — Beanshell among coding resources
  * [[gamelaw|Game Law]] — player-facing systems scripts may interact with