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.
January 2026
Updates To Be Made (Chat)
The chat workflow has changed substantially to support token/image based chat.
If any code has been modified from CoreRPG which affects chat behavior, it will be impacted by this change.
Updates to Be Made (Overlay FX)
To trigger the overlay FX for attack/damage/save rolls, additional calls need to be added to the ruleset in the appropriate places.
Attack
See scripts/manager_action_attack.lua in 5E ruleset, specifically call to GameManager.callEventFunctions("onAttackPostResolve", rSource, rTarget, rRoll);
Damage
See scripts/manager_action_damage.lua in 5E ruleset, specifically call to GameManager.callEventFunctions("onDamagePostResolve", rSource, rTarget, rRoll);
Save
See scripts/manager_action_save.lua in 5E ruleset, specifically call to GameManager.callEventFunctions("onSavePostResolve", rSource, rOrigin, rAction);
Updates to Be Made (Links)
Each link in UI and for images is customized on a per record type basis in CoreRPG and base rulesets.
If a link is not defined for a custom record type, then the default link graphic will be used.
Each ruleset will need to create the linksettings rules to define mapping of custom record type display window classes to the appropriate graphics. We highly recommend matching to the sidebar graphics, and using the copy parameter to pull from CoreRPG base/extra graphics like 5E example.
Please see gameelements.xml in CoreRPG and 5E for an example of the base link graphics defined for each window class type.
Updates to Be Made (Auto Load)
Script support for auto-loading modules for GMs/players was added.
If auto-loading is not desired, there is nothing to do.
We highly recommend limiting the number of modules included in the auto-load to ensure performance for ruleset users.
To ensure that existing campaigns will not be affected, we highly recommend that you add a version change to the code, and add the autoload disable flag to older campaigns.
See scripts/manager_version2.lua script in 5E ruleset for example of calling CampaignSetupManager.disableAutoLoad(); and don’t forget to change version in base.xml to match.
For new campaigns, you can define a number of rules to automatically load modules for GM and set auto-load for players. We highly recommend only doing this for “Core Rules” for each system.
See scripts/data_desktop_5E.lua in 5E ruleset for example of setting up autoload rules.
If a key is specified, then the first matching rule will override and auto-load later.
If no key is specified, then the module will load when it becomes available.
If playerload is specified, those modules will be set to auto-load for the player.
Updates To Be Made (Misc)
Migrations
Desktop.addDataModuleSet(k, v2) -> CampaignSetupManager.addModuleSetsByMode
See scripts/data_desktop_5E.lua in 5E ruleset for example
August, 2025
NOTE: This ruleset update continues the push to standardize user interface/experience, as well as making theming for ruleset creation and extensions much easier long term.
Overview
Review all subsections below.
All themes should pay special attention these linked guidelines.
Updates To Be Made (Dice)
If any code has been modified from CoreRPG which affects onDiceLaunched or onDiceLanded events, you will need to update your code to mimic CoreRPG behaviors to work with the new dice functionality in v4.8.0.
Updates To Be Made (Misc)
Migrations
UtilityManager.getTopWindow → WindowManager.getTopWindow
UtilityManager.getWindowDatabasePath → WindowManager.getDatabasePath
UtilityManager.safeDeleteWindow → WindowManager.safeDelete
Deprecated objects
Templates
anchor_listitem_column_right, button_listitem_column_delete, button_record_locked, link_listitem_column, linkcontrol_static, linkfield_statich, string_listitem_column_name, string_listitem_center_text, string_listitem_right_text, string_textlistitem
button_masterindexitem_idelete, masterindexcategory_idelete
button_activateid, button_charweaponcarried, number_charinv, string_charinvname, string_charinvloc
anchor_listitem_left_encounter, number_listitem_count_encounter, string_listitem_expr_encounterrandom, string_listitem_name_encounter, token_listitem_encounter
button_parcel_id_all, number_parcel, string_parcel
button_setup_column_help
Scripts
ReferenceManualManager
Deleted objects (previously deprecated)
Icons
button_close, button_close_down, button_close_hover, button_help, button_help_down, button_help_hover
Templates
anchor_title_charsheet, anchor_title_charsheethelper, anchor_title_ctbox, button_imagewindow_sizeup, button_imagebackpanel_sizedown, button_imagebackpanel_sizeup, button_imagefullpanel_sizedown, button_window_sizedown, button_window_sizedown_base, button_window_sizeup, button_window_sizeup_base, close, close_base, close_charsheet, close_charsheethelper, close_ctbox, close_imagebox, close_imagepanel, close_recordsheet, close_storybox, help, help_base, help_ctbox, help_imagebox, help_imagepanel, helper_ct,
masterindexitem_access, masterindexitem_anchor_right, masterindexitem_category, masterindexitem_idelete, masterindexitem_link, masterindexitem_modified, masterindexitem_name, masterindexitem_owner, masterindexitem_link_id,
anchor_record_header_right, anchor_record_image_header_right, button_ichat, button_record_activateid, frame_record, frame_record_content, frame_record_content_tabbed, frame_story_content, ft_record, icon_record_locked, label_recordtype, link_record_header, spacer_recordtype, string_record_name, string_record_name_id, string_record_name_image, string_record_name_npc, string_record_name_ref, string_record_name_story, story_page_next, story_page_prev, story_page_top, sub_record_header, portrait_char, scrollbar_record, sub_charsheet, sub_charsheet_overview, subwindow_record, token_char, token_record_header
anchor_ct_client_label_right, anchor_ct_host_label_right, anchor_ct_label_right, anchor_ctbox_client_header, anchor_ctbox_host_header, button_ct_endturn, button_ct_faction_foe, button_ct_faction_friend, button_ct_faction_neutral, button_ct_friendfoe, button_ct_menu, button_ct_nextactor, button_ct_nextround, button_ct_nextround_base, button_ct_nextturn_base, button_ct_setactive, button_ctbox_host_header_visibility, frame_ct, frame_ctbox_host_header_visibility, label_ct, label_ct_client_rounds, label_ct_header_init, label_ct_header_name, label_ct_host_rounds, label_ct_right, list_ctbox_client, list_ctbox_host, number_ct_client_rounds, number_ct_host_rounds, spacer_ct_client_header_buttons, spacer_ct_host_header_buttons
button_folder_image, button_folder_sm, list_utility
Window Classes
record_header_simple
Affected Rulesets
[Dolmenwood], [SotDL],
April, 2025
NOTE: This ruleset update continues the push to standardize user interface/experience, as well as making theming for ruleset creation and extensions much easier long term.
Overview
Review all subsections below.
All themes should pay special attention these linked guidelines.
Updates To Be Made (Character Sheet Specific)
New window assets to copy for Character Sheet Overview section (i.e. top part with name and pictures)
charsheet_overview_base_v2 - For standard character sheets using underlabels
charsheet_overview_base_alt - For character sheets using top label “plates” (such as 5E)
Review character sheet locking capabilities to avoid player accidental changes
Make sure to consider whether something should only be changed in “unlocked” mode vs. “play” (unlocked) mode. (i.e. ammunition, carried weapon, power usage, etc.)
See D&D rulesets for examples
Updates To Be Made (Misc)
Standardize delete/link buttons on the left of all list items
Migration
button_idelete/button_listitem_idelete -> button_listitem_idelete_left
genericcontrol name="rightanchor" -> anchor_listitem_right_sm/anchor_listitem_right
anchor_listitem_column_right -> anchor_listitem_right_sm
button_listitem_column_delete -> button_listitem_idelete_left
link_listitem_column -> link_listitem_left
string_listitem_column_name -> string_listitem_center_bold
Affected Rulesets
[SotDL],
Standardize tags used for roll types (such as attack/damage/effect tags)
String Resources:
action_ability_tag, action_attack_tag, action_cast_tag, action_check_tag, action_damage_tag, action_effect_tag, action_heal_tag, action_init_tag, action_save_tag, action_savevs_tag, action_skill_tag
Many examples in CoreRPG, 5E and other included rulesets
Standard language fonts moved to CoreRPG (Celestial, Draconic, Dwarven, Elven, Infernal, Primordial)
Remove duplicates from rulesets inheriting from CoreRPG
[SotDL],
Retire ActorManager.getTypeAndNode and ActorManager.getTypeAndNodeName
Instead, use ActorManager.isPC, ActorManager.isRecordType, ActorManager.getCreatureNode and ActorManager.getCTNode
Retire “radial” menu settings
Remove menusettings.radial
Remove tooltip.radial
Remove icons - menubackground/menuhub/menuback
February, 2025
NOTE: This ruleset update is part of a larger push to standardize UI frames, fields and menus for consistency for users, as well as making theming for ruleset creation and extensions much easier long term.
Overview
Review all subsections below.
All themes should pay special attention to the Top Level Windows section in the guidelines linked below.
Updates To Be Made (Character Sheet Specific)
New window assets to copy for Character Sheet Overview section (i.e. top part with name and pictures)
charsheet_overview_base_v2 - For standard character sheets using underlabels
charsheet_overview_base_alt - For character sheets using top label “plates” (such as 5E)
Updates To Be Made (Misc)
Standard language fonts moved to CoreRPG (Celestial, Draconic, Dwarven, Elven, Infernal, Primordial)
Remove duplicates from rulesets inheriting from CoreRPG
[SotDL],
December, 2024
NOTE: This ruleset update is part of a larger push to standardize UI frames, fields and menus 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 identified 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)
Frame Migration: charsheet, charsheethelper
Migrate windows to use top-level window usage guidelines for these frames.
If these frames are used for windows not related to character sheets, migrate those windows to the correct top-level frame based on the guidelines.
Search for any windows using those frames; and specify the new top-level templates and rebuild using the new layout templates.
See specific implementation below for Character Sheet (and Mini Character Sheet)
Frame Layout Templates
Use CoreRPG definitions as starting point
Add or update the following templates (only if charsheet frame overriden)
windowmenubar_charsheet, anchor_content_charsheet_top, anchor_content_charsheet_tabbed_top, anchor_content_charsheet_bottom,
Add or update the following templates (only if charsheethelper frame overriden)
windowtitlebar_charsheethelper, windowmenubar_charsheethelper, anchor_content_charsheethelper_top, anchor_content_charsheethelper_bottom,
Remove old templates (see below)
Misc Cleanup
Remove assets no longer used. (see below)
Remove direct “power_action_editor” references; use button_poweractioneditor.
Remove direct color setting for errors/overages:
Ex: setColor("FF0000"), setColor("#FF0000")
Use setColor(ColorManager.getUIColor("field_error")), setColor(nil)
Character Sheet Specific
Redefined “charsheet” window class, using copy=”charsheet_base” and define tabs/scripts.
<windowclass name="charsheet" copy="charsheet_base"> <tab> <name>main</name> <resource>tab_main</resource> <class>charsheet_main</class> </tab> <tab merge="add"> <name>abilities</name> <resource>tab_abilities</resource> <class>charsheet_abilities</class> </tab> <tab merge="add"> <name>inventory</name> <resource>tab_inventory</resource> <class>charsheet_inventory</class> </tab> <tab merge="add"> <name>notes</name> <resource>tab_notes</resource> <class>charsheet_notes</class> </tab> </windowclass> <windowclass name="charsheet_overview" copy="charsheet_overview_base" />If onInit override in window class script, then add super.onInit; or WindowTabManager.populate(self).
Fix internal sub-sheets (Ex: charsheet_main, charsheet_notes, etc.) to remove extra space required from previous layouts that is now automatically handled.
Mini Character Sheet Specific
Add following script call to a global script, such as CharManager or GameSystem.
WindowMenuManager.initCharMinisheetSupport();
Define “charsheetmini” window class, and use copy=”charsheet_base” and define tabs/scripts
<windowclass name="charsheetmini" copy="charsheet_base"> <sizelimits> <minimum width="450" height="495" /> </sizelimits> <tab> <name>main</name> <resource>tab_main</resource> <class>charsheetmini_main</class> </tab> <tab merge="add"> <name>abilities</name> <resource>tab_abilities</resource> <class>charsheetmini_abilities</class> </tab> <tab merge="add"> <name>inventory</name> <resource>tab_inventory</resource> <class>charsheetmini_inventory</class> </tab> <tab merge="add"> <name>actions</name> <resource>tab_actions</resource> <class>charsheetmini_actions</class> </tab> <minisheet /> <script file="campaign/scripts/char.lua" /> <sheetdata> <sub_content_top name="overview"> <class>charsheetmini_overview</class> </sub_content_top> </sheetdata> </windowclass> <windowclass name="charsheetmini_overview" copy="charsheet_overview_base" />If onInit override in window class script, then add super.onInit; or WindowTabManager.populate(self).
Fix internal sub-sheets (Ex: charsheet_main, charsheet_notes, etc.) to remove extra space required from previous layouts that is now automatically handled.
Assets Removed
Templates
button_charactivate, sub_charsheet, sub_charsheet_overview,
close_charsheet, close_charsheethelper, anchor_title_charsheethelper,
button_charmini, button_charfull,
Strings
char_label_minisheet, char_label_fullsheet,
August, 2024
NOTE: This ruleset update is part of a larger push to standardize UI frames, fields and menus 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 identified 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)
Add support for NPC dice
If Type support desired, then register types and type resolution function.
Register system-level name rules, if any.
Migrate windows to use top-level window usage guidelines for these frames: ctbox
If these frames are used for other window types, migrate those windows to the correct top-level frame based on the guidelines.
Search for any windows using those frames; and specify the new top-level templates and rebuild using the new layout templates.
Review any overrides to the following scripts:
LibraryData, ItemManager
Remove unidentified field in body of record (Moved to header) (Items, NPCs, Vehicles)
See CoreRPG for example (i.e. nonid_name field)
Add pictures tab to records that support pictures (Items, NPCs, Vehicles)
See CoreRPG for example
Migrate master index overrides to use latest templates
See CoreRPG for example
Review usage of “mini_name” frame
Will be primarily used for character names on desktop/tokens now
Any usage for widgets or in other places should consider using “tempmodmini” or “fieldlight” frames instead.
Misc asset cleanup
Remove assets no longer used
Updates To Be Made (Specific) [SotDL]
Combat tracker migration
Migration to new top-level templates: [SotDL]
Remove nonid_name field in record body
Add record pictures tab
[SotDL (Item), ]
Migrate master index overrides to use latest templates
Misc asset cleanup
Frames: calendarmonthentry, calendarselectentry, charselectentry, moduleselectentry, partysheetentry
[SotDL, ]
Assets Updated
Templates
string_clientct_name, string_ct_entry_name, token_ctentry_base,
Assets Removed
Icons
button_menu, button_menu_down, ct_reach, ct_space, power_use, window_resize_filled,
Frames
referencepage,
Templates
frame_record_content, frame_record_content_tabbed
masterindexitem_access, masterindexitem_anchor_right, masterindexitem_category, masterindexitem_idelete, masterindexitem_link, masterindexitem_link_id, masterindexitem_modified, masterindexitem_name, masterindexitem_owner,
anchor_ct_client_label_right, anchor_ct_host_label_right, anchor_ct_label_right, anchor_ctbox_client_header, anchor_ctbox_host_header, anchor_title_ctbox, button_ct_endturn, button_ct_faction_friend, button_ct_faction_foe, button_ct_faction_neutral, button_ct_friendfoe, button_ct_menu, button_ct_nextactor, button_ct_nextround, button_ct_nextround_base, button_ct_nextturn_base, button_ct_setactive, button_ctbox_host_header_visibility, close_ctbox, frame_ct, frame_ctbox_host_header_visibility, help_ctbox, helper_ct, label_ct, label_ct_client_rounds, label_ct_header_init, label_ct_header_name, label_ct_host_rounds, label_ct_right, list_ctbox_client, list_ctbox_host, number_ct_client_rounds, number_ct_host_rounds, spacer_ct_client_header_buttons, spacer_ct_host_header_buttons,
March, 2024
NOTE: This ruleset update is part of a larger push to standardize UI frames, fields and menus 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 identified 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: recordsheet, imagebox, storybox,
If frames used for other window types, migrate those windows to the correct top-level frame based on the guidelines.
Search for any windows using those frames; and specify the new top-level templates and rebuild using the new layout templates.
Search for any windows using “record_window*” or “record_header*” copied window classes, and make sure overrides work correctly.
Add icon for window menu link (window_toolbar_link)
Image toolbar has been completely reworked.
See imagewindow_toolbar window class and ImageManager script for new button registrations and templates.
Updates To Be Made (Specific) [SDL]
SDL - Remove
Frames
frame_story_content, referencepage,
Templates
close_recordsheet, close_storybox,
SDL - Review
General
Review all window classes using recordsheet/storybox frame (See CoreRPG implementations)
Review all window classes inheriting from record_window* or record_header* (See CoreRPG implementations)
Add button_toolbar_link icon
Window Classes
ct_entry (link token3Dflat or call base link function), item, npc
Assets Removed
Fonts
npcsheet_header
Frames
campaigncontrolframe, imagebox_header, whitecontrolarea, windowhandle,
Icons
button_collapse, button_collapse_w, button_expand, button_expand_w, button_scrollerpan, button_scrollerpan_down, button_sizedown, button_sizedown_down, button_sizedown_hover, button_sizeup, button_sizeup_down, button_sizeup_hover, button_zoomer, button_zoomer_down, button_zoomin, button_zoomin_down, button_zoomout, button_zoomout_down, tool_down_30, tool_left_30, tool_lock_closed, tool_lock_open, tool_minus_30, tool_plus_30, tool_right_30, tool_up_30,
Script Functions
GameSystem.getCharSelectDetailLocal
Templates
anchor_ctentry_right, area_parcel_content, button_ctentry_activateactive, button_ctentry_activateattributes, button_ctentry_activatedefensive, button_ctentry_activateeffects, button_ctentry_activatespacing, button_ctentry_activatetargeting, button_ctentry_idelete, button_ctentry_isidentified, button_ctentry_tokenvis, button_ctsection_effect_iadd, button_record_isidentified_image, button_record_toolbar, button_window_sizedown, button_window_sizedown_base, button_window_sizeup, button_window_sizeup_base, frame_ctsection_effect, frame_ctsection_spacing, frame_ctsection_targeting, frame_ctsub, frame_parcel, frame_record_lower, frame_refmanualpage_content, handle_record, handle_record_tabbed, helper_imagepanel, icon_clientctsection_effect, icon_ctsection, icon_ctsection_effect, icon_ctsection_spacing, icon_ctsection_targeting, image_toolbar_anchor, image_toolbar_button_deathmarkerclear, image_toolbar_draw, image_toolbar_mode_select, image_toolbar_mode_targetselect, image_toolbar_mode_unmask, image_toolbar_button_zoomtofit, image_toolbar_targeting, image_toolbar_toggle_grid, image_toolbar_toggle_lock, image_toolbar_toggle_preview, image_toolbar_toggle_shortcut, image_toolbar_toggle_tokenlock, imagepanel_record, imagepaneldata_record, label_ctentry_reach, label_ctentry_space, link_ctentry, link_story, list_ctsection_effect, number_ctentry_reach, number_ctentry_space, spacer_clientctsection_effect, story_page_top, story_page_prev, story_page_next, string_ctentry_effects, string_ctname, string_ctname_nonid, string_record_name_ref, sub_ctsection_targeting, sub_note_header, toolbar_button_color_base,
Window Classes
ref_text_header,
Assets Removed (Previously Deprecated with Warnings)
Templates
anchor_ctentry_right, button_ctentry_activateactive, button_ctentry_activatedefensive, button_ctentry_activateeffects, button_ctentry_activatespacing, button_ctentry_activatetargeting, button_ctentry_idelete, button_ctentry_isidentified, button_ctentry_tokenvis, button_ctsection_effect_iadd, frame_ctsection_effect, frame_ctsection_spacing, frame_ctsection_targeting, frame_ctsub, icon_clientctsection_effect, icon_ctsection, icon_ctsection_effect, icon_ctsection_spacing, icon_ctsection_targeting, label_ctentry_reach, label_ctentry_space, link_ctentry, list_ctsection_effect, number_ctentry_reach, number_ctentry_space, spacer_clientctsection_effect, string_ctentry_effects, string_ctname, string_ctname_nonid, sub_ctsection_targeting,
Window Classes
ct_targets,
Assets Deprecated
Templates
button_imagebackpanel_sizedown, button_imagebackpanel_sizeup, button_imagefullpanel_sizedown, button_imagewindow_sizeup, close_imagebox, close_imagepanel, close_recordsheet, close_storybox, frame_record, frame_story_content, help_imagebox, help_imagepanel, icon_record_locked, label_recordtype, link_record_header, spacer_recordtype, string_record_name_id, sub_record_header,
Assets (Review Usage)
Templates
string_record_name, string_record_name_image, string_record_name_story,
Window Classes
power_stats (-> power_main), quest_stats (-> quest_main),
December, 2023
NOTE: This ruleset update is part of a larger push to standardize UI frames, fields and menus for consistency for users, as well as making theming for ruleset creation and extensions much easier long term.
Overview
Review all subsections below.