Setting Default Visibilities Using the Character Sheet

This is one in a series of Combat Tracker EVOE blog posts. The series index can be found here.

Last time I used the Effect Manager Utility to set up default visibilities for conditional effects such as prone or poisoned. When the effect is applied to a character in the Combat Tracker, the effect’s visibility is set to the defined default. If there is no default visibility defined EVOE sets the visibility to GM only. Default visibilities set up using the Effect Manager Utility apply to that effect (e.g. stunned) any time it is applied to any character.

EVOE also allows the GM to set a default visibility for a specific effect when the effect is applied using the Actions tab on a character sheet, for example when a character casts a spell. I’ll cover the details here in this blog.

First I set up immunities to cold, fire and poison using Krystryd’s character sheet. I did this in Krystryd’s instance of FG, not the GM’s instance. In the following screenshot a portion of her character sheet is displayed on the left and the Spell/Ability Effect dialog detailing just one immunity, for the cold effect, is on the right.
Attachment 15894

Items of interest: Note the blank area toward the bottom of the Effect dialog. I’ll refer to it later.

Using the GM’s instance of FG, I opened the copy of Krystryd’s character sheet. Then I opened each of the immunity effects on the Actions tab. The following screenshot displays each of the Spell/Ability Effect dialogs for each of the immunity effects.
Attachment 15895

Items of interest: Note the small Default Visibility button at the bottom of each dialog. This button is only available to the GM; it is not available to the players (as can be seen by its absence in the first screenshot). I set the default visibility for each of the immunity effects as shown in the dialogs.

In the GM’s instance of FG I invoked the Effects Manager Utility. I deleted any Custom Effect definitions and added the three as shown in the following screenshot.
Attachment 15896

Items of interest: I set the default visibility for each custom effect definition as shown. Notice the IMMUNE: effect without any qualifier. I did this to prove a point, the verbiage here in the custom definitions must match exactly the verbiage set up elsewhere (e.g. in the Spell/Ability Effect dialog). A missing qualifier doesn’t act like a wildcard to match any and all IMMUNE effects.

Back to Krystryd’’s instance of FG: on the Action tab I applied each of the immunity effects by clicking the little effect button. Because all three “spells” were set up to apply to “self”, each of the effects are inflicted on Krystryd.

Back to the GM’s instance of FG to analyze the results. I opened the GM’s Combat Tracker and clicked the Effect Details icon to view the initial visibility of each immunity effect. They are depicted in the following screenshot.
Attachment 15897

Items of interest: Krystryd’s immunity to cold has an initial visibility of GM only. This is because the default visibility setting in the Spell/Ability Effect dialog was set to OFF and there was no Custom definition in the Effects Manager Utility. The initial visibility setting for the fire immunity effect is SORC. This is the result of the default visibility not being set in Krystryd’s Effect dialog but there is a Custom definition with SORC default visibility in the Utility. Finally, the initial visibility for poison immunity is TRGT. The default visibility set up in the Utility is SORC but the default TRGT set up in Krystryd’s Effect dialog overrides it. Note that none of applied effects had VSBL visibility, as defined for the iMMUNE effect (without a qualifier it never matched).

The preceding discussion also outlines the hierarchy of default visibility definitions and where they’re set up. When no default is defined, EVOE uses GM only as the initial visibility setting for effects displayed in the Combat Tracker. If a default visibility is defined for an effect in the Custom section of Effects Manager Utility then it overrides EVOE’s fallback default of GM only. A default visibility defined in the Spell/Ability Effect dialog of a player’s character sheet takes precedence over Custom definitions in the Utility.

One final note, and this is fairly slick: when using EVOE Lua patterns, also known as regular expressions, can be used in the Custom area of the Effects Manager Utility. For example, DMG:.*cold will match any cold damage effect, DMG: 2 cold, DMG: 4 cold, DMG: 1d6 cold. But not DMG: 2 nor DMG: 3 fire. (Should EVOE users express interest and want additional elaboration for this powerful little feature I’ll follow up below in a comment.)

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.2.0

Please feel free to post comments, questions and/or criticisms either here or in the forums.

Setting Default Visibilities for Conditional Effects (e.g. Prone)

This is one in a series of Combat Tracker EVOE blog posts. The series index can be found here.

As with nearly every preceding blog post I start out contrasting FG with and without EVOE. Why break tradition? A portion of the GM’s Effect Manager Utility and Combat Tracker are shown in each of the two panels in the first screenshot.. The upper panel displays information without using EVOE, the lower panel with EVOE.
Attachment 15776

Items of interest: Here are the steps I followed. I started FG without EVOE and opened the Effects Manager Utility then dragged the Petrified, Poisoned and Prone conditions into the Custom area. I opened the Combat Tracker and set it to be Krystryd’s turn. To test both button-clicks and dragging from both the Conditions and Custom areas, I clicked the Poisoned button then dragged the Prone button to the Combat Tracker from the Custom area. I clicked the Restrained button and dragged the Stable button to the Combat Tracker from the Conditions area. Note that no matter how I applied a conditional effect the visibility in the Combat Tracker was always set to VSBL when not using EVOE. I closed down FG and brought it back up but this time with EVOE. I opened the Effects Manager Utility and observed three custom definitions for Petrified, Poisoned and Prone were already there. Note the new button in the second column in the Custom area. It is the Default Visibility button. When I first brought up the Utility the default visibility values were all set to VSBL because that is the default when not using EVOE and that is when they were originally defined. I changed the default visibility for Petrified to TRGT and the default visibility for Poisoned to GM (as show in the screenshot). I then clicked and dragged the same buttons, in the same sequence as before (when not using EVOE). Note in the Combat Tracker, that Poisoned’s visibility is GM and Prone’s visibility is VSBL, both as set in the Custom area. Restrained and Stable default to GM only. This is the fall back default visibility if there is no other overriding default visibility set elsewhere.

Detour: Until I coded default visibilities into EVOE, I didn’t really know what the little visibility button that looks like an eyeball in the Effects Manager Utility did. I thought it was non-functional; it had no effect on the Combat Tracker. But now I know, it sets the visibility of a custom defined effect in the player’s instance of the Utility. If the visibility is on, the player sees the custom effect in their instance of the Utility. So I turned it off for the Petrified and Poisoned effects before starting a second instance of FG using the A Paladin character.

The following screenshot displays two panels, both using EVOE. The upper panel shows portions of the Effects Manager Utility and Combat Tracker for the player character A Paladin. The same tools are shown in the lower panel for the GM.
Attachment 15777

Items of interest: As mentioned, I turned off the visibilities for the Petrified and Poisoned conditions in the Custom portion of the GM’s Effect Manager Utility. In the player’s instance those custom conditions are not visible, but the Prone custom defined condition is visible. Now to contrast the Condition buttons and Custom buttons for the player versus the GM. I performed the same set of button clicks and drags as before except that I did them all using the Prone condition. Note that Prone appears four times in the player’s Combat Tracker (once for each button click or drag). In this case no matter which button was clicked (Condition or Custom) nor which function performed (click or drag) the default visibility for Prone as defined in the GM’s Effect Manager Utility (I.e. VSBL) was used. The Condition buttons behave differently for the player than for the GM. By perusing the lower panel, that of the GM we can verify all four instance of the Prone condition were applied with VSBL visibility as defined in the GM’s Custom area.

Why the difference? In my mind it makes no sense to provide the player with the ability to set visibilities as he/she sees fit. Effect Visibility is an option available to the GM and only to the GM. The GM can use the buttons in the Conditions area to quickly apply a condition with the basic GM only visibility or use buttons in the Custom area for alternatively defined default visibilities.

Note the hierarchy, custom defined default visibilities override the fallback GM only visibility. This is important as we’ll see next time. The GM can define yet another default visibility specific to a single effect on a player’s action tab of their character sheet. That default visibility will override any custom default visibilities defined in the Effect Manager Utility.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.2.0

Please feel free to post comments, questions and/or criticisms either here or in the forums.

EVOE Demands Better Role Playing

This is one in a series of Combat Tracker EVOE blog posts. The series index can be found here.

I’m going to detour a little from my usual this time and talk about how EVOE asks more of me, the DM, in terms of role playing. My shortcomings became readily apparent this past weekend when our group play tested the next version of EVOE.

I have a great group; how could they not be: two of the players are my mid-twenty-year-old sons and a third is my brother. I’m hoping I keep my mental faculties long enough to see my grandson enter the D&D arena in about 10 years. The group knows I use EVOE and that at each session we might be play testing a new version.

The characters are currently working their way through Princes of the Apocalypse.
Very minor game spoiler: They encountered a group of specters. For those of you unfamiliar with specters, they’re resistant or immune to just about all nonmagical damage. Based on background, one member of the party knew of this and shouted it out to the other characters.

