Advanced - Parse Effect: Difference between revisions

From Wiki for The Only Sheet
Jump to navigation Jump to search
 
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
BACK to the [[Advanced User Guide]]
== What is Parse Effect ? ==
== What is Parse Effect ? ==


Parse Effect is actually the name of a function that is available to users of the Sheet. Its goal is to allow anyone to create new content which will be compatible with the stacking Rules of D&D. Not only that, but it also permits to handle the stacking of Abilities like Animal Companion or Turn Undead. In these sections, we'll examine in more details what Parse Effect can do to help you create new content. Note that it is quite simple to use, and you do not required advance knowledge of Excel to use it!!
Parse Effect is actually the name of a function that is available to users of the Sheet. Its goal is to allow anyone to create new content which will be compatible with the stacking Rules of D&D. Not only that, but it also permits to handle the stacking of Abilities like Animal Companion or Turn Undead. In these sections, we'll examine in more details what Parse Effect can do to help you create new content. Note that it is quite simple to use, and you do not required advance knowledge of Excel to use it!!


== Stacking Rules ? ==
Let's begin by examining the stacking rules. In D&D, your character gains bonuses from various sources. Magical Rings, Shields, or even Class Features can give your character a bonus on something. In D&D, the makers decided to create many different 'types' of bonuses, and they also provided details so we can know if a specific type can be stacked (meaning added) to something else which provides a similar bonus (meaning of the same type). The best way to understand this is with this example: Let say Brak the barbarian (Famous Last words: "Brak? What a stupid name for a Barbarian!") owns a nice pair of Gauntlets of Ogre power. If you read the description of those, you get " a +2 enhancement bonus to his Strength score". So these Gauntlets give a +2 to Brak's Strength score in the form of an enhancement bonus. After some adventuring, Brak get hold of a Belt of giant Strength +4 and happily wears that to get more bang for the buck! The description of the belt says "The belt adds to the wearer’s Strength score in the form of an enhancement bonus of +4". One might be tempted to claim that Brak now has a +6 bonus to Strength score: +2 from his Gauntlets, and +4 from the new Belt. Alas, the stacking rules specify that enhancement bonuses do not stack. So Brak is actually getting a +4 bonus to his Strength score, instead of a +6 (the effect of the Gauntlets should be ignored)
The [http://www.d20srd.org/srd/theBasics.htm core mechanics] of the game explain how stacking works:
==== Definition of Stacking ====
:''In most cases, modifiers to a given check or roll stack (combine for a cumulative effect) if they come from different sources and have different types (or no type at all), but do not stack if they have the same type or come from the same source (such as the same spell cast twice in succession). If the modifiers to a particular roll do not stack, only the best bonus or worst penalty applies. Dodge bonuses, racial bonuses, and circumstance bonuses however, do stack with one another unless otherwise specified.''
So the Stacking Rule is actually quite simple: No bonuses stack, except for Dodge, Racial and Circumstance bonuses. So this is part of the Magic that the Parse Effect function handles. It will take into account the stacking rules, so whenever your character gains bonuses that should NOT stack, the Sheet will handle them accordingly!
== The Types ==
Ok so we have seen that the stacking rules prevent bonuses of the same type (with a couple of exceptions) from being added. Now let us look at all the Types that Parse Effect can handle - you will see that a few more were added to allow some very powerful parsing! But first: What the heck does Parse Effect means anyways??
The Parse Effect name: The Parse Effect name is twofold: Parse means "''To examine closely or subject to detailed analysis, especially by breaking up into components''". Effect means "''any condition that change a numerical value related to your Character''" (like getting a +2 to your Strength score because your character is wearing Gauntlets of Ogre Power). So in essence, Parse Effect will breakdown all the Effects applied to your Character, analyze them and come up with a total result, taking into account the Stacking Rules! Simple eh?
===The Available Types===
There are basically three types used within Parse Effect. The stackable Types, the non-stackable types and the special types. The Let's look at the first two types that Parse Effect can handle.
{| border="1" width="80%" align="center" class="wikitable" style="text-align:center" cellpadding="1" cellspacing="0"
|+ '''''Table: The stackable and non-stackable Types'''''
! style="background:#ffdead;" | Available Types !! style="background:#ffdead;" | Does it Stack? !!    !! style="background:#ffdead;" |Available Types !! style="background:#ffdead;" |Does it Stack?
|-
|Alchemical || No || || Luck || No
|-
|Armor || No || || Morale || No
|-
|Circumstance|| '''Yes''' || || Natural Armor || No
|-
|Competence || No || || Profane || No
|-
|Deflection || No || || Racial || '''Yes'''
|-
|Dexterity || No || || Resistance || No
|-
|Dodge || '''Yes''' || || Sacred || No
|-
|Enhancement || No || || Shield || No
|-
|Inherent || No || || Size || No
|-
|Insight || No || || Unnamed || '''Yes'''
|}
So as you can see, most types do not stack, with the four exceptions listed above.


{|width="80%" align="center" style="background:#ffdead;"
|-
|style="border:none;padding:1px;" |
[[Image:Exclamation.gif||left]]
What should I do when I have a Effect with a type that does not normally stack, but the description of that ability specifically says that it stacks? Simple! If it should always stack, even with the same typed bonus, use 'Unnamed' instead!
|}




== The Special Types ==
There is something else Parse Effect can be used for. Certainly adding bonuses is very powerful - it would allow you to add effects to any Item or Ability (or spell or power or condition etc.)
For instance, you could define [we will see later how to do this in more detail] a new magical Longsword +1 that also gives a +2 enhancement bonus to Strength AND a +5 Inherent bonus to your Bluff skill! (yeah, it's one ugly-looking sword!). Once this Longsword is defined and equipped, these bonuses would automatically be integrated in the Sheet! (That's the power of Parse Effect at work!). And recall that the you would not need to worry about the stacking rule!
But with the help of a few special types, Parse Effect can be expanded to handle more complex Effects:
{| border="1" width="80%" align="center" class="wikitable" style="text-align:center" cellpadding="1" cellspacing="0"
|+ '''''Table: The special  Types'''''
! style="background:#ffdead;" | Special Types !! style="background:#ffdead;" | Description
|-
|Haste || Although the bonuses granted by the Haste spell are Unnamed (as in they stack), multiple Haste effects do not stack! So if you wish to create an Effect similar to Haste, but that does not stack with other Haste effects, you can use this special type.
|-
|Max Value ||  Certain effects provide benefits that aren’t really bonuses or penalties to an existing ability, but that give a value where an ordinary character wouldn’t have one.  For instance, Spell Resistance. SR is not a bonus per se, but an ability gained by a character. SR does not [usually] stack (but you could define an Effect that would stack it!): If you have multiple sources of Spell Resistance, you use the higher number. This is where Max Value comes into play. Since all SR are defined as Max Values, you are sure that only the highest source will be used.
|-
|Min Value || Similar to the Max Value above, but for the minimum value.
|-
|[[Parse Effect - Class Skill type|Class Skill]] || This is a special type that was created to allow the adition of Class Skills to a Class. Because it is a bit special, it has its own help page which is available [[Parse Effect - Class Skill type|here]].
|}
== How to Use Parse Effect ==
Now that we know what Parse Effect does, we need to look on HOW to use if within TOS!! But before we jump into that, let's make sure we are all on the same page. So let's define some terms:
EFFECT: An Effect is a condition that affects your Character. For instance a "+1 Racial Bonus to Saving Throws" is an effect.
An Effect is composed of 3 parts: The Effect Target (what characteristic is affected), the Effect Type (which type should be applied) and finally an Effect Modifier (what value to apply to this characteristic). For the example above, the three parts are:
{| border="1" width="80%" align="center" class="wikitable" style="text-align:center" cellpadding="1" cellspacing="0"
|+ '''''Table: The three parts of an Effect'''''
! style="background:#ffdead;" | Effect Target !! style="background:#ffdead;" | Effect Type !! style="background:#ffdead;" | Effect Modifier
|-
|Saving Throw  || Racial Bonus || +1
|}
===Effect Target===
Almost anything that is a value can be made into a target. The worksheet called "IntegrationData" [we will get into that on the next page] contains multiple lists of targets. Some targets are more obvious than others. For instance, the 'CON' target means the Character's Constitution score. Other are class features that have been turned into target to allow future custom classes to 'add' to them! For example, the 'Lay on Hands (Su)' target (or ability) is available to allow you to increase the level of a Paladin (like from a prestige class, which adds its level to that of the Paladin! Other targets affect many characteristics at once. For instance, the 'ALL Saves' target will affect all three save values.
===Effect Type===
We have already discussed, the available Types that Parse Effect can handle, and the stacking rules applied to them.
===Effect Modifier===
The effect modifier is simply the value (number) to apply to the effect target. Only the type "Class Skill" does not use a number for the modifier - it uses a string, composed of skill names, each sperated by a comma.


== Using ParseEffect() ==
== Using ParseEffect() ==
Line 114: Line 22:
::::: Third_Target [Optional],<BR>
::::: Third_Target [Optional],<BR>
::::: Fourth_Target [Optional],<BR>
::::: Fourth_Target [Optional],<BR>
::::: Fifth_Target [Optional] )</tt>
::::: Fifth_Target [Optional],<BR>
::::: Sixth_Target [Optionnal] )</tt>
|}
|}


