CraftingSystemManager

Manages crafting system configurations and their component libraries.

Access: game.fabricate.getCraftingSystemManager()


System Methods

getSystems()

Returns all crafting systems.

Returns: object[]

getSystem(systemId)

Returns a single system by ID.

Returns: object | null

createSystem(data)

Creates a new crafting system. GM only.

Parameter Type Description
data object System configuration (name, description, resolutionMode, features, essenceDefinitions, etc.)

Returns: Promise<object>

The features object controls which optional behaviours are active. Every key defaults to false when omitted, except salvage, which defaults to true (see the table below).

Feature key Type Default Description
recipeCategories boolean false Organise recipes into named categories
itemTags boolean false Tag-based ingredient matching
essences boolean false Enable the essences system
propertyMacros boolean false Allow result property macros
effectTransfer boolean false Copy active effects from ingredients to crafted results. Also requires recipe.transferEffects: true on each recipe. See Effect Transfer.
multiStepRecipes boolean false Multi-step recipes
salvage boolean true Allow components to be broken down into constituent parts. Defaults on for backward compatibility; an explicit false is honoured. When enabled (the default), each normalised component gains a salvage sub-object. See Salvage.
gathering boolean false Enable GM authoring for gathering environments and tasks. See Gathering Environments.
const mgr = game.fabricate.getCraftingSystemManager();
const system = await mgr.createSystem({
  name: 'Alchemy',
  description: 'Brew potions and elixirs',
  resolutionMode: 'simple',
  features: {
    recipeCategories: true,
    essences: true,
    effectTransfer: true,
    multiStepRecipes: false,
    salvage: false // opt out; salvage is on by default
  },
  essenceDefinitions: [
    {
      name: 'Fire',
      description: 'The raw energy of flame',
      icon: 'fas fa-fire',
      sourceItemUuid: null
    },
    {
      name: 'Frost',
      description: 'The biting cold of winter',
      icon: 'fas fa-snowflake',
      sourceItemUuid: null
    }
  ]
});
console.log(`Created system: ${system.id}`);

The returned system object also includes the following top-level salvage fields, which are always normalised regardless of whether the salvage feature is enabled:

Field Type Default Description
salvageResolutionMode string "simple" How salvage result groups are selected. Accepts "simple", "routed", or "progressive". Legacy "tiered" input is normalized to "routed". "mapped" and "alchemy" are rejected and fall back to "simple".
salvageCraftingCheck object see below System-level salvage check configuration.

salvageCraftingCheck shape:

Field Type Default Description
enabled boolean false Whether the optional simple-mode salvage check is active.
simple object see below Simple pass/fail salvage check (simple salvage mode). Usable only when simple.rollFormula is set.
routed object see below Routed salvage check (routed salvage mode). Usable only when routed.rollFormula is set.
consumption.consumeComponentOnFail boolean true Consume the source component even when the check fails
consumption.breakToolsOnFail boolean false Break Tools even when the salvage check fails (renamed from the legacy consumeCatalystsOnFail, which is still read as a fallback)
progressive.rollFormula string "" Roll formula for the progressive salvage check (progressive salvage mode). The check is usable only when this is set.
progressive.awardMode string "equal" Progressive award mode: "equal", "exceed", or "partial"
outcomes string[] ["fail","pass"] Named outcome labels used for routed check routing

The craftingCheck field is always present on the returned system object. It controls how skill/ability checks gate recipe outcomes in routed-by-check and progressive modes.

craftingCheck shape:

