Developer Guide - Product Guidelines

As a Community Developer of Fantasy Grounds products, you’ll want to refer to the Fantasy Grounds Community Developer email you were sent upon joining the Community Developer mailing list. It contains important procedural and login information.

To make sure you receive the developer newsletter in your inbox, set your email filter to allow "Fantasy Grounds" in the subject line.

If you have not joined the mailing list yet, please see Procedure - First Steps below.

Development - Product Image Guidelines

Here are the guidelines for images submitted in products for use in Fantasy Grounds. We have our recommended guidelines, along with Maximum thresholds that we recommend for approval of modules in our storefront. Exceptions may be granted, but there should be a specific reason and need for any exception.

Our statistics show that many users still play on small resolution laptops. Our guidelines are meant to improve the overall responsiveness of the system and to keep the displays optimal for all players and gamemasters.

File Names: Should only use simple characters (i.e. A-Za-z0-9, plus underscore and simple dash) (no apostrophes/quotes/accents/etc.). Usage of other characters can cause files not to load in some OS versions.

Supported Image File Types: WEBP, WEBM (VP8), PNG, JPG

Image File Sizes: We recommend static WEBP files at 75% quality for the best trade-off between visuals and file size (memory usage and network file transfer times). Make sure to consider overall file size when including graphic assets, especially animated assets; as file sizes add up fast. Both static PNG files and animated WEBP/WEBM files are much larger file formats, and can create slow downs if individual files or overall product size too big.

NOTE: Images should not be duplicated between GM and Player modules. If they are needed for both, you can place the image in the player module and link to it from the GM module.

Image Type

Recommended Format

Recommended Size

Notes

Image Type

Recommended Format

Recommended Size

Notes

Images
(Player Maps)

WEBP
(High Quality - 75%)

 

<= 4Kx4K pixel resolution

<= 2MB file size (static)
<= 10MB file size (animated)

Target grid size should be <100 pixels;
Break up map as needed;
Include line of sight and lighting info
()

Images
(Brushes/Stamps)

WEBP
(High Quality - 75%)

<= 100x100 pixels per grid size
(i.e. 4x4 tile = 400x400 resolution)

 

Images
(GM Maps and Others)

WEBP
(High Quality - 75%)

<= 1Kx1K pixel resolution
(For embedded reference manual images and transparent creature images)

<= 2Kx2K pixel resolution
(For images meant to be shown separately, and zoomed in on areas)

<= 1MB file size (static)
<= 5MB file size (animated)

Images that are not player maps are rarely zoomed in, and do not need higher resolutions.

 

Charts, Timelines, and images that should be zoomed in to see portions in detail

WEBP

(High Quality - 75%)

<= 2kx2k pixel resolution

<= 1MB file size (static)

<= 5MB file size (animated)

This includes charts, timelines, and other images that require portions to be zoomed in to be viewed, where 1Kx1K pixel resolution would make the text unreadable or the zoomed in image look bad.

Full Body and Tokens - Camera

WEBP

(High Quality - 75%)

<= 1kx1k pixel resolution

<= 1MB file size (static)
<= 5MB file size (animated)

These should have transparent backgrounds and be set up with height information in the .xml (see the relevant wiki page).

Portraits

WEBP
(High Quality - 75%)

<= 100x100 pixel resolution

WEBP is preferred as it allows for larger portrait resolutions and still produces smaller file sizes. Images larger than 100x100 are automatically downsized.

Tokens - Flat

WEBP
(High Quality - 75%)

 

<= 256x256 pixel resolution (Small/Medium)

<= 512x512 pixel resolution
(Large or larger)

WEBP is preferred as it allows for larger token resolutions and still produces smaller file sizes. If you use PNG format, these are still acceptable at 100x100 pixels for small and medium, and 200x200 for anything larger.

NOTE: Token - Flat tokens follow the “Tokens - Flat” specs in the table above.
Full Body and Token - Camera follow the “Full body and Camera tokens” specs.

image-20240307-232731.png

Development - Other Guidelines

