isscrolls.1

.\"
.\" Copyright (c) 2021-24 Matthias Schmidt
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
.Dd September 24, 2024
.Dt ISSCROLLS 1
.Sh NAME
.Nm isscrolls
.Nd Player toolkit for the Ironsworn Family Tabletop RPG
.Sh SYNOPSIS
.Nm isscrolls
.Op Fl bc
.Sh DESCRIPTION
.Nm
is a toolkit for players of the Ironsworn tabletop RPG.
It supports classic Ironsworn, Delve, Starforged and Sundered Isles.
It is intended for both solo and co-op play and allows to track your
character's progress including vows, roll on adventure and exploration moves,
tracks progress for fights, journeys and expeditions and provides results
from the static oracle tables from the official rulebook.
The options are as follows:
.Bl -tag -width Ds
.It Fl b
Suppress the banner on startup.
.It Fl c
Enable colors and additional characters to beautify output.
Recommended if you don't use a screen reader or a braille terminal.
.It Fl x
Roll a
.Dq cursed die
alongside the other dice.
This is a speciality of the
.Em Sundered Isles
expansion, however, it can be used for the other games as well.
.El
.Sh HOW TO USE
.Nm
basically works like a
.Ux
shell.
Commands can be entered and will show their output.
Certain commands need an argument in order to run properly, other commands
might support optional arguments.
Once a character is loaded, the prompt will change and display the
character's name.
The
.Ic help
command will show an overview of all available commands.
.Pp
.Nm
is linked against
.Xr readline 3 ,
thus any shortcut or character combination that work with a common
.Ux
shell also work for the built-in shell.
.Ss Information for general Gameplay
.Nm
supports all games of the Ironsworn family and allows players to freely
use moves or actions from all of them.
Therefore, depending on the game you own you might see statistics or
information that belong to another game, e.g., characters get experience
points in classic Ironsworn for fulfilling vows while in Starforged they
get experience via the so called
.Em legacy track .
Both ways are supported by
.Nm
so choose the one that fits your game the most.
.Pp
Sometimes
.Nm
cannot take a decision for you and refers you to the official rulebook.
In these cases choose the outcome most suitable for your character and
manipulate the stats with the
.Ic increase ,
.Ic decrease
or
.Ic toogle
commands.
See the section below for more information how the commands work.
.Ss Character Display
.Nm
is best used if you generate a character with the
.Ic create
command and load it afterwards with the
.Ic cd
command.
Once you load a character, their current stats will be printed which looks
similar to the following:
.Bd -literal -offset indent
Name: Erin Kalina (Exp: 7/30) Exp spent: 4

Edge: 4 Heart: 3 Iron: 2 Shadow: 2 Wits: 3

Momentum: 10/10 [2] Health: 4/5 Spirit: 5/5 Supply: 3/5

Wounded:        0 Unprepared:   0 Encumbered:   0 Shaken:       0
Corrupted:      0 Tormented:    0 Cursed:       0 Maimed:       1

