# EffectLib

by Ter13
Handle generic temporary combat effects efficiently and cleanly
 ID:2286256   Aug 22 2017, 7:18 pm (Edited on Aug 26 2017, 11:10 pm) This thread is all of the relevant documentation for 13.EffectLib. Please refer all discussion regarding this thread to the general forums, bug reports, or feature requests for this library. Listing:
 Aug 22 2017, 8:33 pm (Edited on Aug 26 2017, 11:09 pm) effects var (mob) See also:   effect   effect_registry var (mob)   AddEffect() (mob)   RemoveEffect() (mob)   Add() (effect)   Remove() (effect) Default value:   An empty list The effects var is a list that stores all active effects on this mob. You should not add or remove elements from this list manually. Rearranging the list is not a problem, so long as the effects aren't removed or added manually. Effects are added by calling mob.AddEffect(), or effect.Add(). Effects are removed by calling mob.RemoveEffect(), or effect.Remove(). Timed and Ticker effects will remove themselves automatically on demand. When effects override one another, they will also remove themselves on demand as well. This variable exists not only to keep track of the internals of the effect library, but also as a tool for working with effects individually. For most use-cases, you will want to default to using effect_registry to find effects, as effect_registry uses an associative list to keep track of effects by their id/sub_id combination. However, effects can be added to the mob's effects variable without an id/sub_id combination, in which case they will not be stored in effect_registry at all. effect_registry var (mob) See also:   effect   AddEffect() (mob)   RemoveEffect() (mob)   Add() (effect)   Remove() (effect) Default value:   An empty list The effect_registry is a list that stores effects in an associative format by their id/subid. effect.Add() takes care of building and maintaining this list. As such, you should never add, assign or remove information from this list manually. Structure: { //id storage is either a list, or a single effect datum, associated to effect.id "id1" = [effect 1], "id2" = list([effect 2],[effect 3]), //unique id is "[effect.id].[effect.sub_id]" "id1.subid" = [effect1], "id2.subid" = [effect2], "id3.subid" = [effect3], //if id is non-null, but sub_id is null, the id storage is still used, but there is no unique id for them. "id4" = list([effect 4],[effect 5]) }  The effect datum will attempt to make up to two entries per effect when it is added. The first entry stores the effect in a list with all other effects already in the registry matching the id variable of the effect. If the effects list has no matching ids, the object itself is used associated to the id instead of the list of effects. The second entry generates a unique id from "[effect.id].[effect.sub_id]". This only happens if sub_id is not null. Effects with the same unique id will attempt to override the older one when added, so the unique id storage in the registry will only ever reference a single effect datum. Examples: Getting a specific debuff by unique id. var/damage = 10var/effect/e = target.effect_registry["FireDebuff.global"] //pull from unique idif(e) damage *= 2  Getting any debuff by id var/damage = 10var/list/l = target.effect_registry["FireDebuff"] //pull from id onlyif(e) damage *= 2  Looping over a series of debuffs by id var/list/l = target.effect_registry["FireDebuff"]if(l) //if l is a list if(!istype(l)) //if l is not a list, it's a single effect. Just plug it into a list anyway. l = list(l) for(var/effect/e in l) e.Cancel(target) //cancel the effect  save_worldtime var (mob) See also:   save_realtime var (mob)   Write() (mob)   Read() (mob) Default value:   null save_worldtime is actually part of StdLib. This is used during loading of a mob from a savefile to ensure that time offsets are regenerated relative to world.time when the savefile is loaded next. save_realtime var (mob) See also:   save_worldtime var (mob)   preserve var (effect)   Write() (mob)   Read() (mob) Default value:   null save_realtime is actually part of StdLib. This is used during loading to ensure that time offsets are regenerated relative to the actual time passed while the mob was not loaded. AddEffect proc (mob) See also:   effect   RemoveEffect() (mob)   Add() (effect)   Remove() (effect) Format:   AddEffect(effect datum)   AddEffect(effect datum, world timestamp) Returns:   0 if unsuccessful   1 is successful This is a convenience hook for effect.Add(). This proc simply calls Add() on the effect passed as the argument. This proc exists so that you don't have to define a variable to store the effect when you initialize it: var/effect/e = new/effect/herpyderp()e.Add(target)  target.AddEffect(new/effect/herpyderp())  The time argument is added so that effects can be backdated. This is useful when loading effects from a savefile, but the time argument is optional. It defaults to the current world.time RemoveEffect proc (mob) See also:   effect   AddEffect() (mob)   Remove() (effect)   Add() (effect) Format:   RemoveEffect(effect datum)   RemoveEffect(effect datum, world timestamp) Returns:   0 if unsuccessful   1 is successful This is a convenience hook for effect.Remove(). This proc simply calls Remove() on the effect passed as the argument. It exists so that you don't have to store references to effects in the local proc: var/effect/e = target.effect_registry["id.sub_id"]if(e) e.Remove(target)  target.RemoveEffect(effect_registry["id.sub_id"])  The time argument is only included for the sake of reciprocity with effect.Add(). It is optional and will default to the current world.time. Read proc (mob) See also:   save_realtime var (mob)   save_worldtime var (mob)   preserve var (effect)   Write() (mob) DO NOT CALL THIS PROC MANUALLY, YOU DONKEY! It is part of the default savefile handling system of BYOND. You should never, ever call it manually. This override handles restoring effects on mobs. It copies the list of effects on the loaded mob, then loops through them, calling Add() on each effect with a backdated time argument. Depending on the effect's preserve variable, this will either account for the time spent offline, or not. effect_registry is temporary by default, so this rebuilds the whole registry and gets timer and ticker effects back on track where you left them.