/
Developer Guide - Product Guidelines

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
(Map Line of Sight Style Guide)

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.

Printables

WEBP

(High Quality - 75%)

<= 4k x 4k pixel resolution

<= 2MB file size (static)

These should be used sparingly as they use a lot of memory when loaded and can cause delays when sending to clients.

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.

Initiative Indicators - Static

WEBP

(High Quality - 75%)

<= 1kx1k pixel resolution
<= 1MB file size (static)

These should have transparent backgrounds to allow the tokens to show over or under the indicator.

Initiative Indicators - Animated

WEBM (VP8)

(High Quality - 75%)

<= 1kx1k pixel resolution
<= 5MB file size (animated)

These should have transparent backgrounds to allow the tokens to show over or under the indicator.

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

    • 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 - Before You Start Adapting Your Approved Product

Development Planning

Before starting a new conversion process, you should skim through the content material to plan out your adventure or accessory. Please reach out to developer_relations@smiteworks.com to discuss it first if the module you are working on will require any new features, functionality, or record types.

New functionality or record types may require you to develop an extension (.ext) to go with the content, but it may be best handled directly within the ruleset by the ruleset developer. If the new features are specific only to the module you are planning, then this would likely be best served with an extension. If the functionality will ultimately be used across multiple products, then a ruleset update is most likely preferred.

Our team can help determine the best path forward, and if that development is something we can provide in a timely fashion. Once you know this, you can decide to move forward or switch to another product.

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.

Submission - DropBox or SVN

For products submitted via DropBox,

  • Your shared folder should be named “Smiteworks_for_<your name>”

  • Place each product into it’s own master folder. Use the FG product ID as the master folder name (if provided); otherwise, use a name as close to product name as possible.

  • Place the master folder in the Outgoing folder on DropBox.

  • To save space, you can zip the main product folder up in a zip file.

  • Do not perform any file manipulation within Dropbox itself as this can leave phantom files for other users. Once you’ve arranged the files into the subfolders below, then copy the zip or folder over to Dropbox.

  • You should retain an exact copy of the files outside of Dropbox in case there are issues. We use Dropbox only to transfer files and as soon as we receive them we delete them from Dropbox to avoid issues with Dropbox that we have no control over.

For products submitted via SVN,

  • You will be given an SVN path for the product code assigned to the product.

  • Set up the folder structure noted below as needed to submit files (if not already configured).

Submission - Folder Structures

When submitting the product via either DropBox or SVN, please set up the following subfolder structures within the product folder. See special notes for Portrait/Token only pack products below table.

When submitting your product, you'll need to create two separate folders:

  1. Main Product Folder

    • Name this folder using your product ID (for example: "MYAWESOMERULESET")

    • This folder should contain only your ruleset or non-theme extension files

  2. Data Folder

    • Name this folder by adding "-data" to your product ID (for example: "MYAWESOMERULESET-data")

    • This folder should contain all supporting content, including:

      • Campaign files

      • Module files

      • Parse files

      • Portrait files

      • Theme extension files

Think of it like keeping your core rules and non-themed extensions in one folder and all the extra content in a separate folder.

Subfolder

Contents

Subfolder

Contents

campaign

Any campaigns used to develop modules should be stored here. Please store each campaign in its own nested subfolder. Please make sure it is “campaign” and not “campaigns” as this is a reserved folder name.

You should remove the following files from any submissions or SVN commits (where '*' is any number of letters or numbers):

db.script.*.xml
chatlog.html
db.session.*.xml
windowstate.xml
extensionstate.xml
modulestate.xml
moduledb folder
usersettings folder
Any files or folders not generated by Fantasy Grounds

extensions

Any extension files should be placed in this subfolder.
For SVN commits, the files should be extracted from .EXT into a nested subfolder, and remove the original .EXT file.

modules

Any module files should be placed in this subfolder.
For SVN commits, the files should be extracted from .MOD into a nested subfolder, and remove the original .MOD file.

rulesets

Any ruleset files should be placed in this subfolder.
For SVN commits, the files should be extracted from .PAK into a nested subfolder, and remove the original .PAK file.

store

Any cover, screenshots, and Steam images for the product.

Any portrait and/or token packs should be turned in as modules. These can be created outside of FG by creating a nested subfolder under modules with a definition.xml file, and portraits and/or tokens subfolders containing the portraits/tokens.

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.

Related content