2.2.0 Feature: Ruleset Extensions

[Goblin-King]

The latest update includes the support for ruleset extensions. These are technically similar to basic ruleset files. The difference is that you can activate them on top of an existing ruleset based on your needs and what is available.

Like rulesets, all extensions are activated by the host and are selected when the campaign is chosen. Extensions are likely to be ruleset dependent, so they might not all be available for all rulesets.

Extensions live in the "extensions" subfolder under the Fantasy Grounds II application data folder (easiest to reach though the Fantasy Grounds II start menu group). Like modules, they can be delivered as a single package with the .ext extension. Installation consists of copying the file into the aforementioned folder.

This is a complex feature that is impossible to test for all possible configurations of custom rulesets and usage scenarios. We'd like to ask you to keep that in mind when working with extensions. Please back up your campaigns before making extensive use of extensions in running campaigns with important data.

For development, you can also create new extensions by creating a new folder in the extension directory and placing any files in there. This is convenient when you're developing one and do not want to perform the packaging each time you make a change. There will be further documentation about this in the Ruleset Modification Guide in the library on the site, and I'll post a notification on this thread once that is ready. Ruleset reloads will reload any active extensions as well.

For those of you eager to start experimenting on your own, attached is a very basic example extension that creates a rudimentary sheet allowing inputting of town data, compatible with the d20 ruleset. It is available both as the .ext file (town_packed.zip) and as separate source files (town_source.zip).

Please post any questions and discussion below. I will probably not answer questions that are covered in the upcoming documentation.

Extension friendliness in rulesets

A word must be said about the topic of rulesets and extensibility using this new feature.

Many current rulesets have been designed around the idea that everything the user wants to do is included in the core ruleset files. Making an extension that alters something may break another extension relying on the particular feature being the same it is in the core ruleset.

There is a mechanism available that allows extensions to create dependency relationships between each other, and a particular ruleset version. This may help in some cases. Another option is redesigning parts of the rulesets themselves to be modular, based on templates and equipped with scripting functionality that allows extensions to hook into the core functionality of the ruleset. The d20 ruleset was modified to provide something like this for desktop icons (see desktopmanager.lua).

Our future improvements to any rulesets will probably address this issue, at least to some extent, but we'd be happy to read discussion about this topic to see if there are any ideas you may have about particular areas where you'd like to see stronger extensibility support.

[Oberoten]

Okay. With fully updated FG, I still can't get the Extensions to load or even show up.

The subfolders name should be extensions, right? A minor gripe about the update not creating this, maybe?

[Blue Haven]

Yeah, me too :( i had to create the folder myself for the ext. to work...

[Goblin-King]

I managed to replicate this on one of our test machines. It seemed to be Vista specific in that case. The d20.pak file was, for some reason, stored in the Vista VirtualStore, and kept overriding the patched file in the FG2 program folder.

If this happens, and you are on Vista, go to C:\Users\[your-user-name]\AppData\Local\VirtualStore\Program Files and delete the Fantasy Grounds II folder in that location. You should be fine after that. If not, try rerunning the update to make sure the d20.pak file under program files is ok.

The reason the extension isn't showing up is the minimum ruleset release version requirement. The overiding ruleset in VirtualStore is not satisfying this requirement.

Let me know if this solves it for you, we'll investigate the reasons behind this happening in the first place.

[Oberoten]

I managed to replicate this on one of our test machines. It seemed to be Vista specific in that case. The d20.pak file was, for some reason, stored in the Vista VirtualStore, and kept overriding the patched file in the FG2 program folder.

If this happens, and you are on Vista, go to C:\Users\[your-user-name]\AppData\Local\VirtualStore\Program Files and delete the Fantasy Grounds II folder in that location. You should be fine after that. If not, try rerunning the update to make sure the d20.pak file under program files is ok.

The reason the extension isn't showing up is the minimum ruleset release version requirement. The overiding ruleset in VirtualStore is not satisfying this requirement.

Let me know if this solves it for you, we'll investigate the reasons behind this happening in the first place.


Eh... I am running XP and I also created the folders by hand. Still no dice so to say.

[Goblin-King]

Eh... I am running XP and I also created the folders by hand. Still no dice so to say.
The first thing to try would be to remove the <minrelease>12</minrelease> line in the extension.xml file and see if this brings it up on the list. If this doesn't work, could you run the d20unpak utility, and check the base.xml file generated in the examples/rulesets/d20 folder, see if its <root> element has an attribute release="12". If you can't see one, your d20.pak isn't updating properly for some reason.

[nezzir]

So, is the code that supports this in the .exe upgrade, or spread out in the scripts and xml? I edited the source and replaced 'd20' with 'my ruleset name', zipped it, then renamed it to .ext and copied it to the dir (with the sample that does work in d20). It didn't show.

Edit: I was posting when you wrote the above post. If I do that, it shows in the list, but does nothing in game.

Can you make the
<ruleset>
<name>WFRP2</name>
</ruleset>
blank, or leave it out or something and make it generic to all rulesets?

[Goblin-King]

So, is the code that supports this in the .exe upgrade, or spread out in the scripts and xml? I edited the source and replaced 'd20' with 'my ruleset name', zipped it, then renamed it to .ext and copied it to the dir (with the sample that does work in d20). It didn't show.
It's in the program upgrade. What you did should work, even if it didn't actually do anything really once you start up. If you didn't remove the <minrelease> element when you did the edit, it would not work (because the ruleset probably doesn't include a release attribute).