Field Type Default Description
enabled boolean false Whether the optional simple-mode crafting check is active. This toggle gates the simple pass/fail check in simple mode only.
simple.rollFormula string "" Roll formula for the simple pass/fail check (simple mode, and alchemy when alchemy.checkMode is "simple"). The check is usable only when this is set.
simple.dc number 15 Static difficulty class for the simple check. Roll total must meet or exceed it (or strictly exceed it when simple.thresholdMode is "exceed").
simple.dcMode string "static" "static" uses simple.dc. "dynamic" computes the DC from the macro at simple.macroUuid.
simple.macroUuid string\|null null UUID of the dynamic-DC macro, used only when simple.dcMode is "dynamic". The macro computes the DC. It never resolves the check outcome.
routed.rollFormula string "" Roll formula for the routed crafting check. Required in routedByCheck mode and in alchemy when alchemy.checkMode is "tiered", and optional in routedByIngredients mode. The check is usable only when this is set.
progressive.rollFormula string "" Roll formula for the progressive check (progressive mode). The check is usable only when this is set.
consumption.consumeIngredientsOnFail boolean true Remove ingredients from inventory when the check fails.
consumption.breakToolsOnFail boolean false Break Tools when the crafting check fails (renamed from the legacy consumeCatalystsOnFail, which is still read as a fallback).
progressive.awardMode string "equal" Progressive award mode: "equal", "exceed", or "partial".
outcomes string[] ["fail","pass"] Named outcome labels used for routed check routing.
modifiers {id, label, expression, isRollExpression, icon?, min?, max?}[] [] The ONE system-level modifier library (issue 1117): every activity check selects over it, and every gathering drop row, event and stamina cost references it. A check adds its eligible entries to the roll automatically as flavoured [Modifiers] terms: the flat ones sum into one + N[Modifiers] term and each rolling one is appended as its own + (…)[Modifiers] dice term. Each expression is a roll-data fragment evaluated against the acting character (a missing/failed expression contributes 0, never NaN). isRollExpression is DERIVED on every normalise and never read from input; it is a DISPLAY classification and never a gate, because a check appends a rolling entry as dice (issue 1118 retired the blocking modifierRollExpression readiness issue). icon, min and max are stored only when authored, so absence round-trips as key-absent and means unbounded — a bound of 0 is a real bound. min/max clamp that entry’s contribution — the resolved value for a flat expression, and the ROLLED result for a rolling one, expressed in the formula as min(max((1d8), -1), 6). An authored min > max is kept verbatim, raises the blocking modifierBoundsInverted readiness issue, and makes the entry contribute 0 until it is fixed. The 1.22.0 migration moves the check catalogue up from craftingCheck.checkModifiers; 1.23.0 merges that with the gathering characterModifiers library into this one key and deletes both.
defaultModifierPolicy string "addAll" The combination rule, carried INDEPENDENTLY by craftingCheck, salvageCraftingCheck and gatheringCraftingCheck: how the eligible modifiers combine into what is added to the roll, and who selects them. "addAll" takes that activity’s default set and "highest" takes its single highest-AVERAGING entry — 1d4 (2.5) beats a flat +2, and the winner is appended as dice; neither asks anyone to select. "bySubject" lets the record being resolved select at authoring time — the recipe, the component or the gathering task, labelled “By recipe” / “By component” / “By gathering task” — and "playerPicks" lets the player select at roll time on an interactive attempt; both SUM what was picked, and both are bounded by maxModifierPicks. A non-interactive "playerPicks" attempt resolves to the best legal selection (the highest-AVERAGING maxModifierPicks entries, which is "highest" at a cap of 1). The system owns this field alone — a subject never overrides it. The pre-1095 "byRecipe" is read as "bySubject" and never written back. An unrecognised value falls back to "addAll".
defaultModifierIds string[] [] Library entry ids this activity applies by default. An id naming no entry in the SYSTEM’s modifiers is dropped (order and de-duplication preserved). Under "bySubject" this is what a subject inherits until it picks its own; under "playerPicks" it is the menu the player chooses from.
maxModifierPicks number key absent The cap on how many modifiers a selecting rule ("bySubject", "playerPicks") may pick, per activity check. Only a positive integer is stored, so null, 0, 2.5, and junk all normalise to the same shape: key absent. Absence means unlimited, resolved as Infinity, and is never defaulted — a check that was never asked must not acquire a bound that truncates subject picks already on disk. Meaningless under "addAll"/"highest", but stored regardless of the current rule. Under "bySubject" it truncates a subject’s resolved picks to the first N in authored order without deleting the rest.

progressive.allowPlayerReorder is retired (issue 651) and is dropped from the crafting, salvage, and gathering progressive check blocks on every normalise, including on import of a legacy payload. The 1.17.0 migration strips it from stored systems. The permission it carried now lives on the recipe as allowPlayerResultReorder and on the component as salvage.allowPlayerResultReorder, and it defaults to true where it previously defaulted to false. Gathering never had an ordered result-stage surface, so it has no replacement field.

