Core RPG Ruleset Architecture

[LordEntrails]

This is a work in progress. When it becomes mature enough, we can see about having it added to the wiki if appropriate.

Please take a look and see if the way that I am laying this out, the notation, syntax and verbiage I'm using makes sense. I'm not a software developer, so when I refer to a "function", maybe that's not the right word I should use. Also, maybe their is a better or more standard notation that I should be using. Plus, I probably have some of the descriptions wrong. I'm working off of a very limited knowledge of the FG architecture.

Please comment and jump in anywhere. I've pasted the text below, could not attached the rtf file that I'm working in.

CoreRPG Architecture
This is intended as a dissection of the existing CoreRPG Ruleset for developers to use when developing custom extensions or other rulesets.


The structure of this document mimics the file and object structure of the ruleset itself. The nomenclature is as follows:
graphics/icons this is a folder with a path relatice to the base CoreRPG folder
base.xml (/graphics) this is a file in the CoreRPG/graphics folder
includefile (base.xml) this is a function or object call inside the base.xml file


The folder and file references (in parenthesis) may be excluded when talking about the function or file contained within the preceding folder or file. i.e. this document will present the structure in a hierarchical manner matching that of the actual folders and files.


CoreRPG this is the base folder in which all of the ruleset files are structured.
base.xml this is the primary declaration for what files are loaded when the ruleset is loaded.

includefile this function tells FG what xml files to load at ruleset initialization. These are usually xml files that define attributes and object.

script this function tells FG what Lua script files to load at ruleset initialization. Each script includes a name for later reference that the script can be reference by other entities. A script is a set of logical commands and code that are run against the database when executed.
gameelements.xml this is the file that defines the base tabletop settings.

die callout the position and type of dice that show up on the tabletop.

diebox ??

pollbox ??

viewerlistsettimgs ?? Displays the connected character portraits? Note that the referenced .png files do not exist, though similarly named ones do. ??

hotkeybar defines the hot bar at the bottom of the desktop

categoryselectionsettings ?? maybe this sets the icons for the hot bar??

tooltip this starts to defines the right mouse tool tip menu

distance ??

textsettings sets the color for...??
campaign this is the folder where campaign records (campaign specified storage such as stories, characters, items, etc) are specified. It also includes the CharManager script.
common this is the folder where common functions and templates such as buttons, windows, lists, records and toolbars are specified.
ct this is the folder where combat tracker functions are specified.
desktop this is the folder where the desktop window is specified and stores some scripts as well.
graphics this is the folder where the graphic definitions for fonts, frames, icons, portraits and the radial menu are specified.
ps this is the folder where the party sheet functions are specified and the scripts PartyManager and PartyLootManager.
ref this is the folder where reference templates and examples are specified.
scripts this is the folder where most of the Lua scripts are stored.
strings this is the folder where ???
utility this is the folder where the functions; calendar, options, modifiers, export, library, modules, effects, modifiers, and templates are specified.

[Trenloe]

Good job.

But.... this thread, in particular post #2, already includes most of this: https://www.fantasygrounds.com/forums/showthread.php?20651-Modifying-the-CoreRPG-ruleset

[LordEntrails]

Ahh, I see :)
I started this thread after discussion in this one, https://www.fantasygrounds.com/forums/showthread.php?25983-Definition-of-UI-Elements

No one pointed out that your thread existed. I'm also looking to go into more depth than what you did. Actually calling out the various methods and classes (right terms?) so that in most cases their would not be a need to have all the files open and then do a multi-file search in order to track down a needed set of modifications (as described as the common method in the other thread I linked.)

I'll go through the links you posted, they might help. Also been using the resources here; https://www.fantasygrounds.com/refdoc/https://www.fantasygrounds.com/modguide/windowing.xcp

Thanks Trenloe, you always have so much to share :)

[LordEntrails]

Does listing the function calls within a script file provide benefit? Such as:

manager_desktop.lua registers windows (chat), calculates window locations and docks

function registerContainerWindow(w)
function updateControls()
function registerStackShortcut(iconNormal, iconPressed, tooltipText, className, recordName)
function createFunc() createStackShortcut(iconNormal, iconPressed, tooltipText, className, recordName)
function registerStackShortcut2(iconNormal, iconPressed, sTooltipRes, className, recordName)
function createFunc() createStackShortcut(iconNormal, iconPressed, Interface.getString(sTooltipRes), className, recordName)
function createStackShortcut(iconNormal, iconPressed, tooltipText, className, recordName)
function registerDockShortcut(iconNormal, iconPressed, tooltipText, className, recordName, useSubdock)
function createFunc() createDockShortcut(iconNormal, iconPressed, tooltipText, className, recordName, useSubdock)
function registerDockShortcut2(iconNormal, iconPressed, sTooltipRes, className, recordName, useSubdock)
function createFunc() createDockShortcut(iconNormal, iconPressed, Interface.getString(sTooltipRes), className, recordName, useSubdock)
function createDockShortcut(iconNormal, iconPressed, tooltipText, className, recordName, useSubdock)
manager_dicetower.lua registers and updates the dicetower