Edit: I was writing when you were editing... yes you can leave it out and make it generic. Creating something that would look decent with all the various graphic and naming schemes present in different rulesets would be a challenge, but it could be an option for a general purpose script library for example.

[nezzir]

Yeah, I'm getting a console error. I think there may be some code needed from d20:

Script Error: [string "towninit]:1: attempt to index global 'DesktopManager' [a nil value]

I've changed the ruleset/name variable to match my ruleset and deleted the minirelease section.

[joshuha]

There is a mechanism available that allows extensions to create dependency relationships between each other, and a particular ruleset version. This may help in some cases. Another option is redesigning parts of the rulesets themselves to be modular, based on templates and equipped with scripting functionality that allows extensions to hook into the core functionality of the ruleset. The d20 ruleset was modified to provide something like this for desktop icons (see desktopmanager.lua).

Nezzir according to the above the desktop manager is now different than in the base d20 ruleset. This file needs to be rolled into your ruleset (and maybe other supporting XMLs) to get the example to work.

[nezzir]

Nezzir according to the above the desktop manager is now different than in the base d20 ruleset. This file needs to be rolled into your ruleset (and maybe other supporting XMLs) to get the example to work.

Thanks, I was afraid of that. I really wish I had written down the files that were changed. I'll have to to a compare or something.

[joshuha]

Thanks, I was afraid of that. I really wish I had written down the files that were changed. I'll have to to a compare or something.

https://fantasygrounds.com/forums/showpost.php?p=63168&postcount=17

[Foen]

I've just compared the files from the d20 ruleset v2.1, v2.1.1 and v2.2 to identify the differences. There are no changes between 2.1 and 2.1.1 (which we already knew) but the following changes have been made in v2.2:



adventure_items.xml
+433 identifyUpdated();

base.xml
~18 <root version="2.0" release="12">
+41 <script name="DesktopManager" file="scripts/desktopmanager.lua" />
+42 <script name="d20desktop" file="scripts/d20desktop.lua" />

desktop_classes.xml
Added a script block to the three window classes gmshortcuts, playershortcuts and localshortcuts:
<script>
function onInit()
DesktopManager.registerContainerWindow(self);
end
</script>
Deleted everything between the sheetdata tags in gmshortcuts, and commented it out in playershortcuts and localshortcuts.

desktop_templates.xml
+66
+67 <template name="desktop_stackitem">
+68 <windowreferencecontrol>
+69 <bounds>0,0,47,27</bounds>
+70 <nodrag />
+71 <closetoggle />
+72 </windowreferencecontrol>
+73 </template>
+74
+75 <template name="desktop_dockitem">
+76 <windowreferencecontrol>
+77 <bounds>0,0,91,86</bounds>
+78 <nodrag />
+79 <closetoggle />
+80 </windowreferencecontrol>
+81 </template>

utility.xml
~173 <scrollercontrol>
~174 <bounds>-98,-60,45,27</bounds>
~180 </scrollercontrol>
~282 <scrollercontrol>
~283 <bounds>-98,-60,45,27</bounds>
~289 </scrollercontrol>

frames/chatbox.png
Replaced the frame image with a clearer one.

scripts/charsheet_skilllist.lua
~64 local unspentnode = window.getDatabaseNode().getChild("skillpoints.unspent");

scripts/combattracker_entry.lua
Replaced line 309 with:
~309 local imageinstance = token.populateFromImageNode(entry.tokenrefnode, entry.tokenrefid);
+310 if imageinstance then
+311 token.acquireReference(imageinstance);
+312 else
+313 token.setPrototype(entry.token);
+314 end

scripts/d20desktop.lua
New script file.

scripts/desktopmanager.lua
New script file.

scripts/library_booklist.lua
~77 return w1.name.getValue() > w2.name.getValue();
~80 return category1 > category2;


A number of these changes are bug fixes, but base.xml, desktop_classes.xml and desktop_templates.xml add the new functionality, along with the two new script files, d20desktop.lua and desktopmanager.lua.

Stuart

[Oberoten]

The first thing to try would be to remove the <minrelease>12</minrelease> line in the extension.xml file and see if this brings it up on the list. If this doesn't work, could you run the d20unpak utility, and check the base.xml file generated in the examples/rulesets/d20 folder, see if its <root> element has an attribute release="12". If you can't see one, your d20.pak isn't updating properly for some reason.

The Pak files contains release="12" and even the D20 set can't open properly.

The one thing I see here that could affect this is that due to the wisdom of Windows i have my application data folder on D: instead of C:.

But since my ruleset works as it should, I am still pretty happy and will just have to live without extensions until there comes along something that fixes it.

- Obe

[Spyke]

I've just compared the files from the d20 ruleset v2.1, v2.1.1 and v2.2 to identify the differences. There are no changes between 2.1 and 2.1.1 (which we already knew) but the following changes have been made in v2.2 ...Hey, many thanks Stuart. You've just saved me my first job of the day! :)