Here are the other guidelines for products submitted for use in Fantasy Grounds.

  • Any text should be entered as text. No text should be part of an image with the following exceptions:

    • Text that has special characters that Fantasy Grounds doesn’t support.

    • Text with relevant image features overlayed that should be shared with players (for example a note with an image element that is a clue that the player need, such as a note with spots of slime).

    • Timelines and charts (see image sizes above for these).

  • Each product should be accompanied by 5 or more screenshots at 1920x1080 70% compressed JPG one of which should feature the cover, and the cover and Steam images (see Guidelines - Product Store Images wiki page). These should no longer be uploaded to SVN. You should upload them to your shared Dropbox folder when you turn the product in. Only turn in these images in to the shared Dropbox folder. No other files should be turned in to this location if you have access to SVN.

  • Products should be created with a Reference Manual. Story entries are no longer required.

  • Anytime a story entry or reference manual page mentions an encounter, area, NPC, or other Fantasy Grounds record, there should be a link to that record.

  • Anytime an NPC talks it should be added as boxed text with the speaker added.

  • Anytime the GM is meant to narrate it should be boxed text.

  • Every product should have a page in the reference manual and/or a story entry called “Developer Notes”. In this entry a version number and version history for the module should be included as well as any changes that were necessary from the PDF versions (such as replacing page number references with links to the content).

  • All products should be exported from Fantasy Grounds Unity.

    • Help Link -

    • Rule books should be divided between Player material and GM material modules; with the Player material exported with the “player” setting, and the GM without that setting.

    • Adventures should not be exported with the “player” setting.

    • Modules should be as optimized as possible and be below 100mb in size total. Exceptions can be made for adaptations from extremely large products on a case by case basis.

    • Tokens that are used in the module should be dragged and dropped onto the bottom of the export window to be included.

    • Requirement: The module file name should match the product ID provided by Smiteworks with a decorator as needed for multiple modules (i.e. <ProductID> GM, <ProductID> PG).

    • Requirement: The module Name field (i.e. "name" tag) should match the product ID provided by SmiteWorks with a decorator as needed for multiple modules (i.e. <ProductID> GM, <ProductID> PG).

    • Recommendation: Avoid special characters in module Display Name field to avoid possibility that specialty fonts in themes may not have those characters. (i.e. copyright, trademark, etc.).

  • Finished conversions should be run through the Conversion Checker or, for Savage Worlds products, SWEL (Savage Worlds Enhanced Library) tool. The SWEL can be found on the forums.

  • Most emails should CC Doug, except for routine product requests and turning in finished products.

Development - Helpful Tools

You can find helpful tools for development on the FG Forge:

Procedure - First Steps

If you are interested in becoming a Community Developer, you can send an email to:
Developer Relations at developerrelations@smiteworks.com or
James Holloway at jholloway@smiteworks.com

Be sure to include your name, email address and let them know that you are interested in becoming a Community Developer and joining the Community Developer mailing list.

Procedure - Signing Up To Complete a Product

The procedure is to pick a product from Adaptation List. The Adaptation List can be found in the Developer Portal.

Once you’ve selected a product, email James Holloway at jholloway@smiteworks.com

Let him know the full title and about how long you think it will take to convert. Please email James before you start the adaptation process and he will make sure that Smiteworks USA, LLC. is licensed to sell it and that it is not already claimed by another developer. To check if its claimed click the green “Show All Products” button. Then find the product in the list. Look to the right side and it will indicate whether its claimed or not. The blue “Show Only Available“ button filters out all of the products except for those that are unclaimed. When you first load the page, this is how it is filtered.

If the product is not on the list, please provide a store link or the price, ruleset, type of product, and full title as seen on the cover.

Once it’s approved, and if it’s not on the adaptation list, you can enter the product store information into the Add New Product page. The Add New Product page can be found in the Developer Portal.

Once the Store info is approved, you can begin working on the product.

When you have finished converting the product, log into the Developer Portal and click the Review button on the product’s status.

Folder Structures

When turning in products each type of file should be turned in to a specific folder. Each of these folders should be in a main folder with the same name as the product (or as close as you can get with the folder naming restrictions) plus the ruleset abbreviation. This main folder goes in the Outgoing folder.

