/
Developer Guide - Product Guideline and Procedures

Developer Guide - Product Guideline and Procedures

 

As a Community Developer of Fantasy Grounds products, refer to the Fantasy Grounds Community Developer email sent when joining the Community Developer mailing list.
It contains required procedural and login information.

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

1. Overview

This guide defines the standards, requirements, workflows, and submission procedures for Fantasy Grounds products, including modules, adventures, rulebooks, asset packs, extensions, and rulesets.

Intended Audience

  • Community Developers

  • Conversion Developers

  • Artists (maps, tokens, portraits)

  • Ruleset and extension developers

2. Core Product Requirements

2.1 Naming & File Conventions

  • Filenames must use A–Z, a–z, 0–9, underscore (_), dash (-) only

  • Avoid apostrophes, quotes, accents, or special characters

  • Module filename must match the Product ID provided by SmiteWorks

  • Decorators may be used for multiple modules:

    • <ProductID> GM

    • <ProductID> PG

2.2 Module Metadata Requirements

  • The module Name field must match the Product ID (with decorators if needed)

  • Avoid special characters in the Display Name

  • All products must be exported from Fantasy Grounds Unity

3. Image & Asset Guidelines

These guidelines exist to maintain performance on lower-resolution systems and reduce memory/network load.

3.1 Supported Image Formats

  • WEBP

  • WEBM (VP8)

  • PNG

  • JPG

3.2 Image Optimization

  • Static WEBP at 75% quality is recommended

  • Be mindful of total product size, especially animated assets

  • Avoid duplicating images between Player and GM modules

If an image is needed in both Player and GM modules, store it in the Player module and link to it from the GM module.

3.3 Image Size & Type Specifications

Image Type

Recommended Format

Recommended Size

Notes

Image Type

Recommended Format

Recommended Size

Notes

Images (Maps)

WEBP (75%)

≤ 4K×4K pixels; ≤ 2MB static; ≤ 10MB animated

Target grid <100px; break up large maps; include LOS & lighting

Images (Brushes / Stamps)

WEBP (75%)

≤ 100×100 pixels per grid square

Example: 4×4 tile = 400×400

Images (Creatures)

WEBP (75%)

≤ 2K×2K; ≤ 1MB static; ≤ 5MB animated

Creature images are rarely zoomed

Images (Other)

WEBP (75%)

≤ 4K×4K; ≤ 2MB static; ≤ 10MB animated

 

Tokens (2D – Top Down)

WEBP (75%)

≤ 512×512 (Small/Medium); ≤ 1K×1K (Large+)

 

Tokens (2.5D – Camera)

WEBP (75%)

≤ 2K×2K; ≤ 1MB static; ≤ 5MB animated

Transparent background; height data required

Initiative Indicators

WEBP / WEBM

≤ 1K×1K; ≤ 1MB static

Transparent background

Skybox (Panoramic)

WEBP / WEBM

≤ 2800×1400 recommended; ≤ 4K×2K max

See Skybox template documentation

Top-down or Flat tokens follow Tokens (2D) specs.

Full-body and camera tokens follow Tokens (2.5D) specs.

4. Content & Authoring Standards

4.1 Text Usage

All text should be entered as text, not embedded in images, except for:

  • Unsupported special characters

  • Visual clues embedded in artwork

  • Timelines and charts

4.2 Reference Manuals & Story Entries

  • Products should be created with a Reference Manual (Books > Campaign)

  • The reference manual should be divided into Chapters and Sub-chapters to closely resemble the printed book or PDF

  • Page Headers should not duplicate page names

  • Page sections should apply appropriate Frames to resemble the book or PDF

  • Images should be placed from the Asset Window in-line with text

  • Text should be formatted to match the book or PDF. See guide

  • Tables should be laid out with appropriate column span widths relative to content. See guide

  • Any referenced FG record (encounter, area, NPC, item, treasure) must be linked

  • NPC dialogue must use boxed text with a speaker

  • GM narration must be boxed text

