System-agnostic ship combat engine for Foundry VTT. The core module ships the data models, sheets, canvas overlays, socket handlers, and templates. All system-specific behaviour (roll formulas, success-level math, hit resolution, skill labels, model integration) lives in a companion module that pairs this engine with a specific game system.

A companion module MUST do four things:

1. Subclass SystemAdapter and implement the abstract methods.
2. Call ShipCombat.configure({ moduleId, adapter }) at module-evaluation time (top-level in your entry-point script), before Foundry fires the init hook.
3. Provide a lang/en.json (and other locales) that overrides any of core's neutral default strings with system-flavoured terminology.
4. Optionally, register Handlebars partial overrides during its own init hook to swap out specific UI panels.

If ShipCombat.configure() is not called by the time init fires, core logs a warning and disables itself.

import { MyAdapter } from "./scripts/my-adapter.js";

ShipCombat.configure({
  moduleId: "my-shipcombat-module",
  adapter:  new MyAdapter(),
});

Hooks.once("init", () => {
  // Optional: replace specific UI partials.
  ShipCombat.registerPartialOverride(
    "captain-conditions",
    "modules/my-shipcombat-module/templates/my-conditions.hbs",
  );
});

Subclass SystemAdapter from scripts/systems/SystemAdapter.js. Methods marked abstract throw if not overridden; overridable methods have a working default and only need overriding when the host system requires different behaviour.

Core reads and writes ship data through two adapter methods rather than touching actor.system directly. This lets flag-based adapters (e.g. SF2e, which does not allow module-defined actor sub-types) store ship data in actor.flags[moduleId] while other adapters use actor.system.

// impmal (default — system sub-type)
getShipData(actor) { return actor.system; }
systemPath(key)    { return `system.${key}`; }

// SF2e (flag-based — no module sub-types allowed)
getShipData(actor) { return actor.flags[this.moduleId] ?? {}; }
systemPath(key)    { return `flags.${this.moduleId}.${key}`; }

The salvo loop calls these lightweight methods for every individual shot. For non-salvo (single-fire) actions, core calls resolveHitRoll() instead.

Adapters may declare extra fields stored on every component item (armour class, hardpoint slots, etc.). Core stores them under system.extended.

If you declare extension fields, also register a partial override for component-extended-fields to render inputs for them in the item sheet.

Core renders ship sheets from named Handlebars partials. Each name resolves to a default path under templates/actor/partials/<name>.hbs. Override any of them with ShipCombat.registerPartialOverride(name, path) during the companion module's init hook.

The full inventory of valid names is in scripts/templates.js. Override paths must consume the same context shape and emit the same data-action attributes as the defaults, otherwise event wiring breaks.

The most commonly overridden slot is component-extended-fields — rendered at the bottom of the component item sheet's Details tab. Empty by default; override it to expose UI for the fields you declared in getComponentSchemaExtensions().

Core defaults to Foundry's ApplicationV2 (AppV2) for all ship sheets. To use the legacy AppV1 bridge (required by some systems, e.g. SF2e), override two adapter methods:

get useApplicationV1() { return true; }
get SheetBaseClassV1() { return foundry.appv1.sheets.ActorSheet; }

When useApplicationV1 is true:

• Core registers ShipSheetV1Mixin(SheetBaseClassV1) instead of ShipSheetV2Mixin(SheetBaseClass).
• The popup resolver automatically selects the bundled V1-compatible popups (TargetingPopupV1, RamTargetPopupV1, etc.) for any key not explicitly registered via registerPopupOverride.
• Tab show/hide rules are provided by styles/appv1-compact.css; Foundry V14 removed the global AppV1 hide rule that older modules relied on.

ShipCombat._popupClass(key, DefaultClass) resolves in this order:

1. An explicit registerPopupOverride(key, PopupClass) call (highest priority).
2. The bundled V1 default for key when useApplicationV1 === true.
3. DefaultClass — the AppV2 popup bundled with core.

Valid keys: "targeting", "ramTarget", "battleClarity", "strikeCraftAttack", "recoverCraft".

AppV1 sheets do not use Foundry's data-action system. Core uses a custom dispatchAction(type, element) call on the sheet controller. Register new actions in ShipSheetV1Mixin.DEFAULT_OPTIONS.actions.

Core ships neutral default strings. Companion modules supply a lang/en.json that overrides any keys the system flavours differently. Foundry merges all loaded modules' lang files automatically, so a partial override file only needs to contain the keys it changes.

Lang values may reference other lang keys with {{Some.Key}} syntax; core resolves those tokens once at init so a single change to (say) SHIPCOMBAT.Role.Pilot propagates to every string that mentions the pilot role. The token form must be a fully-qualified dot path; nesting is not supported.

The table below shows every hook core registers and what it does. Hooks marked with ★ call an adapter method and may interact with companion code.

causodes-shipcombat-core/
├── causodes-shipcombat-core.js   # Entry point, ShipCombat global, all Hooks
├── module.json
├── scripts/
│   ├── constants.js              # MODULE_ID, CORE_MODULE_ID, role/slot keys
│   ├── settings.js               # Global module settings
│   ├── templates.js              # Partial registry + CORE_PARTIAL_DEFAULTS list
│   ├── socket.js                 # socketlib actions
│   ├── lang.js                   # Lang token-substitution helper
│   ├── theme.js
│   ├── animations.js
│   ├── systems/
│   │   └── SystemAdapter.js      # The contract documented above
│   ├── actors/                   # ShipModel, OrdnanceModel, NPC ship, sheet mixins
│   ├── items/                    # ShipComponentSchema, item sheet
│   ├── apps/                     # Targeting, BDA, Strike Craft, V1 popups
│   ├── canvas/                   # Helm preview, arc/shield overlays, radar
│   ├── roles/                    # Per-role action handlers (captain, gunner, …)
│   └── state/                    # ShipCombatState + per-role state slices
├── styles/
│   ├── appv1-compact.css         # Tab show/hide rules for AppV1 sheets
│   └── custom-class-compat.css   # Compat shims for systems that inject CSS classes
├── templates/                    # Sheets, partials, chat cards
└── lang/en.json                  # Neutral default strings