Behaviour change (issue 1055). A recipe’s stored craftingModifier.modifierIds is now consulted only under defaultModifierPolicy === "bySubject" (spelled "byRecipe" before issue 1095). Before this change the eligible-id resolution preferred a recipe’s own set under every rule. Under "addAll", "highest", and "playerPicks" a system now resolves its own defaultModifierIds for every recipe, whatever any recipe stored; nothing is deleted, and switching the system to "bySubject" applies those picks again. A recipe’s legacy craftingModifier.policy is never consulted at all — the combination rule is the system’s alone — and Recipe drops the key on read.

The 1.20.0 migration stamps maxModifierPicks: 1 onto systems already on "playerPicks" that carry no cap, because that rule historically meant “pick exactly one” and an absent cap now means unlimited. The other three rules are left unbounded: "addAll" and "highest" select nothing, and the subject-selecting rule may already have records that picked several modifiers, which a stamp of 1 would silently truncate. An authored cap always wins, which makes the migration idempotent, and migrateExportPayload applies the identical per-system transform to an imported bundle, branch-independently of the schema-envelope upcast.

There is ONE modifier library from 1.23.0 (issue 1117). It used to live at craftingCheck.checkModifiers, which made it crafting-owned by construction; 1.22.0 moved it to CraftingSystem.checkModifiers so salvage and gathering could select over the same entries, and 1.23.0 merged that with the gathering characterModifiers library into CraftingSystem.modifiers. Every old key is deleted rather than aliased. An id authored in BOTH libraries keeps the check entry’s id; the gathering entry is re-keyed with a -gathering suffix and every gathering reference to it is rewritten. The same migration rewrites craftingCheck.defaultModifierPolicy === "byRecipe" to "bySubject", and migrateExportPayload applies the identical per-system transform to an imported bundle. The move is guarded — an authored system-level catalogue is never clobbered — and it seeds nothing onto a salvage or gathering check that has no block. Downgrading to 1.22.0 LOSES the merged library: that build’s normalisers are allowlists that never saw CraftingSystem.modifiers, so it is dropped on the first read — every check modifier stops contributing to every roll AND every gathering drop row, event and stamina cost loses the entry it references, until a GM re-authors both.

The alchemy field is present only when resolutionMode is "alchemy". It carries the alchemy check mode and the discovery/consumption options.

alchemy shape:

Field Type Default Description
checkMode string "none" How a matched brew is resolved. "none" runs no check and always succeeds. "simple" runs a pass/fail check from craftingCheck.simple (pass produces the success group, fail produces the reserved role: 'failure' group). "tiered" runs a mandatory routed check from craftingCheck.routed and routes by outcome tier, exactly like routedByCheck.
learnOnCraft boolean true Mark a recipe as learned for the crafting character when a submission matches it. A match learns the recipe whether or not the check passed, and whether the brew resolves immediately or after a time gate. Under global visibility this is the only source of discovery a player can reach for themselves, so turning it off leaves every player’s Known list empty of everything except a recipe a GM grants through game.fabricate.grantRecipeKnowledge.
consumeOnFail boolean true Consume the submitted components on a no-match fizzle and on a matched Simple-check failure.
showAttemptHistoryToPlayers boolean true Remember a character’s fizzled combinations so the workbench can mark them as a dead end rather than an untried mix.

Example: routed-by-check. Configure a routedByCheck system to roll a check and route the result by outcome name:

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('alchemy-system-id', {
    resolutionMode: 'routedByCheck',
    craftingCheck: {
      routed: {
        rollFormula: '1d20 + @abilities.int.mod',
        dc: 18
      },
      outcomes: ['fail', 'pass']
    }
  });
});

Example: optional simple check. Enable an optional pass/fail check in simple mode by setting a roll formula and turning the check on:

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('alchemy-system-id', {
    craftingCheck: {
      enabled: true,
      simple: {
        rollFormula: '1d20 + @abilities.int.mod',
        dc: 15
      }
    }
  });
});