Line 123: Line 32:


===Table_to_Search===
===Table_to_Search===
This parameter is to tell ParseEffect() which internal table it should search the effects in. For now, leave this parameter to "t_Integration", which is the named cell that contains all the Effects that ParseEffect() has to go thru.
This parameter is to tell ParseEffect() which internal table it should search the effects in. For now, leave this parameter to '''t_Integration''', which is the named cell that contains all the Effects that ParseEffect() has to go thru.


So with just those two parameters, we can already access the power of ParseEffect()! For example:
So with just those two parameters, we can already access the power of ParseEffect()! For example:
Line 148: Line 57:
Now what would happen if we would have created a very powerful godlike effect that would grant a +1 bonus to ALL ability scores? (an effect like "+1 Sacred Bonus to ALL ability Score"). This is where all the others parameters to Parse Effect would come into play.
Now what would happen if we would have created a very powerful godlike effect that would grant a +1 bonus to ALL ability scores? (an effect like "+1 Sacred Bonus to ALL ability Score"). This is where all the others parameters to Parse Effect would come into play.


===Second_Target, Third_Target, Fourth_Target, Fifth_Target===
===Second_Target, Third_Target, Fourth_Target, Fifth_Target, Sixth_Target===
These four aditional parameters tells ParseEffect() to also add the bonus from these effects.
'''WARNING''': If using these, all effects names, including the first one, will be case sensitive! Be sure to check the spelling!
 
