sword-engine

Pure game rules engine for Il Tempo della Spada (SwORD system). Zero platform dependencies.

This package contains all game mechanics as pure functions: they take plain objects and return plain objects, with no side effects. It can be used by any platform adapter (Foundry VTT, Discord bots, CLI tools, etc.).

Used by the SwORD Foundry VTT System. Adapters build an intent from UI choices, roll dice, call a use-case function, then apply the returned patches to the platform's data layer.

Modules

Usage

Low-level: check pipeline

import { swordCheckResolve } from "sword-engine";

const result = swordCheckResolve({
  characteristicScore: 10,
  diceCount: 2,
  grade: 4,
  extraDice: 0,
  successBonus: 0,
  successPenalty: 0,
  difficultyThreshold: null,
  opposedSuccesses: null,
  diceRolled: [6, 5],
  discardIndices: null
});
// result.finalSuccesses === 2

High-level: full skill check with resources

import { resolveCheck } from "sword-engine";

const { engineOutput, valoreUsed, patches } = resolveCheck(
  {
    characteristicScore: 10,
    diceCount: 2,
    grade: 3,
    extraDice: 0,
    focusDice: 1,
    valoreSelected: "honor",
    valoreScore: 2,
    spiritoCancelPenalty: 1
  },
  {
    fatiguePenalty: 1, woundPenalty: 0,
    spirito: 8, fama: 2, fatica: 10, riflessi: 10
  },
  [4, 2, 1] // pre-rolled dice
);
// engineOutput.finalSuccesses includes valore bonus
// patches = { "resources.spirito": 4 } (3 valore + 1 cancel)

Combat: attack → defense → outcome

import { resolveAttack, resolveDefenseCheck, resolveDefenseOutcome } from "sword-engine";

// 1. Attacker rolls
const attack = resolveAttack(
  {
    characteristicScore: 10, diceCount: 3, grade: 3,
    approach: "carica", specialMove: "targetedAttack",
    specialMoveTarget: "weaponArm_chest"
  },
  { fatiguePenalty: 0, woundPenalty: 0, spirito: 8, fama: 2, fatica: 12, riflessi: 10 },
  [6, 4, 1] // pre-rolled dice
);
// attack.effectiveAttackHit, attack.patches

// 2. Defender rolls (character)
const defense = resolveDefenseCheck(attack, {
  characteristicScore: 9, diceCount: 2, grade: 2,
  defenseMode: "schivata"
}, { fatiguePenalty: 0, woundPenalty: 0, spirito: 5, riflessi: 8 }, [5, 3]);

// 3. Resolve outcome (shared by all 4 defense flows)
const outcome = resolveDefenseOutcome(
  { ...attack, damageValue: 3, damageType: "T" },
  { defenseSucceeded: defense.defenseSucceeded, netSuccesses: defense.engineOutput.netSuccesses },
  { woundLevels: {graffi:0,leggere:0,gravi:0,critiche:0,mortali:0},
    woundCapacities: {graffi:3,leggere:2,gravi:2,critiche:1,mortali:1},
    fatica: 10, riflessi: 8 }
);
// outcome.damageResult, outcome.forzaReactions, outcome.patches

Reactions

import { resolveReaction, REACTION_SKILL_MAP } from "sword-engine";

const result = resolveReaction(
  { reactionType: "paura", threatSuccesses: 3, characteristicScore: 8,
    diceCount: 2, grade: 2, inCombat: true },
  { fatiguePenalty: 1, woundPenalty: 0, spirito: 5, fatica: 10, riflessi: 8 },
  [4, 3]
);
// result.passed, result.fearOutcome, result.fearFatigaLost, result.patches

Tests

npm test

Runs 4,894 tests across 18 test suites (check, combat, talent, equipment, bestiary, sfida, rest, resolve-check, resolve-attack, resolve-defense, resolve-reaction, ars-oratoria, contacts, interlude, resolve-sfida-turn, resolve-ars-oratoria-turn, resolve-contacts, resolve-interlude).

Changelog

1.3.0

Features:

• combat.mjs: resolveDamage now accepts attackerSizeCategory parameter. Grande/Enorme creatures use multiplicative damage (netSuccesses × weaponDamage). Default "media" preserves additive behavior.
• resolve-attack.mjs: targetSizeCategory parameter for target size bonuses (Piccola -1, Grande +1 ranged, Enorme +2 ranged / +1 melee). targetMounted parameter for mounted vs unmounted +1 bonus.
• All 5 resolve functions: Spirito overflow to Fatica when spending takes Spirito below 0.
• combat.mjs: hitShield special move difficulty (2).

1.2.0

Bug fix:

• combat.mjs: Grapple difficulty now uses targeted attack difficulty minus 1 (PDF line 2666). Previous values matched targeted attack exactly. New values: head/vitals 3 (was 4), legs/shieldArm 2 (was 3), weaponArm/chest 1 (was 2).

1.1.0

Bug fix:

• rest.mjs: Rest failure Fatica loss now uses effective condition penalty (after Spirito cancellation) instead of raw condition penalty. Per PDF line 1600: "1 Fatica per uncontested success." Previously, spending Spirito to cancel penalty still resulted in the full penalty Fatica loss on failure.

Feature: Encumbrance penalty in all resolve functions:

• All 5 use-case resolve functions now include state.encumbrancePenalty (default 0) in the basePenalty computation. Per PDF §12.3: encumbrance penalty applies to all checks.
• Affected files: resolve-check.mjs, resolve-attack.mjs, resolve-defense.mjs, resolve-reaction.mjs, resolve-ars-oratoria-turn.mjs.
• Backward compatible: encumbrancePenalty defaults to 0 when not provided.

1.0.0

Initial release. Full implementation of the SwORD check engine, combat mechanics, extended tests, social challenges, contacts, interludes, rest/meditation, 72 talents, 12 cultures, 60 equipment items, 39 creatures.

License

MIT