Spyke

[Foen]

NP! The d20 ruleset changes are not backwards-compatible, as it seems desktopmanager.lua doesn't work in 2.1.1, so you'll need to upgrade to 2.2 if you want to run 2.2 rulesets.

Cheers

Stuart

[Oberoten]

Has anyone managed to get more than one extension to load at a time?

[Oberoten]

Has anyone managed to get more than one extension to load at a time?

Eh nevermind my dumbness of the day. I just saw the error, need to make a separate init-script with a DIFFERENT name than the default.

Now have both covenants and lightsabers as extensions depending on what kind of campaign I will run.

Nice. I love this option.

- Obe

[Goblin-King]

The documentation is up, here (https://www.fantasygrounds.com/modguide/extensions.xcp).

[Oberoten]

Perfect. *rubs hands in glee*

[Foen]

Thanks Tero, very helpful. I was wondering about the ruleset tag and whether it could be omitted to enable universal compatibility.

As an aside, it would be handy to have exclusions (negative dependencies) so that only one of several extensions may be loaded at any time. As an example, I am hoping to use extensions to make the Call of Cthulhu base ruleset extendible to different eras (1890s, Dark Ages, Modern) and it wouldn't make sense to allow more than one of them to be loaded. The same would be true of campaign-specific extensions to the base d20 ruleset (say).

Perhaps that could be implemented as a named group, so that only one of a group could be selected (eg a group such as CoCEra, or d20Campaign)?

Just a thought.

Stuart

[Goblin-King]

Thanks Tero, very helpful. I was wondering about the ruleset tag and whether it could be omitted to enable universal compatibility.
Yes: "If no ruleset dependencies are declared, the extension is usable with all rulesets."


As an aside, it would be handy to have exclusions (negative dependencies) so that only one of several extensions may be loaded at any time. As an example, I am hoping to use extensions to make the Call of Cthulhu base ruleset extendible to different eras (1890s, Dark Ages, Modern) and it wouldn't make sense to allow more than one of them to be loaded. The same would be true of campaign-specific extensions to the base d20 ruleset (say).

Perhaps that could be implemented as a named group, so that only one of a group could be selected (eg a group such as CoCEra, or d20Campaign)?
Great idea. Will be in the next update. If you want to prepare, it's an element called exclusiongroup under properties, containing a simple string. Two extensions with the same value can't be loaded at once, and one extension can belong to multiple exclusion groups by defining several of the elements.

[Oberoten]

A point not mentioned in the reference though... If I have the extension on the clients computer before we start a campaign, would he/she have to re-download it again for every new campaign or every time I switch?

[Goblin-King]

A point not mentioned in the reference though... If I have the extension on the clients computer before we start a campaign, would he/she have to re-download it again for every new campaign or every time I switch?

All extensions are downloaded from the host into the client cache. The operation is similar to shared data in modules.

I have a mental note in my head to see how the adoption of the extension system progresses, and then have a think if a general trend would benefit from some other mechanism.

[Oberoten]

Admittedly with some rulesets being rather heavy it'd be a boon if we could send out extensions to the players before of the time, especially witht the bandwith issues of dissapearing tokens and all being what they are.

[Doswelk]

Admittedly with some rulesets being rather heavy it'd be a boon if we could send out extensions to the players before of the time, especially witht the bandwith issues of dissapearing tokens and all being what they are.

The way I get around that is launch the GM client twice on the same PC:

Launch FGII and host game once game has finished loading start a Player session and connect to localhost.

This kicks off a file copy of the cache, once the copy is finished I upload to my webspace and the users download and create the required folders and place the cache file in there.

[Dragkun]

I think I found a little gotcha... when dealing with scripts and extensions

When I declare a script in a extension with the script file in a sub folder within the extension file:


<script name="GmIdentityManager" file="scripts/gmidentitymanager.lua" />

Every works perfectly, the issue arrives when I attach a script file to an object:


<windowclass name="identitylist">
<sizelimits>
<minimum>
<height>20</height>
</minimum>
</sizelimits>
<sheetdata>
<genericcontrol name="anchor">
<bounds>0,0,1,1</bounds>
</genericcontrol>
</sheetdata>
<script file="scripts/identitylist.lua" />
</windowclass>

Placing the script file in the sub folder of the extension doesn't work, I get an error:


[17.09.2008 09:12] Ruleset Warning: Could not load script file scripts/identitylist.lua

However placing that script file in the main ruleset's scripts folder resolves the problem.

[Foen]

As another thought, it would be nice to be able to iterate over the loaded extensions from within Lua, just like the Module.getModules() method, but also giving a handle from which extension methods could be invoked.

Cheers, and just to say the new feature is fab!

Stuart

[demonsbane]

(...)
Let me know if this solves it for you, we'll investigate the reasons behind this happening in the first place.

Hi, Goblin-King:

After patching to version 2.2.0, I don't see any "extensions" folder in my App Data Folder. I'm running FG 2 in Vista, but I don't have anything of this app stored in C:\Users\[user]\AppData\Local\VirtualStore\Program Files. I updated the application again for no result, either.

Currently, I can't use these extension files nor make them to show for selecting it. I tried to make this work manually making an "extensions" folder, but it doesn't work in that way.

Any hint about what can be happening here?

[Oberoten]

For me, it was uninstalling and reinstalling FG entirely AND removing the registry keys. (Caused by having had FG1 installed at the same time I think. )

[Griogre]

Hi, Goblin-King:

After patching to version 2.2.0, I don't see any "extensions" folder in my App Data Folder. I'm running FG 2 in Vista, but I don't have anything of this app stored in C:\Users\[user]\AppData\Local\VirtualStore\Program Files. I updated the application again for no result, either.

Currently, I can't use these extension files nor make them to show for selecting it. I tried to make this work manually making an "extensions" folder, but it doesn't work in that way.

Any hint about what can be happening here?
If you installed correctly you *should not* have anything in the Virtual Store. Only non Vista compliant programs end up on the virtual store.

Look in C:\Users\[user]\AppData\Roaming\Fantasy Grounds II. You may need to create the extentions folder yourself.

[demonsbane]

If you installed correctly you *should not* have anything in the Virtual Store. Only non Vista compliant programs end up on the virtual store.

Yes. I mentioned not having anything in that folder for discarding that as one of the possible errors.


Look in C:\Users\[user]\AppData\Roaming\Fantasy Grounds II. You may need to create the extentions folder yourself.

Finally, having an Oberoten's skin (a Sci-Fi one) at hand (thanks), I have created again that "extensions" folder, and I now it works having that .ext file inside.

But I wonder why the extensions folder wasn't created in first place with the last update.

Regards

[Talen]

I'm running an XP machine and similarly, do do not see the extensions folder as described. Given my programming limitations, I'm inclined to avoid rooting throught the possible solutions described here if the next patch update addresses the issue...I'm assuming that's likely to happen?

[Griogre]

If you don't have any extentions there is no reason for the program to create an extention folder, so it doesn't.

Talen on XP the path is different. You can be sure you are in the right place by press the Start button -> All Programs -> Fantasy Grounds II -> Application Data Folder. Create the extensions folder there and then drop in your extentions.

[Talen]

I can find the directory it should be in...thought I understood from earlier posts that the directory should have be created with the patch and when it wasnt I thought tehre was an error. If thats not the case, all is well.