These four additional parameters tells ParseEffect() to also add the bonus from these effects.


So for example, with our new godlike ability, if we wanted to see ALL the bonuses applied to Strength, we would use:
So for example, with our new godlike ability, if we wanted to see ALL the bonuses applied to Strength, we would use:
Line 171: Line 82:
Here is another example - check it out and see if you can figure it out:
Here is another example - check it out and see if you can figure it out:


:::<tt>=ParseEffect("Climb",t_Integration,"",
{| border="1" width="80%" align="center" style="text-align:center" cellpadding="1" cellspacing="0"
:::::"All Skills",
|+ '''''Example of use'''''
:::::"All STR-based skills")</tt>
|-
! colspan="2" style="background:#efefef;" | =ParseEffect("Climb",t_Integration,"","All Skills","All STR-based skills")
|}
 
 


This would be useful to catch all effects that would affect the Climb Skill, including any effects that would increase ALL skills (like the Heroism spell that gives a +2 morale bonus on all skills). It would also catch any effects that would modify all the strength based skills (Remember that the Sheet allows you to create a Feat/Ability/Class feature/Weapon... that would do exactly that!)
This would be useful to catch all effects that would affect the Climb Skill, including any effects that would increase ALL skills (like the Heroism spell that gives a +2 morale bonus on all skills). It would also catch any effects that would modify all the strength based skills (Remember that the Sheet allows you to create a Feat/Ability/Class feature/Weapon... that would do exactly that!)
Line 184: Line 99:
Although many of the Class features have been turned into Effects, some things cannot be made into an effect because it does not grant a specific bonus to something. For instance, while the Cleric's "Turn Undead (Su)" is easily made into an effect, the Monk's "Diamond Body (Su)" cannot!
Although many of the Class features have been turned into Effects, some things cannot be made into an effect because it does not grant a specific bonus to something. For instance, while the Cleric's "Turn Undead (Su)" is easily made into an effect, the Monk's "Diamond Body (Su)" cannot!
|}
|}
== Limitations ==
As powerful as ParseEffect() is, there are a couple of limitations you should be made aware of. First, ParseEffect() is a Visual Basic function: This means it is a piece of code which is executed each time the function is called. You need to be aware that, although it has been optimized for speed, there is a cost to having many calls to it. The more Effects are in your character, the more often ParseEffect() will be called. This leads to a progressive slowdown when Excel recalculates, which is a direct result of those many calls to ParseEffect().
The second limitation is Circular References: Since many of the total numbers presented in the Sheet are based on work done by ParseEffect(), it is easy to inadventently create circular references. For instance, if you create an Effect which checks the valus of the Strength ability, you will have a circular reference, since the Strength ability itself is based on the work of ParseEffect(). So do not be surprised if this happends.
== Reducing Calls to ParseEffect() ==
To reduce the number of calls to ParseEffect(), dozens of named cells representing specific calls to ParseEffect() have been defined in the [[Tables Worksheet|Tables worksheet]]. You can see those if you click on the "ParseEffect Def." link provided at the top of the Tables worksheet. Comments are present to explain the purpose. To use any of these effects, simply refer to the named cell.
For instance, if you want to know the total level counting toward your Familiar, the "PE_FamiliarLevel" named cell has that total value. So for a 2nd Wizard/3rd Sorcerer, PE_FamiliarLevel will contain the value 5!
Please examine that table for a list of all ParseEffect() shortcuts!
== More Examples of Use ==
If you would like to see more example on using ParseEffect(), the [[Advanced - Parse Effect Samples|Parse Effect Samples]] page will be a good source of knowledge.
BACK to the [[Advanced User Guide]]