The visibilities of the monsters’ effects being GM only by default presented a perfect encounter to put EVOE through it paces. After the first few attacks by the party I asked each of the players to read to me exactly what appeared in their Chat Windows. Their curiosities then piqued, I related to them what damages had actually occurred and why. (Of course this little discussion would not have occurred outside of play test.)

I tend to let the numbers speak for themselves during combat, it helps move combat along more quickly. In this case though the numbers were lying. One of the players took exception to this. He was very diplomatic, explaining his understanding of how EVOE might enhance play but that without proper information his character could very well be fighting “a castle wall”, believing he’s making headway but in fact getting no where.

This could be remedied by taking away more information from the players by changing the game and combat options in the Options Manager Utility - an unpalatable solution in my opinion. After some discussion, we agreed upon a resolution: more description of damage rendered during the fray. This will of course slow down combat encounters as I endeavor to add descriptive flavor while trying to impart information to the players as to the attack’s affect on their opponents.

Now, when dealing out damage due to a successful attack to a specter, not only does the player see a damage of 7, but I relate that the “sweeping blow of the broad sword passes through his opponent, without any sort of resistance that one might expect, and that the specter didn’t even flinch”. Or that the fire ball projected by the wizard “splashes upon the specter’s chest, but passes through the creature, leaving a viewable sparkling trail not unlike the tail of a comet, and a howl of anger from the specter”.

Being a technical sort, I know I’ll never approach the descriptions that Matt Mercer offers up in his sessions on Geek & Sundry, but I do have to try to better myself and enhance my players’ experience in the game.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.2.0

Please feel free to post comments, questions and/or criticisms either here or in the forums.

Displaying Defense Effects that Apply to Damage Rolls

This is one in a series of Combat Tracker EVOE blog posts. The series index can be found here.

When I first started writing this blog I noticed a problem with the Chat display for the RESIST, VULN, and IMMUNE effects used to counteract damage rolls. EVOE now properly handles these effects and accurately reports outcomes in the Chat Window.

Damage rolls have two sets of information. The first set is data about the roll itself: the dice cast values, modifiers, and damage types. The second set of information imparts the actual damage applied after any counter actions, like resistance and immunity. The second block of information, as reported in the Chat Window, is the topic of this blog post.

I’ll provide a couple of examples to illustrate the usefulness and caveats of using the EVOE

Throughout this series I use the following settings in the Options Manager, unless otherwise specified: (1) Chat: Show GM rolls - On, (2) Chat: Show results to client - On, (3) Chat: Show roll totals - On.

I’ll start with a comparison of a dice roll with and then without the use of EVOE. In this first screenshot, a hobgoblin is dealing damage to a player character. The left panel in the screenshot is the GM’s Chat Window, without EVOE. The right panel is the GM’s Chat with EVOE. The center panel is the Combat Tracker common to both.

Attachment 15598

Items of Interest: The hobgoblin attacked with a long sword which deals1d8+1 slashing damage. It has effects which deal +5hp lightning damage, +2hp cold damage and +4 fire damage. Farideh has immunity to lightning damage, resistance to fire damage but vulnerability to cold damage. The Combat Tracker details all of this. There are slight differences in the information displayed to the GM in the first section of data. These differences are discussed in detail in my previous blog. The second set of data in the Chat shows 10hp rather that the 15hp shown in the first data set. Lightning immunity reduces the damage by 5hp, fire resistance reduces the damage by 2hp and cold vulnerability increases the damage by 2hp. A total adjustment of 5hp less than was calculated in the first data set. Note that the data in the second data set, both when EVOE is used and when it is not used is exactly the same.

Here’s the scenario for the next example: Three characters happen upon a group of hobgoblins. A Paladin has successfully attacked one of the hobgoblins and has made his damage throw. Krystryd just finished her turn when she announced and then cast a spell on the hobgoblins making them vulnerable to cold damage. She then quietly tells A Paladin that she cast a spell, giving him the ability to deal additional cold damage. Furthermore, A Paladin has a weapon that deals lightning damage, which is known to him, but also fire damage which he does not know about. The hobgoblin has immunity to lightning damage and resistance to fire damage. All of these effects and their respective visibilities are shown in the GMs panel below.

In each of the following images the player’s Chat Window and a portion of their Combat Tracker are shown. I’ll start with Farideh who has the least information about the effects in play.

Attachment 15599 Attachment 15600 Attachment 15601 Attachment 15602

Items of Interest: Farideh was out of earshot so she did not hear Krystryd speak to A Paladin; she is unaware of one of the spells Krystryd cast. In the first image, that of Farideh’s, she is aware of the hobgoblin’s vulnerability to cold damage, but nothing other than A Paladin’s morningstar damage roll of 3hp. She believes he’s dealt 3hp of damage to the hobgoblin. Next Krystryd’s panel: she knows of the target’s vulnerability to cold plus A Paladin’s ability to deal cold damage (she cast both spells). Given the morningstar’s 3hp damage roll she expects the damage to be 7hp. Her panel highlights a shortcoming of EVOE. SORC visibility is not fully implemented yet, and frankly I’m tired of the inaccuracy! It’s on my list. Now A Paladin’s panel: he expects the hobgoblin to suffer the morningstar’s 3hp, 2hp of cold damage from Krystryd’s spell, plus 5hp lightning damage. Then an additional 2hp because of the hobgoblin’s vulnerability to cold for a total of 12hp. Finally the GM‘s panel, it displays the true damage that the hobgoblin suffers, a total of 9hp. (I’ll let you work it out.) Note that the “PARTIALLY RESISTED” clause only appears in the GM Chat since the GM is the only person privy to the RESIST and IMMUNE effects. Also note, the “VULNERABLE” clause appears in the GM’s and A Paladin’s Chats. It should appear in Krystryd’s Chat but doesn’t due to the mistreatment of the SORC visibility option by EVOE.

Given the displayed information the GM should expect some player remarks. Farideh’s player: “Ah.. Too bad, only 3hp damage!” Krystryd’s player: “Where’s the 4hp cold damage?” A Paladin’s player: “Nice! A crappy roll of three and I still inflicted 12hp.” Now the GM does not need to address the difference between A Paladin’s believed damage and the actual 9hp damage. No one but the GM is truly aware of the actual total damage assessed. But the GM might inform everyone, “There are effects in play that you might not be aware of.”

Thanks for your patience as I slowly bring more and more functionality to EVOE.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.1.1

Please feel free to post comments, questions and/or criticisms either here or in the forums.

Displaying Damage Effects

This is one in a series of Combat Tracker EVOE blog posts. The series index can be found here.

In this post and the next, I’ll describe the Combat Tracker effects that change or modify the result of a damage dice roll and what EVOE displays to players in the Chat Window. Damage rolls vary, some doing more or less damage than others. Effects might cause additional dice to be rolled or dice roll outcomes might be positively or negatively impacted. Depending on an effect’s visibility setting in the Combat Tracker, none, some or all of the effect impacts will be displayed in each player’s Chat Window.

In most cases, for combat rolls, two sets of information are displayed for the roll. The dice roll information and the results information. In this blog post I’ll discuss the first set, the dice roll info. In the case of damage rolls, the information, separated into “clauses“, includes whether the roll was melee or ranged, the weapon type if any, contributions to the damage due to effects if any, and the separate damage types and amounts. I’ll discuss the second set of information, the damage results in a future post.

A few examples to illustrate the usefulness and caveats of EVOE follow.

Throughout this series I’ll use the following settings in the Options Manager, unless otherwise specified: (1) Chat: Show GM rolls - On, (2) Chat: Show results to client - On, (3) Chat: Show roll totals - On.

In this first screenshot I contrast a damage roll while not using the EVOE with one when using the EVOE. A potion of the GM’s Chat Window and Combat Tracker are shown in each panel. The upper panel displays the results of a damage roll when not using the EVOE. The lower panel has the EVOE loaded.

Attachment 15430
Items of interest: Note the difference in the [EFFECTS] clauses. When using EVOE the clause contains not only the sum of the damage values due to effects but a list of their damage types too. When not using EVOE, the damage types due to effects are not shown in this clause. Typically there are at least as many damage [TYPE] clauses, if not more, when using EVOE as there are when not using it. This is because FG without EVOE combines same type damages into a single clause, EVOE reports each damage contribution separately. The reason for this is visibility. At times two damages may be of the same type but have different visibilities.

In a previous blog I displayed and discussed how for a single attack roll with differing attack effects some players may see more or less information about the roll than other players depending on the visibility settings. In the next set of screenshots I’ll show similar information for a damage roll. There are four images, one for the GM and one for each of the three players. There is a label, by character, on each image. Each player’s Chat and a portion of the Combat Tracker are displayed. Krystryd rolled a damage roll against the orc. The base damage for her handaxe is 1d6+3 slashing. Because of the effects in play 3d6 are rolled. Everyone sees three dice rolling around in the Chat, but for some players, as displayed in the image, the information about the roll imparts but a single die of data.

