Timed Effects

[moyack]

Timed Effects
by moyack. 2009

Introduction

So... have you been needing a simple way (or function) to create an effect temporally and don't worry about destroying it? or you're needing that an effect with different animations (birth, stand, death) will show all of them?? if your answer is yes to any of those questions, then you're in the right place.

This script is used in my project Power of Corruption, as you'll see, it's simple as hell.

Just to point out: this library is very useful with effects that have different animations, so using this library with single animation effect will do the same as call DestroyEffect(AddSpecialEffect(....))


How to use it?

Just add an effect as parameter and then you set its duration.

Example: call StartTimedEffect(AddSpecialEffect(fx, 0., 0.), 2.)

You won't need anything else, the system will care of cleaning the effect properly and recycle the values for you.

The code.

This library requires TimerUtils

TimedEffects - TimerUtils version:

//***********************
//*    Timed Effects    *
//*   by moyack. 2011   *
//***********************
//*
//* Requires Jass NewGen Pack and TimerUtils
//*    
//* Introduction
//* ============
//*
//* So... have you been needing a simple way (or function) to create an effect temporally
//* and don't worry about destroying it? or you're needing that an effect with different 
//* animations (birth, stand, death) will show all of them?? if your answer is yes to any
//* of those questions, then you're in the right place.
//*
//* This script is used in my project Power of Corruption (http://poc.it.cx), as you'll see, 
//* it's simple as hell.
//*
//* Just to point out: this library is very useful with effects that have different 
//* animations, so using this library with single animation effect will do the same as 
//* call DestroyEffect(AddSpecialEffect(....))
//*
//* How to use it?
//* ==============
//* - Create a trigger with a convenient name (like Timed Effects :P)
//* - Convert the trigger to custom text
//* - Copy and paste this code and save your map.
//*
//* With all this done, you just have to call the function StartTimedEffect(), and as parameters
//* an effect and a real value which will be the effect duration.
//*
//*   Example: call StartTimedEffect(AddSpecialEffect(fx, 0., 0.), 2.)
//*
//* You won't need anything else, the system will care of cleaning the effect properly 
//* and recycle the values for you.

library_once TimedEffects requires TimerUtils

private struct data
    effect f = null
    timer t
    static method create takes effect f returns data
        local data dt = data.allocate()
        set dt.t = NewTimer()
        set dt.f = f
        call SetTimerData(dt.t, integer(dt))
        return dt
    endmethod
endstruct

private function DestroyTimedEffect takes nothing returns nothing
    local data d = data(GetTimerData(GetExpiredTimer()))
    call DestroyEffect(d.f)
    call ReleaseTimer(d.t)
    call d.destroy()
endfunction

function StartTimedEffect takes effect f, real dur returns nothing
    local data d = data.create(f)
    call TimerStart(d.t, dur, false, function DestroyTimedEffect)
endfunction

endlibrary

TimedLoop version:

//***********************
//*    Timed Effects    *
//*   by moyack. 2011   *
//***********************
//*
//* Requires Jass NewGen Pack and TimedLoop by Vexorian
//*    
//* Introduction
//* ============
//*
//* So... have you been needing a simple way (or function) to create an effect temporally
//* and don't worry about destroying it? or you're needing that an effect with different 
//* animations (birth, stand, death) will show all of them?? if your answer is yes to any
//* of those questions, then you're in the right place.
//*
//* This script is used in my project Power of Corruption (http://poc.it.cx), as you'll see, 
//* it's simple as hell.
//*
//* Just to point out: this library is very useful with effects that have different 
//* animations, so using this library with single animation effect will do the same as 
//* call DestroyEffect(AddSpecialEffect(....))
//*
//* How to use it?
//* ==============
//* - Create a trigger with a convenient name (like Timed Effects :P)
//* - Convert the trigger to custom text
//* - Copy and paste this code and save your map.
//*
//* With all this done, you just have to call the function StartTimedEffect(), and as parameters
//* an effect and a real value which will be the effect duration.
//*
//*   Example: call StartTimedEffect(AddSpecialEffect(fx, 0., 0.), 2.)
//*
//* You won't need anything else, the system will care of cleaning the effect properly 
//* and recycle the values for you.

library_once TimedEffects requires TimedLoop