Latest revision as of 20:17, 24 August 2020

BACK to the Advanced User Guide

What is Parse Effect ?

Parse Effect is actually the name of a function that is available to users of the Sheet. Its goal is to allow anyone to create new content which will be compatible with the stacking Rules of D&D. Not only that, but it also permits to handle the stacking of Abilities like Animal Companion or Turn Undead. In these sections, we'll examine in more details what Parse Effect can do to help you create new content. Note that it is quite simple to use, and you do not required advance knowledge of Excel to use it!!



Using ParseEffect()

The prototype to use Parse Effect is:

The ParseEffect() Function with its arguments
=ParseEffect(
Main_Target,
Table_to_Search,
Specific_Type [Optional],
Second_Target [Optional],
Third_Target [Optional],
Fourth_Target [Optional],
Fifth_Target [Optional],
Sixth_Target [Optionnal] )

Ok this seems a bit complex at first, but this is only an illusion (cast by the evil gnome!). Lets review the parameters to the function. Only the first 2 parameters are required, the rest are optional.

Main_Target

As we've already seen, the target is what characteristic we wish to locate, like 'Lay on Hands (Su)' or 'All CHA-based skills'. The IntegrationData worksheet lists all the available targets. It is ordered by category to facilitate searching for specific effects.

Table_to_Search

This parameter is to tell ParseEffect() which internal table it should search the effects in. For now, leave this parameter to t_Integration, which is the named cell that contains all the Effects that ParseEffect() has to go thru.

So with just those two parameters, we can already access the power of ParseEffect()! For example:

Example of use
=ParseEffect("STR", t_Integration)