Attachment 15433 Attachment 15434 Attachment 15435 Attachment 15436
Items of interest: Let’s examine each image in turn starting with the GM’s. Effect visibilities do not limit what the GM sees. The damage values from the Combat Tracker shown in the [EFFECTS] clause is: 2d6-7+3 = 2d6-4, and the types are: slashing, cold and silver, also as displayed. There is a [TYPE] clause for the base damage, 1d6+3 slashing, plus one for each DMG effect. Note that the silver DMGTYPE effect was added to each [TYPE] clause. Total damage done to the orc is 8 hp. On to the Paladin. The only effect that Krystryd is affected with that the Paladin is aware of is the one he cast on her giving her the DMG: +3 cold effect (visibility SORC). It shows up in his Combat Tracker. Note that there is no [EFFECTS] clause in his Chat nor any damage clauses other than Krystryd’s base damage. This is a known shortcoming of EVOE, the incomplete handling of the SORC visibility, that I’ll remedy in the future. Note that the Paladin believes only 5 hp damage occurred. Next up, Krystryd. She is aware of all effects with visibilities of VSBL, SORC or TRGT but not GM. The information displayed in her Chat is consistent with the visibilities: [EFFECTS] and [TYPE] clauses identical to those of the GM, except silver damage is not reported in any of the clauses because of its GM only visibility. She observes 8 hp total damage. Finally, Jimmy. He is privy to only VSBL effects, of which there are none, so he sees a total damage of 5 hp, the base damage for the handaxe.

The above analysis brings to light three issues: (1) poor handling of the SORC visibility, which I will remedy in the future, (2) seeing more dice rolled than are reported on in the Chat (see this and this for a possible mitigation remedy using dice averages), and (3) reporting less damage to some players than the amount actually inflicted. This last inconsistency introduced by hiding effects, in my opinion, is not as large of problem as it might seem. As shown in the player Combat Trackers I tend to use the “Status” instead of “Detailed” for View: Health - Non-ally in the Options Manager. So the exact hit point damage an enemy has suffered is not readily apparent. Though, if the discrepancy is large, say a player sees 5 hp damage when 34 hp were actually done, killing the orc outright, the player might comment, “Wow! That was a wimpy orc!” More than likely the player will leave it at that, a dead orc?, out of sight, out of mind.

Next time I’ll talk about the effects that modify the damage result information, effects like IMMUNE and RESIST.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.1.0.

Please feel free to post comments, questions and/or criticisms either here or in the forums.

Displaying The Defender's Effects

This is one in a series of Combat Tracker EVOE blog posts. An index can be found here.

In this article, I’ll discuss effects that the target of an attack, i.e. the defender, would use that influence the Hit or Miss of an attack roll and EVOE’s impact on what players see. These effects include AC and COVER.

Now for a few examples to illustrate the usefulness and caveats of EVOE.

Throughout this series I’ll use the following settings in the Options Manager, unless otherwise specified: (1) Chat: Show GM rolls - On, (2) Chat: Show results to client - On, (3) Chat: Show roll totals - On.

This time a bugbear will attack A Paladin. The Paladin’s AC is 15. He has an AC effect bonus of +3. The bugbear has a base attack of +4 and no addition attack effects.

The screenshot below contains Chat Windows for the GM (left panel), A Paladin (center) and Krystryd (right panel). Three attacks were made by the bugbear, the first (uppermost results) were with the visibility of A Paladin’s AC effect set to GM only. The second attack (middle results) with the visibility set to TRGT. And the third attack (lowermost results) with the visibility set to VSBL.

Attachment 15270
Items of interest: In all three panels for all three results, the only differences are the presence or absence of “[DEF EFFECTS +3]”, the Paladin’s AC: +3 defense effect. The bugbear’s base attack bonus of +4 remains the same as well as the total attack roll outcomes, in all results. The defense bonus doesn’t change any of the values but it does influence the hit or miss outcome. One can verify this by repeatedly rolling attacks until one observes a die roll of 13 misses (13+4=17 < 15+3=18) while a 14 hits (14+4=18 >= 15+3). Notice that when the visibility is set to GM (uppermost results of each panel) the defense effect is only shown to the GM. When the visibility is changed to TRGT, A Paladin sees the AC effect bonus in his Chat (note that A Paladin is the target of the AC effect as well as the target of the attack). And finally when the visibility is set to VSBL, the defense effect bonus is shown in everyone’s Chat (lowermost results).

And now to point out another inconsistency in display.

Same setup - bugbear attacks A Paladin but with an additional defense bonus of +2 due to COVER. In the screenshot below, the left panel contains the GM’s Chat Window and a portion of the Combat Tracker. The right panel contains A Paladin’s Chat Window only. The bugbear makes two attacks, the first (upper results) is with the visibilities for both effects set to VSBL (this is not shown in the Combat Tracker), the second attack (lower results) is with the COVER effect’s visibility having been changed to GM only (as shown in the Combat Tracker).

Attachment 15269
Items of interest: In the first attack the bugbear rolls a 14, for a total adjusted attack value of 18. The AC of A Paladin is 15so the attack should have hit A Paladin barring any defense bonuses. Even with the AC: +3 bonus the attack would have hit. But it is reported in the Chat as a miss so we can conclude that both defense bonuses were taken into account in EVOE’s determination of hit or miss. The inconsistency: When both defense effects’ visibilities were VSBL, “[DEF EFFECTS +5]” was displayed in all Chats (upper results). However when the COVER effect visibility was changed to GM only (lower results) no effect was displayed in A Paladin’s Chat Window. One would expect to see “[DEF EFFECTS +5]” in the GM’s Chat and “[DEF EFFECTS +3]” in A Paladin‘s Chat. The reason for the inconsistent display is defense effects are “grouped” together for display purposes and displayed according to the least visible effect visibility setting, in this case GM only. This is how FG behaves without EVOE and a lot of programming code would be required to display each defense effect separately. There aren’t as many defensive attack effects as there are offensive attack effects so I did not add all that additional code. If this presents an issue due to numerous complaints I’ll add the extra code in the future.

I suspect the usual player complaint might be, “Hey, I have an AC: +3 bonus effect, but it doesn’t show it. Did I get the bonus?” A quick look at the Chat by the GM, and he/she can tell the player, “You sure did.” And leave it at that.

I’ll cover the damage throw next time.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.1.0.

Please feel free to PM me or post comments, questions and/or criticisms either here or in the forums.

Displaying The Attacker’s Effects

This is one in a series of Combat Tracker EVOE blog posts. An index can be found here.

In this article and the next, I’ll discuss the Combat Tracker effects that change or modify the result of an attack dice roll and EVOE’s impact on what players see. Typically an attack is a simple roll of a 1d20 die. There are base modifiers such as the attacking character’s strength ability and proficiency bonus. Sometimes dexterity contributes a bonus. When effects are employed additional dice might be rolled or the dice roll outcome might be positively or negatively impacted. Depending on an effect’s visibility setting in the Combat Tracker, none, some or all of the additional modifier values will be displayed in a player’s chat window. It is important to note that, even though what each player sees may be different, the GM always sees complete and accurate results.

Now for a few examples to illustrate the usefulness and caveats of EVOE.

Throughout this series I’ll use the following settings in the Options Manager, unless otherwise specified: (1) Chat: Show GM rolls - On, (2) Chat: Show results to client - On, (3) Chat: Show roll totals - On.

Krystryd, a level three paladin has a strength bonus of 3 and a proficiency bonus of 2, (so her base attack bonus is +5).

In this first example I’ll contrast her attack on an orc with her +2 attack bonus while not using the EVOE and then using the EVOE. The effect’s visibility has been set to GM only.

In this first screenshot, a potion of the GM’s Chat Window and Combat Tracker are shown in the upper panel. Portions of Krystryd’s Chat Window, Combat Tracker and Actions Tab of her Character Sheet are shown in the lower panel.

Attachment 15268
Items of interest: With the GM only visibility setting, as expected, the effect is not visible in Krystryd’s Combat Tracker. Krystryd’s Chat Window has exactly the same information as the GM’s, even though the GM has set the visibility of the effect to GM only. What’s the use of setting the effect’s visibility to GM only, if, as soon as Krystryd rolls an attack, the Chat announces some sort of effect is in play. Krystryd doesn’t know what the effect is but she knows she received a +2 bonus on her die roll.

The setup for this next screenshot is nearly identical to the above. The only differences are, EVOE is loaded and Krystryd rolls a 7 instead of an 11.

Attachment 15267
Items of interest: “[EFFECTS +2]” does not appear in Krystryd’s Chat Window. The player is not tipped off to an effect in play. This being completely consistent with a GM only effect visibility. While the GM’s Chat looks the same as before.

Which bring me to a point I’d like to make, I have tried to do my best to ensure the GM’s Chat Window information is consistent to the information one would see when not using the EVOE. There are a few differences and I’ll point them out when they present themselves.