4.3 Developer Notes (Required)

Each product must include a Developer Notes page containing:

  • Version number

  • Version history

  • Notes describing deviations from the PDF (e.g., page numbers replaced with links)

4.4 Exporting the Module

  • Player-facing content should be marked as a Player Module

  • The Read Only checkbox should no longer be used

  • Mark all Record Types needed for the final product

  • Match the Category to existing products

5. Development Workflow

5.1 Before You Start

  • Review source material thoroughly

  • Contact Developer Relations if new functionality or record types are required

5.2 Extensions vs Rulesets

  • Module-specific features → Extension (.ext)

  • Cross-product features → Ruleset update

  • Developer Relations will help determine the best approach

6. Screenshots & Store Assets

Requirements

Store images must be uploaded to Dropbox only.

Do not upload store images to SVN.

7. Helpful Tools

8. Procedures

8.1 First Steps

Email:

Include your name, email address, and request to join the Community Developer mailing list.

8.2 Signing Up for a Product

  • Select a product from the Adaptation List in the Developer Portal

  • Email James Holloway with:

    • Full product title

    • Estimated completion time

  • Wait for confirmation before starting work

If AI-generated content is included, disclose the tools used and affected assets in the product notes.

9. Submission – Dropbox or SVN

9.1 Dropbox

  • Shared folder name: Smiteworks_for_<your name>

  • One master folder per product

  • Zip/unzip folders before upload

  • Do not manipulate files inside Dropbox

Warning: Store backup copies of your work separately from this submission Dropbox folder. These folders are periodically cleared out to free up space.

9.2 SVN

  • Use assigned SVN path

  • Extract MOD / EXT / PAK files

  • Remove packaged originals

  • Do not checkout folders in SVN. Just run an Update prior to committing a new version. This will flag any possible conflicts that need to be resolved prior to submission.

10. Submission – Folder Structure

Each product should be put into a folder named with the product id. Inside this folder you will put one or more of the following:

Subfolder

Contents

Subfolder

Contents

campaign

Development campaigns (cleaned of session/user files)*. Take the folder inside the Fantasy Grounds data/campaigns folder and copy it inside the campaign folder that you are turning in.

extensions

Unzip your extension files and place them in a subfolder here. Name that inner folder with the product ID (and add a short descriptor if needed, like "ABC123GM").

modules

Unzip your module files and place them in a subfolder here. Name that inner folder with the product ID (and add a short descriptor if needed, like “ABC123GM”).

rulesets

Unzip your ruleset files and place them in a subfolder here. Name that inner folder with the product ID (and add a short descriptor if needed, like “ABC123GM”).

store

Cover art, screenshots, Steam images go directly into the store folder. No need for any subfolders here.

For example a module folder should look like: <productid>\modules\<productid>\definition.xml
You only need to add a descriptor if there are multiple sub-folders such as multiple modules or multiple extensions or multiple rulesets.

folder structure.jpg
Folder structure for turning in files

 

* db.script.XXX.xml, chatlog.html, db.session.XXX.xml, windowstate.xml, extensionstate.xml, modulestate.xml, usersettings folder, moduledb folder.

Products containing a non-theme extension or ruleset must include:

  • <ProductID> folder (ruleset/extension only)

  • <ProductID>-data folder (modules, campaigns, portraits, themes)

11. Turning In a Product

  1. Upload files via SVN or Dropbox

  2. Upload store images to Dropbox

  3. Go to the Developer Portal

  4. Click Review on the product

12. Updating a Product

  1. Upload updated files

  2. Click Update in the Developer Portal

  3. Document changes using:

    • [Fixed]

    • [Updated]

    • [Added]

    • [Removed]

  4. Submit the update

13. Product Status Definitions

  • Development – Assigned, awaiting submission

  • Review – Under internal review

  • Bugfixes – Issues found, awaiting fixes

  • Steam – Submitted to Steam

  • Priced – Approved and scheduled

  • Posted – Live on store and Steam