Package Exports
- @federicomorando/sword-engine
- @federicomorando/sword-engine/ars-oratoria
- @federicomorando/sword-engine/check
- @federicomorando/sword-engine/combat
- @federicomorando/sword-engine/constants
- @federicomorando/sword-engine/contacts
- @federicomorando/sword-engine/data/bestiary
- @federicomorando/sword-engine/data/cultures
- @federicomorando/sword-engine/data/equipment
- @federicomorando/sword-engine/data/talents
- @federicomorando/sword-engine/interlude
- @federicomorando/sword-engine/rest
- @federicomorando/sword-engine/sfida
Readme
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
| Module | Description |
|---|---|
src/check.mjs |
9-step check pipeline + valore activation |
src/combat.mjs |
Damage, wounds, misura, reactions, grapple, mounted combat, talent effects |
src/sfida.mjs |
Extended tests: presets, approach modifiers, turn successes, resources |
src/rest.mjs |
Rest, meditation, fattucchiere: condition penalties, recovery |
src/constants.mjs |
Shared constants: skills, valori, approach mods, characteristic helpers |
src/data/talents.mjs |
72 talent definitions + unlock/progress logic |
src/data/cultures.mjs |
12 culture traits |
src/data/equipment.mjs |
25 weapons, 3 shields, 3 armor, 29 gear, pregi, currency, encumbrance |
src/data/bestiary.mjs |
39 creature stat blocks |
src/use-cases/resolve-check.mjs |
High-level skill check: valore, fama, combined maneuvers, penalties, resource patches |
src/use-cases/resolve-attack.mjs |
Attack resolution: approach, range, special moves, talents, mounted, resource patches |
src/use-cases/resolve-defense.mjs |
Defense check + outcome: damage, wound distribution, special moves, forza reactions |
src/use-cases/resolve-reaction.mjs |
All 7 reaction types: fear, cavalcare, fatigue, wounds, resource patches |
src/ars-oratoria.mjs |
Ars oratoria: risk-reward, outcome tiers, drain, senza parole |
src/contacts.mjs |
Contacts: ceto/region penalties, settlement limits, talent bonuses |
src/interlude.mjs |
Interlude: work earnings, bond costs, currency conversion |
src/use-cases/resolve-sfida-turn.mjs |
Sfida turn: resolveCheck + approach + accumulation + drain + deductions |
src/use-cases/resolve-ars-oratoria-turn.mjs |
Ars oratoria turn: opposed check + risk-reward + drain + combined + senza parole |
src/use-cases/resolve-contacts.mjs |
Contact creation: skill check with ceto/region penalties |
src/use-cases/resolve-interlude.mjs |
Interlude actions: study (PE), work (earnings), bond (cost check) |
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 === 2High-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.patchesReactions
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.patchesTests
npm testRuns 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).
License
MIT