The astute reader might have picked up on an inconsistency. An alert player is probably aware that it typically takes a 13 (orc’s AC = 13) to hit an orc, but Krystryd did it with a 12! The GM knows the roll plus bonuses totals 14. But Krystryd, and the other players, see 12.

An in game conversation might go like this:
A Paladin: “We’ve been dispatching orcs all night, I’ve rolled plenty of 12’s and missed. How come Krystryd just hit with a 12?”
GM: “That’s meta-gaming. The calculations are correct. It‘s a hit.”
(That answer probably isn’t going to win you any friends. Instead try..)
GM: “There are things going on that you aren’t aware of. Krystryd did hit the orc.”
A Paladin: “Like what things?”
GM: “You’re going to have to have to discover that for yourself.”

Now on to another inconsistency: effect modifiers that involve dice.

The setup is similar, Krystryd will be attacking an orc, but her attack bonuses are 2d4-2 with a visibility of TRGT and 1d6 with a visibility of GM only. It is imperative that the user of EVOE remember TRGT means the character with the effect, not the target of the attack.

In the screenshot below, portions of the Combat Trackers and Chat Windows for the GM (left panel), A Paladin (center), and Krystryd (right panel) are shown. I tried to capture the dice throw plus the results in the Chat.

Attachment 15266
Items of interest: From each of the respective Combat Trackers, note the effects on Krystryd and their visibilities. The GM sees both, as always, A Paladin is aware of neither and Krystryd is aware of the 2d4-2 attack effect. Four dice were rolled, the ubiquitous d20, a d6 and two d4s. Every player sees them. However the Chats are inconsistent. The DM of course sees all, as usual. A Paladin sees only a single die contributing to the attack which is accurate, he is unaware of any contributing effects. Krystryd, aware of the 2d4-2 effect sees three dice. Also note who has “[EFFECTS …]” reported in their Chat, plus the difference in modifier totals reported.

I tried various ways to remedy this. Using random number generation instead of an actual dice throws for the modifying dice. However this was unpalatable to me, because, as in this example Krystryd knows two more dice should be thrown. The DM can make the dice “secret” but silhouettes are displayed. I also thought about always throwing say 10 dice, and using only the appropriate ones in the evaluation, but that seemed a ridiculous solution.

In the end I believe the easiest mitigation is to use averages instead of dice for any ATK effect that is not VSBL. The average throw for d4 is 2.5 and the average throw for d6 is 3.5. So the DM could use ATK: +3 for the first effect and ATK: +4 for the second. Once everyone is aware of the effects the DM could use the die modifiers instead of numerics.

Conditional effects, blindness, poisoned, invisible, etc. introduce the same inconsistency issue because they cause two d20s to be rolled due to advantage or disadvantage. I’ve been thinking about possible solutions and I think using an average difference modifier may be the best way to go. I have calculated the average difference between two thrown d20s and it is 6.65. Using this idea, the player would rolls the d20 attack, EVOE would add 7 to the roll if the die cast value is 1 through 10 and subtract 7 if the die cast value is 11 through 20. Then the higher of the two values would be used for advantage or the lower of the two for disadvantage. I have a physics background which was very math intensive, but I’m sure a practicing mathematician would have a fit over this methodology. I would happily entertain alternative solutions.

Next time I’ll detail the defensive response to the attack roll (e.g. AC and Cover).

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

This blog post was written using EVOE v0.1.0.

Please feel free to PM me or post comments, questions and/or criticisms either here or in the forums.

Effect Display in the Player‘s Combat Tracker

This is one in a series of Combat Tracker EVOE blog posts. An index can be found here.

Effects can be added to the Combat Tracker in a multitude of ways. They can be added using the Effects Manager button in the upper right corner of FG’s desktop. The GM can add an effect using the little green “Add Effects” button in the Combat Tracker. Or a player can inflict or target another character with an effect using the Actions tab of the character sheet, for instance when a spell is cast.

When an effect is added to the Combat Tracker, without the use of the EVOE, the default visibility is VSBL (visible to everyone). However, if the EVOE is employed, the default visibility is GM (visible to the GM only). Each effect’s visibility can be independently controlled by the GM. This means, it is up to the GM as to who sees which effect.

Below is an image I’ve constructed to illustrate visibility settings and their affect on what different players see in their Combat Tracker. I set up four instances of FG, a host (the GM), and three players (Krystryd, A Paladin and Jimmy the Greek). The image is a collage of portions of the Combat Tracker from each of the four instances. The GM’s Combat Tracker is shown on the left, Krystryd’s the upper right , A Paladin’s middle right and Jimmy’s to the lower right (each as indicated with a red X). Note the visibility settings for each of the four effects shown in the GM’s Combat Tracker. “Poisoned” has a visibility set to VSBL. Note that that effect appears in the snippet of every player. The “ATK +2” effect has a visibility setting of GM and therefore does not appear in any of the player Combat Trackers. “DMG: +1d4” has a visibility of TRGT meaning that the GM and the target, Jimmy, should see it in their Combat Trackers. Note that the snippet of Jimmy’s Combat Tracker does show the “DMG: +1d4” effect, while it is absent from the other two player snippets. Finally “RESIST: cold” was applied to Jimmy by Krystryd, she targeted Jimmy with the effect. Its visibility was set to SORC in the GM’s Combat Tracker and so it should be visible to both Jimmy (the target) and Krystryd (the source). A perusal of the snippets shows this to be true; the Paladin (middle right) is the only character unaware of Jimmy’s resistance to cold.

Attachment 15265

This blog post was written using EVOE v0.1.0.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

Help Me Help You

This is one in a series of Combat Tracker EVOE blog posts. An index can be found here.

Inevitably users of EVOE will run into problems. Whether it’s install issues, inaccurate documentation, misunderstanding, user errors, unsupported options or worst of all, programming errors.

In order for me to help you I’ll need information. ”The extension doesn’t work.” is not sufficient for me to figure out why you may be having difficulties, nor just what those difficulties are.

If you have problems with EVOE please provide as much information as you can. The minimum would include:
(1) EVOE version - announced in the Chat window at start up (v0.1.0 and later).
(2) What effects were in play?
(3) What triggered the issue? Dice roll? Applying an effect?
(4) What were the visibility settings, who did it affect? The DM? One or more players?
(5) A copy of the contents of the Debug.console dialog window if it popped up.
(6) Anything else that might be pertinent, including screenshots, which are always helpful.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

Please feel free to PM me or post comments, questions and/or criticisms either here or in the forums.

Series Index, Version Information, and Supported Options

I’ll use this blog entry as a place to index the Combat Tracker EVOE blogs, revision information plus list Effects that are or are not supported in the current version of EVOE.


Blog Index
1. Introduction
2. Index (this page)
3. Help Me Help You
4. Effect Visibility, Who Sees What
5. Effects Display for an Attacker
6. Effects Display for the Attack Defender
7. Effects Display for the Damage Roll
8. Effects Display for Damage Roll Counteractions
9. GMs Need Better Role Playing
10. Default Visibilities for Conditional Effects
11. Defining Default Visibilities Using the Character Sheet


Version Information
1. v0.0.1 (Jul 07, 2016) - Iinitial release
2. v0.1.0 (Sep 10, 2016) - Attack and damage rolls
3. v0.1.1 (Oct 10, 2016) - Bug fix, damage roll counteractions (IMMUNE, VULN, RESIST)
4. v0.2.0 (Oct 27, 2016) - Added GM defined default visibilities.
5. v0.2.1 (Nov 04, 2016) - Fantasy Grounds v3.2.0 compatibility.
6. v0.2.2 (Dec 03, 2016) - Fantasy Grounds v3.2.1 compatibility.


List of Effects Supported
Supported:
Opportunity attack modifiers (e.g. ATK +2, opportunity)
ATK:
AC:
ADVATK and DISATK
as well as ADV and DIS for all
Conditional effects except Incorporeal
COVER, SCOVER and HIDDEN
EXHAUSTION
DMG, DMGTYPE
RESIST, IMMUNE, VULN

Initiative (INIT), saving (SAVE), and death roll effects are not handled, nor are skill and ability check effects in the current EVOE version.

“Supported“ means, properly reported in the Chats’ of all players according to the visibility settings specified in the Combat Tracker. Calculations and/or determinations are not in any way affected by EVOE, whether an effect is or is not supported. EVOE only controls what is or is not displayed to players.

The Combat Tracker Effect Visibility Options Extension (EVOE) can be downloaded here.

Please, feel free to PM me or post comments, questions and/or criticisms either here or in the forums.

Introducing the Combat Tracker EVOE

Hello and welcome to a new instructional blog series (the series index).

In my previous “Neophyte Tackles” series I meander my way through my experiences and the lessons learned in developing my first Fantasy Grounds Extension. The fruit of that series was the starting point of this series: The Combat Tracker Effect Visibility Options Extension (or EVOE).