Example: alchemy Simple check. Give an alchemy system a mandatory pass/fail check so a matched brew rolls, and produces the reserved failure result group on a fail:

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('alchemy-system-id', {
    alchemy: { checkMode: 'simple' },
    craftingCheck: {
      simple: {
        rollFormula: '1d20 + @abilities.int.mod',
        dc: 15
      }
    }
  });
});

updateSystem(systemId, updates)

Updates a system’s configuration. GM only.

Parameter Type Description
systemId string System ID
updates object Partial system data to merge

Returns: Promise<object>

When updating features, only the keys you provide are changed. Other feature flags are preserved from the existing system.

// Enable effect transfer on an existing system without changing other features.
Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('alchemy-system-id', {
    features: { effectTransfer: true }
  });
});
// Enable salvage with routed mode on an existing system.
Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('blacksmithing-system-id', {
    features: { salvage: true },
    salvageResolutionMode: 'routed',
    salvageCraftingCheck: {
      routed: {
        rollFormula: '1d20 + @abilities.int.mod',
        dc: 18
      },
      consumption: {
        consumeComponentOnFail: true,
        breakToolsOnFail: false
      },
      outcomes: ['critical', 'pass', 'fail']
    }
  });
});

Changing resolutionMode is destructive and deletes all recipes in the system.

deleteSystem(systemId)

Deletes a system and all its recipes. GM only.

Returns: Promise<void>

Deleting a system emits one summary notification naming the crafting system and counting related entities deleted with it. It does not emit one notification per deleted recipe.

Deleting a system also removes the scoped membership records that name it, in the component, essence, and tool scopes. That prune runs after the system’s removal is saved, and only once the saved systems no longer include that system. A failure in one scope is logged and does not stop the others.

Deletion is resilient to a recipe that cannot be removed. If an individual recipe deletion fails, that failure is logged to the console with the recipe id, the remaining recipes are still deleted, and the system itself is still removed. In that case the summary is a warning that also reports how many recipes could not be auto-deleted and may need manual removal.


Component Methods

Returns components for a system, optionally filtered by search text.

Parameter Type Description
systemId string System ID
search string Optional search filter

Returns: object[]

The system object exposes components under two equivalent properties: components (primary) and managedItems (transitional alias). Both always refer to the same array.

addItemFromUuid(systemId, itemUuid, options)

Adds a single Foundry Item document to the system as a component. GM only. The component is also registered as a world component in the world Component catalogue, held by this system, as described under World component registration below.

Returns a result object that indicates whether the item was newly created, updated, or already up to date, so callers can show appropriate notifications.

The method resolves the dropped item’s live UUID and, when the item is a copy of a compendium entry, its canonical source UUID (via _stats.compendiumSource, with flags.core.sourceId as a legacy fallback) before deciding what to do. An item that was built from a compendium entry and given a different name is its own item: its compendium source is not used to find or claim a component, and it creates a separate component. A copy that keeps the entry’s name still matches the component registered from that entry. A sidebar duplicate is likewise matched only by its own UUID. If the compendium source does not resolve, the name cannot be compared, so the source is not used to find or claim a component. Items that share such a source register as separate components, and adding one again finds its component by its own UUID. The source does not resolve when its pack is missing (the module or system that provides it is disabled or uninstalled), its entry was deleted, or the lookup failed. The split is permanent once made. Restoring the entry does not rejoin the components. To remove an unwanted split, delete the extra component, then either restore the entry and import the item again, or use replace-source to link the original component to the item. A component that already absorbed several such items stays merged, so delete it and import the items again. If the canonical source UUID no longer resolves, Fabricate stores the live dropped item UUID as the component’s primary source and keeps the broken canonical UUID in aliasItemUuids, unless another component of the system, or a World Component other than the one the import adopts, already claims it. The first import still reports its sourceFallbacks entry when the alias is withheld. Adding again an Item whose own UUID a component already claims adds no alias and reports no fallback. A component can claim a full source-reference chain through registeredItemUuid, originItemUuid, and aliasItemUuids.

  1. Claimed source chain. An existing component already claims the dropped live UUID or, for a copy that keeps the entry’s name, the canonical source UUID or a fallback UUID in the same chain. A component that claims the dropped live UUID is preferred over one that claims only the compendium source. Re-adding an item whose own UUID a component already claims never changes which compendium entry that component claims. Fabricate refreshes the component in place and returns action: "updated" when metadata or stored references changed, or action: "skipped" when nothing changed.
  2. Unclaimed source chain. No component claims any of those references, so a new component is created and action is "added".
