Monday, September 24, 2012

The Advanced Hellcore $action Tutorial

This post is a continuation of the Hellcore $action tutorial.  It is broken up into three parts: a complete listing of the default $action properties, a complete breakdown of the extended $action verbs that can be overridden by your custom actions, and special usage of action on non $action objects.

$action properties

These properties can be set on your action objects to control messages and behavior:

  • .duration (FLOAT) - number of seconds the action takes (from _start to _finish or _continue to _finish)
  • .preemptible (INT) - can this action be pre-empted by another action?  [unused]
  • .unstoppable (INT) - can this action be stopped by the player?
  • .doing_msg (STR, default "%ting") - the doing message (eg the action play would become "playing")
  • .doing_to_msg (STR, default "%ting %il") - the message printed when doing an action to something (eg the action play, on space bagpipes, would print "playing the space bagpipes")
  • .oabort_msg (STR) - the message displayed to other players when the player executing the action types STOP.
$action verbs

These verbs can be overridden with your own versions for customized behavior.
  • _forbidden(OBJ source, LIST callbacks) - do any clean up when the action is forbidden by the room or area.
  • is_being_done_by(OBJ who)  - returns 1 if who is executing this action.
  • unstoppable(OBJ who) - by default, returns this.unstoppable.  Can be overridden to allow stopping of an action in certain circumstances.
  • _abort(OBJ who) - by default tells who that the action has been stopped.  If this.oabort_msg is valid, prints it to the room.
  • duration() - by default returns this.duration.  Customize and pass arguments to vary duration based on circumstances.
  • doing_msg(OBJ who, LIST callbacks) - by default prints doing_msg or doing_to_msg based on the length of callbacks.
Special $action usage

* Executing non $action objects as an $action

Aside from using $action objects, you can use any object, providing it has appropriately defined _start and _finish verbs.  An example might be creating a throwing spear item with a THROW verb on it:
player:queue_action(this, {player.target});

The above example would queue the spear itself as an action (first calling _start, which would then return duration as normal) and passing player.target as the first callback argument.

* $actions.verb

A default action called verb is available in hellcore.  Similiar to executing a non action, this allows you to call any verb as an action (instead of requiring _start or _finish).  Example:
player:queue_action($actions.verb, {some_object, "_start_action", {callback1, callback2}, 5.0, 1}, "custom action message");

Where some_object is an object number or variable of type OBJ, "_start_action" is the actual name of the verb you want to call, callbacks are the callback arguments, 5.0 is any float representing the duration, and custom action message is a string to display as the doing_msg.