The EVOE currently only works with the 5E ruleset. The 5E Combat Tracker provides two visibility options for effects to the Game or Dungeon Master: a visible to all (VSBL) option and a visible to the GM only (GM) option.

The EVOE provides two additional visibility options for the DM to use: an option that displays an effect to the player whose character has the effect (TRGT) and an option that displays an effect to the player who inflicted the effect (SORC).

One can think of these options as providing a range of visibilities, from less to more, to the players. GM is the least visible, only one person sees these effects in their Combat Tracker. TRGT provides a little more visibility: the effect is displayed to the GM and to the player whose character has the effect. SORC, yet a little more visibility, displays the effect to the GM, the player whose character is affected, and to the player whose character is the source or inflictor of the effect. VSBL provides the most visibility, showing the effect to everyone.

Here is a potion of the GM’s Combat Tracker showing the four visibility options (circled in red).

Attachment 15264

Important: Please note the change of the button labels. In v0.0.1 the labels, from least visible to most visible were: GM, SELF, TRGT, VSBL. But as of version v0.1.0 the respective labels are: GM, TRGT, SORC, VSBL. While implementing my latest revisions to the EVOE it became readily apparent that the previous set of labels had been a poor initial choice. I apologize for any confusion.


So why would one use the Combat Tracker Effects Visibility Options Extension? At times the GM might not want to blurt out, your character is exhausted or your character has a disease or your character put on a cursed ring. Instead the DM might want the player to puzzle out what is happening to their character and why. An immediate response is, you’re “hiding” effects from the player. I prefer to think of this as consistency with how other information is revealed to players. The GM is constantly “hiding” information from, and then revealing a little at a time to, the players. Whether it is terrain, hidden traps, unsolved puzzles, or monsters lying in ambush. Some effects should be just one more item to explore in the fabric of a campaign.

Why use a blog to distribute information about the EVOE? Why not a Wiki page or a simple .PDF manual? It wasn’t until I started adding more functionality to the EVOE that I realized that inconsistencies are introduced by limiting effect visibility. The employer of EVOE will face this problem. As I discover some myself and GMs uncover others, I want to provide a forum for discussing mitigation tactics, helpful hints, for dealing the with meta-gaming that might occur.

Here’s an example of one scenario that I’ve posted before in the FG Forums:
Krystryd drinks from a fountain. The DM adds the intoxication effect with GM visibility to Krystryd. Later on the party comes upon some orcs and the party immediately attacks. When Krystryd rolls her attack it’s at disadvantage. A astute player would ask, “Why was Krystryd’s attack at disadvantage?” The DM might reply, “She’s feeling a little light headed. Maybe not in complete control of her faculties.” The player: head scratching, thinking - Oh crap! Fountain! “Is she drunk?” DM: “Yeah, I’d say that’s accurate” and changes the visibility to VSBL.

Besides verbal mitigation there might be ways to employ an effect one way when there is limited visibility and another way when the effect is visible to all. One example is a die modifier to damage. The EVOE doesn’t hide the rolling of dice. But it might not reveal the additional damage to all players. An orc swinging a magical Great Axe might deal 1d12+3 slashing damage plus the effect DMG: 1d4+1, fire. If the magical fire damage is hidden then the players will see two dice silhouettes but only see the 1d12 die of damage reported. “What’s up?” they ask. To mitigate this ahead of time the DM might use DMG: +4, fire while the effect is hidden, but change it to DMG: 1d4+1, fire once everyone knows about the magical property of the axe.

Finally, in the immediate future I will be adding more and more functionality to EVOE. For example, as of this writing the ATK, DMG and DMGTYPE offensive effects are supported. Some defensive effects are supported, such as AC, RESIST and COVER. Plus most of the conditional effects, Poisoned, Invisible, etc. Some effects that are not yet handled properly are those operating on saving throws, ability and skill checks. I’ll add these as soon as I can.

And a spoiler alert! I hope to eventually add support for effects operating on items, like a cursed sword or magical ring.

I hope you enjoy using the Combat Tracker Effect Visibility Options Extension, which can be downloaded here.

This blog post was written just prior to the release of EVOE v0.1.0.

Please feel free to PM me, or post comments, questions and/or criticisms either here or in the forums.

In a previous post I detailed how I added additional effect visibility button options to the Combat Tracker‘s GUI. This time I’ll step through the process of adding the Lua to make those button options functional.

Detour: This is post 18 in this series. I hope that by now, as a neo-developer, you have the confidence to do many things without the detailed instruction I have provided in the past. I’ll explain concept and intent but I won’t detail some of the more mundane code.

Setup: I started with a fresh, unzipped copy of the 5E ruleset. I created a new campaign. In the host I imported a couple PCs: Krystryd and a Paladin (in that order). I joined the game as Client1 and selected the Paladin as the client’s PC. I joined the game again as Client2 and picked Krystryd. I opened the Combat Tracker in the GM’s instance and added actors in the following order: an Orc, Krystryd, a Kobold, Paladin, and a Goblin. I made all actors visible. I opened the Effects Manager (EM) then used it or the PC’s Actions to apply the following effects: the Orc frightened (EM) the Paladin, Krystryd poisoned (EM) the Goblin and paralyzed (EM) the Orc, the Paladin applied (client Action) Aura of Courage to Krystryd and Aura of Warding to self. Finally I set the effect visibility options as shown here:
Attachment 14646
Note the following in the Combat Trackers: (1) The GM’s (left panel) displays all effects as desired. (2) The Goblin’s poisoned effect, does not show up in either the Paladin’s (upper right) nor Krystryd’s (lower right). (3) All other effects show up in both clients.

There are four button options, two of which behave appropriately, but I’ll have to address the Self option and the Target option in the client’s Combat Tracker.

Recall from previous work, the ct_host.xml file in the 5E\ct subfolder. There is also a ct_client.xml file. I started there. There are two windowclasses, one for the whole Combat Tracker and one for each list entry. I perused the <sheetdata> of the list entry, it was easy to reconcile the one-to-one correspondence to what is seen on screen. “string_ctentry_effects” must be the control that displays the effects. I searched for a template and found it in the Core’s template_ct.xml file. Which led me to the ct_effect_summary.lua file also in the Core. One of its functions points to the familiar EffectManager.getEffectsString(). Recall that I used a “forwarding” function for it. I put Debug statements in getEffectsString() in both the 5E and the extension manager_effect.lua files. I closed all instances of FG and restarted the host. Sure enough getEffectsString() in the 5E ruleset was called multiple times, but surprisingly, the one in the extension was never called.

A dilemma: should I chase down why the extension code is not being utilized, or work on modifying when the effects are displayed? The latter is the point of the current exercise, so I’ll do the development in the ruleset for now then move it to the extension and deal with the other issue later. After all, I might not even be in the right code yet!

Now to cursorily ascertain what the getEffectsString() function does: The first five or so lines create a “table” of nodes from the DB and sort it. Each table item is then operated on in a for loop that takes up the rest of the function. Within the for loop, some variables are set that are used in decision making further along. Then depending on the value of the variable bAddEffect, some string construction occurs.

I tried to change the display of the effects strings by changing the value of bAddEffect. I forced it to be false, just before it was tested (~line102, FG v3.1.7):

Code:

      bAddEffect = false;
      if bAddEffect then

I saved, restarted, brought up the host and clients; the effects strings were gone! But in the host, when I clicked the Effects button, I saw the effects were still present, the summary strings just weren’t displayed.

I was in the right place! (I removed my negation statement.)

The following code took hours to develop. I constantly referred to the DB page of the XML and Scripting Reference. Numerous times I viewed the campaign‘s db.xml file and inserted Debug statements to confirm variable values.

A word about getEffectsString(): This function is called for every running instance of FG, and for every actor in the Combat Tracker. I had a console up for each instance, I observed the function being called 5 times in each instance, processing each of the 5 effects.

The decision tree: (1) Depending on certain criteria, e.g. what FG instance is being operated on, what the visibility button’s value is, etc., the code will need to force bAddEffect’s value to be false. (2) The effects strings in the host instance are always displayed, so further decisions need only be processed if the current instance is not the host. (3) Visibility button values of 0 (All), or 1 (GM), do not need to be processed. Only values of 2 (Self) or 3 (Target) need to be addressed. This leads to a base decision tree of:

Code:

  if User.isHost() == false then
    local nVisibility = DB.getValue(v, "isgmonly", 0);
    if nVisibility == 2 then

    elseif nVisibility == 3 then

    end
  end

The decision process for Self: Only display the effects string if the current instance is the same as the actor possessing the effect. Within the DB, the effect has a property that lists the character sheet id (i.e. which PC is afflicted). The decision specific to case 2 becomes:

Code:

    if nVisibility == 2 then
      local sUser = User.getCurrentIdentity();
      local sCharSheetID = DB.getValue(DB.getValue(nodeCTEntry, "link"));
      if sCharSheetID ~= "charsheet." .. sUser then
        bAddEffect = false;
      end
    else …

