Developer Guide

Developer Guide

This page is for contributors who want to change the SW5e Module itself, not just use it.

If you are trying to understand where code lives, how the module hooks into Foundry and DND5e, where to make a change, how compendium data is built, or how to test your work without creating a mess, start here.

Who this page is for

Use this page if you want to:

• understand the repo structure before editing anything
• find the right file or layer for a change
• build or rebuild compendium content safely
• test changes in a local Foundry environment
• avoid breaking compatibility, migration paths, or generated content

If you only want to create custom content inside the module’s existing workflows, use Homebrew and Content Authoring instead.

The most important architectural idea

The SW5e Module is a module layered on top of DND5e, not a standalone replacement system.

That means most changes live at the boundary between:

• FoundryVTT core
• the DND5e system
• SW5e-specific patches, templates, styles, localization, and content

When you start a change, do not ask only “what file should I open?” Ask:

• is this a runtime behavior problem?
• a sheet or template problem?
• a style or theme problem?
• a localization problem?
• a migration or normalization problem?
• a compendium source-data problem?

If you answer that first, you will usually save yourself a lot of wasted time.

Repo map

These are the main layers contributors touch most often:

• scripts/: runtime hooks, feature logic, custom apps, migrations, and patch layers
• scripts/patch/: DND5e-to-SW5E behavior integration points
• templates/: Handlebars UI structure for sheets and apps
• styles/: LESS and built CSS for module presentation
• languages/: localization strings
• packs/_source/: editable compendium source data
• packs/: generated compendium output
• utils/: helper scripts such as pack tooling and style builds

The most important source-of-truth rule is simple:

• edit packs/_source/
• build into packs/

Runtime entrypoints

At a high level:

• scripts/module.mjs is the main runtime entrypoint
• feature-specific behavior is usually registered through scripts/patch/* or nearby runtime files
• templates and styles support the runtime layer rather than replacing it

That means a visible UI bug is not always “just a template bug.” It may be:

• a template problem
• a bad render context
• a runtime-prep problem upstream
• or a style scoping problem

1.3.8 feature hotspots

If you are working on one of the most support-heavy 1.3.8 systems, start with these file groups.

Blaster reload and ammo UX

Start here:

• scripts/patch/blaster-reload.mjs
• scripts/patch/blaster-ammo-ux.mjs

This is the right area when the question involves:

• the Reload control on weapon rows
• private Reload cards
• out-of-ammo or not-enough-ammo interception
• managed blaster magazine behavior

Power bonuses and powercasting overrides

Start here:

• scripts/patch/power-bonuses.mjs
• scripts/powercasting-overrides.mjs
• scripts/power-casting-ability-config.mjs

This is the right area when the question involves:

• Force or Tech power attack bonuses
• power save DC bonus handling
• save-target DC bonus logic
• Configure Powercasting behavior
• actor override flags for Force-school casting

Starship combat state

Start here:

• scripts/starship-system-damage.mjs
• scripts/starship-destruction-saves.mjs
• scripts/starship-conditions.mjs
• scripts/starship-token-status.mjs
• scripts/patch/starship-sheet.mjs

This is the right area when the question involves:

• System Damage
• Destruction Saves
• starship conditions
• Used or Slowed state
• token HUD status sync
• the current Core | Inventory | Features | Effects | Description workflow

Themes

Start here:

• Themes and Appearance for the current appearance model
• starship and sheet LESS/CSS that still support functional layout and branding

This is the right area when the question involves:

• retained Pause / lightsaber / logo branding after selectable themes were removed in the 1.4.0 feature set
• dialog styling or scope application that still uses module CSS
• icon contrast or control regressions on stock Foundry chrome

Note: scripts/theme.mjs and theme-mode LESS paths described in older notes are removed with the selectable theme system.

Common change routing

Here is the practical version of “where should this change go?”

Visible text, labels, or wording

Check:

• languages/en.json
• relevant templates
• any prep code that supplies labels or localized summaries

Sheet layout or visible structure

Check:

• templates/ first
• then the runtime layer that prepares the template context

Behavior changed, but the sheet looks fine

Check:

• scripts/patch/*
• feature-specific runtime files
• data preparation paths

Theme or visual polish issues

Check:

• styles/less/*
• scripts/theme.mjs
• any app-specific theme scope hook

Fresh compendium example works, older copied content does not

Check:

• migration and normalization paths
• whether the older item needs refresh or re-import
• whether the change belongs to source content rather than runtime code

Compendium content is wrong

Check:

• packs/_source/
• any related normalization or pack-build helper

Migration and legacy sensitivity

If you are editing this module, you need to respect migration.

Before calling a change “done,” ask:

• what happens to older world content?
• what happens to copied items?
• what happens to starships created before the current workflow?
• what happens to existing compendium references or old module IDs?

If you skip those questions, you are usually solving only half the problem.

Module identity rule

Avoid reintroducing hardcoded assumptions about older module IDs or paths.

If a helper already exists for:

• module ID resolution
• compendium path normalization
• legacy reference cleanup

use the helper instead of introducing a new raw string assumption.

Compendium workflow

The content workflow is source-first.

That means:

• edit packs/_source/
• do not hand-edit generated packs/
• rebuild packs through the documented scripts

If a content change is only visible in source JSON and not in Foundry, the pack build step is probably the missing piece.

Typical contributor workflow

A safe workflow looks like this:

1. identify the feature area and likely layer first
2. confirm whether the change belongs in code, templates, styles, localization, migration, or source content
3. edit the source-of-truth location, not a generated artifact
4. rebuild what actually needs rebuilding
5. test in a local Foundry environment that matches the supported versions
6. test the obvious success case and at least one nearby edge case
7. call out anything legacy-sensitive, version-sensitive, or still untested

Testing expectations

The right test depends on the layer you changed.

Examples:

• patch logic: verify real in-play behavior, not just data prep
• template work: verify both read mode and edit mode
• theme work: verify visibility, icons, and control contrast on the affected surfaces
• source content: verify the built result in Foundry, not just the JSON diff
• migration-sensitive work: compare fresh content and older content when possible

Use Testing & Contribution for more detailed regression checklists.

Where to go next

Use these pages next depending on what you need:

• Developer Reference for fast lookup while you are already coding
• Local Setup and Workflow for rebuild and reload rules
• Testing & Contribution for regression mindset and contribution discipline
• Active Effect Keys if the change involves actor effect paths

Practical summary

If you want the shortest useful summary of this page, it is this:

• figure out the layer before you edit
• treat scripts/, templates/, styles/, languages/, and packs/_source/ as different kinds of source-of-truth
• use the 1.3.8 feature hotspots above when the bug is in blasters, powercasting, starships, or themes
• do not ignore migration or older copied content
• rebuild and retest the layer you actually changed