Parameter Type Description
systemId string System ID
itemUuid string UUID of the Foundry item to add. Accepts both world item UUIDs (Item.abc123) and compendium item UUIDs (Compendium.pack.id.itemId).
options.persist boolean Optional. Pass false to change the system in memory only, so a caller importing many items can save once itself. Defaults to true.
options.registrations object[] Optional. An array the call records its world component registration into instead of writing it. Pass it with persist: false, then hand the same array to flushWorldComponentRegistrations() after your own save.

Returns: Promise<{ item: object, action: 'added' | 'updated' | 'skipped', sourceFallbacks: object[], worldRegistrationError?: Error }>

  • item is the component object (new or existing).
  • action is "added" if a new component was created, "updated" if an existing component’s name/image/source references were refreshed, "skipped" if the claimed source chain was already current.
  • sourceFallbacks holds broken source-link fallback notices in the form { itemName, brokenUuid, fallbackUuid }. It is empty when no fallback occurred, including when the Item was already registered by its own UUID.
  • worldRegistrationError is present only when the world Component catalogue could not be written. The component is still in the system when it is set. A call that was given a registrations array never sets it, because it writes nothing to the catalogue itself.

Throws: Error if the system ID is not found, or if the UUID resolves to a non-Item document (such as an Actor or JournalEntry).

World component registration

Every import also registers the component as a world component the system holds, so it appears in the world Component catalogue. Only a GM client writes the catalogue.

  • A new component whose source an existing world component already shares adopts that world component. The new component takes its id, no second world component is created, and the component follows any world category and world essence values that world component already carries until the system overrides them. A category staged by a folder-mapping import is kept as the system’s own override against a world category the adopted world component already carries. If the system already holds a component under that id, nothing is written to the catalogue.
  • A new component that no world component shares registers a new one from the component’s name, image, description and source. A newly registered component carries no world category and no world essence values, so the system resolves its own values until they are authored. A staged category is an ordinary value of the system, and a world category authored later replaces it in that system unless the system overrides it.
  • A component the import finds already present with no world component gains one, and it keeps every value it resolved before.
  • A component is left without one when the world component sharing its source has a different id from the component’s own, typically because another system imported the item first. Linking it would renumber a component that recipes, salvage results, gathering drops, tools and owned items may name. To recover, check what uses the other system’s component for that item, then remove it from every system that holds it, which rewrites the recipes that name it. Then delete the other world component in the catalogue, which is only possible once no system holds it, and import again. Where several systems hold the same item, import it again first in the systems that already hold it, because importing it into a new system first gives that system a world component the older components cannot adopt.
  • An Item that belongs to an actor is imported as before and registers nothing.
  • A call with persist: false and no registrations array registers nothing, because it has no way to flush after its own save.
  • With no catalogue available, the import behaves as it did before.

The catalogue write follows the system write and is issued only after it succeeds. If the catalogue write fails, the import still resolves, and worldRegistrationError reports it. Importing the same items again registers them.

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  const result = await mgr.addItemFromUuid(
    'alchemy-system-id',
    'Compendium.dnd5e.items.moonpetalHerb123'
  );
  if (result.action === 'added') {
    console.log(`Added: ${result.item.name} (componentId: ${result.item.id})`);
  } else if (result.action === 'updated') {
    console.log(`Updated metadata for: ${result.item.name}`);
  } else {
    console.log(`Already registered: ${result.item.name} — no changes needed.`);
  }
});

addItemsFromPack(systemId, packId)

Imports all Item documents from a compendium pack into the system as components. GM only.

Each item is processed via addItemFromUuid(), so the same source-chain deduplication rules apply: items already registered by the same live UUID, or by a copy of the same compendium entry that keeps the entry’s name, are updated or skipped in place, and only unclaimed source chains create new components. A pack item and a single drop of the same entry land on the same component. Every component is registered as a world component under the same rules as addItemFromUuid(). The whole run costs one write of the system and then one write of the world Component catalogue, and a run that registers nothing writes nothing to the catalogue.