The decision process for Target: Display the effects string as above for Self or display it if the inflictor of the effect is the same as the instance. Again within the DB, there is a property that lists the source or inflictor. Note that I’ve stated when to display the string, not when not to. Fortunately there is a “math” that will help me write the code.

Detour: Boolean Algebra is the “math” of true and false. For example, if one ORs something true with something false the result is always true. If one ANDs something true with something false the result is always false. What I have above is, if Self is true OR inflictor is true then display is true. A Boolean Algebra axiom states that if one negates each of the arguments and changes the operation (e.g. OR becomes AND) then the result is negated. In my case, if Self is false AND inflictor is false then don’t display.

Code:

    elseif nVisibility == 3 then
      local sUser = User.getCurrentIdentity();
      local sCharSheetID = DB.getValue(DB.getValue(nodeCTEntry, "link"));
      local nodeCTSource = DB.findNode(sSource);
      local sInflictorID = DB.getValue(DB.getValue(nodeCTSource, "link"));
      if (sCharSheetID ~= "charsheet." .. sUser) and (sInflictorID ~= "charsheet." .. sUser) then
          bAddEffect = false;
        end
      end
    end

Note that within the whole tree, there are duplicated statements for sUser and sCharSheetID, so I refactored the code. I also split the if statement, containing the and operation, into two statements and nested the nodeCTSource and sInflictorID evaluations between them. These variable resolutions don’t need to be done if the first part of the if statement fails. (This blog post is running long so I am not displaying the code here. I’ll put the refactored code in a comment attached to the blog.)

Bad News & Good News: As mentioned earlier in this post the getEffectsString() function in the extension was not being called. I tried to determine why and how to fix it. I copied quite a bit of code into the extension from both the Core and 5E rulesets without success. It appears as though it is some sort of interplay as code is loaded, parsed and executed from the various sources. As a last resort I posted a question in the FG Forums. To say the answer by Moon Wizard was inspiring, does not do him justice.

I employed the methodology brought to light in the forum thread. I discarded the manager_effect.lua and manager_effect_maker.lua files and replaced them with a manager_effect_boss.lua file. I copied the two functions, getEffectsString() and addEffect() from the 5E manager_effect.lua file to my “boss” file, renamed them, and added my functionality into them. Here is what the “boss” file contains (abbreviated):

Code:

function onInit()
  -- supplant the getEffectsString() functionality 
  EffectManager.getEffectsString = Ext_getEffectsString;
  -- supplant the addEffect() functionality
  EffectManager.addEffect = Ext_addEffect;
end

function Ext_getEffectsString(nodeCTEntry, bPublicOnly)
  -- override the functionality of the EffectManager's
  -- getEffectsString() function with that of this function
  . . . . .
end

function Ext_addEffect(sUser, sIdentity, nodeCT, rNewEffect, bShowMsg, sEffectTargetNode)
  -- override the functionality of the EffectManager's
  -- addEffect() function with that of this function
  . . . . .
end

Obviously the <base> in my extension.xml file changed too:

Code:

  <base>
    <includefile source="strings/strings_5e.xml" />
    <includefile source="ct/ct_host.xml" /> 

    <script name="SuperviseEffectManager" file="scripts/manager_effect_boss.lua" />
  </base>

That’s it! Done. Note the effects in this screenshot:
Attachment 14647

(PLEASE VIEW COMMENTS BELOW.)

Until next time keep on role playing.

In a previous post I detailed how I reduced duplicated lua script in my fledgling extension. Play testing the extension revealed a design error. The issue: Windows cannot resolve a folder path into a ruleset .pak file. (For background information, the reader might consider reviewing the prior post and in particular the first few comments attached to it.)

An obvious remedy for the problem is to insert .pak into the path as it is specified in the extension.xml file. I had doubts, but I tried it anyway.

Code:

    <script name="EffectManager5E" file="../../rulesets/5E.pak/scripts/manager_effect.lua" />

As I had surmised, the attempted quick fix failed.

Detour: As damned points out in a comment attached to the prior post, the 5E manager_effect.lua file is loaded twice. A few words about when FG loads its files. The Ruleset Modification Guide’s Extensions page provides more details. Specific to the manager_effect.lua files used by my extension, as FG comes up the CoreRPG’s file is loaded first. 5E’s file is loaded “over the top” of it, replacing the Core. Then the extension’s file is loaded “over the top” of 5E’s providing the extension’s functionality for “EffectManager“. My extension.xml file loads the 5E file a second time and assigns it to “EffectManager5E”, giving the extension access to the functionality in both the 5E and the extension manager_effect.lua files. But this only works in an unzipped 5E ruleset folder.

Theory: I’m working on the premise that my methodology for reducing the amount of duplicated code is sound so my extension’s manager_effect.lua file will remain relatively untouched. But, since the code cannot force a reload of the 5E manager_effect.lua file because the path to it cannot be resolved within a .pak file, my extension must “copy” the 5E EffectManager to EffectManager5E before it is overwritten during the load process.

As I step through the code development, I will be working with the unzipped 5E folder. When finished I’ll replace the unzipped 5E folder with the 5E.pak file to ensure proper function.

The extension.xml file cannot solely be relied upon to do things in the order that’s required. Instead, most machinations will be done in lua. A “maker” script file will supervise the construction of the EffectManager and the EffectManager5E objects. When execution proceeds to the “maker” script, both the 5E and the extension manager_effect.lua files must already be loaded. To prevent possible overwrite, load the extension’s lua into a “scratch” object. Here is the new <base> of the extension.xml file:

Code:

  <base>
    <includefile source="./strings/strings_5e.xml" />
    <includefile source="./ct/ct_host.xml" />

    <script name="MakeEffectManagers" file="./scripts/manager_effect_maker.lua" />
    <script name="EffectManagerExt" file="./scripts/manager_effect.lua" />
  </base>

Since there are a total of three manager_effect.lua files that are loaded, two of which are of concern, I need a way of discerning which file is being referred to at run time in the code. I can achieve this by temporarily adding the following function to the extension’s manager_effect.lua file, just after onInit( ):

Code:

function tom()
  Debug.console("TWD|manager_effect.lua|tom()|status", "EXT Arrived at tom");
end

My code will call this function each step of the way. If an error is reported, the function doesn’t exist in that manager. But, getting the above message means the manager has the extension code.

I created a manager_effect_maker.lua file in the scripts folder, put the following code in it, saved all files and invoked FG:

Code:

function onInit()
  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Initializing Maker");

  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Maker calling tom()...");
  EffectManager.tom();
End

When the tom function was called, an error was reported in the console, indicating EffectManager currently is not extension code.

Runtime Notice: s'TWD|manager_effect_maker.lua|onInit()|status' | s'Maker calling tom()...'
Script Error: [string "./scripts/manager_effect_maker.lua"]:11: attempt to call field 'tom' (a nil value)

That is what was expected since the last code assigned to EffectManager at that point in the load process was that of 5E. Reassigning EffectManager to EffectManager5E should preserve 5E’s manager_effect.lua. I replaced the above code with the following, saved the file and reloaded the rulesets:

Code:

  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Making 5E manager...");
  EffectManager5E = EffectManager;
  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Maker calling 5E tom()...");
  EffectManager5E.tom();

The console informed me the 5E manager was created and when tom( ) was called from the 5E manager an error occurred because the function wasn’t found. That confirms the EffectManage5E refers to 5E code!

Now to reassign the EffectManager to the extension’s code file. Again I replaced code, all of it except the EffectManager5E assignment statement. Here are the onInit( ) function’s contents:

Code:

  EffectManager5E = EffectManager;

  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Making Ext manager...");
  EffectManager = EffectManagerExt;
  Debug.console("TWD|manager_effect_maker.lua|onInit()|status", "Maker calling Ext tom()...");
  EffectManager.tom();

After saving the file and reloading the ruleset, the console’s messages were:

Runtime Notice: s'TWD|manager_effect_maker.lua|onInit()|status' | s'Maker calling Ext tom()...'
Runtime Notice: s'TWD|manager_effect.lua|tom()|status' | s'EXT Arrived at tom'

Note that the call to tom( ) succeeded this time, indicating the use of the extension’s manager_effect.lua code.

One final check, “it’s the only way to be sure”. I removed all the code except the EffectManager5E assignment and the EffectManager reassignment, then added these two Debug.console( ) calls to dump each of the objects:

Code:

  Debug.console("TWD|manager_effect_maker.lua|onInit()|5E manager", EffectManager5E);
  Debug.console("TWD|manager_effect_maker.lua|onInit()|Ext manager", EffectManager);

Save and reload. Console output (abbreviated):

