V1.1.0: gear levels, encounter overhaul, guided builder, trading, docs

Characters
- Builder: pick-then-Next on every step with live preview, Back button,
  plain-language help throughout, and "Suggest for me" for ability scores
- Motivation is picked from a list; new steps for special abilities,
  background and appearance, all composed from fixed lists and DM-only
  to edit afterwards
- Copy a character to another campaign
- Characters can give gold, weapons, items and spells to each other
- Money tracker: gold only changes through a logged ledger
- Fixes: level/XP/location are DM-only, HP stays within 0..max, physical
  dice ability rolls, every die is rolled once

Gear
- DM-managed item pool; weapons, items and spells are handed out by the DM
- Starting-option flag per pool entry
- Gear levels 1-9 per held copy with a damage ladder, growth rate and
  starting level; spells gated by spell level with a fixed damage value
- Spell library carries default damage; damage is picked from a list

Encounters
- Battle and NPC quest modes, turn tracking, scene description, DM notes
- NPCs, richer combatant cards, conditions from a list
- Rewards (gold, weapons, items) lined up and awarded, with gold splitting
- Character HP is shared between the sheet and the encounter
- Monster stat blocks and NPC secrets are never sent to players

Other
- Dice roller on every page
- Docs for characters, weapons, spells, items, encounters, monsters and
  NPCs, with full lists generated from the data (npm run docs:lists)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-05 16:47:28 +02:00
co-authored by Claude Opus 5.5
parent 94067f1268
commit 4a6a09bae8
44 changed files with 9405 additions and 700 deletions
+151
View File
@@ -0,0 +1,151 @@
# Items and Inventory
How items work in this app: the campaign's item pool, what a character
carries, item levels, and how items are handed out.
This describes the code as it stands. Related: [WEAPONS.md](WEAPONS.md) (items
level up the same way weapons do), [SPELLS.md](SPELLS.md),
[CHARACTERS.md](CHARACTERS.md) (money is covered there, in section 12).
## Contents
1. [The basics](#1-the-basics)
2. [The item pool](#2-the-item-pool)
3. [A character's inventory](#3-a-characters-inventory)
4. [Item levels](#4-item-levels)
5. [Dice on items](#5-dice-on-items)
6. [Starting items](#6-starting-items)
7. [Items as rewards](#7-items-as-rewards)
8. [Permissions](#8-permissions)
9. [What is not modelled](#9-what-is-not-modelled)
---
## 1. The basics
- Every campaign has its own **item pool**: rope, potions, keys, quest items,
anything that is not a weapon or a spell.
- A character's **inventory** is the items it holds from that pool. Players
cannot type in items of their own.
- The DM creates items and hands them out. Players can only tick Equipped.
- Items are **descriptive**. Holding or equipping one never changes a number
on the sheet.
## 2. The item pool
The pool is the "Items Pool" card on the campaign page (DM only).
| Field | What it is |
|---|---|
| Name | Free text, up to 120 characters |
| Description | Optional. Shown under the item in a character's inventory |
| Base dice | Optional dice such as `2d4+2`, for items that deal damage or heal (section 5) |
| Starts at level | 1 to 9. The lowest level this item can be (section 4) |
| Growth | Standard, Powerful or Legendary. Only matters if the item has dice |
| Starting option | Whether a brand-new character may pick it in the builder (section 6) |
- **Adding:** the "+ Add Item" form. There is no built-in library of items.
- **Changing:** starting level, growth (when the item has dice) and the
starting-option tick box can be changed in the table. Name, description and
dice cannot be changed on screen once created (the API accepts it); remove
and re-add instead.
- **Removing:** the ✕ button. This takes the item out of **every inventory**
and off every encounter's reward list. There is no undo.
## 3. A character's inventory
On a character's sheet, the DM picks an item from the pool and clicks Give.
| Each held item has | Who changes it |
|---|---|
| Quantity | The DM, with the − and + buttons |
| Level | The DM, with the level picker |
| Equipped | The owning player or the DM |
- Giving an item the character already holds **adds to the stack**. A
character holds one stack per item, and the whole stack shares one level.
- Quantity cannot go below 1; to take the last one away the DM uses ✕.
- **Using up** an item (drinking a potion) is not automatic: the DM lowers the
quantity or removes it.
- **Equipped** is a label. It does not change Armor Class or anything else;
armor is represented by the single "armor bonus" number on the sheet.
**Passing items on.** A character's owner (or the DM) can give some or all of
a held stack to another character in the campaign from the "Give to Another
Character" card on the sheet. The items leave the giver and arrive with the
recipient at the giver's level, unequipped. If the recipient already holds
that item, their stack grows and keeps its own level. Gold is given the same
way, and both characters' money logs record it.
## 4. Item levels
Items use the same level system as weapons (a house rule of this app):
- Each held stack has a **level from 1 to 9**, never below the pool entry's
starting level.
- A character must be **at least the item's level** to use it. A higher-level
item is still held, but shows "Requires level N" and cannot be equipped.
- Only the DM changes an item's level.
- If the DM levels an item past its holder, or lowers the character's level,
it is unequipped automatically.
For an item with no dice, the level is purely a requirement: a level 3 amulet
is one a character cannot use until level 3.
## 5. Dice on items
An item can carry optional dice: a healing potion's `2d4+2`, a firebomb's
`3d6`. The app does not know whether they heal or harm; the DM applies them.
The dice grow with the item's level exactly as a weapon's do, climbing the
same ladder (1d4 → 1d6 → 1d8 → 1d10 → 1d12 → 2d6 → …) by one, two or three
rungs per level depending on Growth. The full ladder is in
[WEAPONS.md, section 6](WEAPONS.md#6-how-damage-grows).
| Healing Potion, `2d4+2`, Standard growth | Dice shown |
|---|---|
| Level 1 | 2d4+2 (as typed) |
| Level 2 | 1d6+1d8 |
| Level 3 | 2d8 |
The dice are shown beside the item in the inventory. Nothing is rolled or
applied automatically; use the dice roller.
## 6. Starting items
In the builder's equipment step a new character can pick items that are:
- ticked as a **starting option** in the pool, and
- **starting level 1**.
Starting items and starting weapons share the campaign's "starting items"
allowance. Each arrives at level 1, quantity 1, unequipped.
## 7. Items as rewards
On an encounter the DM can line up an item as a reward, at a chosen level and
quantity, and later award it to a character. Awarding adds it to the
character's inventory, stacking with any they already hold. See
[ENCOUNTERS.md](ENCOUNTERS.md).
## 8. Permissions
| Action | DM | Owning player | Other players |
|---|---|---|---|
| See the item pool | Yes | Yes | Yes |
| Add, change or remove pool items | Yes | No | No |
| Give an item from the pool, or take one away | Yes | No | No |
| Give a held item to another character | Yes | Yes | No |
| Change quantity or level | Yes | No | No |
| Equip or unequip | Yes | Yes, if the character can use it | No |
| See a character's inventory | Yes | Yes | Yes |
## 9. What is not modelled
- Any effect of an item on stats (AC, speed, abilities)
- Armor and shields as items
- Using up items automatically, charges, and attunement
- Weight, carrying capacity and containers
- Prices, buying and selling (record the gold change in the money log)
- Swaps as a single step (each side gives separately), and asking the
recipient to accept