Parameter Type Description
systemId string System ID
packId string Compendium pack identifier in "scope.name" format (e.g. "dnd5e.items")

Returns: Promise<{ added: number, updated: number, skipped: number, total: number, sourceFallbacks: object[], worldRegistrationError?: Error }>

  • added is the number of items created as new components on this call.
  • updated is the number of items already registered whose name, image, or description was refreshed from the source.
  • skipped is the number of items already registered and already up to date, with no changes written.
  • total is the total number of Item documents found in the pack.
  • sourceFallbacks holds aggregated broken source-link fallback notices from imported items.
  • worldRegistrationError is present only when the world Component catalogue could not be written. The imported components are still in the system.

Throws: Error if the system ID or pack ID is not found.

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  const result = await mgr.addItemsFromPack(
    'herbalism-system-id',
    'world.herbs-and-reagents'
  );
  console.log(
    `Imported ${result.added} new, updated ${result.updated}, ` +
    `skipped ${result.skipped} of ${result.total} items.`
  );
});

You can also trigger bulk import from the UI by dragging a compendium pack header onto the Items tab drop zone in the Crafting Admin panel. The same deduplication logic applies. See Bulk compendium pack drop for details.

flushWorldComponentRegistrations(registrations)

Writes the world component registrations that a caller collected through the registrations option of addItemFromUuid(), in one write of the world Component catalogue. Call it after your own save of the system has resolved, and call it even when that save was not needed, because importing items that are already in the system can still register them. For a non-GM client it writes nothing and answers { registered: 0, error: null } instead of throwing.

Parameter Type Description
registrations object[] The array you passed as options.registrations, and give each run its own array

Returns: Promise<{ registered: number, error: Error | null }>

  • registered is the number of components it registered.
  • error is the failure when the catalogue write was rejected, otherwise null. It does not throw for that failure, so it is safe inside a finally block.

It registers only components the saved system still holds, so a component whose save failed, or that was deleted in the meantime, is skipped. A run that has nothing to register writes nothing.

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  const registrations = [];
  for (const uuid of itemUuids) {
    await mgr.addItemFromUuid('alchemy-system-id', uuid, { persist: false, registrations });
  }
  await mgr.save();
  const { error } = await mgr.flushWorldComponentRegistrations(registrations);
  if (error) ui.notifications.warn('The world Component catalogue could not be updated.');
});

addToolFromUuid(systemId, itemUuid)

Registers a single Foundry Item document directly as a first-class Tool in the system’s Tools library (issue 561). GM only.

The Item does not need to be imported as a component first. Tool registration follows the same name-based rule as components: an item built from a compendium entry and renamed becomes its own tool instead of updating one registered from the same entry. As with a component, a tool is not matched through a compendium source that does not resolve, so items sharing a missing entry register as separate tools. The split is permanent once made, and the recovery is to delete the extra tool, restore the entry, and import the item again. The new tool carries its own source references and a name/image display snapshot captured from the Item, and componentId is null. The method stamps the durable tool identity flag (flags.fabricate.roles[systemId].toolId) on the source Item so future copies are recognised. An Item that is already a managed component can also be registered as a tool this way, in which case the Item carries both the component and tool role flags.

Parameter Type Description
systemId string System ID
itemUuid string UUID of the Foundry item to register as a tool

Returns: Promise<{ item: object, action: 'added' }>

Throws: Error if the system ID is not found, or if the UUID resolves to a non-Item document.

Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  const result = await mgr.addToolFromUuid(
    'blacksmithing-system-id',
    'Item.hammer123'
  );
  console.log(`Registered tool: ${result.item.name} (toolId: ${result.item.id})`);
});

updateItem(systemId, itemId, updates)

Updates a component’s properties (category, tags, essences, difficulty, salvage). GM only.

Parameter Type Description
systemId string System ID
itemId string Component ID
updates object Partial item data

Returns: Promise<object>

If updates changes registeredItemUuid, originItemUuid, or aliasItemUuids, the manager enforces the same per-system uniqueness rule used by imports. An update that would make two components claim the same source-reference chain throws an Error.

updates is shallow-merged over the stored component, so a field you omit is preserved. Note this merge is shallow: updates.salvage REPLACES the whole stored salvage sub-object rather than merging into it, so a partial patch such as { salvage: { enabled: true } } drops resultGroups. Spread the existing sub-object when patching one of its keys.

