Category Archives: Documentation

Things Writers of Plugins Should Know

Since release, and as of 5.0.197, there have been some important changes to be aware of:

* Notes/Notes()

As mentioned in the build notes, the purpose of the notes() tag on traits has been pretty muddled over time due to a variety of folks using it in ways that were not intended. That tag was meant to be used in a tiny space to show table notes references such as “[1,2]” for weapon or armor footnotes. Yes, notes() was a bad name for it, but it originated back when GCA did far less.

The notes() tag is now enforced as a mode-specific tag for the original intended purpose (and even that is now discouraged in favor of using itemnotes() instead), and any use of notes() that was intended by a user to be general item-related notes or commentary should be changed to usernotes() or included in the description(), instead.

* Each trait’s Description() and UserNotes() tags are probably RTF formatted strings.

This may not work for you.

The new functions GetNotes(Optional ByVal AsPlainText As Boolean = True) As String and GetDescription(Optional ByVal AsPlainText As Boolean = True) As String allow for retrieving the usernotes() and description() tags of a trait, as normal RTF or as plain-text.

Line breaks (as LF characters) will be preserved.

* The Notes property on GCATrait has been will now return usernotes() as plain-text.

If you set it, it sets usernotes() with that text.

* Character.Settings has an ApplyDBToActiveDefenses property.

When TRUE, all active defense scores (block, parry, dodge) *will* include the DB value for the active shield (one equipped on an arm). When FALSE, those scores won’t include the DB (which is the traditional way GCA has done it).

If your application needs the scores *not* to include the shield DB but this setting is TRUE, you can set the value to FALSE, call RecalculateAll(True, False), do your exporting, then reset things for the user by setting the value back to TRUE and calling RecalculateAll(True, False) before quitting.

You can get the current DB being applied in the DefenseBonus() As Integer or DB() As Integer functions. The applied DB may be 0 if no shield is equipped.

* Each shield will have a charblockscore() tag.

This contains the character’s Block level when using that shield. This will include the DB for the shield, but if ApplyDBToActiveDefenses is TRUE, then the better of the two values (this shield’s DB or equipped shield’s DB) will be included.

* GCA provides the VTTNotes() tag.

This is per-trait as a way for the user to include VTT-specific notes or formulas, such as OTF expressions for Foundry. On an attack-mode level, GCA provides the mode-specific VTTModeNotes() tag for the same purpose.

* I have added Public Function DamageDisplayText() As String to the Mode object.

This function returns a string that represents the standard damage notation including damage, armor divisor, damage type, and radius. Example: 2d+1 (2) cut (2). You can also access this using Item.DamageModeTagItem() with “DamageDisplayText” as the tag, if you’re accessing mode values that way. This should obviate the need for you to build damage strings yourself, and it will correctly show the new comma-separated mini-modes if those are used by a trait.

Finally combined the Data File References

I have finally combined the two different Data File reference documents into a single one: GCA Data File Reference Guide (2022). It’s so convenient you probably won’t even notice it’s over 140 pages.

As I mention on the Documentation page, it could probably use some more love, but it’s all in one one place now, and I’ll work to improve the content and the presentation over time.

Very Early, Still-A-Work-In-Progress Draft of the GCA5 User’s Reference Guide

I’ve got a few things into the GCA5 User’s Reference Guide at this point, so I thought I’d share a work-in-progress link, just in case anyone cares.

This is first draft territory; most of the links that will be there are not there yet, and the only editing so far is my own review as I write each piece, so there are likely lots of typos and whatnot.

If you want to take a look, please only comment on what kinds of content you’d like to see, depth of coverage, and so on. Anything at the copy-edit level will be wasted at this point.

Link to the file on my OneDrive is here: GCA5 User Reference Guide (link updated to new doc January 12, 2022)

Plugin Reference Guide (in progress, slowly)

I’m working on the user reference guide for GCA5 right now, but I occasionally spend time on more technical docs as well.

If you are writing a plugin, or want to write one, here are some docs I’m slowly working on that may help you (along with looking at the code for existing sheets to see how I do something in particular.)

Plugin Reference Guide.PDF

I’m afraid I haven’t actually updated it in a while, but it may already have some useful info within.

Data File Features

I haven’t done a preview in a while, so for something a bit different, I thought I’d post some of the additions to what data files can support. This also provides a peek into what kinds of new features traits support, as well, since one follows on the other.

Since I made a pretty document about it recently, I figure I’ll just link to that, and let you check it out if you’d like.

Here it is:

GCA5 Updated Data File Info (PDF Doc)

GCA5 Updated Data File Info (PDF Doc)