the-sunken-reach/docs/WEAPONS.md

# Weapons

How weapons work in this app: the campaign's weapon pool, how a character
comes to hold a weapon, weapon levels, and how attack and damage numbers are
worked out.

This describes the code as it stands. The formulas live in
`backend/src/game/calculations.js`; the built-in list is
`backend/src/game/data/weaponsLibrary.js`. Related: [ITEMS.md](ITEMS.md),
[SPELLS.md](SPELLS.md), [CHARACTERS.md](CHARACTERS.md).

## Contents

1. [The basics](#1-the-basics)
2. [The weapon pool](#2-the-weapon-pool)
3. [The built-in library](#3-the-built-in-library)
4. [Giving weapons to characters](#4-giving-weapons-to-characters)
5. [Weapon levels](#5-weapon-levels)
6. [How damage grows](#6-how-damage-grows)
7. [Attack and damage numbers](#7-attack-and-damage-numbers)
8. [Starting weapons](#8-starting-weapons)
9. [Weapons as rewards and for sale](#9-weapons-as-rewards-and-for-sale)
10. [Permissions](#10-permissions)
11. [What is not modelled](#11-what-is-not-modelled)
12. [The complete weapon library](#12-the-complete-weapon-library)

---

## 1. The basics

- Every campaign has its own **weapon pool**. A weapon exists in one campaign
  only.
- A character never owns a free-standing weapon: it holds a **copy** of a pool
  entry, with its own quantity, level and equipped flag.
- The DM runs the pool and decides who gets what. Players can only equip and
  unequip what they hold.

## 2. The weapon pool

The pool is the "Weapons" part of the campaign page (DM only). It lists each
weapon as a short row: its name, base damage, starting level and what it does
while equipped. The list has a search box, shows ten to a page, and clicking a
row opens the weapon's **pop-out**, which shows everything below and is where
it is changed.

| Field | What it is |
|---|---|
| Name | Free text, up to 80 characters |
| Base damage | Dice such as `1d8` or `2d6` — the damage at the weapon's starting level |
| Damage type | Free text: slashing, piercing, fire… |
| Attack ability | Strength, Dexterity, or Finesse (whichever of the two is higher for the wielder) |
| Starts at level | 1 to 9. The lowest level this weapon can be (section 5) |
| Growth | Standard, Powerful or Legendary: how fast the dice climb per level (section 6) |
| Starting option | Whether a brand-new character may pick it in the builder (section 8) |
| Properties, range | Stored for library weapons (light, thrown, 20/60 ft…). Shown in the weapon's pop-out, and not used anywhere |
| Effects | What it does to whoever has it equipped: bonuses and penalties to the sheet's numbers, and a note. Works exactly as for items ([ITEMS.md](ITEMS.md), section 5) |

- **Adding:** by hand with "+ Add Weapon", or from the library. Both open in
  a pop-out. A weapon added by hand opens its own pop-out straight away, to
  set what it does; "+ Add another weapon" at its top goes straight back to
  an empty form.
- **Effects:** under "While equipped" in the weapon's pop-out, saved with
  "Save Effects". A defending blade can give +1 AC, a heavy maul −5 speed.
  They count only while the weapon is equipped, and do not change its own
  attack or damage.
- **Changing:** starting level, growth and the starting-option tick box are
  changed in the pop-out, and saved as they are changed. Name, damage, type
  and ability cannot be changed on screen once created (the API accepts it);
  remove and re-add instead.
- **Removing:** "Remove from campaign" at the foot of the pop-out, after a
  confirmation. This takes the weapon away from **every
  character holding it** and off every encounter's reward list. There is no
  undo.
- The same weapon can be added twice; nothing stops duplicate names.

## 3. The built-in library

"📚 From Library" offers 41 weapons to copy into the pool:

| Category | Count | Examples |
|---|---|---|
| Simple melee | 10 | Club 1d4, Dagger 1d4, Mace 1d6, Spear 1d6 |
| Simple ranged | 4 | Shortbow, Light Crossbow, Dart, Sling |
| Martial melee | 18 | Longsword 1d8, Rapier 1d8, Greataxe 1d12, Greatsword 2d6 |
| Martial ranged | 5 | Longbow, Heavy Crossbow, Hand Crossbow |
| Paired | 4 | Paired Daggers 2d4, Paired Shortswords 2d6, Paired Scimitars 2d6, Paired Handaxes 2d6 |

**Paired weapons.** A character has one weapon equipped at a time (section
4), so fighting with a weapon in each hand is not two weapons: it is **one
weapon made as a pair**, whose damage is both blades. The library has four,
and a DM makes others the same way with "+ Add Weapon" ("Twin Hammers",
2d4 bludgeoning).

A weapon added from the library arrives with starting level 1, Standard
growth, and **not** ticked as a starting option. Change those in the table
afterwards. Every library weapon is listed in
[section 12](#12-the-complete-weapon-library).

Each library weapon can be added once. A weapon the pool already has by that
name is left out of the library list, and comes back if the pool's weapon is
renamed or deleted.

## 4. Giving weapons to characters

On a character's sheet, the DM picks a weapon from the pool and clicks Give.

- It arrives at the weapon's starting level, quantity 1, unequipped.
- Giving a weapon the character already holds **adds to the stack**; the stack
  keeps the level it has. A character holds one stack per weapon, so two
  copies of the same weapon at different levels is not possible.
- The DM can take a weapon away with ✕ on the sheet.
- The owning player, or the DM, ticks **Equipped**. While the character is in
  a battle in progress, a player can only change it as the battle begins or on
  their own turn after their attack has landed
  ([ENCOUNTERS.md](ENCOUNTERS.md), section 5); the DM always can.
- **Only what is equipped counts.** A weapon has to be equipped to be used
  in an encounter, and gear only gives its effects while equipped. What is
  not equipped stays in the pack: still the character's, still listed on the
  sheet and in the character panel, but not in hand.
- **There is a limit on how much can be equipped at once**, set per campaign
  in Campaign Settings ("Equipped at once"):

  | Setting | Starts at | Means |
  |---|---|---|
  | Things equipped at once | 2 | Weapons and items together |
  | Of which weapons | 1 | So: one weapon, or one weapon and one item, or two items |

  Armor and shields are items and count toward the limit. With the starting
  numbers a character can have a weapon and a shield, or a weapon and armor,
  but not all three; a DM who wants armor, shield and weapon together sets
  the first number to 3.
- **Putting something on when the limit is reached is refused**, with a
  message naming what is already equipped. Take something off first.
- **Equipping can be changed at any time, including in the middle of an
  encounter**, by the owning player or the DM: on the sheet, or in the
  character panel (the 🧙 button, or "🎒 Inventory" on the character's
  encounter card).
- Lowering the limits takes nothing off anyone. A character with more on
  than the new limit keeps it until they change what they have equipped.
- Everything arrives unequipped: gear from the DM, from a reward, bought, or
  given by another character.

**Passing a weapon on.** A character's owner (or the DM) can give a held
weapon to another character in the campaign from the "Give to Another
Character" card on the sheet. Some or all of the stack moves: it leaves the
giver and arrives with the recipient at the giver's level, unequipped. If the
recipient already holds that weapon, their stack grows and keeps its own
level. A recipient below the weapon's level holds it but cannot use it yet.

## 5. Weapon levels

This is a house rule of this app, not standard D&D.

- Each held copy has a **level from 1 to 9**. Two characters can hold the same
  weapon at different levels.
- Only the DM changes a copy's level, with the level picker beside it on the
  sheet. Each option shows the damage at that level.
- A copy can never go below the pool entry's **starting level**. Raising a
  pool entry's starting level lifts any copies below it and unequips them.

**Who can use it.** A character must be at least the copy's level:

| Character level | Can use weapons of level |
|---|---|
| 1 | 1 |
| 2 | 1–2 |
| 5 | 1–5 |
| 9 and above | 1–9 |

A weapon above its holder's level is still held, but it shows "Requires level
N", cannot be equipped, and so is never on its holder's encounter card. The
character panel lists it, marked "needs level N". If the
DM levels a weapon past its holder, or lowers the character's level, it is
unequipped automatically.

## 6. How damage grows

The dice in the pool are the damage at the weapon's starting level. Each level
above that moves the dice up a fixed ladder, in the smallest steps dice allow:

| Rung | Dice | Average |
|---|---|---|
| 1 | 1d4 | 2.5 |
| 2 | 1d6 | 3.5 |
| 3 | 1d8 | 4.5 |
| 4 | 1d10 | 5.5 |
| 5 | 1d12 | 6.5 |
| 6 | 2d6 | 7 |
| 7 | 1d6+1d8 | 8 |
| 8 | 2d8 | 9 |
| 9 | 1d8+1d10 | 10 |
| 10 | 2d10 | 11 |
| 11 | 1d10+1d12 | 12 |
| 12 | 2d12 | 13 |
| 13 | 3d8 | 13.5 |
| … | adding a die each time the current dice max out | |

Every rung is +1 average damage over the last, or +0.5 where a die is added.

**Growth** sets how many rungs a weapon climbs per level:

| Growth | Rungs per level | A 1d6 weapon at levels 1, 2, 3, 4 | At level 9 |
|---|---|---|---|
| Standard | 1 | 1d6, 1d8, 1d10, 1d12 | 2d10 |
| Powerful | 2 | 1d6, 1d10, 2d6, 2d8 | 1d10+2d12 |
| Legendary | 3 | 1d6, 1d12, 2d8, 1d10+1d12 | 4d12 |

A weapon with a higher starting level counts from there: a 2d6 greatsword that
starts at level 3 with Standard growth is 2d6 at level 3, 1d6+1d8 at level 4
and 2d8 at level 5.

- At its starting level a weapon always shows its dice exactly as typed.
- Dice that are not on the ladder (`1d4+1`, `2d4+2`) climb from the highest
  rung that is not stronger than them: `2d4+2` (average 7) continues from 2d6.
- Dice the app cannot read (free text such as "special") never change.

## 7. Attack and damage numbers

| Number | Formula |
|---|---|
| Attack bonus | Ability modifier + proficiency bonus |
| Damage | The dice at the copy's level + ability modifier |

- The ability modifier is Strength, Dexterity, or the higher of the two for a
  Finesse weapon.
- The weapon's level changes the **dice only**, never the bonuses.
- Every character is treated as proficient with every weapon.

These numbers appear on the character sheet, in the quick-stats drawer, and
on the character's card in an encounter.

## 8. Starting weapons

In the builder's equipment step a new character can pick weapons that are:

- ticked as a **starting option** in the pool, and
- **starting level 1** (a new character is level 1).

Starting weapons and starting items share the campaign's "starting items"
allowance. They arrive at level 1, unequipped.

## 9. Weapons as rewards and for sale

On an encounter the DM can line up a weapon as a reward, at a chosen level
(not below its starting level) and quantity, and later award it to a
character. Awarding adds it to what the character holds, exactly as giving it
on the sheet would. See [ENCOUNTERS.md](ENCOUNTERS.md).

The DM can also put a weapon **up for sale**, at a level, a price (in gold,
silver, copper or cash) and an optional stock. An NPC can sell it, wherever
that NPC is met, or an encounter can sell it itself. Players see what is for
sale and buy it in an NPC quest that is in progress: the price leaves their
purse and the weapon joins what they hold, unequipped. See
[NPCS.md](NPCS.md), section 5, and [ENCOUNTERS.md](ENCOUNTERS.md), section 10.

## 10. Permissions

| Action | DM | Owning player | Other players |
|---|---|---|---|
| See the pool | Yes | Only what their own character holds, plus the starting options while they have a character to build | The same, for their own character |
| See the built-in library | Yes | No | No |
| Add, change or remove pool entries | Yes | No | No |
| Give a weapon from the pool, or take one away | Yes | No | No |
| Give a held weapon to another character | Yes | Yes | No |
| Put a weapon up for sale | Yes | No | No |
| Buy a weapon that is for sale, in a quest in progress | Yes, for any character in it | Yes, if the character is in it | No |
| Change a held weapon's level or quantity | Yes | No | No |
| Equip or unequip | Yes | Yes, if the character can use it | No |
| See a character's weapons | Yes | Yes | Yes |

## 11. What is not modelled

- Weapon proficiency by class (everyone is proficient with everything)
- Properties: two-handed, versatile, light, reach, loading, thrown (a
  two-handed weapon counts as one thing equipped, like any other)
- Range and ammunition
- Critical hits, advantage, and rolling the attack itself (use the dice roller)
- Magic bonuses to a weapon's own attack or damage, such as +1 weapons (use a
  higher level or growth instead)
- A price on the weapon itself (a price is set each time it is put up for sale), and weight

## 12. The complete weapon library

Every weapon "📚 From Library" offers. Base damage is the damage at level 1.
Properties and range are carried into the campaign but not shown or used.
"While equipped" is the weapon's effects and note, which are carried in too.

This list is written from the app's own data by `npm run docs:lists` (in `/backend`). Re-run it after changing the data; do not edit the list by hand.

<!-- BEGIN GENERATED: weapon-library -->
### Simple Melee (10)

| Weapon | Base damage | Type | Attacks with | Properties | Range | While equipped |
|---|---|---|---|---|---|---|
| Club | 1d4 | bludgeoning | Strength | light | — | — |
| Dagger | 1d4 | piercing | Strength or Dexterity (finesse) | finesse, light, thrown | 20/60 ft | — |
| Greatclub | 1d8 | bludgeoning | Strength | two-handed | — | — |
| Handaxe | 1d6 | slashing | Strength | light, thrown | 20/60 ft | — |
| Javelin | 1d6 | piercing | Strength | thrown | 30/120 ft | — |
| Light Hammer | 1d4 | bludgeoning | Strength | light, thrown | 20/60 ft | — |
| Mace | 1d6 | bludgeoning | Strength | — | — | — |
| Quarterstaff | 1d6 | bludgeoning | Strength | versatile (1d8) | — | — |
| Sickle | 1d4 | slashing | Strength | light | — | — |
| Spear | 1d6 | piercing | Strength | thrown, versatile (1d8) | 20/60 ft | — |

### Simple Ranged (4)

| Weapon | Base damage | Type | Attacks with | Properties | Range | While equipped |
|---|---|---|---|---|---|---|
| Light Crossbow | 1d8 | piercing | Dexterity | ammunition, loading, two-handed | 80/320 ft | — |
| Dart | 1d4 | piercing | Strength or Dexterity (finesse) | finesse, thrown | 20/60 ft | — |
| Shortbow | 1d6 | piercing | Dexterity | ammunition, two-handed | 80/320 ft | — |
| Sling | 1d4 | bludgeoning | Dexterity | ammunition | 30/120 ft | — |

### Martial Melee (18)

| Weapon | Base damage | Type | Attacks with | Properties | Range | While equipped |
|---|---|---|---|---|---|---|
| Battleaxe | 1d8 | slashing | Strength | versatile (1d10) | — | — |
| Flail | 1d8 | bludgeoning | Strength | — | — | — |
| Glaive | 1d10 | slashing | Strength | heavy, reach, two-handed | — | — |
| Greataxe | 1d12 | slashing | Strength | heavy, two-handed | — | — |
| Greatsword | 2d6 | slashing | Strength | heavy, two-handed | — | — |
| Halberd | 1d10 | slashing | Strength | heavy, reach, two-handed | — | — |
| Lance | 1d12 | piercing | Strength | reach, special | — | — |
| Longsword | 1d8 | slashing | Strength | versatile (1d10) | — | — |
| Maul | 2d6 | bludgeoning | Strength | heavy, two-handed | — | — |
| Morningstar | 1d8 | piercing | Strength | — | — | — |
| Pike | 1d10 | piercing | Strength | heavy, reach, two-handed | — | — |
| Rapier | 1d8 | piercing | Strength or Dexterity (finesse) | finesse | — | — |
| Scimitar | 1d6 | slashing | Strength or Dexterity (finesse) | finesse, light | — | — |
| Shortsword | 1d6 | piercing | Strength or Dexterity (finesse) | finesse, light | — | — |
| Trident | 1d6 | piercing | Strength | thrown, versatile (1d8) | 20/60 ft | — |
| War Pick | 1d8 | piercing | Strength | — | — | — |
| Warhammer | 1d8 | bludgeoning | Strength | versatile (1d10) | — | — |
| Whip | 1d4 | slashing | Strength or Dexterity (finesse) | finesse, reach | — | — |

### Martial Ranged (5)

| Weapon | Base damage | Type | Attacks with | Properties | Range | While equipped |
|---|---|---|---|---|---|---|
| Blowgun | 1 | piercing | Dexterity | ammunition, loading | 25/100 ft | — |
| Hand Crossbow | 1d6 | piercing | Dexterity | ammunition, light, loading | 30/120 ft | — |
| Heavy Crossbow | 1d10 | piercing | Dexterity | ammunition, heavy, loading, two-handed | 100/400 ft | — |
| Longbow | 1d8 | piercing | Dexterity | ammunition, heavy, two-handed | 150/600 ft | — |
| Net | - | special | Dexterity | special, thrown | 5/15 ft | — |

### Paired (4)

| Weapon | Base damage | Type | Attacks with | Properties | Range | While equipped |
|---|---|---|---|---|---|---|
| Paired Daggers | 2d4 | piercing | Strength or Dexterity (finesse) | finesse, light, paired | — | A dagger in each hand: takes both hands. |
| Paired Shortswords | 2d6 | piercing | Strength or Dexterity (finesse) | finesse, light, paired | — | A shortsword in each hand: takes both hands. |
| Paired Scimitars | 2d6 | slashing | Strength or Dexterity (finesse) | finesse, light, paired | — | A scimitar in each hand: takes both hands. |
| Paired Handaxes | 2d6 | slashing | Strength | light, paired | — | A handaxe in each hand: takes both hands. |
<!-- END GENERATED: weapon-library -->