category

category is the component’s single-valued grouping axis, and it drives grouping and filtering in the GM component browser. It is normalised to a non-empty string on every write. Any unusable value (a non-string, an empty string, or an absent key) reads as the reserved 'general' bucket, so every component has a category and there is no uncategorised state. This default is applied by normalisation rather than by a migration.

category is distinct from tags, which is many-valued and is not a grouping axis.

The system’s authored vocabulary lives in the top-level componentCategories array on the system. It is a sibling of the recipe categories array and is deliberately independent of it: the two vocabularies are never merged or cross-populated, so a component category is never offered as a recipe category. The reserved 'general' bucket is implied and is never stored in componentCategories. A category naming no entry in the vocabulary is still stored and shown verbatim.

// Categorise a component. Existing fields are preserved by the shallow merge.
Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateSystem('dragoncraft-system-id', { componentCategories: ['Reagent', 'Scale'] });
  await mgr.updateItem('dragoncraft-system-id', 'dragon-scale-component-id', {
    category: 'Scale'
  });
});

salvage

When features.salvage is enabled on the system, you can set the salvage sub-object here. The shape is normalised on write. See Component Salvage for the GM-facing walkthrough.

salvage.enabled gates salvageability per component and defaults to false. It is clamped to false whenever the normalised salvage.resultGroups is empty, because a component that is salvageable but yields nothing is a forbidden state. The clamp only ever turns enabled off, so it never enables salvage on a component that did not ask for it. This runs on every write, including imports, so { enabled: true, resultGroups: [] } normalises to { enabled: false, resultGroups: [] }.

// Configure salvage for a Dragon Scale component
Hooks.once('fabricate.ready', async () => {
  const mgr = game.fabricate.getCraftingSystemManager();
  await mgr.updateItem('dragoncraft-system-id', 'dragon-scale-component-id', {
    salvage: {
      enabled: true,
      ingredientQuantity: 1,
      resultGroups: [
        {
          id: 'rg-scales',
          name: 'Scale Shards',
          results: [{ componentId: 'scale-shard-component-id', quantity: 2 }]
        }
      ]
    }
  });
});

deleteItem(systemId, itemId)

Removes a component from the system. GM only.

When a component is deleted, any essence definitions that had their sourceItemUuid pointing to that item are automatically updated. Their sourceItemUuid is set to null.

Returns: Promise<boolean>

deleteComponents(systemId, componentIds)

Removes several components from the system in one craftingSystems write and one recipes write. GM only.

Recipes that name a removed component are rewritten once each, and a recipe left without a usable ingredient set or result is disabled. Essence definitions that pointed at a removed component have those links cleared.

Once the system save resolves, the call also removes this system’s membership records for the removed components. Another system’s membership for the same component is kept. The prune reads the persisted systems after the write and removes a record only when that snapshot no longer holds the component’s row. A snapshot that still holds the row or cannot be read removes nothing, a failed membership save is logged, and in every case the delete itself still succeeds.

Returns: Promise<{deleted, componentIds, recipesUpdated, recipesDisabled, membershipsParted}>

Field Type Description
deleted number Components removed from the system.
componentIds string[] Their ids.
recipesUpdated number Recipes rewritten.
recipesDisabled number Recipes this call took from enabled to disabled.
membershipsParted number This system’s membership records removed. 0 when nothing was pruned.

Essence Methods

getEssenceDefinitions(systemId)

Returns all essence definitions for a system.

Returns: object[]

Each returned object has the following shape:

Field Type Description
id string Unique identifier derived from the name
name string Display name
description string Flavour text (may be empty)
icon string FontAwesome class string. Always a non-empty string, and defaults to fas fa-mortar-pestle.
colorToken string\|null Palette key for the essence’s colour, or null for the theme accent default
enabled boolean Default true. Gates essence-carried behaviour only, never essence arithmetic: a disabled essence still matches, accumulates, and is consumed, but neither its effect transfer nor its property macro runs. See Essences.
propertyMacroUuid string\|null UUID of a script Macro run against every result this essence contributes to, before that item is created. Requires features.propertyMacros and features.essences. See Essences.
sourceItemUuid string\|null Authoritative field. The componentId of the component linked to this essence, or null.
const mgr = game.fabricate.getCraftingSystemManager();
const essences = mgr.getEssenceDefinitions('alchemy-system-id');
for (const ess of essences) {
  console.log(`${ess.name} (${ess.id}) — icon: ${ess.icon}`);
}

