Developer Guide - Historical Change Guide
Overview
This section was created in order to document ongoing changes to the Fantasy Grounds API and CoreRPG base ruleset layer development that should be applied to rulesets going forward for the best compatibility with CoreRPG, standard themes, and new features.
We typically try to keep some backward compatibility for functions and features for at least 6 months (longer in some cases), in order to minimize disruption to ruleset and extension developers. However, we want to try to continuously raise the bar for what users can expect when they use Fantasy Grounds, as well as reduce overall code maintenance by retiring old code.
The SmiteWorks team will usually provide notification to rulesets that are included with the standard installation or in the SmiteWorks store; but does not attempt to provide proactive code analysis of extensions or any community/forge projects.
The notes will be provided by the month and year that the developer notes were provided to developers.
If you have any questions, please reach out to the SmiteWorks development team via the Workshop forum on the web site.
August, 2023
NOTE: This ruleset update is part of a larger push to standardize UI frames and fields for consistency for users, as well as making theming for ruleset creation and extensions much easier long term.
Overview
Review all subsections below.
Note specific ruleset changes indentified and called out in following three sections.
All themes should pay special attention to the Top Level Windows section in the guidelines linked below.
Frame Usage Guidance (Continuing)
Guidelines to be used when migrating
Updates To Be Made (General)
Migrate windows to use top-level window usage guidelines for these frames: utilitybox, tokenbag, referencelist, charselect
If frames used for other window types, migrate those windows to the correct top-level frame based on the guidelines.
Rebuild Top-Level Windows with chatbox/charselect/referencelist frames
chatbox - Use/define new anchoring templates for any windows defined using chatbox frame
Remove “basicchat*” template overrides; and use standard top/bottom anchors to adjust placement [SDL, ]
charselect - Use/define new anchoring templates for any windows defined using charselect frame
referencelist - Use/define new anchoring templates for any windows defined using referencelist frame
Review Specific/Auxiliary Asset Definitions (Per Frame) section in the Top Level Windows guidelines to implement all the primary and auxiliary requisite assets to go with any frames redefined in the ruleset or theme.
chatbox, utilitybox, tokenbag, referencelist, charselect, recordsheet, charsheet, imagebox, npcsheet, storybox, charsheethelper, ctbox, partysheet
Update dice tower coding
Migrate dice tower assets to use icons, instead of frames (dicetower_normal, dicetower_drop)
Remove dicetower roll specifications (now dynamically pulls from ActionsManager)
Updates To Be Made (Specific Rulesets)
[SDL]
Implement Top-Level Window Templates Noted in Guidelines for Specific Asset Definitions (Per Frame)
Ex: Font: button-white -> (Copy to ruleset from Classic theme; or from CoreRPG and set color to FFFFFF)
Assets To Be Deprecated (and Replacements)
Fonts
reference-groupsubdesc -> (Remove; Handled by header_content_groupdesc template)
Frames
referencepage -> recordsheet
Templates
sub_ref_header -> sub_record_header
close_referencepage -> close_recordsheet (and use recordsheet frame)
frame_ref_content -> frame_record_content
sub_refmanualpage_content -> subwindow_record (and activate tag)
sub_ref_content -> subwindow_record (and activate tag)
scrollbar_ref_content -> scrollbar_content
anchor_reftitle -> anchor_content_referencelist_top/anchor_content_referencelist_bottom
button_reftable_collapse -> button_content_grouped_collapse
button_reftable_expand -> button_content_grouped_expand
filter_reftable -> filter_content_grouped_bottom
frame_groupdesc -> header_content_groupdesc
ft_reftablefooter -> (Remove usage; handled by ref_listgroup.lua script)
header_reftablegroup -> anchor_list_content_label_left/anchor_list_content_label_right
label_reftable -> label_list_content_number_right/label_list_content_string_noframe_right/label_list_content_noframe
list_ref -> list_content_framed_groupbox_alternating_filtered
list_reftablegroup -> list_content_framed_groupbox/list_content_noscroll_alternating_top
list_reftablegroupitems -> list_content_noscroll_alternating_top
number_ref_weightwithsuffix -> stringc_listitem_left_noframe_static (and custom window onInit)
number_reftable -> number_text_listitem_left_noframe_static
filter_ref -> filter_content_bottom
resize_referencepage -> resize_recordsheet (and use recordsheet frame)
scrollbar_reftablegroup -> scrollbar_content_grouplist
string_groupdesc -> header_content_groupdesc
string_groupsubdesc -> (Remove; Handled by header_content_groupdesc template)
string_reftable -> string_listitem_left_noframe_static/string_listitem_left_noframe_static_linked
button_iadd_campaign -> button_iadd_list_content_controls
button_iedit_campaign -> button_iedit_list_content_controls
Assets Removed
Fonts
button-white-large
Frames
durationadjustment
fielddice
storybox2
Icons
button_collapse_down
button_expand_down
char_defenses
image_loading
image_locked
minimized_charability
minimized_charattacks
minimized_charequipment
minimized_charnotes
minimized_charpowers
Strings
masterindex_button_category_editon
masterindex_button_category_editoff
Templates
anchor_charselect_button
anchor_refgroupedlist_bottom
anchor_refgroupedlist_label
anchor_refgroupedlistgroupitem_left
anchor_reflist_paging
button_backcharwindow
button_importcharfile
button_importcharwindow
filter_charselect
filter_refgroupedlist
filter_reflist
frame_groupedlist_group
ft_refgroupedlist_notes
label_item_reftype
label_reftype
label_source
link_refgroupedlistgroupitem
list_refgroupedlist
link_reflistitem
list_reflist
masterindex_anchor_bottom
masterindex_anchor_paging
masterindex_category_scroll
scrollbar_refgroupedlist_notes
scrollbar_reflist_notes
string_reflistitem
sub_refgroupedlist_notes
sub_reflist_notes
June, 2023
NOTE: This ruleset update is part of a larger push to standardize UI frames and fields for consistency for users, as well as making theming for ruleset creation and extensions much easier long term.
Frame Usage Guidance (Update to UI Standards)
https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/2172420127/UI+Standards+-+Rulesets+and+Extensions#Top-Level-Windows
https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/2172420127/UI+Standards+-+Rulesets+and+Extensions#Content-UI-and-Layout
Migrate utilitybox2/utilitybox3 to utilitybox
Remove calendar/utilitybox2/utilitybox3 frame definitions and graphics;
as well as help_*/close_*/resize_* templatesUse new anchoring templates for any windows defined using utilitybox frame
(see link above, and see examples in CoreRPG)Update anchor templates as needed for utilitybox/tokenbag
(if frames or windowtitle position updated by ruleset/extension)
(i.e. anchor_content_utilitybox_top/anchor_content_utilitybox_bottom)
(i.e. anchor_content_tokenbag_top/anchor_content_tokenbag_bottom)Already defined in all official themes
Remove deprecated templates (or copy to ruleset locally)
template: anchor_campaign
template: anchor_campaign2
template: filter_campaign
template: filter_utility
template: anchor_title_utilitybox (Migrate to anchor_content_utilitybox_top)
template: anchor_title_utilitybox3 (Migrate to anchor_content_utilitybox_top)
template: anchor_bottom_utilitybox3 (Migrate to anchor_content_utilitybox_bottom)
template: close_utilitybox3 (Migrate to close_utilitybox)
template: resize_utilitybox3 (Migrate to resize_utilitybox)
template: helper_effects (Migrate to help_utilitybox; Add window.helplinkres)
Remove Debug code from release
Remove print calls (use ChatManager.SystemMessage)
Remove printstack and Debug.printstack calls (not for release code)
Remove debugging output from release code (Debug.chat, Debug.console)
Use ChatManager.SystemMessage or remove
Investigate sound trigger support
All sound triggers are based on Lua pattern matching
Ruleset sound triggers also pre-baked expressions to match for specific action types
See CoreRPG:SoundSetManager global script, lines 40-115, for examples
Several official rulesets we are supporting directly already handled here (5E, 4E, 3.5E, ...)
Investigate chat record sharing support
RecordShareManager global script added to support simple chat text output of records
(see 5E for examples of records using button_ichat template in headers, as well as RecordShareManager5E script)
Common Code
Use new "button_text_toggle" template when defining toggle-able buttons using buttonup/buttondown frames
"helper_<topic>" templates being replaced with "help_<frame>" templates and window.helplinkres tag
DesktopManager.setSidebar* -> ColorManager.setSidebar* long term migration
February, 2023
General
Use getChildList instead of getChildren for DB/databasenode calls when you don't need the node key name. Uses numerical keys instead, which is faster and can use ipairs to iterate.
databasenode -> DB API calls migration. See post below.
Convert multiple concatenated strings into single string.format call
Portraits
Update standard portrait size to 100x100 pixels
charlist_base -> (increased to 100x100)
charlist_mask -> (increased to 100x100)
Remove mini portraits
miniportrait_base -> (removed)
miniportrait_mask -> (removed)
Combat Tracker
Use subwindowing to improve performance (toggles, sections, …)
(See examples in 5E/4E/3.5E using CoreRPG base objects and inheritance.)
Update ct_entry.lua:delete to use CombatManager.deleteCombatant (or just inherit)
Use CombatManager.deleteFaction/deleteNonFaction in ct_menu.lua
Character Sheets
Review template:list_charinv and script:char_invlist.lua usage for simplification
(Move char sheet updates to CharManager, in case character sheet not open during PS distribution)
Actions tab generalization and optimization
Use subwindowing to improve performance
(See examples in 5E/4E/3.5E using CoreRPG base objects.)
Dice Skins
Add dice skin customization for critical/precision dice (D&D clones)
Death Markers
Investigate adding death marker support to each ruleset
Token Height Support
Update any TokenManager overrides to use new code that supports token height natively.
Theming Support
Token Decorations
font: token_name, token_ordinal, token_height, token_height_negative
frame: token_name, token_ordinal, token_height
functions: TokenManager
setTokenFrameName(sFrame, sFrameOffset)
setTokenFontName(sFont)
setTokenFrameOrdinal(sFrame, sFrameOffset)
setTokenFontOrdinal(sFont)
setTokenFrameHeight(sFrame, sFrameOffset)
setTokenFontsHeight(sPositiveFont, sNegativeFont)
Migrated frame: tokennumber -> token_ordinal
Other Theming Changes
Icon: spell_cast -> roll_cast
Icon: spell_damage -> roll_damage
Icon: spell_heal -> roll_heal
Icon: spell_effect -> roll_effect
Icon: usepower -> power_use
Cleanup
Icon: footer_narrow (remove)
Template: button_toggledetail (remove; moved to CoreRPG)
Font: reference-subtitle (remove)
template: windowtitlebar_char -> windowtitlebar_charsheethelper
template: anchor_title_charsheethelper (remove)
frame: charsheethelper (remove)
Common Code
Consolidate updateControl -> WindowManager.callSafeControlUpdate(self, sControl, bReadOnly, bForceHide)
Rework of iedit/idelete buttons to support alternate use requiring less update code
button_iedit -> edittarget tag(s) (or no target tag) calls onEditModeChanged for all children of edittarget(s) (or window parent)
button_idelete -> editmode tag checks for numerical control value == 1 (on window parent object and up)
Added spacer_header_idelete template -> uses editmode tag to check for numerical control value == 1 (on window parent object and up)
August, 2022
Cleanup
Remove definitions for common resources moved to CoreRPG that do not need to be overriden.
(base, dash, lvl, level, hp, hitpoints, ac, armorclass, cr_label_hptemp, ct_label_nonlethal, ct_label_wounds, ct_label_status, ct_tooltip_hptemp, ct_tooltip_nonlethal, ct_tooltip_wounds, ct_tooltip_size, ct_tooltip_reach)
Combat Tracker
Review new combat tracker templates and logic in CoreRPG/5E to see if you should use. Subwindows improves performance and reduces control overhead when not needed.
February, 2022
Currencies/Encumbrance
Update GameSystem.currencies to provide name, value, weight for each
Ex: { name = "GP", weight = 0.02, value = 1 }
Enable new system (CharEncumbranceManager.addStandardCalc() or addCustomCalc(fnCustomCalc))
Ex: See 3.5E ruleset for typical example
Ex: See SFRPG ruleset for custom example with partial replace and extra functionality
Note: Requires coin list updates (see below)
Note: Can use custom func that calls back into default functions for partial customization or additional functionality
Update charsheet_inventory
Remove old coinname and coinamount fields
Add standard templated currency list
If "coinother" support, then use:
sub_charcurrency, scrollbar_sub_charcurrency, button_iadd_sub_charcurrency, button_iedit_sub_charcurrencyIf no other field needed, then use:
list_charcurrency, scrollbar_currencylist, button_iadd_currencylist, button_iedit_currencylistEx: See 3.5E ruleset for standard case with "coinother"
Ex: Ask for example of standard case without "coinother". (CoC/WOIN)
Update main window and inventory list scripts if override
Remove handlers for "count", "weight" and child delete in list
Remove onEncumbranceChanged calls
Update CharManager script overrides (updateEncumbrance)
Update global scripts that use old coins.slot# (Ex: Overrides of PSLootManager/ItemManager)
Implement custom overrides
setEncumbranceField("encumbrance.load");
setCustomItemLists({ "inventorylist" });
setCustomItemFields({ "carried", "count", "weight" });
setCustomCurrencyLists({ "coins" });
setCustomCurrencyFields({ "amount", "name" });
Remove other monitoring
Remove any other monitoring of item carried/count/weight fields that update encumbrance
Remove any other monitoring of coin amount/name fields that update encumbrance
Sidebar
Add any custom buttons to sidebar
DesktopManager.registerSidebarToolButton(tButton, nIndex)
tButton = { sIcon = "<IconAsset>", tooltipres = "<StringAsset>", class = "<WindowAsset>", path = "<DBPathOrEmptyString>" }
Ex: See SFRPG ruleset for custom sidebar button example (DesktopSFRPG script)
Remove old sidebar tool button graphics references/files (button_ct, button_color, etc.)
D66 support
Add global script to register D66 handling
<script name="D66Support">function onInit() DiceManager.addDefaultD66Handling(); end</script>
Add "d60" and "d66" dice assets
<customdie name="d66"><model>d6</model><menuicon>d66icon</menuicon></customdie>
<customdie name="d60"><model>d6</model><script>function onValue(result) return DiceManager.onD60ResultValue(result); end</script></customdie>
Remove custom TableManager overrides (if any)
New house rule support
Once currency/encumbrance tied to built-in system, remove any coin weight options and encumbrance calculations.
Remove any diagonal distance measurement option, since it's built into CoreRPG layer now.