private struct data
    effect f = null
    real time = 0.
    real dur 
    
    private method onTimedLoop takes nothing returns boolean
        set .time = .time + TimedLoop_PERIOD
        if .time > .dur then
            call DestroyEffect(.f)
            return TimedLoop_STOP
        endif
        return TimedLoop_CONTINUE
    endmethod
    
    implement TimedLoop
    
    static method create takes effect f, real t returns thistype
        local thistype dt = thistype.allocate()
        set dt.dur = t
        set dt.f = f
        call dt.startTimedLoop()
        return dt
    endmethod
endstruct

function StartTimedEffect takes effect f, real dur returns nothing
    local data d = data.create(f,dur)
endfunction

endlibrary

.:

I did by request an addition to the code: a library which will allow to the user to set a delayed effect. In other words: if you need that an effect takes X seconds to start and keeps visible by Y seconds, this extension allows you to do that in one single line.

TimedEffects Extension (TEEX), adds delay settings. Uses TimerUtils:

//***************************
//* Timed Effects Extension *
//*     by moyack. 2009     *
//***************************
//*
//* Requires Jass NewGen Pack, TimerUtils and TimedEffects libraries.
//*
//* This library extends the TimedEffects library by adding a delay property,
//* with this, we can set in one line of code and effect that should wait X
//* seconds to start and then create it for Y seconds.
//*
//* How to use it?
//* ==============
//*
//* Let's say you want to create an effect in a point that appears after 5 
//* seconds and last 3 seconds, then we'll use this function:
//*
//* call StartSpecialEffectTimed( "effect//path", X, Y, 5., 3. )
//*
//* If you want to add an effect to a unit after 4 seconds and last 2 seconds,
//* we'll use this function:
//*
//* call StartSpecialEffectTargetTimed( "effect//path", Unit, "attach,point", 4., 2. )

library TEEX requires TimedEffects

private struct data
    real d
    string p
    real x
    real y
    widget w = null
    string at
    static method create takes string p, real x, real y, widget w, string at, real d returns data
        local data dt = data.allocate()
        set dt.d = d
        set dt.p = p
        set dt.x = x
        set dt.y = y
        set dt.w = w
        set dt.at = at
        return dt
    endmethod
endstruct

private function Play takes nothing returns nothing
    local data d = data( GetTimerData(GetExpiredTimer()) )
    local effect f
    if d.w == null then
        set f = AddSpecialEffect(d.p, d.x, d.y)
    else
        set f = AddSpecialEffectTarget(d.p, d.w, d.at)
    endif
    call StartTimedEffect(f, d.d)
    call d.destroy()
    call ReleaseTimer(GetExpiredTimer())
    set f = null
endfunction

//********************************************
//* The only functions you'll need to use... *
//********************************************
function StartSpecialEffectTimed takes string s, real X, real Y, real DELAY, real DURATION returns nothing
    local timer t
    if DELAY <= 0 then
        call StartTimedEffect(AddSpecialEffect(s, X, Y), DURATION)
    else
        set t = NewTimer()
        call SetTimerData(t, integer(data.create(s, X, Y, null, null, DURATION)))
        call TimerStart(t, DELAY, false, function Play)
    endif
    set t = null
endfunction

function StartSpecialEffectTargetTimed takes string s, widget w, string at, real DELAY, real DURATION returns nothing
    local timer t
    if DELAY <= 0 then
        call StartTimedEffect(AddSpecialEffectTarget(s, w, at), DURATION)
    else
        set t = NewTimer()
        call SetTimerData(t, integer(data.create(s, 0., 0., w, at, DURATION)))
        call TimerStart(t, DELAY, false, function Play)
    endif
    set t = null
endfunction

endlibrary

Usage of TEEX:

JASS:

call StartSpecialEffectTimed("Some_File_Path.mdx", X, Y, DELAY, DURATION)
call StartSpecialEffectTargetTimed("Some_File_Path.mdx", SOMEWIDGET, "Attach_point", DELAY, DURATION)

Now enjoy your new code :) Comments and such are welcome and appreciated.

Changelog:

* 1/21/2009: First Release
* 3/08/2009: Now StartTimedEffect returns the index of the TimedEffect object and added the StopTimedEffect function so you can stop it manually.
* 3/20/2009: Simplified more to avoid the .execute call
* 6/10/2011: Added TimedLoop version

[Rising_Dusk]

Ah yes, now this is about the size a library of this nature should be.

Although, I see lots of flaws in this method versus Deaod's. Firstly, you are dynamically creating timers for use in your code, which is a thing of the past. You should probably use a flavor of TimerUtils for this library, as it will remove that unnecessary and silly step.

Additionally, this doesn't allow effects to be created after an X second delay from when the function is called. I think that is a useful quantity to have access to in a library such as this.

Finally, I think the mode for calling the code is not as effective as it should be. I recommend the following function form --

JASS:

call UnitAddTimedEffect("Some_File_Path.mdx", X, Y, DELAY, DURATION)
call UnitAddTimedEffectTarget("Some_File_Path.mdx", SOMEUNIT, DELAY, DURATION)

I think that would be the optimal manner by which to code it for it to fit into jass' syntax structure most effectively.

[moyack]

Originally Posted by Rising_Dusk

Although, I see lots of flaws in this method versus Deaod's. Firstly, you are dynamically creating timers for use in your code, which is a thing of the past. You should probably use a flavor of TimerUtils for this library, as it will remove that unnecessary and silly step.

What?? No!!! I'm not creating timers for each effect if you mean that. I use a single timer that controls all the effects. It seems the struct arrangement is confusing you. Every method in a struct that is called onInit will run at map init.

Additionally, this doesn't allow effects to be created after an X second delay from when the function is called. I think that is a useful quantity to have access to in a library such as this.

Well, honestly in all my time coding I've never needed this as a regular function, I achieve this with the spells themselves rather than using a system because it has not been a common task, but well, we can do that... like an extension of this script.

Finally, I think the mode for calling the code is not as effective as it should be. I recommend the following function form --

JASS:

call UnitAddTimedEffect("Some_File_Path.mdx", X, Y, DELAY, DURATION)
call UnitAddTimedEffectTarget("Some_File_Path.mdx", SOMEUNIT, DELAY, DURATION)

I think that would be the optimal manner by which to code it for it to fit into jass' syntax structure most effectively.

well, I did this function in that way because in this way I cover all the kind of effect possible, but I can't deny your proposal is nice too. I'll do something to make happy everybody, a library extension with that input form, inline friendly.

[Anitarf]

Dusk, where do you see dynamic timers being used?
I agree, however, it would be more sensible to code this using TimerUtils.

Also, what Dusk said about naming conventions, minus the Unit part which looks like it's just a silly typo.

[moyack]

Originally Posted by Anitarf

I agree, however, it would be more sensible to code this using TimerUtils.

hmmm... just to confirm if I understand properly, use TimerUtils for... performance? precision?

Also, what Dusk said about naming conventions, minus the Unit part which looks like it's just a silly typo.

Ohh yes, minus the Unit part...

[Anitarf]

Originally Posted by moyack

hmmm... just to confirm if I understand properly, use TimerUtils for... performance? precision?

Both.

I imagine having more timers isn't such a bad thing when it means WC3 doesn't have to execute slow jass code many times per second; it should be the faster solution.

The greater precision of having a timer per each effect is entirely undisputed; whether it matters or not is up to debate, but at worst the precision is irrelevant, and at best it's also in favour of a timer per effect method.

[moyack]

Originally Posted by Anitarf

Both.

I imagine having more timers isn't such a bad thing when it means WC3 doesn't have to execute slow jass code many times per second; it should be the faster solution.

The greater precision of having a timer per each effect is entirely undisputed; whether it matters or not is up to debate, but at worst the precision is irrelevant, and at best it's also in favour of a timer per effect method.

Well, I've tested this code in very hard situations and I haven't had any performance issues. About precision, it's not important in the spell duration but it is it the delay if I follow dusk suggestion. Can you notice if an effect ends in 5.1 seconds or if it ends at 5.151 seconds?? I'm pretty sure you can't, and this is more masked by effects with death animation.

I've added in the first post a library extension which allows the delay option and a version that uses TimerUtils.

[Rising_Dusk]

Originally Posted by Anitarf

Dusk, where do you see dynamic timers being used?

