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 |
---|---|---|---|
Images | WEBP
| <= 4Kx4K pixel resolution <= 2MB file size (static) | Target grid size should be <100 pixels; |
Images | WEBP | <= 100x100 pixels per grid size |
|
Images | WEBP | <= 1Kx1K pixel resolution <= 2Kx2K pixel resolution <= 1MB file size (static) | 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) | These should have transparent backgrounds and be set up with height information in the .xml (see the relevant wiki page). |
Portraits | WEBP | <= 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
| <= 256x256 pixel resolution (Small/Medium) <= 512x512 pixel resolution | 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 | 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 | 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.
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:
Conversion Checker - Fantasy Grounds Forge
Properties Inspector - Fantasy Grounds 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:
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
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 |
---|---|
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 |
extensions | Any extension files should be placed in this subfolder. |
modules | Any module files should be placed in this subfolder. |
rulesets | Any ruleset files should be placed in this subfolder. |
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:
Upload the product through SVN or Dropbox as mentioned above (see folder structures).
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).
Go to the developer portal products page
Filter for your product using the top right text box
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
Upload the product through SVN or Dropbox as usual
Go to the Developer Portal products page
Filter for your product using the top right text box
Click the ‘Update’ button at the right
Fill in what was changed. Each line should start with [Fixed], [Updated], [Added], or [Removed] (see the buttons above the text box).
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.