view release on metacpan or  search on metacpan

Object.pod  view on Meta::CPAN

There is another important difference between incremental and non-incremental
persistent modifiers. A non-incremental modifier's effect is removed when
the modifer is later cancelled. Thus in the above example, if the "strength"
modifier caused it to go from 15 to 16, when the modifier is removed, it will
drop back from 16 to 15. However, in the case of the incremental modifier,
the effects are permanent. When the "health" modifier goes away, it does not
"take away" the accumulated additions to the attribute.

Note that the effects of modifiers and tend-to rates are cumulative. This
needs to be taken into account to make sure modifiers are doing what you
think they're doing. For instance, if the idea is to add a modifier that
saps away health by -1 each time C<process()> is called, but the health
attribute has a I<-tend_to_rate> of 1, the net effect will simply be to cancel
out the tend-to, which may or may not be what you wanted. Future directions
for this module may include ways to automatically nullify tend-to rates.

Also note that modifiers are still subject to limitations via I<-minimum> and
I<-maximum> options on the attribute.

=item Self-limiting modifiers

It was noted above that persistent modifiers stay in effect until they are
purposely cancelled. However, you can set up a modifier to cancel itself after
a given amount of time by adding the I<-time> option:

    $obj->mod_attr(-name => "wisdom",
		   -modify => 2,
		   -persist_as => "spell:increase_wisdom",
		   -time => 10);

In this case, -time refers to the number of times C<process()> is called (rather
than real time). The above indicates that the modification will last through
the next 10 full calls to C<process()>. These means that after the 10th call
to C<process()>, the modification is still in effect. Only when the 11th
call is made is the modifier removed.

A self-limiting modifier can still be manually cancelled like any other
persistent modifier.

=item Applying persistent modifier effects immediately

As stated above, the usual behavior of persistent modifiers is that they
do not take effect immediately, but rather when the next process() call is
made on the object.

With version 0.05 of Games::Object, you can force a persistent modifier to
take effect immediately. This is done by using the I<-apply_now> option to
the mod_attr() call. Setting this to a true value will cause mod_attr()
to apply the effects of the modifier right now. This also means that any
events associated with modifying the attribute will be triggered at this
time.

Be careful when using this feature with incremental modifiers. This means
that the target attribute will be modified now, and then again when the
process() is next called on the object.

=item Delayed-action modifiers

A persistent modifier, either one that is timed or not, can be set up such
that it does not take effect for a given number of iterations through the
C<process()> method. This is done via the I<-delay> option, as in this example:

    $obj->mod_attr(-name => "health",
		   -modify => -5,
		   -incremental => 1,
		   -persist_as => "food_poisoning",
		   -time => 5,
		   -delay => 3);

This means: For the next 3 calls to C<process()>, do nothing. On the 4th,
begin subtracting 5 from health for 5 more times through C<process()>. The
last decrement to health will take place on the 8th call to C<process()>. On
the 9th call, the modifier is removed.

Note that while this example combined I<-delay> with I<-time> and
I<-incremental> to show how they can work together, you do not have to combine
all these options.

A delayed-action modifier can be cancelled even before it has taken effect.

=item Cancelling persistent modifiers

Any persistent modifier can be cancelled at will. There are two ways to cancel
modifiers. One is to cancel one specific modifier:

    $obj->mod_attr(-cancel_modify => 'spell:increase_wisdom');

Note that the I<-name> parameter is not needed. This is because this information
is stored in the internal persistent modifier. You only need the ID that you
specified when you created the modifier in the first place.

Or, you can choose to cancel a bunch of modifiers at once:

    $obj->mod_attr(-cancel_modify_re => '^spell:.*');

The value of the I<-cancel_modify_re> option is treated as a Perl regular
expression that is applied to every modifier ID in the object. Each that matches
will be cancelled. Any matching modifiers on that object will be cancelled,
no matter what attribute they are modifying. This makes it easy to cancel
similar modifiers across multiple attributes.

For each non-incremental modifier that is cancelled, C<mod_attr()> will reverse
the modification that was made to the attribute, but not right away. It will
instead take place the next time C<process()> is called. To override this
and force the change at the very moment the cancellation is done, include
the I<-immediate> option set to true, as in this example:

    $obj->mod_attr(-cancel_modify_re => '^spell:.*',
		   -immediate => 1);

=back

=head2 The I<-force> option

Any modification of an attribute via C<mod_attr()> may take the I<-force>
option. Setting this to true will cause the modifier to ignore any bounds
checking on the attribute value. In this manner you can force an attribute
to take on a value that would normally be outside the range of the attribute.

For example, the following modification would force the value of the attribute