function onInit()
function registerControl(ctrl)
function activate()
function update()
function encodeOOBFromDrag(draginfo, i, rSource)
function decodeRollFromOOB(msgOOB)
function onDrop(draginfo)
function handleDiceTower(msgOOB)

[damned]

Even though some/much of the starting info you posted is listed in the other thread continuing to improve the thread is still a good thing. Good Doco is always in demand. Good tutorials, good explanations.

[leozelig]

Listing the functions is helpful, probably not all of them need an explanation. It would be great if the FGwiki included something like this.

Strings defines all of the text labels and tooltips in the game. I think it's kept in a separate file to allow easy conversion to a non-English language.

[Trenloe]

For me, I'm not sure how helpful listing all of the functions in a file is. It ends up being one big list of names that I could get by looking in the file myself if I really wanted to. If you want to list functions, list the main ones that do some specific piece of functionality and that a developer might need to change if they were doing customizations. No need to list the ancillary/handler/init functions.

For example, for manager_dicetower.lua , onDrop is really the only function that does anything specific (the rest are just handler functions/OOB message delivery and setup functions). Even onDrop probably isn't going to be of much interest to a developer as it would be rare for this function to be customized as all of this is just pass-through of the dropped action. Perhaps just include a summary for the whole manager_dicetower.lua file, rather than list and detail each function.

EDIT: An overview approach also means that your documentation is more likely to stand the test of time - i.e. it isn't invalidated if a couple of new functions are added to a LUA file in some future update.

[ianmward]

Listing the functions is helpful, probably not all of them need an explanation. It would be great if the FGwiki included something like this.


I agree that it would be best to have this in the Wiki and be hyperlinked.
The problem is getting someone to dedicate the time long term to keep it up to date and useful.

[leozelig]

Yeah, maybe why that's why it doesn't exist :)

[LordEntrails]

For me, I'm not sure how helpful listing all of the functions in a file is. It ends up being one big list of names that I could get by looking in the file myself if I really wanted to. If you want to list functions, list the main ones that do some specific piece of functionality and that a developer might need to change if they were doing customizations. No need to list the ancillary/handler/init functions.

<SNIP>

For example, for manager_dicetower.lua , onDrop is really the only function that does anything specific (the rest are just handler functions/OOB message delivery and setup functions). Even onDrop probably isn't going to be of much interest to a developer as it would be rare for this function to be customized as all of this is just pass-through of the dropped action. Perhaps just include a summary for the whole manager_dicetower.lua file, rather than list and detail each function.

EDIT: An overview approach also means that your documentation is more likely to stand the test of time - i.e. it isn't invalidated if a couple of new functions are added to a LUA file in some future update.

That's why I'm asking. I'm not experienced enough to know what will really result in something useful. So far, it seems to me that most anything named in one of the xml files would be important. It was actually starting to look that some type of indexing on the .lua files was unnecessary, but, I wasn't sure. Though a description would be valuable.


I agree that it would be best to have this in the Wiki and be hyperlinked.
The problem is getting someone to dedicate the time long term to keep it up to date and useful.

That's why I'm starting to think about figuring out how to parse the files. I haven't used PAR5E yet, but looking to read up on it. If I could setup a parsing script and environment, then each complete ruleset could be parsed each time it is updated with minimal hassle. Someone more familiar with the wiki, or with how the mod guide is setup, might be able to comment on the feasibility of then converting this to something more than a large static document.

[Trenloe]

That's why I'm starting to think about figuring out how to parse the files. I haven't used PAR5E yet, but looking to read up on it. If I could setup a parsing script and environment, then each complete ruleset could be parsed each time it is updated with minimal hassle. Someone more familiar with the wiki, or with how the mod guide is setup, might be able to comment on the feasibility of then converting this to something more than a large static document.
I'm not sure what you're thinking about here. PAR5E is for parsing user created text files and creating FG library data modules for (primarily) use in the 5E ruleset. That's all it's designed to do.

[LordEntrails]

I only know little about par5e, but what I'm thinking is it extracts portions of text files and puts them into into differently formatted text files.

I've done a tiny bit with regex before to grab text strings out of text files and put them into other yet files. Things like extracting error messages from log files etc. If I could parse a directory oc files for one of several phases,like "<windowclass" or "<function" and then put that while line into a text file, then it could build the entire index of calls/onbjects/fumctions in a structured manner.

Is that clear enough?

[Trenloe]

Is that clear enough?
Yep, that's clear enough. But PAR5E isn't designed to do that - it's specifically for parsing for 5E (hence the name). Zeus originally had the idea that it would allow library module parsing for CoreRPG and 3.5/PF but that functionality hasn't been implemented (I doubt it ever will).

If you want to produce LUA documentation there are various projects available external to Fantasy Grounds for that. Use your chosen search engine(tm) to look for "create documentation from lua" or similar. Here's one example: https://keplerproject.github.io/luadoc/