I guess I'm just an idiot. I should stop posting in these code threads, I apparently can't even read them properly.

Originally Posted by Anitarf

minus the Unit part which looks like it's just a silly typo.

...I must be having an off day... That shouldn't have been in there, bleh.

[Seshiro]

If I see rightly, you forgot to add the globals block into the TimerUtils one:
call TimerStart(t, d, false, function End) The variable d isnt existing, thought

The rest looks very good, but could you maybe Change the function Name to TimedEffect or something kinda, because StartEffect doesn't say anything 'bout the function, and what its doing, but handling something with effects


Greez

[moyack]

Ok, fixed, I tested the code in WE last night, but I was soo sleepy that I forgot to paste the right one....

Thanks for the feedback Seshiro

[Rising_Dusk]

I do still think AddTimedEffect() would be much more practical than TimedEffect. It'd also match closer with AddSpecialEffect(). Also, why in the world do you still have your single timer version? It's much more inefficient than a single timer with one execution after a precise amount of time. Not to mention you never pause the timer even if no effects are loaded to it, which isn't very good.

[moyack]

PoC runs the single timer version, and it works very smooth...

I propose the following: if somebody could help me benchmarking, it will be great and man love will be given for that (to be honest I'm not good doing this).

[Anitarf]

Originally Posted by moyack

PoC runs the single timer version, and it works very smooth...

Perhaps for you, but on weaker hardware or in a more challenging map it could lead to problems. I agree that the difference isn't big; but if you apply that logic to every spell and system then you eventually get a considerable difference once you compose them all together into a single map.

The single-timer version doesn't require other libraries, which could be considered a bonus in the case of any system other than TimerUtils. In the case of such a used library, however, it's pretty inconsequential.

If you insist on including a one-timer version then you may do so, but it should be secondary to the TimerUtils one (put it lower in the post, maybe use hiddenjass tags and explain beforehand it's intended for people who for some bizzare reason don't use TimerUtils) and the timer definitely shouldn't be running when there are no effects being timed.

Also, I second Dusk on the naming conventions. If you insist on this function format (function taking an already existing effect) at least name it accordingly, something like DestroyEffectDelayed or something.

The first post should also note in the introduction that many effects (the ones with a single animation) can be destroyed immediately after they are created. People who don't know that and stumble on this resource might otherwise think they should use it on all their effects.

[moyack]

Originally Posted by Anitarf

Perhaps for you, but on weaker hardware or in a more challenging map it could lead to problems. I agree that the difference isn't big; but if you apply that logic to every spell and system then you eventually get a considerable difference once you compose them all together into a single map.

The single-timer version doesn't require other libraries, which could be considered a bonus in the case of any system other than TimerUtils. In the case of such a used library, however, it's pretty inconsequential.

If you insist on including a one-timer version then you may do so, but it should be secondary to the TimerUtils one (put it lower in the post, maybe use hiddenjass tags and explain beforehand it's intended for people who for some bizzare reason don't use TimerUtils) and the timer definitely shouldn't be running when there are no effects being timed.

Also, I second Dusk on the naming conventions. If you insist on this function format (function taking an already existing effect) at least name it accordingly, something like DestroyEffectDelayed or something.

The first post should also note in the introduction that many effects (the ones with a single animation) can be destroyed immediately after they are created. People who don't know that and stumble on this resource might otherwise think they should use it on all their effects.

Hey, don't worry, I'm not being stubborn about that single timer is better than other, I just want a small benchmark for curiosity and learning, it will be quite interesting seeing the efficiency of both flavors, and if the one with TimerUtils is best, I'll immediately update my map with that version.

About naming, don't worry either, AddTimedEffect sounds nice to me, and if you like it, I'll do it.

[Anitarf]

In the post, you say the function is called StartEffect yet in the script it's called TimedEffect. I don't think either is very suitable, though. The function AddTimedEffect sounds good because it's style follows the related Blizzard's function, AddSpecialEffect (perhaps even better would be AddSpecialEffectTimed). The TimedEffect function should be similar to it's native counterpart, DestroyEffect, hence why I think the most suitable name is something like DestroyeffectTimed.

Also, you should include some short documentation on the use of the library in the library itself, not just the post, since users might get your library from maps that use it rather than from here.