getEssenceDefinition(systemId, essenceId)

Returns a single essence definition by its ID.

Parameter Type Description
systemId string System ID
essenceId string Essence ID

Returns: object | null

const ess = mgr.getEssenceDefinition('alchemy-system-id', 'fire');
if (ess) {
  console.log(`Fire essence icon: ${ess.icon}`);
  console.log(`Source item: ${ess.sourceItemUuid ?? 'none'}`);
}

Internal Normalisation Helpers

These methods are called automatically by createSystem, updateSystem, createItem, addItemFromUuid, addItemsFromPack, and updateItem. You do not call them directly, but understanding them helps when inspecting or migrating stored data.

The bodies of _normalizeSalvage, _normalizeToolIds, _normalizeSalvageResult, _normalizeSalvageResultGroup, _normalizeTimeRequirement, and _normalizeCurrencyRequirement live in src/systems/normalize/salvage.js as free functions. They are reached only through these manager delegates, so they remain documented here as manager methods.

_normalizeCraftingCheck(check)

Normalises the craftingCheck object on a crafting system. Applies defaults for all fields including enabled, consumption, outcomes, and the per-mode simple, routed, and progressive sub-objects (each with its own rollFormula). enabled is the on/off toggle for the optional simple-mode check. A check becomes usable only when its resolution-mode sub-object carries an authored rollFormula.

_normalizeSalvage(salvage = {}, options = {})

Normalises the salvage sub-object for a single component. Called by _normalizeComponent when features.salvage is true on the system.

Applies defaults: enabled: false, allowPlayerResultReorder: true, ingredientQuantity: 1, toolIds: [], resultGroups: []. The optional fields outcomeRouting, timeRequirement, and currencyRequirement are included only when present and non-null in the input.

enabled is normalised as salvage.enabled === true && resultGroups.length > 0, so it is clamped to false whenever the normalised resultGroups is empty. This enforces the Component invariant that an enabled salvage configuration has at least one result group. The normaliser is the single chokepoint every writer passes, so the clamp holds for API writes, imports, copy-mode, and migrations alike, not only for the GM editor. The clamp only ever turns enabled off, never on, so it seeds nothing and no migration accompanies it.

allowPlayerResultReorder is the GM-authored permission for player re-ordering of this component’s progressive salvage result stages (issue 651). It is normalised as salvage.allowPlayerResultReorder !== false, so an absent key reads as true and only an explicit false pins the authored order. The same default is applied when the component carries no salvage object at all. It is read in progressive salvage mode only, and it replaces the retired system-level salvageCraftingCheck.progressive.allowPlayerReorder.

_normalizeToolIds(toolIds)

Normalises salvage.toolIds (the library Tool ids required for the salvage operation). Coerces to trimmed, non-empty, deduped strings. Tolerant of non-array / nullish input (returns []).

_normalizeSalvageResult(result)

Normalises a single entry in a result group’s results array. Uses componentId as the identifier field. quantity must be a positive finite number. Invalid values fall back to 1.

_normalizeSalvageResultGroup(group)

Normalises a single entry in salvage.resultGroups. Assigns a random ID when id is absent. Falls back to "Result Group" when name is absent or empty. Normalises each entry in results via _normalizeSalvageResult. Returns null for invalid input. null entries are filtered out.

_normalizeTimeRequirement(time)

Normalises a time requirement object. Accepts any combination of minutes, hours, days, months, and years. Only keys whose values are positive finite numbers are included in the output. Zero, negative, or non-numeric values are dropped entirely.

_normalizeCurrencyRequirement(currency)

Normalises a currency requirement object. unit defaults to "gp" when absent or empty. amount must be a positive finite number. Invalid values produce 0.

_normalizeSalvageCraftingCheck(check)

Normalises the system-level salvageCraftingCheck object. See the field reference table in createSystem above for the full default and validation rules applied by this method.