Module files (.mod) should be in an all lowercase ‘modules’ folder. They should be extracted out as if it were zip files into a folder with the same name as the module (i.e. <main product folder>\modules\<module filename folder>\db.xml). You should then delete the module files and leave only the extracted folder and files.

Ruleset files (.pak) should be in an all lowercase ‘rulesets’ folder. They should be extracted out as if they were zip files into a folder with the same name of the ruleset (see modules above). You should then delete the pak files and leave only the extracted folder and files.

Portrait files (.ppk) should be in an all lowercase ‘portraits’ folder. They should be extracted out as if they were zip files into a folder with the same name of the Portrait Pack (see modules above). You should then delete the ppk files and leave only the extracted folder and files.

Extension files (.ext) should be in an all lowercase ‘extensions’ folder. They should be extracted out as if they were zip files into a folder with the same name as the extension (see modules above). You should then delete the ext files and leave only the extracted folder and files.

Campaign source files should be in an all lowercase ‘campaign’ folder, with each folder used to create the campaign inside (inside FGU you can find the campaign folder by clicking the folder icon on the first screen menu and navigating to the campaign folder. Inside are folders for each campaign, copy the entire folder). You should remove these files before uploading (where '*' is any number of letters or numbers):

  • db.script.*.xml

  • chatlog.html

  • db.session.*.xml

  • windowstate.xml

  • extensionstate.xml

  • modulestate.xml

  • drawings folder

  • maskedimages folder

  • moduledb folder

  • temp folder

  • usersettings folder

  • Any files or folders not generated by Fantasy Grounds

If you are using Dropbox to turn in products and want to save space, you can zip the main product folder up in a zip file.

When turning in products to Dropbox, keep in mind that no file manipulation should be done within Dropbox itself as this can leave phantom files for other users. Once you’ve arranged the files, then copy the zip or folder over to Dropbox.

Regardless of whether you are using SVN or Dropbox, you should turn in the cover, screenshots, and Steam images in the Dropbox folder that was shared with you. Your shared folder should be named “Smiteworks_for_<your name>”. Place the images into a folder named “store” inside the main product folder. As mentioned above the main product folder should have the same name as the product with the ruleset or the product id.

Procedure - Turning In A Product

To turn in a product:

  1. Upload the product through SVN or Dropbox as mentioned above (see folder structures).

  2. Then upload the cover, five or more screenshots, and the Steam images to your shared Dropbox folder (which should be named “Smiteworks_for_<your name>” as mentioned above).

  3. Go to the developer portal products page

  4. Filter for your product using the top right text box

  5. Click the ‘Review’ button in the status column.

You should receive a confirmation email. If you don’t, please inform James Holloway at jholloway@smiteworks.com.

Procedure - Updating A Product

  1. Upload the product through SVN or Dropbox as usual

  2. Go to the Developer Portal products page

  3. Filter for your product using the top right text box

  4. Click the ‘Update’ button at the right

  5. Fill in what was changed. Each line should start with [Fixed], [Updated], [Added], or [Removed] (see the buttons above the text box).

  6. Click ‘Submit’

You should receive a confirmation email. If you don’t, please inform James Holloway at jholloway@smiteworks.com.

There's no need to send a separate email if you receive a confirmation email on any of these.

As a developer, James will share a Dropbox folder with you where we can send you files and you can turn in completed conversions. Inside the "Outgoing" folder is a readme.txt file that explains how to turn in products.

The easiest way is to create a zip file of the 'Example Product" folder and all sub-folders and then extract that out each time you have a new product to turn in.

Explanation of the status of products

  • Development - The product has been assigned and is awaiting the Developer to turn in the finished files.

  • Review - The developer has turned in the finished files and is awaiting our internal technical review.

  • Bugfixes - An issue was found in our internal technical review and is awaiting the developer to address and turn in new files. When they are turned in the Developer should click the review button in the Developer Portal products page.

  • Steam - The products have been turned in to Steam for their review.

  • Priced - Steam has approved the product and we’ve priced it and scheduled its release date.

  • Posted - The product has been released on both our store and on Steam.