Will return the total modifier to apply to the STR Ability Score. So if your character is wearing Gauntlets of Ogre Power, this would return '2'. If the character is also wearing a Belt of Giant Strength +4, you know those bonuses will not stack, and the call to ParseEffect() would return '4'.

Specific_Type

Specifies which type you wish the ParseEffect() to return - all other types will be ignored.

If the same character would also become enraged (like a 1st level Barbarian), a +4 [unnamed] bonus to strength would be added to the +4 already granted by the enhancement bonus of the Belt (the gauntlets are ignored, as the bonus is also enhancement, and does not stack with the belt). What if you wanted ONLY to see the enhancement bonus to Strength, then you could use the 3rd parameter of ParseEffect() to specify that you want only to see these bonuses:

Example of use
=ParseEffect("STR", t_Integration, "Enhancement")

Now what would happen if we would have created a very powerful godlike effect that would grant a +1 bonus to ALL ability scores? (an effect like "+1 Sacred Bonus to ALL ability Score"). This is where all the others parameters to Parse Effect would come into play.

Second_Target, Third_Target, Fourth_Target, Fifth_Target, Sixth_Target

WARNING: If using these, all effects names, including the first one, will be case sensitive! Be sure to check the spelling!

These four additional parameters tells ParseEffect() to also add the bonus from these effects.

So for example, with our new godlike ability, if we wanted to see ALL the bonuses applied to Strength, we would use:

Example of use, with parameter breakdown
=ParseEffect("STR",t_Integration,"","ALL Ability Scores")
Parameter Description
"STR" the Strength ability score
t_Integration The table to check effect (always the same)
"" No specific type checked
"ALL Ability Scores" Include values affecting ALL ability Scores

Here is another example - check it out and see if you can figure it out:

Example of use
=ParseEffect("Climb",t_Integration,"","All Skills","All STR-based skills")


This would be useful to catch all effects that would affect the Climb Skill, including any effects that would increase ALL skills (like the Heroism spell that gives a +2 morale bonus on all skills). It would also catch any effects that would modify all the strength based skills (Remember that the Sheet allows you to create a Feat/Ability/Class feature/Weapon... that would do exactly that!)


Although many of the Class features have been turned into Effects, some things cannot be made into an effect because it does not grant a specific bonus to something. For instance, while the Cleric's "Turn Undead (Su)" is easily made into an effect, the Monk's "Diamond Body (Su)" cannot!

Limitations

As powerful as ParseEffect() is, there are a couple of limitations you should be made aware of. First, ParseEffect() is a Visual Basic function: This means it is a piece of code which is executed each time the function is called. You need to be aware that, although it has been optimized for speed, there is a cost to having many calls to it. The more Effects are in your character, the more often ParseEffect() will be called. This leads to a progressive slowdown when Excel recalculates, which is a direct result of those many calls to ParseEffect().

The second limitation is Circular References: Since many of the total numbers presented in the Sheet are based on work done by ParseEffect(), it is easy to inadventently create circular references. For instance, if you create an Effect which checks the valus of the Strength ability, you will have a circular reference, since the Strength ability itself is based on the work of ParseEffect(). So do not be surprised if this happends.

Reducing Calls to ParseEffect()

To reduce the number of calls to ParseEffect(), dozens of named cells representing specific calls to ParseEffect() have been defined in the Tables worksheet. You can see those if you click on the "ParseEffect Def." link provided at the top of the Tables worksheet. Comments are present to explain the purpose. To use any of these effects, simply refer to the named cell.

For instance, if you want to know the total level counting toward your Familiar, the "PE_FamiliarLevel" named cell has that total value. So for a 2nd Wizard/3rd Sorcerer, PE_FamiliarLevel will contain the value 5!

Please examine that table for a list of all ParseEffect() shortcuts!

More Examples of Use

If you would like to see more example on using ParseEffect(), the Parse Effect Samples page will be a good source of knowledge.


BACK to the Advanced User Guide

Retrieved from "https://theonlysheet.com:443/wiki/index.php?title=Advanced_-_Parse_Effect&oldid=3384"