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
(https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/996640584)

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. The exceptions are 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.

 

Tokens

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.

Development - Other Guidelines

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

  • Each product should be accompanied by 5 or more screenshots at 1280x720 70% compressed JPG, and the largest cover image you can get (minimum 1080px wide) at 70% compressed JPG or layered PSD with the title and background image on their own layers with nothing else. You should also provide Steam images (see Steam image section). 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 both a Reference Manual and Story records for best access.

  • 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 - https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/996640899/Using+the+Library+and+Activating+Modules#Module-Export

    • 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.

    • When exporting the product name should be the product id with “Player” or “GM” added. The module filename should be the same (product id with “Player” or “GM” added). The display name should match the product name on the cover with “Player” or “GM” added.

  • 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.

Email developerrelations@smiteworks.com if you need help accessing the Developer Portal.

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.

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).

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).

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).

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).

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

 

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.