Bonds: 0.00 (L: 0) Quests: 0.00 (L: 0) Discoveries: 0.00 (L: 0)
.Ed
.Pp
The first line shows the character's name, their experience points, the
amount of experience points spent to acquire new resources or improve
existing ones and their failure track in ticks in case the character has rolled
more than one miss.
.Pp
The second line shows the character's stats and the third one the current
values.
The number in the square brackets after
.Em Momentum
is the reset momentum.
.Pp
Debilities are shown in the next two lines, a 0 means that the character
does not suffer from this particular debility while a 1 means that they
suffer from it.
.Pp
The last line shows the character's progress for bonds, quests and
discoveries including the progress on the legacy tracks.
.Ss Vows, Expeditions, Journeys, Fights and Delve
As soon as a character starts one of them, the prompt changes and
displays the current undertaking and the current progress.
.Pp
Progress will be tracked automatically according to the rank.
For lower ranks (Troublesome - Formidable),
progress will be shown as absolute numbers, e.g. a 2 represents
two boxes.
For higher ranks (Extreme and Epic), progress will be shown as decimal
numbers and 0.25 represents one tick,
e.g. 0.75 means that the character already made 3 ticks progress.
Since
.Em Ironsworn's
progress bar is always 10 boxes, only the current progress is shown.
.Pp
In case the rulebook gives you more options, you always have the possibility
to manually mark progress with the
.Ic markprogress
command.
In case you have an active vow, its title and description will be shown.
.Sh AVAILABLE COMMANDS
The following sections shows all commands that can be entered on
.Nm
command prompt.
.Ss General Commands
This sub-section shows general commands that are not dice rolls and game moves.
.Bl -tag
.It Ic cd Op name
Load the character
.Op name ,
if it exists.
If
.Op name
is not provided and a character is loaded, the character is saved and unloaded.
.It Ic help
Show an overview of all available commands.
.It Ic ls
List all available characters.
.It Ic quit
Quits
.Nm
and saves all characters, journeys, fights, delves, vows  and the command line
history.
.It Ic save
Saves the current character including an active vow, journey, fight, or delve.
.El
.Ss Dice Rolls
The following commands can be used to roll dice according to the game's
mechanics.
They can be used since
.Nm
does not provide commands for all moves in the game.
.Bl -tag
.It Ic action Cm stat Op bonus
Roll one
.Em action die
and two
.Em challenge dice .
Providing one number as
.Cm stat
is mandatory.
Provide an optional
.Op bonus .
.It Ic challenge
Roll one
.Em challenge die .
.It Ic oracle
Roll one
.Em oracle die .
.It Ic markabond
Mark a bond.
Usually, this is done automatically if you have a strong hit on the
.Ic forgeabond
move.
On a weak hit, consult the Rulebook first and then use this command.
.It Ic markprogress
Mark progress according to the rank.
.Nm
progresses the undertaking in the following order:
.Bl -enum -compact
.It
Fight
.It
Delve
.It
Journey
.El
.It Ic yesorno Cm odds
Roll two
.Em challenge dice
to get an answer to a yes/no question from the oracle.
.Cm odds
has to be a number (1-5) of the following list:
.Bl -enum -compact
.It
Almost certain
.It
Likely
.It
50/50
.It
Unlikely
.It
Small chance
.El
.It Ic burnmomentum
Burn your character's momentum and set it to the reset momentum.
.El
.Ss Character Commands
The following commands can be used to modify your character.
.Nm
supports multiple characters, however, only one can be loaded at a time.
Most commands do nothing or present a warning if no character is loaded.
.Bl -tag
.It Ic create Op name
Create a new character.
If the optional argument
.Op name
is provided, it will be used as the character's name.
Otherwise, the name will be asked interactively.
.It Ic decrease Cm stat
Decrease the character's value
.Cm stat .
You can also decrease the progress of a fight or a journey.
Hereby, the progress is automatically decreased according on the rank.
You can also decrease the progress of or the quest,
discovery and failure track.
.Pp
To give the player a bit more flexibility, this allows to decrease values even
if this is forbidden by the official rulebooks.
.Pp
The following values can be decreased:
.Bl -bullet -compact
.It
Edge
.It
Heart
.It
Iron
.It
Shadow
.It
Wits
.It
Momentum
.It
Health
.It
Spirit
.It
Supply
.It
Exp
.It
Expspent (the experience you spent to acquire new resources or improve
existing ones).
.It
Weapon (hereby
.Em 1
means a simple weapon doing 1 harm and
.Em 2
means a deadly weapon doing 2 harm).
.It
failure (progress on the failure track)
.It
quests (progress on the quests (vows) track)
.It
discoveries (progress on the discoveries track)
.El
.It Ic delete
Delete the current character without warning!
.It Ic increase Cm stat
Opposite of the
.Ic decrease
command described above.
.It Ic print
Print the current character's stats.
.It Ic toggle Cm stat
Toggle a character's stat named
.Cm stat .
If it's set to 0, it will be set to 1 or vice versa.
The following values can be modified.
.Bl -bullet -compact
.It
Wounded
.It
Unprepared
.It
Shaken
.It
Encumbered
.It
Maimed.
Note that this is a permanent bane and cannot be changed once it has been set.
.It
Cursed.
Note that this is a permanent bane and cannot be changed once it has been set.
.It
Corrupted
.It
Tormented
.El
.El
.Ss Vow Management
The following commands let you manage vows.
Additional vow related commands can be seen below in the
Quest Move section.
.Bl -tag
.It Ic vowactivate Cm id
Activate the vow
.Cm id ,
with
.Cm id
being a number between 1 and 255.
Every vow has a unique number that can be seen with the
vowshow command.
Activating a vow means that the prompt shows the title and certain moves
will influence it.
.It Ic vowdeactivate
Opposite command which deactivates the current vow.
Certain vow related commands will not work.
.It Ic vowshow
Shows the character's vows including the following details:
.Bl -bullet -compact
.It
ID that can be used with vowactivate and vowdeactivate
.It
Title of every vow
.It
Current progress
.It
The rank
.It
Fulfillment status.
0 means unfulfilled, 1 means fulfilled.
.El
.El
.Ss Adventure and Exploration Moves
Adventure Moves are used as your character travels the Ironlands, investigates
situations and deals with threats.
Exploration moves are the same concept, however, the new name was introduced
with Ironsworn Starforged.
.Bl -tag
.It Ic facedanger Cm stat Op bonus
Roll a
.Em Face Danger
move using the character's stat named
.Cm stat .
This move can done using the following stats: edge, heart, iron, shadow, and
wits.
An additional
.Op bonus
can be provided.
.It Ic secureanadvantage Cm stat Op bonus
Roll a
.Em Secure an Advantage
move using the character's stat named
.Cm stat .
This move can done using the following stats: edge, heart, iron, shadow, and
wits.
An additional
.Op bonus
can be provided.
.It Ic gatherinformation Op bonus
Roll a
.Em Gather Information
move.
Provide an optional
.Op bonus .
.It Ic heal Cm who Op bonus
Roll a
.Em Heal
move.
If the character wants to heal themselves, the argument
.Cm me
has to be provided.
.Nm
automatically selects the character's Iron or Wits, whichever is lower.
If the character wants to heal someone else, the argument
.Cm others
has to be provided.
An additional
.Op bonus
can be provided.
.It Ic hearten
Roll a
.Em Hearten
move.
.It Ic resupply Op bonus
Roll a
.Em Resupply
move.
An additional
.Op bonus
can be provided.
.It Ic makecamp Op bonus
Roll a
.Em Make Camp
move.
.It Ic exploreawaypoint
Roll an
.Em Explore a Waypoint
move
Note that a strong hit with a match provides you with a different result..
.It Ic setacourse Op bonus
Roll an
.Em Set a course
move.
Provide an optional
.Op bonus .
.It Ic undertakeanexpedition Cm stat Op bonus
Roll an
.Em Undertake an Expedition
move using the character's stat named
.Cm stat .
This move can done using the following stats: edge, shadow, and wits.
Provide an optional
.Op bonus .
.Pp
In case this is the first move of a new expedition,
.Nm
will ask for a rank and save it for the character.
.It Ic undertakeajourney Op bonus
Roll an
.Em Undertake a Journey
move.
Provide an optional
.Op bonus .
.Pp
In case this is the first move of a new journey,
.Nm
will ask for a rank and save it for the character.
.It Ic finishanexpedition Op bonus
Roll a
.Em Finish an Expedition
move.
In case of a
.Em miss
, the character can choose to abort the expedition or continue with it.
An additional
.Op bonus
can be provided.
.It Ic reachyourdestination Op bonus
Roll a
.Em Reach Your Destination
move.
In case of a
.Em miss
, the character can choose to abort the journey or continue with it.
An additional
.Op bonus
can be provided.
.El
.Ss Relationship Moves
The following moves are made as the character interacts with others in the wild,
fight duels, form bonds, supports their allies, and determines the ultimate
fate.
.Bl -tag
.It Ic compel Cm stat Op bonus
Roll a
.Em Compel
move using the character's stat named
.Cm stat .
This move can done using the following stats: heart, iron, and shadow.
An additional
.Op bonus
can be provided.
.It Ic sojourn Op bonus
Roll a
.Em Sojourn
move.
Provide an optional
.Op bonus .
.It Ic drawthecircle Op bonus
Roll a
.Em Draw The Circle
move.
Provide an optional
.Op bonus .
.It Ic makeaconnection Op bonus
Roll a
.Em Make a Connection
move.
An additional
.Op bonus
can be provided.
Note that
.Nm
does not ask your for a rank and does not track connections, this is up to
the player.
.It Ic forgeabond Op bonus
Roll a
.Em Forge a Bond
move.
An additional
.Op bonus
can be provided.
.It Ic testyourbond Op bonus
Roll a
.Em Test Your Bond
move.
An additional
.Op bonus
can be provided.
.It Ic testyourrelationship Op bonus
Roll a
.Em Test Your Relationship
move.
An additional
.Op bonus
can be provided.
.It Ic writeyourepilogue
Roll a
.Em Write your epilogue
move.
.El
.Ss Combat Moves
When there are no other options, when the sword flips free of its sheath, when
the arrow is nocked, when the shield is brought to bear, these moves can
be made.
.Bl -tag
.It Ic enterthefray Cm stat Op bonus
Roll an
.Em Enter the Fray
move using the character's stat named
.Cm stat .
This move can done using the following stats: heart, wits, and shadow.
.Pp
In case this is the first move in a fight,
.Nm
will ask for a rank and save it for the fight.
Progress per harm will be tracked automatically according to the rank.
For lower ranks (Troublesome - Formidable), progress will be shown as absolute
numbers, e.g. 2/10.
For higher ranks (Extreme and Epic) progress will be shown as decimal
numbers and 0.25 represents one tick,
e.g. 0.75/10 means that the character already made 3 ticks progress.
An additional
.Op bonus
can be provided.
.It Ic gainground Cm stat Op bonus
Roll an
.Em Gain Ground
move using the character's stat named
.Cm stat .
This move can done using all stats.
An additional
.Op bonus
can be provided.
.It Ic reactunderfire Cm stat Op bonus
Roll an
.Em React under Fire
move using the character's stat named
.Cm stat .
This move can done using all stats.
An additional
.Op bonus
can be provided.
.It Ic endthefight Op bonus
Roll an
.Em End the Fight
move.
An additional
.Op bonus
can be provided.
.Nm
checks automatically that your last move was a strong hit.
.It Ic strike Cm stat Op bonus
Roll a
.Em Strike
move using the character's stat named
.Cm stat .
This move can done using the following stats: iron, and edge.
An additional
.Op bonus
can be provided.
.It Ic clash Cm stat Op bonus
Roll a
.Em Clash
move using the character's stat named
.Cm stat .
This move can done using the following stats: iron, and edge.
An additional
.Op bonus
can be provided.
.It Ic battle Cm stat Op bonus
Roll a
.Em Battle
move using the character's stat named
.Cm stat .
This move can done using the following stats: edge, heart, iron, shadow, and
wits.
An additional
.Op bonus
can be provided.
.El
.Ss Quest Moves
The commands represent important moves characters make during their quest.
.Bl -tag
.It Ic fulfillyourvow
Roll a
.Em Fulfill your Vow
move.
The active vow will be set as fulfilled so that the player cannot activate
it again.
Your character receives experience points equal to the rank of the vow.
.It Ic forsakeyourvow
Roll a
.Em Forskace your Vow
move.
The active vow will be forsaken and removed from the list of vows.
Your character will endure stress equal to the rank of the quest.
.It Ic reachamilestone
Roll a
.Em Reach a Milestone vow
move.
The progress of the active vow is advanced equal to the rank.
.It Ic swearanironvow Op bonus
Roll a
.Em Swear an Iron Vow
move.
You will be asked for a title - which is like a short description of the vow -
and a longer description.
The prompt changes and shows the title of the active vow and the current
progress.
Provide an optional
.Op bonus .
.El
.Ss Suffer Moves
These moves are made as a result of a perilous event or bad outcome on other
moves.
They represent what happens to the character, and how they hold up against
the trauma.
.Bl -tag
.It Ic endureharm Op value
Roll an
.Em Endure Harm
move.
In case the character is in a fight, the amount of harm to suffer is
automatically derived from the foe's rank.
If the character is not in a fight, the amount of harm to suffer can be
provided with the optional argument
.Op value .
Since there are multiple options on what can happen on a
.Dq miss ,
the decision is up to the player and not implemented in
.Nm .
.It Ic facedeath Op bonus
Roll a
.Em Face Death
move.
In case the character dies, it is marked as such and
.Dq Deceased
is printed in the character's statistics.
An additional
.Op bonus
can be provided.
.It Ic facedesolation Op bonus
Roll a
.Em Face Desolation
move.
An additional
.Op bonus
can be provided.
.It Ic endurestress Cm value
Roll an
.Em Endure Stress
move.
Provide a
.Cm value
that will be removed from your spirit.
Since there are multiple reasons why the character can suffer stress, the
amount of
.Em Spirit
to suffer has to be provided and is not implemented within
.Nm .
.It Ic sacrificeresources Cm value
Roll an
.Em Sacrifice Resources
move.
Provide a
.Cm value
that will be removed from your supply.
.El
.Ss Delve Moves
These moves are part of the
.Em Ironsworn Delve
supplement.
They will help you delve into sites and hopefully locate your objective.
.Bl -tag
.It Ic learnfromyourfailures
Roll a
.Em Learn from your Failures
move.
This is a progress move where the result is compared against the failure
track.
It can only be used if the character has more than 6 boxes marked in the
failure track.
The latter is automatically tracked by
.Nm
and reset after this move.
Although this is a character move, it is part of the
.Em Delve
supplement.
.It Ic discoverasite
Roll a
.Em Discover a Site
move.
This is the first move towards a delve into a site.
.Nm
will ask for the site's rank.
.It Ic delvethedepths Cm stat Op bonus
Roll a
.Em Delve the Depths
move using the character's stat named
.Cm stat .
This move can done using edge, shadow, and wits.
An additional
.Op bonus
can be provided.
.It Ic checkyourgear Op bonus
Roll a
.Em Check your Gear
move.
An additional
.Op bonus
can be provided.
.It Ic locateyourobjective
Roll a
.Em Locate your Objective
move.
.It Ic escapethedepths Cm stats Op bonus
Roll an
.Em Escape the Depths
This move can done using edge, heart, iron, shadow, and wits.
An additional
.Op bonus
can be provided.
.El
.Ss Oracle Moves
The following commands provide results from the various oracle tables in both
the
.Em Ironsworn
and
.Em Ironsworn Delve
Rulebook.
.Bl -tag
.It Ic generatenpc
Generate a random NPC with a role, a goal and their disposition.
.It Ic actionoracle
Show a random action.
.It Ic combataction
Show a random combat action.
.It Ic coastalwaterlocation
Show a random coastal waters location.
.It Ic elfname
Show a random elf name.
.It Ic findanopportunity
Show a random opportunity.
.It Ic giantname
Show a random giant name.
.It Ic ironlandername
Show a random Ironlander name.
.It Ic location
Show a random location.
.It Ic locationdescription
Show a random description for a location.
.It Ic moonoracle
Roll random on the
.Em Sundered Isles
moons, Wraith and Cinder.
.It Ic mysticbackslash
Show a random mystic backslash.
.It Ic paytheprice
Show a random
.Dq Pay the price
result.
.It Ic plottwist
Show a random plot twist.
.It Ic rank
Show a random rank.
.It Ic region
Show a random Ironlands region.
.It Ic revealadanger
Show a random danger region.
.It Ic settlementtrouble
Show a random settlement trouble.
.It Ic theme
Show a random theme.
.It Ic varou
Show a random Varou name.
.El
.Sh ENVIRONMENT
.Nm
makes use of the following environment variables.
.Bl -tag -width XDG_CONFIG_HOME
.It Ev HOME
If the
.Ev XDG_CONFIG_HOME
variable is not set,
.Nm
stores its history and other data in the
.Pa .config/isscrolls
subdirectory in the user's home directory.
.It Ev XDG_CONFIG_HOME
In case this variable is set,
.Nm
stores its history and other data in the
.Pa isscrolls
subdirectory below the path set by this environment variable.
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /usr/local/share/isscrolls
Contains shared files such as the JSON files for the oracle tables.
.El
.Sh EXIT STATUS
.Nm
normally exists with 0 or with 1 if an error occurred.
.Sh SEE ALSO
.Xr readline 3
.Sh STANDARDS
.Rs
.%A Shawn Tomkin
.%B Ironsworn. A tabletop RPG of perilous Quests
.%D 2018
.%U https://www.ironswornrpg.com/
.Re
.Pp
.Rs
.%A Shawn Tomkin
.%B Ironsworn Delve. Perilous Expeditions for the Ironsworn RPG
.%D 2020
.%U https://www.ironswornrpg.com/
.Re
.Pp
.Rs
.%A Shawn Tomkin
.%B Ironsworn Starforged
.%D 2022
.%U https://www.ironswornrpg.com/
.Re
.Sh AUTHORS
.Nm
was written by
.An Matthias Schmidt Aq Mt xhr@giessen.ccc.de .