Runtime Notice: s'TWD|manager_effect_maker.lua|onInit()|5E manager' | { s'addEffect' = fn, s'removeEffect' = fn, s'unlock' = fn, ...
Runtime Notice: s'TWD|manager_effect_maker.lua|onInit()|Ext manager' | { s'addEffect' = fn, s'removeEffect' = fn, s'unlock' = fn, ...

I copied the console to the clipboard, opened Notepad and pasted the clipboard. Using Notepad’s search capability I looked for tom. It only appeared once in the contents, in the dump of EffectManager; a final confirmation EffectManager5E refers to the 5E lua and EffectManager refers to the extension’s lua.

Since, FG was up, I brought up the Combat Tracker, deleted any effects, brought up the Effects Manager and tried to paralyze the Orc. A slightly cryptic error message occurred:

Script Error: [string "./scripts/manager_effect.lua"]:113: attempt to index global 'EffectManager5E' (a nil value)

So, what exactly has a nil value? The EffectManager5E? To confirm I placed the Debug.console( ) command that dumps the 5E manager (see above) into the addEffect( ) function of the extension’s manager_effect.lua file. As before, save…paralyze. The console reported the EffectManager5E was okay in the onInit( ) of the "maker" scripts, but somehow nil in the EffectManager. Curious! Another oddity, the EffectManager was not nil since the addEffect( ) function ran.

Evidently the EffectManager5E is being set to nil, after "maker" creates it but before it’s utilized by the EffectManager. This predicament often occurs with global variables. So I’ll isolate it in the code, I’ll make it local to each script, and use a function that EffectManager must call to gain access to EffectManager5E. Here is manager_effect_maker.lua in its entirety:

Code:

local EffectManager5E = nil;

function onInit()
  EffectManager5E = EffectManager;
  EffectManager = EffectManagerExt;
end

function get5eEffectManager()
  return EffectManager5E;
end

As stated above the EffectManager must have access to the functionality of EffectManager5E. In fact it is needed by nearly every function the EffectManager contains. The EffectManager’s onInit( ) function will obtain the EffectManager5E object and save it locally, that way obtaining access need only be done once. Here is the onInit( ) function plus the local variable definition in the extension’s manager_effect.lua file:

Code:

local EffectManager5E = nil;

function onInit()
  OOBManager.registerOOBMsgHandler(OOB_MSGTYPE_APPLYEFF, handleApplyEffect);
  OOBManager.registerOOBMsgHandler(OOB_MSGTYPE_EXPIREEFF, handleExpireEffect);

  CombatManager.setCustomInitChange(processEffects);
 
  EffectManager5E = MakeEffectManagers.get5eEffectManager();
end

Save…paralyze, and it works!! At least with the unzipped 5E ruleset. To test it with the 5E.pak file I removed the unzipped 5E ruleset from the rulesets folder and renamed the 5E.pak.orig to 5E.pak (.orig? Confused? See this blog). Reload the rulesets…paralyze. Success!!

Now to play test the extension!

Until next time keep on role playing.

Play testing the Effect Visibility Extension indicated more visibility options are required. When effects are only visible to the GM, if a player applies an effect to their character and doesn’t see it in the Combat Tracker, they tend to apply it again, and then again. When the GM views the player’s character in the Combat Tracker, the self applied effect could be listed 2, 3 or more times.

What additional options are needed? Certainly, an option that allows the player to see effects applied to their own character (“self”). Plus an option that allows the player applying an effect and the target of the effect to see it (“target”). I’ll start by implementing these two additional options.

Detour: A note about consistency. As I work through the steps of creating an FG extension I am trying to be mindful of consistency. Using object names, folder names and folder placement, and even programmatic indentation consistent with the rulesets. After all, I am creating an extension of FG’s functionality. If it were my application I could go off on whatever willy-nilly, haphazard naming scheme I like. It seems only prudent to be courteous to others coming behind me to provide a seamless programming style between the rulesets and my extension rather than subject them to my individuality.

Recall from a prior blog that I had located the XML file where the Combat Tracker’s effect visibility button is defined. For each new state of the button I’ll need a named icon, a tooltip, and an associated graphic (the button face). I’ll go through this process by creating new .png graphics files, then creating <icon> definitions to reference them. I’ll define tooltip strings and sew everything together with button <state> definitions.

First the graphics that will show up on the button for “self“ and “target“. As a start, I wanted to find the .png graphics files for the current button faces, then in a graphics editor like Paint, change the lettering and save them in new files.

Using Notepad++, I searched for the <icon> names in the 5E and CoreRPG rulesets. That led me to the graphics_icons.xml files and then to the graphics\buttons subfolders. Looking through the graphic files in the folders I discovered button_toggle_self.png and button_toggle_trgt.png files. Unbelievable luck - it’s as if someone started this project but didn’t finish it.

Next I searched for the new-found file names in the rulesets to see if they had already been assigned to <icon> names and they were, in the graphics_icons.xml file.

All that was left were tooltips. I looked in some of the XML files that have other Combat Tracker tooltip strings defined but I found nothing relevant, so I created a strings subfolder in my extension folder. I then put the following definitions in a new strings_5e.xml file:

Code:

<?xml version="1.0" encoding="iso-8859-1"?>

<root>
  <string name="effect_tooltip_visibilityself">Visible to GM and Self</string>
  <string name="effect_tooltip_visibilitytrgt">Visible to GM, Self and Target</string>
</root>

A reference to the new strings file must be included in the extension.xml file:

Code:

  <base>
    <includefile source="./strings/strings_5e.xml" />
   . . .

As mentioned above, from a prior posting, I know the visibility button is defined in the ct_effect <windowclass> in the 5E\ct\ct_host.xml file, so I created a ct subfolder in my extension and then copied the ct_host.xml file into it from the 5E ruleset. The new visibility options were added to the button using <state>:

Code:

  <buttonfield name="isgmonly">
    <bounds>28,1,24,10</bounds>
    <state icon="button_toggle_visible" tooltipres="visibilityon" />
    <state icon="button_toggle_gm" tooltipres="visibilityoff" />
    <state icon="button_toggle_self" tooltipres="effect_tooltip_visibilityself" />
    <state icon="button_toggle_trgt" tooltipres="effect_tooltip_visibilitytrgt" />
  </buttonfield>

I included the new file in my extension.xml file:

Code:

  <base>
    <includefile source="./strings/strings_5e.xml" />
    <includefile source="./ct/ct_host.xml" />    

    <script name="EffectManager5E" file="../../rulesets/5E/scripts/manager_effect.lua" />
    <script name="EffectManager" file="./scripts/manager_effect.lua" />
  </base>

Now to look at how the changes affect the GUI. I saved all my files, reloaded the ruleset, brought up the Combat Tracker, deleted all existing effects, and then clicked the little Add Effect button four times. Note the undesired behavior of the button still exists, the effect’s initial visibility is “VSBL”. It’s moot since it doesn’t show up in the player’s Combat Tracker, but it is still irritating. I’ll surely revisit this in the future! I then cycled the visibility buttons so that each one displayed a different state and added a bit of descriptive text. Here’s a screenshot:
Attachment 14470

I saved the DB to disk using /save in the Chat box. I brought up the campaign’s db.xml file in Notepad++ and searched for <effects>. The <isgmonly> and <label> fields have the desired values: <isgmonly> cycles through the four button states, 0 through 3, and each <label> has the correct corresponding string.

Code:

  <effects>
    <public />
    <id-00002>
      <public />
      <duration type="number">0</duration>
      <init type="number">0</init>
      <isactive type="number">1</isactive>
      <isgmonly type="number">0</isgmonly>
      <label type="string">Visible</label>
    </id-00002>
    <id-00003>
      <public />
      <duration type="number">0</duration>
      <init type="number">0</init>
      <isactive type="number">1</isactive>
      <isgmonly type="number">1</isgmonly>
      <label type="string">GM Only</label>
    </id-00003>
    <id-00004>
      <public />
      <duration type="number">0</duration>
      <init type="number">0</init>
      <isactive type="number">1</isactive>
      <isgmonly type="number">2</isgmonly>
      <label type="string">Self and GM</label>
    </id-00004>
    <id-00005>
      <public />
      <duration type="number">0</duration>
      <init type="number">0</init>
      <isactive type="number">1</isactive>
      <isgmonly type="number">3</isgmonly>
      <label type="string">Target, Self and GM</label>
    </id-00005>
  </effects>

Detour: The order that I defined each <state> was deliberate. VSBL and GM were left as is to be compatible with existing db.xml files and existing lua code. The two new options were added with visibility “restriction” in mind. GM restricts visibility the most. SELF is a little less restrictive, TRGT even less so and VSBL the least restrictive. As one cycles the button from the initial state GM, the visibility cycles to SELF, then TRGT and back around to VSBL.

Next some clean up: rid the extension’s copy of ct_host.xml of some of the duplicate code it contains. Unlike lua script files I can delete some of the XML without detriment. With ct_host.xml open in Notepad++, I opened the “View” menu and selected “Fold All”, then clicked the little “+” next to <root>. I deleted all code except for the <windowclass> named “ct_effect” since it contains the modified button.

Having read parts of the Ruleset Modification Guide, I recalled references to various forms of “merge”, in the Templates section. After rereading that section I still didn’t have a very good handle on using merge so I went looking in the forums for examples. This recent thread looked very pertinent. I experimented with some of the merge attribute options mentioned but without success. So I searched for more examples of “merge” in the rulesets using Notepad++. The use of “delete” in the 5E\campaign\record_char_inventory.xml file was inspiring, use delete to remove a control then redefine it. Using the knowledge gained I reduced the extension’s ct_host.xml file to this:

Code:

<?xml version="1.0" encoding="iso-8859-1"?>

<root>
  <windowclass name="ct_effect" merge="join">
    <sheetdata>
      <buttonfield name="isgmonly" merge="delete" />
      <buttonfield name="isgmonly">
        <bounds>28,1,24,10</bounds>
        <state icon="button_toggle_visible" tooltipres="visibilityon" />
        <state icon="button_toggle_gm" tooltipres="visibilityoff" />
        <state icon="button_toggle_self" tooltipres="effect_tooltip_visibilityself" />
        <state icon="button_toggle_trgt" tooltipres="effect_tooltip_visibilitytrgt" />
      </buttonfield>
    </sheetdata>
  </windowclass>
</root>

The new options work fine in the GUI, but lack the lua that implements useful functionality. It looks to be big work, I’ll start gearing up.

Until next time keep on role playing.

This time I’ll look at reducing the size of the manager_effect.lua file in my extension. Recall from last time, I copied that lua file, in its entirety, to my extension then added a single line of code to change the default behavior of an effect’s initial visibility. Having nearly 1500 lines of duplicate code troubles me.

Detour: Why is duplicating code bad practice? For one it bloats the size of your program, and for certain languages that can cause decreased execution speed. But, in my mind, even worse, it creates a maintenance nightmare. If one simply copies code, later on if new functionality is being added, one must remember where those copies are in order to change them. If one is new to the code, one doesn’t even know the copies exist. An example: say you’ve written a program that manages elevator buttons. The building has five floors and you just copy the code five times, once for each button. Now suppose your customer wants lit buttons. That’s five places in code you have to modify. Later on you get a contract to use your program in a building with three elevators servicing 350 floors. That’s 1050 copies of that code! What if, your new customer later wants flashing button lights?

In many of my prior posts I’ve typically only reported processes that produced positive results. This time I’ll include those that yield negative or failed results. I’m doing this to illustrate my tactics as I try to solve a problem.

Each time, after I perform code modifications I’ll do the following: I’ll save the edited files, reload the ruleset in FG, bring up the Combat Tracker, remove all existing effects, bring up the Effects Manager and paralyze the Orc. I’ll abbreviate this as: “save … and paralyze”.

There are nearly 40 functions in the copied manager_effect.lua file. Previously, I added one line of code to one of those functions. All the other functions in the extension are identical to their corresponding function in the 5E ruleset. Recall how an extension works, code in the extension overrides code in the ruleset. If the ruleset code is still accessible, the extension might be able to call it, thereby eliminating the need for the duplicate code.

Theory: The easiest way to eliminate duplicate code is to simply delete all functions in the extension that are identical to those in the ruleset.

Since I know how to invoke the addEffect( ) function I can use it as a test case. I’ll delete it from manager_effect.lua in my extension. If this is a workable solution the code in the 5E ruleset will execute in place of the missing extension function. I’ll place a Debug.console( ) call in the 5E’s addEffect( ) function, delete addEffect( ) from the extension‘s lua file and “save … and paralyze”. The console reports an error ‘…addEffect a nil value’. I believe this somewhat cryptic message means there is no addEffect( ) function to execute. Fail! I undo my edits and resave the file.

Theory: I’ll keep the function definitions in my extension lua file but forward execution to the ruleset. To do this I’ll replace the guts of the function with a call to the 5E function.

To force access to the 5E functions I’ll add a <script> file reference in my extension.xml file, that “creates“ a “5E Effects Manager“. Notice that the reference to the 5E manager precedes the other reference. I’ve done this because I don’t want any initialization done by my extension to be overridden or changed by the 5E manager’s initialization.

Code:

  <base>
    <!-- As of FG v3.2.0 the following should no longer be necessary -->
    <script name="EffectManager5E" file="../../rulesets/5E/scripts/manager_effect.lua" />
    <script name="EffectManager" file="./scripts/manager_effect.lua" />
  </base>

As the test case, I’ll add a line of code to the extension’s addEffect( ) function that utilizes the new “5E Effect Manager”:

Code:

function addEffect(sUser, sIdentity, nodeCT, rNewEffect, bShowMsg, sEffectTargetNode)
  Debug.console("TWD|manager_effect.lua|addEffect()|status", "EXT Adding");
  rNewEffect.nGMOnly = 1;
  return EffectManager5E.addEffect(sUser, sIdentity, nodeCT, rNewEffect, bShowMsg, sEffectTargetNode);
  -- VALIDATE
  if not nodeCT or not rNewEffect or not rNewEffect.sName then
  . . .

I saved the files, and during ruleset reload an error was thrown to the console: “..end expected..” I believe the message means that the lua interpreter recognized that my “return” statement prevents any of the rest of the code in the addEffect( ) function from executing. My quick hack failed! So I’ll comment out the rest of the function all the way down to, but not including, end. After I “save … and paralyze”, it works!

It appears as though I have found a solution. I have almost 40 “forwarding” functions to implement, but it will reduce the size of my lua file from ~1500 lines to ~160 and remove all duplicated code. I am going to do this a few functions at a time, just in case there are unforeseen affects.

I am going to leave the onInit( ) function alone because I don’t want the extension to initialize then call 5E to initialize over the top of it. After implementing the forwarding calls in five functions I “save … and paralyze” and it fails - the initial visibility comes up “VSBL” not “GM”! I restore the functions with undos.

Okay then, one function at a time :( . The first one, handleApplyEffect( ) causes a fail! An undo and a look at the function’s code… The last line is an addEffect( ) call! Here is my guess as to what is happening. The extension’s handleApplyEffect( ) is called, the execution is forwarded to the 5E ruleset function then the addEffect( ) in the ruleset is called instead of the one in my extension, the default visibility isn’t changed. I’ll verify this by putting Debug.console( ) calls in the onInit( ), handleApplyEffect( ) and addEffect( ) functions in both the extension and the ruleset, plus put the forwarding call back in.

Runtime Notice: Reloading ruleset
Runtime Notice: s'TWD|manager_effect.lua|onInit()|status' | s'5E Initializing'
Runtime Notice: s'TWD|manager_effect.lua|onInit()|status' | s'EXT Initializing'
Runtime Notice: s'TWD|manager_effect.lua|handleApplyEffect()|statu s' | s'EXT Handling'
Runtime Notice: s'TWD|manager_effect.lua|handleApplyEffect()|statu s' | s'5E Handling'
Runtime Notice: s'TWD|manager_effect.lua|addEffect()|status' | s'5E Adding'

Sure enough, that’s it. Note the initializers occur in the proper order, 5E first then the extension (and they occur as FG is loading up). When I paralyze, the extension forwards execution to 5E and then 5E calls its own addEffect( ) not the one in the extension!

The handleApplyEffect( ) cannot forward execution to the ruleset. It has to keep the duplicated code. A quick search of the file for addEffect( shows that there are no more of those calls to worry about.

After implementing the forwarding calls, a few at a time, in the remaining functions, a test of the extension by paralyzing the Orc yields the desired default visibility behavior.

I have attached my manager_effect.lua (as a .txt) file for your perusal.

Some explanation about the methodology and the forwarding call statements: First: Did I accomplish what I set out to do? Most assuredly. I eliminated almost 1000 lines of duplicate code! Second: By eliminating the duplicated code using this methodology, should the 5E ruleset’s manager_effect.lua file be modified in a later version of FG it is very unlikely that I will have to “fix” my extension to be compatible with the new version. Three exceptions are: (a) if more arguments are added to any of the functions, (b) if new functions are added, or (c) if an addEffect( ) call is added anywhere in the 5E lua file. Third: Lua is very forgiving, a reduction of arguments won’t matter. Also, if one paid close attention to the code that was being replaced by the forwarding function statements, one would have noted that many of the functions did not return values to their callers. Lua’s forgiveness ignores returned values if they’re not used and returns nil if there’s nothing to return. I’ve used consistency in coding the forwarding statements for ease of maintenance.

I haven’t noticed anyone else using this methodology in other extensions, but then again I haven’t looked at every extension out there. I would really be appreciative of comments by other programmers and especially by the developers at Smiteworks, as to the general reusability of this methodology in FG extensions.

I can’t wait to play test my extension!

Until next time keep on role playing.