Effect System

From HEWIKI
Jump to: navigation, search

Contents

An effect is a timed event that can be added to any node.

The Effect System is an easy-to-use way for GameMasters to add timed events to their own systems. In it's simplest form, the GameMaster need only add three shared functions to their script and make one call to Effect, to add the effect.

Example

MyScript
 
function DoSomethingCoolIn5Seconds(myChar as NodeRef)
  Effect:AddEffect("MyCoolEffect", myChar, myChar, SYSTEM.EXEC.THISSCRIPT, 00:00:05.000)
.
shared function OnEffectStart()
  // Do something cool when the effect starts here
.
shared function OnEffectStop()
  // Do something cool when the effect stops here
  // which in this example will be when 5 seconds are up
.
shared function OnEffectTick()
.

Related functions

AddEffect Add an effect to the specified target
FindEffect Find an effect on the specified target based on the name you give
EndEffect End the specified effect (calls onEffectStop)
RemEffect Removes the specified effect any further script calls


Convenience functions

AddInfiniteEffect Add an effect that does not remove itself.
AddCountingEffect Add an effect that ticks till a specified tick count is reached



Shared functions

(to be implemented in your script)

OnEffectStart Called when the effect is added
OnEffectTick Called when the effect reaches it?s duration (if not ONESHOT)
OnEffectStop Called when the effect ends


Adding an Effect

To add an effect to a node, you use the AddEffect function.

AddEffect(eName as String, theOwnerID as ID, theTargetID as ID, scriptName as ScriptRef, duration as TimeInterval) as NodeRef of Class Effect

This function will create an effect node, associates it to theTargetID, and start the effect?s timer. It returns a noderef to the effect which allows you to Glom any data you wish to save specifically on the effect.

EName the Name you give to this effect
TheOwnerID The ID of the node that initiated the effect. If you have no need to track this, pass in theTargetID or 0.
TheTargetID The ID of the node that this effect will be placed on.
ScriptName The script that this effect will call when the timer starts, stops and ticks.
Duration The timeinterval that the effect waits to do something.


When added, the effect will be started making a callback to onEffectStart, wait the specified duration then stop, making a callback to onEffectStop.

Finding an Effect

If you want to see if a node already has a particular effect on it, you can use the FindEffect function.

public function FindEffect(eName as String, targetNode as NodeRef) as NodeRef of Class Effect
EName The name given to the Effect when originally added.
TargetNode The node that the effect is attached to


Ending an Effect

If you have need to end an effect before its natural lifespan is up, you can make a call to EndEffect.

public function EndEffect(theEffect as NodeRef of Class Effect)

TheEffect A noderef to the effect which you got via one of the shared function callbacks or thru FindEffect


When EndEffect is called, the effect's script will receive a function call to OnEffectStop so that systems can allow for it?s ending normally (perform messaging, special effects etc?). Once all callbacks are complete, the effect is removed from the target node.

Removing an Effect

On some occasions, though perhaps rarely, you may need to remove an effect without allowing any script callbacks. This is done with the RemEffect function.

public function RemEffect(theEffect as NodeRef of Class Effect)

TheEffect A noderef to the effect which you got via one of the shared function callbacks or thru FindEffect


Once called, the effect is deleted.

Different types of effects

Infinite effects

Occasionally, you may want an effect that does not removed itself from the target until an action occurs other than the effect?s duration ending. For example, the player contracts a disease, which can only be removed by a cure disease potion.

To do this, we want to add an effect that never ends. This is done with the AddInfiniteEffect function.

public function AddInfiniteEffect(eName as String, theOwnerID as ID, theTargetID as ID, scriptName as ScriptRef, interval as TimeInterval) as NodeRef of Class Effect

EName The name you have chosen for this effect
TheOwnerID The ID of initiator of this effect. If not tracking this, set to the targeted or 0.
TheTargetID The ID of the node that we will be attaching this effect to.
ScriptName The name of the script that implements the shared functions for this effect
Interval The amount of time this effect will wait before calling OnEffectTick. It will repeat waiting the interval and calling OnEffectTick indefinitely, until ended.


In our above disease example, we might set this effect to an interval of 10 minutes and add some messaging to the OnEffectTick function saying something like You feel feverish. And then play an fx script that puts spots in front of their eyes.

The effect script will repeat this forever, until another script (in this case our cure disease potion) is used, which will find the effect using FindEffect and then call EndEffect to end the disease normally.

Counting Effects

If you wanted to create an egg that will hatch after a certain period of time, but while it?s waiting for that time it regularly jiggles with a tap tap from the youngling bird inside, you might want to use a counting effect via the AddCountingEffect function.

public function AddCountingEffect(eName as String, theOwnerID as ID, theTargetID as ID, scriptName as ScriptRef, tickinterval as TimeInterval, endcount as Integer) as NodeRef of Class Effect
EName The name you have chosen for this effect
TheOwnerID The ID of initiator of this effect. If not tracking this, set to the targeted or 0.
TheTargetID The ID of the node that we will be attaching this effect to.
ScriptName The name of the script that implements the shared functions for this effect
TickInterval The amount of time this effect will wait before calling OnEffectTick. Each call it will also increment a counter. It will repeat waiting the interval and calling OnEffectTick indefinitely, until the counter reaches the specified endCount.
EndCount This is the counter that denotes the end of the effect.


In the above hatching egg example, we could set the interval to 7 seconds and the end count to 100. Then each call to OnEffectTick, we could randomly choose to play a jiggle egg effect, play some egg tapping sound effects, perhaps even cause the egg to roll around abit. This will repeat until the count reaches the endcount when the effect would end, calling OnEffectStop, where we put a call in to our youngling bird hatching script.

Client Side Effects vs Server Side Effects

Effects used on the client side are all temporary. They will vanish when the user logs off.

Effects used on the server, may be temporary or permanent. This depends entirely on the persistence of the target node you are attaching the effect to. If you attach an effect to a permanent node, such as character node, then the effect will persist.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox