Creation, building, and registration, of an effect object

The initial_effect function defined in each card script has the purpose of creating the original effects of the card and registering them to the latter when it is invoked. The process of giving an effect to a card can be summarized in three steps.


 * 1) Creation of the effect object
 * 2) Adding components to the effect
 * 3) Registration of the effect to the card

This page lists all the functions that you need to invoke during each of these steps in order to correctly implement an effect. A brief explanation of the function's behavior will be provided each time a new function is introduced, followed by a table containing information on the required (and possibly optional) parameters, and on the outputs returned by the function (if any), and by an example depicting the correct usage of the function.

In addition, at the end of the page, an alternative method of effect creation (based on cloning an already-existing effect) is introduced.

Effect.CreateEffect
Creates an effect object and returns it. At the time of its creation, the effect is "empty" and does basically nothing: you need to add the required components to it in order to make it work correctly.

Example
This line of code is found most commonly inside the initial_effect function: it defines a local variable that represents the effect created by the aforementioned function. Following the estabilished naming conventions, the name of this variable starts with  (short for "effect") followed by a number. When we want to modify and/or register the effect, we just need to use the variable associated with it.

Adding components to the effect
The following functions allow you to build and modify an effect object. Their names are easily identifiable as they all begin with the word "Set".

Effect.SetDescription
See also: EFFECT_FLAG_CLIENT_HINT Assigns a description string to the effect, allowing the players to easily identify the latter during a Duel.

This function is especially needed if your card has multiple Trigger or Quick Effects that could be activated at the same time, or, in general, when there could be ambiguity regarding the effect activated by a card. For example, "Tragoedia" has two Ignition Effects whose activation conditions are not exclusive, and there could be a gamestate where the player can activate either of them: by assigning two different strings to the effects, the player will have an easier time identifying the desired effect when the game prompts them to select which one they want to activate.

Even if your card has no effects that could be mistaken for one another, assigning strings to them is still recommended as there exist multiple cards in the game that can grant additional effects to other cards. For example, when "Hazy Flame Hydra" is used as Xyz Material, it grants a Trigger Effect that can be activated on the Xyz Summon to the Xyz Monster; if the Summoned monster also has a Trigger Effect that can be activated upon its Xyz Summon, such as "Number 6: Chronomaly Atlandis", then both effects would activate at the same time, and the player would probably want to know which effect they are activating since they need to place them in a Chain.

Furthermore, description strings are not only a prerogative of activated effects, but should also be assigned to certain continuous effects, such as "inherent Special Summon" procedures (this is obvious for cards like "Constellar Ptolemy M7", which have an alternative Xyz Summon procedure other than the regular one), and effects that grant additional Normal Summons/Sets to a player (usually a player can only be gain this kind of effect once per turn, and if multiple of them can be applied the player would want a way to distinguish them).

Auxiliary.StringID
In order to assign a string, you must use its ID.

If you want to use one of the system strings of your simulator, open the  file and look for the desired   string; the ID of that string is the number next to. If you don't find the file, here are some general directions. If you want to use a string associated to a card entry in a .cdb, you can generate its ID using the  function.
 * EdoPRO stores a  file inside the   folder; additionally, in the delta subfolders of repositories you can find additional   files containing updated strings.
 * KoishiPRO stores a  file inside the root folder; furthermore, it can also read   files present in the   folder (if present) and in the subfolders of   (depending on the language that was set on the simulator settings)

Example
In the above examples I am assigning a string to the effect e1.


 * In the first example, I use one of the system strings of the simulator, identified by !system 1107 inside the strings.lua file
 * In the second example, I use the first string present in the database entry of the card that has 12345678 as original ID.

Effect.SetCategory
Sets the categories the effect belongs to.

There exist multiple categories, in the form of CATEGORY constants, each one representing a certain kind of effect: for example, if the effect lets a player(s) draw a card(s), it should be included in the category of effects that include drawing cards (CATEGORY_DRAW); if that same effect also makes a player discard a card, then it should also belong to the category of effects that include discarding cards (CATEGORY_HANDES).

You must choose the categories depending on what the effect does at the time of its resolution, and you must take into account both the mandatory and the optional parts of the effect. For instance, the effect of "Sky Striker Mobilize - Engage!" is comprised of two parts, one of which is optional:


 * Mandatory part: Add 1 "Sky Striker" card from your Deck to your hand, except "Sky Striker Mobilize - Engage!"...
 * Optional part: ...then, if you have 3 or more Spells in your GY, you can draw 1 card.

Even if the drawing part is optional, the effect still falls into the category of effects that include drawing cards.

Setting the correct categories for your effect is important since some cards (that interact with effects that involve specific actions, such as "Ghost Belle & Haunted Mansion") rely on them in order to function properly.

Parameters
In order to set the categories, you can use CATEGORY constants. If your effect belongs to multiple categories, you can "combine" multiple CATEGORY constants by separating them using  or.

Effect.SetType
Sets the type of the effect.

There exist multiple types of effects, which, according to the official terminology of the game, can be mainly classified into Continuous, Ignition, Trigger, Flip, and Quick Effects. Aside from these, there are also various "unclassified" effects that do not fall into any of the aforementioned categories.

In order to set the type of the effect, you can use EFFECT_TYPE constants. Each one of these constants is associated to a specific type of effect, but they do not necessarily follow the exact official classification. For instance, EFFECT_TYPE_SINGLE, EFFECT_TYPE_FIELD, and EFFECT_TYPE_CONTINUOUS all deal with different kinds of Continuous and "unclassified" effects.

You must always set the type of an effect, and your choice will determine what other functions you need to invoke to build it correctly: for instance, if you're making a Trigger Effect, you will also need to invoke Effect.SetCode in order to set the activation timing of the effect; the same cannot be said for Ignition Effects, which do not require you to use the Effect.SetCode function since their activation timing is already defined.

Parameters
Sometimes, you will need to "combine" multiple EFFECT_TYPE constants to achieve a specific type of effect: if that situation arises, separate the different constants you use with  or.

Effect.SetProperty
Sets the properties of the effect.

There exist multiple properties in the form of EFFECT_FLAG constants, and each one allows you to add a special characteristic to the effect you are creating and/or modifying. You have many options you can choose from, but for now I will only introduce the most common flags that you'll encounter:

In addition to EFFECT_FLAG constants, there are special properties that can be accessed through EFFECT_FLAG2 constants. These properties are not used as frequently as their EFFECT_FLAG counterparts and must only be applied in a few situations.
 * EFFECT_FLAG_DELAY: If applied to a Trigger Effect, the effect will not miss the timing. It is the equivalent of writing the activation condition of the effect using  rather than  . It can also be applied to a Quick Effect in order to transform it into a "delayed" Quick Effect, such as the one of "Droll & Lock Bird".
 * EFFECT_FLAG_DAMAGE_STEP: Allows the effect to be activated during the Damage Step, except during damage calculation.
 * EFFECT_FLAG_DAMAGE_CAL: Allows the effect to be activated during damage calculation.
 * EFFECT_FLAG_CARD_TARGET: If applied to an effect, the effect will target.

Parameters
If you want to assign multiple properties to your effect, you can "combine" multiple EFFECT_FLAG constants by separating them using  or.

Effect.SetCode
This function performs different tasks depending on the EFFECT_TYPE constant(s) that was used when setting the type of the effect.


 * If exactly 1 of the following types was set (EFFECT_TYPE_SINGLE, EFFECT_TYPE_FIELD, EFFECT_TYPE_XMATERIAL, EFFECT_TYPE_EQUIP) and no other type constants were used, then Effect.SetCode sets what the effect does.
 * If one of the following types was set (EFFECT_TYPE_TRIGGER_O, EFFECT_TYPE_TRIGGER_F, EFFECT_TYPE_QUICK_O, EFFECT_TYPE_QUICK_F, EFFECT_TYPE_CONTINUOUS), then Effect.SetCode sets the activation timing, or, in other words, the event that needs to occur in order for the effect to activate.

In the first case, you must use EFFECT constants, whereas in the second case you must use EVENT constants.

Parameters
Unlike the previous functions, you can only use exactly 1 constant this time.

Effect.SetRange
Sets the location(s) from which the effect can be applied/activated. If the handler of the effect is not in any of the specified locations, the effect does not apply, and cannot be activated.

You can pass LOCATION constants when invoking this function.

Parameters
If you want to include multiple locations, you can "combine" multiple LOCATION constants by separating them using  or.

Effect.SetTargetRange
This function performs different tasks depending on the EFFECT_FLAG constants that were used to set the effect's properties.


 * 1) Normally, this function allows you to set the location(s) that are affected by the effect. If a card(s) is in any of the specified locations, then it can be affected by the effect.
 * 2) If EFFECT_FLAG_TARGET_PLAYER was set as property, the function sets the player(s) that are affected by the effect.
 * 3) In case of "inherent Special Summon procedures", if EFFECT_FLAG_SPSUM_PARAM was set as property, the function allows you to set the battle position the card will be Summoned in, and the field it will be Summoned into.

In the first two cases, you must pass exactly 2 arguments (disregarding the Effect Object) when invoking this function, whereas in the last one you are free to pass only one. As for the type of arguments you need to pass, they vary depending on the same cases as before:


 * 1) You can use LOCATION constants: the first argument determines the effect handler's controler locations that will be affected, the second determines that player's opponent's ones instead. If you do not want to affect a specific player's locations, you can pass 0.
 * 2) *If the EFFECT_FLAG_ABSOLUTE_TARGET is set as property, then the first argument will always determine your locations, while the second one will always determine your opponent's locations, independently from the current controler of the effect's handler.
 * 3) You must pass either 0 or 1: 0 means that the respective player is not affected by the effect, whereas 1 means that they are affected instead. The first argument refers to the effect's handler's current controler, whereas the second one refers to that player's opponent.
 * 4) *If the EFFECT_FLAG_ABSOLUTE_TARGET is set as property, then the first argument will always refer to you, while the second one will always refer to your opponent, independently from the current controler of the effect's handler.
 * 5) You can pass position constants (POS constants) as the first argument, and either 0 or 1 as the second argument: if you pass 1 the monster will be Special Summoned to your opponent's field instead of yours.

Parameters
If you want to include multiple locations (or positions in the third case), you can "combine" multiple LOCATION (or POS) constants by separating them using  or.

Effect.SetCountLimit
With this function, you can establish a usage limit for the effect, which typically applies to a single turn. In the game, there exist various types of usage restrictions that can be assigned to an effect; the most common ones are:


 * Once per turn (colloquially abbreviated to OPT, or SOPT, as in Soft Once per Turn): They can be identified by the line of text "Once per turn..." (located in the activation condition before a colon, in the case of activated effects). These effects can only be used once per turn while the card is in its current location, and in its current position. Examples of cards with a SOPT effect are "Link Spider" (activated) and "ZW - Pegasus Twin Saber (non-activated). This restriction has some special properties that you should keep in mind:


 * 1) Even if the activation of a SOPT effect is negated, the restriction still applies and effect cannot be activated again.
 * 2) The restriction only applies to a specific copy of a card, so, if there are two copies of a card that has a SOPT effect, each copy can activate that effect during the same turn (but the same copy cannot activate it again).
 * 3) If a card that has already activated its SOPT effect in its current location is removed and later returns to that location, the effect can be activated once again, as if the restriction had expired.
 * 4) If a card that has already activated its SOPT effect in its current location is flipped face-down and then subsequently flipped face-up, the effect can be activated once again, as if the restriction had expired.


 * Once while this card is [location]: A fairly uncommon kind of restriction, it allows an effect to be activated/used only once while the card is in the specified location. Examples of cards with this clause are the "Wind-Up" monsters (activated) and "Elemental HERO Necroshade" (non-activated). This restriction has the same properties as the one above.


 * You can only use [effect] of [card name] once per turn (colloquially known as Hard Once per Turn, or HOPT): This line has many variations, depending on the structure of the card's text, and is often found before or after the effect(s) it refers to, separated from the actual texts of the latter(s). Each player can only use these effects once per turn, and the restriction extends to all cards with the name specified by the clause. Examples of cards with this clause are "Ash Blossom & Joyous Spring" (activated) and "Alghoul Mazera" (both activated and non-activated). This restriction has the following properties:


 * 1) Even if the activation of an HOPT effect is negated, the restriction still applies and effect cannot be activated again during that same turn.
 * 2) Unlike SOPT effects, this restriction applies to all cards with the name specified by the clause, so, if there are two copies of a card that has an HOPT effect, only 1 of them can activate/use that effect during a turn, and only once during that turn.
 * 3) This restriction is not affected by card name changes: this means that even if a card has already activated its HOPT effect and later undergoes a name change, the effect cannot be activated again.


 * You can only activate 1 [card name] per turn (another form of HOPTs): This line is only found on Spells/Traps, and always refers to the activation of the card itself, and not to one of its effects. Each player can only activate these cards once per turn, and the restriction extends to all cards with the name specified by the clause. Examples of cards with this clause are "Pot of Desires" and "Trap Trick" This restriction has the following properties:


 * 1) If the activation of the card is negated, a player can still activate another card with that name during that same turn, as if the restriction never applied in the first place.
 * 2) The restriction applies to all cards with the name specified by the clause.
 * 3) The restriction is not affected by card name changes.


 * You can only use 1 [card name] effect per turn, and only once that turn (a stronger form of HOPTs): Each player can only use 1 of the effects the clause refers to once per turn, and that effect can only be used once during that turn, also this restriction extends to all cards with the specified name. Basically, once I use 1 effect of such a card, I cannot use any other effect of cards with that name during that turn. Examples of cards with this clause are "Cyber Dragon Core" and "Eldlixir of Scarlet Sanguine". This restriction has the same properties as the one introduced before, in the third bullet point.
 * You can only use [effect] of [card] once per Duel (commonly abbreviated to OPD): Arguably the most strict restriction that can be applied to an effect. These effects can only be used once during the entire Duel, and the restriction extends to all cards with the name specified by the clause. Examples of cards with this clause are "Glow-Up Bulb" and "Blackwing - Zephyros the Elite". This restriction has the same properties as the one introduced before, in the third bullet point.

Parameters
This function is defined differently in EdoPRO and KoishiPRO: while the required parameters are the same, the format of the optional ones changes. The EFFECT_COUNT_CODE constants you can use are:


 * EFFECT_COUNT_CODE_OATH: If the activation of the effect is negated, then you can still activate that same effect (of cards with the same name specified in the restriction clause) during that same turn.
 * EFFECT_COUNT_CODE_DUEL: Makes the restriction apply for the entire Duel, instead of a single turn.
 * EFFECT_COUNT_CODE_SINGLE: You can use register this flag to multiple SOPT effects in order to make them share the same restriction. In other words, it can be used to script the following clause (see "Daigusto Emeral"): "Once per turn: You can activate 1 of these effects; . . ."

You can combine multiple flags by using the  operator.

Conventional examples
This section will only show how to implement the conventional TCG/OCG restrictions, distinguishing between the EdoPRO and KoishiPRO formats.

Effect.SetHintTiming
This function allows you to set specific timings in which the game asks the player whether they want to apply/activate the effect before proceeding with the Duel.

This feature is really only needed when creating Fast Effects (like the Quick Effect of monsters, or the effects of Trap Cards) that do not have an estabilished activation timing. Let's take, for example, the following effects:


 * "Torrential Tribute": Its Fast Effect has a very specific activation condition ("When a monster(s) is Summoned: . . ."). During a Duel, when that event occurs, the game will always pause and ask the player for confirmation before proceeding. In this case,  is not required.


 * "Spright Elf": Its Quick Effect can only be used during the Main Phase, but its activation timing is not set in stone, since it can be activated any time as long as the rules of the Fast Effect Timing chart are followed. For example, it could be activated in response to the activation of another card or effect, or to another action performed by a player (such as Summoning a monster, or drawing a card). In this case, it is recommended to invoke  in order to specify the timings when the game has to stop and ask the player whether they want to activate this effect.

An effect's usage timings are represented by TIMING constants. There exist many different kinds of them, but, for the sake of brevity, here are only listed the ones you'll have to apply the majority of times:


 * TIMING_SUMMON, TIMING_SPSUMMON, and TIMING_FLIPSUMMON: These three timings represent the moment a monster is Normal Summoned, Special Summoned, and Flip Summoned, respectively. There also exists a constant that combines all these timings, called TIMINGS_CHECK_MONSTER.
 * TIMING_DAMAGE_STEP, and TIMING_DAMAGE_CAL: If you use these timings the game will always ask the player whether they want to activate the effect once they/their opponent has entered the Damage Step, and the damage calculation, respectively.
 * TIMING_MAIN_END: If a player intends to end their Main Phase, their opponent has the opportunity to activate a Fast Effect before the game moves on to the next Phase. It is recommended to use this timing if you want to avoid scenarios where a player misses the chance of activating an effect due to a skipped prompt at the end of the Main Phase.
 * TIMING_END_PHASE: If you use this timing, the game will always ask the player whether they want to activate the effect once the End Phase is entered.

A useful combination to remember is the following, or   if you are scripting for EdoPRO.

Parameters
Normally, you only need to pass one argument (excluding the effect object) when you invoke this function, that argument being the timing(s) of the prompt.

Effect.SetCondition
Sets the Condition Function of the effect, which defines the condition that must be satisfied in order for the effect to be applicable/activatable.

Effect.SetCost
Sets the Cost Function of the effect, which defines the cost that must be paid in order for the effect to be applied/activated.

Effect.SetTarget
Set the Target Function of the effect, which has various different purposes:


 * 1) Verifies if the activation of the effect would be legal
 * 2) Defines the procedures that are executed at the time of the effect's activation, such as targeting cards, or declaring card properties
 * 3) Sets the information about what the effect will accomplish when it will eventually resolve, thus handling interactions with cards like "Ash Blossom & Joyous Spring".
 * 4) If the effect targets, it defines the requisites that a card must satisfy in order to be a valid target: this way, it handles the interactions with other effects that are capable of changing the target designated by the player (i.e. "Cairngorgon, Antiluminescent Knight")

Effect.SetOperation
Sets the Operation Function of the effect, which defines the behaviour of the effect at the time of resolution.

Effect.SetValue
This function is generally invoked when building a non-activated effect, and allows you to assign a value to said effect. This value will influence the behaviour of the effect it was assigned to.

Effect.SetLabel
This function allows you to set the effect's internal label. In simple terms, you can imagine the effect as a box: you can use this function to "store" one or more integers inside the box (in other words, the "effect"), in order to use them at a later point.

Each time you invoke this function, all the previously stored labels will be overwritten. This means that, if you are storing multiple labels, and you only want to modify one of them, you must invoke the function by passing all the current labels as arguments (not only the one you want to modify).

You can access all the labels stored inside an effect by invoking : if you do so, it will return all the labels in the same order they were set in the last time   was called.

Effect.SetLabelObject
Similarly to the previous function, this one allows you to "store" an object inside an effect. There are a couple of differences from Effect.SetLabel:


 * 1) You can only store 1 object at a time.
 * 2) Instead of an integer, you can now store a card, a group of cards (even an empty one), or even another effect, inside the effect. Additionally, EdoPRO also allows you to store tables.

Note that, if you want to store a group of cards, you must also call the  function, in order to prevent the group (and thus the label object= from getting deleted once you exit from the function.

Each time you invoke, the previously stored object is overwritten.

You can access the stored object by invoking.

Effect.SetReset
Main article: Resetting an effect

This function allows you to set a timing and/or an event which causes the effect to reset, or, in other words, to stop applying permanently. Usually, you will never need to actually use this feature inside the initial_effect function.

Parameters
You can "combine" multiple RESET, EVENT, and/or PHASE constants by separating them using  or.

Card.RegisterEffect
This function allows you to register an effect to a card, which will then be able to use it properly.

Conventionally, this function is only invoked once you added all the necessary components to the effect object during the building process. Nonetheless, once you register an effect to a card, you can still modify said effect and/or add further components to it: if you do that, you do not need to invoke this function again (since it would bear no effect).

Once an effect has been registered to a card, it cannot be registered again to any card (not even to the card it is currently registered to)

Clonation of an effect
Sometimes, you might find yourself in a situation where the effect you want to create is really similar to another effect that you already created previously. In this case, instead of following the usual effect creation procedure, you can adopt a faster approach: it would be better to clone the effect you want to use as reference, modify the parts that need to be changed, and then register the newly formed effect.

The function you can use to clone an effect is : it only takes 1 parameter, which is the effect you want to clone, and outputs a clone of the imputted effect; the clone will inherit all the components you previously assigned to the original effect, so you do not need to add them again.

Once an effect has been cloned, we can modify it without affecting the original effect. Vice versa, once an effect has been cloned, any modification applied to the original effect will not be inherited by the clone.

In the provided example, I implemented the following effect:"'This card gains 1000 ATK/DEF'."The ATK boost is handled by, while the DEF boost is handled by. As you can see, instead of copy-pasting the same lines from, I invoked the   function and assigned its output (the clone of  ) to the variable named. The only change I need to do is modify the EFFECT constant of the cloned effect (from EFFECT_UPDATE_ATTACK to EFFECT_UPDATE_DEFENSE). After that, I can register  to the card.