>
> |
This document describes the Lua interface to Zippy's action system. You might want to read the ZippyActionGuide as an introduction. In addition, the pre-implementation specification is available, although its usefulness is probably purely historical at this point.
Every action results in a set of effects, which are measured along Effect Axes. EffectAxes? are created with the EffectAxis{} function:
EffectAxis{
name = "MyEffect",
namespace = ANamespace,
valid = Range{min, max}
}
"valid" in this case is the range on which the effect is defined. In versions through 0.0.4 this is not enforced.
Every action must have an Action Class of which it is an instance. ActionClasses? are created with the ActionClass{} function:
ActionClass{
name = "MyAction",
namespace = ANamespace,
effects = {
OneEffect,
AnotherEffect,
[...]
}
}
The "effects" table contains a list of the effects corresponding to an action of the class. In versions through 0.0.4 no errors will result from ignoring this list; however, it is strongly reccomended that you obey it in your action handlers.
Actions are represented by values created with the act() function:
my_action = act(ANamespace.MyAction, origin, target, ...)
The first argument is the action class. The second and third specify the origin and target of the action, where the origin must be some value that can be indexed as a table (most commonly a Character) and the target may also be such a value or nil to indicate there is no target. Extra arguments are read in order and stored as numbered fields of the action, starting from one.
In addition to the numeric fields, action values have the following members, all of which are read-only:
| Name | Description |
|---|
| class | The action class for this action, as defined above |
| origin | The origin of the action |
| target | The target of the action, or nil if there is no target |
The action resolution process involves two entities by default, the origin and the target. Watches may be used to involve third parties in the action, and they are created using the Watch{} function:
my_watch = Watch{
owner = self,
criteria = {
{ [criterion specification] },
[...]
}
}
Here, "owner" must be a value that can be indexed as a table. The "criteria" table contains one or more tables in one of the following formats:
|
>
> |
{ criterion = { entity [[[, another_entity] , a_third_entity], ...] }, role = ["origin" | "target"] [, sufficient = 1] [, necessary = 1] }
-- or:
{ criterion = ACharacterType, role = ["origin" | "target"] [, sufficient = 1] [, necessary = 1] }
-- or:
{ criterion = APassage, role = ["origin" | "target"] [, sufficient = 1] [, necessary = 1] }
-- or:
{ criterion = a_function, tier = [1..3], role = ["origin" | "target"] [, sufficient = 1] [, necessary = 1] }
A watch is only relevant to an action if all of its necessary criteria are relevant, or if at least one of its sufficient criteria is relevant. A valid criterion must be either necessary or sufficient, or both.
In the first form above, the criterion is relevant if the participant specified by the role (the origin or the target of the action) is the same as a member of the list labeled "criterion". This is a "third-tier" criterion (see #ActionResolution).
In the second form, the criterion is relevant if the participant specified by the role is a character of the type given. This is a "second-tier" criterion.
In the third form, the criterion is relevant if the participant specified by the role is located inside the given passage. This is also a "second-tier" criterion.
In the final form, the criterion is relevant if the given function returns true when called with the watch owner, the watch value, and the action. Role is irrelevant but required (as of 0.0.4, subject to change). This criterion's tier is specified explicitly (see #ActionResolution).
The process of resolving an action takes place in two stages. The first is the "polling" stage, which polls participants in order to arrive at a final result for the action. The second directs the participants to apply this result.
Every participant in an action may define a method poll(), which takes three arguments: the participant itself, the action for which polling is taking place, and the current result of the action (possibly nil). The method is expected to return a new result. Results are tables where effect names (corresponding to their definitions as described in #EffectAxes) are mapped to numeric values (in versions through 0.0.4 the format of the result table is not enforced). Participants may also define methods of the form poll_ActionClass(); these methods are only called if the poll() method is not provided and the action is of the type named.
In each polling stage the origin of the action is polled first, then the owner of each relevant watch, and finally the target (if one exists). The watch owners are polled in order of their tiers; third-tier watches are polled first, then second-tier, and finally third-tier watches are polled. The ordering of watches in the same tier is undefined and possibly unreliable.
As with polling, participants may define methods apply() or apply_ActionClass(). These methods take the same arguments as their polling counterparts (with the exception that the result is never nil) but they are not expected to return anything.
In each application stage, the target of the action is called upon first, then the owner of each relevant watch, and finally the origin. The watch owners are called upon again in tiers, but in reverse order; first-tier watches are first, second-tier watches are second, and third-tier watches are third.
In the pre-implementation spec the tiers corresponded to different levels of "specificity". This classification may or may not be desired (feel free to comment below), so stay tuned.
-- ElminI - 05 Nov 2004
-- ArakoN - 29 Sep 2004 |