Module *m_npcscript*
*********************

Documentation for the modules-m_npcscript module in */std/modules/m_npcscript.c*.

Module Information
==================

m_npcscript (M_NPCSCRIPT)

This object provides functionality for MOBILE adversaries to execute scripts at given intervals that involve a series
of steps and checks along the way. Need your NPC to go buy a sandwich? This is the way.

This modules inherits M_ACTIONS by itself. If triggers are used, inherit M_TRIGGERS in your mob as well.
Only 1 trigger is supported at a time. Example of script:

  |       create_script(
  |           "lunch",
  |           ({
  |               step(SCRIPT_ACTION, (: set_for_sale, 0:)),
  |               step(SCRIPT_DESC, "Harry the affectionate"),
  |               step(SCRIPT_ACTION, "say Well, time for some lunch."),
  |               step(SCRIPT_ACTION, "go south@@go south@@go south@@hum"),
  |               step(SCRIPT_WAIT, 5),
  |               step(SCRIPT_ACTION, "push button"),
  |               step(SCRIPT_TRIGGER, "The elevator door opens.", "go northwest"),
  |               step(SCRIPT_DESC, "Harry, leaning against the elevator panel."),
  |               step(SCRIPT_TRIGGER, "The elevator door closes.", "push 8"),
  |               step(SCRIPT_NPCACTION, "wave harry", "greeter"),
  |               ...
  |           }));

Note, ``set_for_sale(0)`` above closes up shop, so a vendor temporarily sells nothing.

Alternatively, the ``create_script_from_file("lunch","scripts/lunch.npcs")`` function can be used.
These scripts should follow this format:

  |    # My lunch script (this is a comment)
  |    ACTION:hungry
  |    WAIT:30
  |    ACTION:(: set_for_sale, 0 :)
  |    ACTION:emote stands up.@@say Well:I guess it's time for some lunch.
  |    DESC:Harry looks hungry.
  |    TRIGGER:Troll enters.->go east
  |    NPCACTION:greeter->wave harry

Notice, the TRIGGER syntax ``->`` which tells us what to do when something happens.

.. TAGS: RST

Functions
=========
.. c:function:: int query_recovery_time()

Returns the time in minutes before recover() is called
and the script is aborted.


.. c:function:: void set_recovery_time(int rt)

Set the time in minutes before the script should have finished
and the recover() function is called in the NPC and the script
is aborted.


.. c:function:: void recover()

Override this function in your NPC inheriting M_NPCSCRIPT.
It will be called after the minutes set using ``set_recovery_time()``
are up.


.. c:function:: varargs class script_step step(int type, mixed payload, mixed extra)

Creates a script_step class. The following types are supported:

  - SCRIPT_ACTION: Do things, say things. Actions can be seperated by @@ to include more actions in one step.

  - SCRIPT_TRIGGER: Will create a step waiting for something to happen, and will then do action.

  - SCRIPT_WAIT: Wait a number of seconds.

  - SCRIPT_DESC: Change the in room description for the mob as they move along in the world.


.. c:function:: int create_script_from_file(string name, string file)

Use this function to parse in an NPC-script style file
and read the script from there using ``name``.


.. c:function:: int started_at()

Returns a timestamp for when the script was launched.


.. c:function:: void execute_script(string name)

Run a script for the mob by "name".


.. c:function:: int *status()

Returns 0 if no scripts are running, or an array of 2 integers ({x,y}),
where x is the current step in the script, and y is the max number of steps.
See also ``query_running_script()``.


.. c:function:: string query_running_script()

Returns the current running script if any.
See also ``status()`` for description on how far the NPC is into the script.


.. c:function:: object debug(object ob)

Call debug() with your body object to receive debug information
while the script is running. Pass it 0 again to stop the debug output.
This can be useful for not having to chase NPCs around the MUD to debug
them.


.. c:function:: mapping query_scripts()

Returns the scripts contained in the mob.



*File generated by Lima 1.1a4 reStructured Text daemon.*