| name | ose-statblock-writer |
| description | Write OSE B/X statblocks for Foundry VTT import (v14.3+). Use Nx stacks (10x Potion of Healing) and {worn}/{stowed} for equipped weapons and armor. |
| applyTo | statblock+ose+bx+dnd+foundry |
| allowed-tools | [] |
OSE Statblock Writer Skill
Overview
This skill teaches you to write statblocks in the exact format consumed by the OSE Statblock Importer for Foundry VTT v14 (module v14.3.0+). The format is a semi-colon-delimited key-value text representation of a B/X D&D (Old School Essentials, Basic D&D, Moldvay B/X) creature or character. It also supports extended modern-OSR conventions: ascending AC, explicit attack bonuses, named equipment, item stack quantities (10x Potion of Healing → 10/10 on the sheet), worn/equipped markers (Sword +2 {worn}, Plate Mail {worn} → system.equipped), multi-attack damage lists, spells, languages, multi-line bestiary paste, level-up/partial reimport, class-feature auto-import, and multi-block batch import.
Actors can also be exported back to this format via Copy Statblock (sheet header / actor directory). Prefer writing import-safe text that round-trips cleanly — including Nx stacks and {worn} on equipped weapons/armor.
Agent checklist when writing equipment
Whenever you emit Weapon:, Armor:, Equipment:, or Gear: for a character or classed NPC:
- Stacks — multiples use
Nx Name (e.g. 10x Potion of Healing), never the name repeated N times.
- Worn — put ready weapons and worn armor with a trailing
{worn} (e.g. Weapon: Sword {worn}; Armor: Plate Mail {worn}, Shield {worn}).
- Stowed — off-hand / pack weapons use
{stowed} when you want them unequipped (e.g. Dagger {stowed}).
- Pack gear — potions, rations, rope stay unequipped unless you intentionally mark something
{worn} (cloaks, etc.).
Deterministic Generation Workflow
When you are asked to generate NPC or character statblocks rather than only
explain the format, prefer the bundled script:
scripts/OSE_GENERATE_STATBLOCKS.py
Use it whenever the request can be expressed as:
- AI-imagined NPCs with class, level, role, armor, weapon, or morale hints
- Book or module text that can be converted into structured NPC inputs
- User suggestions such as "make me three 2nd-level guards and a paladin
captain"
Recommended workflow:
- Extract or infer structured inputs such as
name, class, level,
armor, weapon, location, alignment, traits, goals, and
optional equipment.
- Run
scripts/OSE_GENERATE_STATBLOCKS.py for deterministic generation rather
than hand-authoring the whole block from scratch.
- Use the script's default
line output as the base statblock.
- Add or revise
Feature: blocks manually only for details the script does
not synthesize yet.
- Keep the final output import-safe: no stray semicolons inside field values,
and no explanatory prose outside the statblock unless the user asked for it.
The script already emits importer-safe fields such as AAC/AC, separate
HD and SV, explicit Weapon: / Armor: fields, Traits:, Role:, and
Feature: blocks for extra metadata.
Example single-NPC command:
python scripts/OSE_GENERATE_STATBLOCKS.py \
--name "Brother Oren" \
--class Cleric \
--level 2 \
--armor "chain mail" \
--weapon "mace" \
--location "Chapel" \
--alignment L \
--traits "devout, steady" \
--equipment "holy symbol, rations" \
--feature "Blessing|Allies within 10 ft. gain +1 morale."
Example batch workflow:
- Turn the source text into a JSON array of NPC records.
- Run
python scripts/OSE_GENERATE_STATBLOCKS.py --data-file my_npcs.json.
- Return the generated
line statblocks, adjusting only edge-case flavor or
special abilities as needed.
Useful script controls:
--weapon-mode auto|melee|missile for daggers, spears, and other dual-use weapons--qualities "poison, fear" for extra Qual tags beyond melee/missile- repeatable
--feature "Name|Text" for bespoke abilities
--emit-class-abilities when you want generic Feature: blocks even before
compendium auto-import happens- repeatable
--item-json '{"name":"Whetstone","type":"item","quantity":2}'
for deterministic rich inventory items
--mode inventory --apply-to "Actor Name" for loadout-only statblocks--gp, --sp, --cp, --ep, --pp for coin object creation
If the request is for a monster with unusual bespoke abilities, you may
still write the statblock by hand using the field rules below, but prefer the
script first for classed NPCs, henchmen, guards, retainers, and other humanoid
characters.
Import Modes (Mode: field)
| Mode value | Meaning |
|---|
(omit) / full | Full import: stats + equipment + features + spells |
Inventory | Gear/coins only — does not change combat stats |
Level-up / Levelup | Updates HD, SV/saves, class features, homebrew, spells; keeps inventory and ability scores; updates HP only if HP: is present |
Partial | Only fields listed in Fields: (e.g. Fields: hd, spells) |
Mladen: Mode: Level-up; HD F2; SV F2
Mladen: Mode: Partial; Fields: hd, spells; HD F3; Spells: sleep, magic missile
Human Warrior: Mode: Inventory; Apply To: Human Warrior; Weapon: Sword; Coins: 5 gp
Level-up / partial / inventory always target an existing actor (open sheet, or Apply To: Name). They do not create new actors.
Rich Inventory and Loadout Mode
When the user needs custom items, metadata-aware inventory, or a
template that adds gear to an existing actor, prefer these two formats.
Item stack quantities (multiples of one item)
When an NPC or loadout has more than one of the same item, do not list the name repeatedly. Prefix (preferred) or suffix the count so Foundry gets one item with quantity.value / quantity.max (sheet shows 10/10).
Preferred form (always use this when writing new statblocks):
Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), 20x Torches (6)
| Write this | Not this |
|---|
10x Potion of Healing | Potion of Healing, Potion of Healing, … (×10) |
2x Rations (standard, 7 days) | two separate ration entries |
20x Arrows (quiver of 20) only if you truly want 20 separate quivers — prefer catalog sense | |
All accepted quantity forms:
| Syntax | Example | Result |
|---|
Nx Name (preferred) | 10x Potion of Healing | qty 10, name Potion of Healing |
N x Name | 10 x Potion of Healing | same |
Name xN | Potion of Healing x10 | same |
Name x N | Potion of Healing x 10 | same |
N Name | 10 Arrows | bare count before name |
| Rich JSON | [Potion of Healing::{"type":"item","quantity":10}] | same via metadata |
Rules for agents:
- Prefer
Nx ItemName (no space required between number and x).
- Put the quantity on each list segment that needs a stack:
10x A, 3x B, C → A×10, B×3, C×1.
- Parenthetical catalog names with commas are fine:
2x Rations (standard, 7 days).
- Do not put
x on magic bonuses: write Sword +1, never treat +1 as a quantity.
- Coins use
Coins: 5 gp, 8 sp, not 5x GP (coins have their own parser).
- Works on
Equipment:, Gear:, Weapon:, Armor:, and equipment directives inside Notes:.
Full character example with stacks:
Quartermaster: AAC 12; HD F1; HP 8; MV 40; #AT 1; Dmg 1d6; ML 8; SV F1; AL N; Weapon: Sword {worn}; Armor: Leather Armour {worn}; Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), 6x Torches (6), Rope (50'), Backpack; Coins: 15 gp
Inventory-only restock example:
Mladen: Mode: Inventory; Apply To: Mladen; Equipment: 5x Potion of Healing, 2x Holy Water (vial); Coins: 10 gp
Worn / equipped ({worn} and {stowed})
Trailing curly markers set OSE system.equipped so weapons are ready in hand and armor is worn (counts for AC).
Always do this for ready combat loadouts when writing character/NPC statblocks:
Weapon: Sword +2 {worn}, Dagger {stowed}
Armor: Plate Mail {worn}, Shield {worn}
Equipment: Holy Symbol, 10x Potion of Healing, Rope (50')
| Marker | Meaning | Use for |
|---|
{worn} | Equip now (equipped: true) | Primary weapon, armor, shield; optional worn cloak |
{equipped} {held} {wielded} {ready} | Same as {worn} | Aliases |
{stowed} | Force unequipped | Backup dagger, spare weapons in pack |
{carried} {packed} {unequipped} | Same as {stowed} | Aliases |
Defaults (when no marker):
| Field | Default equipped? |
|---|
Weapon: … | Yes (ready) — still write {worn} for clarity and export round-trip |
Armor: … | Yes (worn) — still write {worn} on plate/shield |
Equipment: / Gear: | No — bag items; add {worn} only when something should be worn (e.g. cloak) |
Combine with stacks and magic names:
Weapon: 2x Dagger {stowed}, Sword +1 {worn}
Armor: Chainmail {worn}, Shield (Steel) {worn}
Equipment: 10x Potion of Healing, Cloak of Defence {worn}
Do not put the marker inside catalog parentheses: write Shield (Steel) {worn}, not Shield (Steel worn).
Rich JSON alternative: [Sword::{"type":"weapon","equipped":true}].
Rich item blocks
Use square-bracket item envelopes inside Equipment: when you need description or extra metadata beyond a plain stack:
Equipment: [Oil Flask::{"type":"item","quantity":3,"weight":1}::Enough for three night watches.]
For plain stacks, 10x Oil Flask is enough — rich blocks are optional.
Rules:
- segment 1 is the item name
- segment 2 is compact JSON metadata (
"quantity": N sets the stack)
- segment 3 is description text
- use
|| between multiple rich items in one field
- avoid semicolons inside item descriptions
Inventory-only mode
Use this when stats should stay untouched and only inventory should change:
Human Warrior: Mode: Inventory; Apply To: Human Warrior; Weapon: Sword {worn}; Armor: Chainmail {worn}, Shield {worn}; Equipment: 2x Whetstone, 10x Potion of Healing, [Backpack::{"type":"item"}]; Coins: 5 gp, 8 sp
Use inventory-only mode for workflows like:
- create a naked base actor, then apply
swordsman (mark main weapon/armor {worn})
- convert one guard into an axeman or spearman with
Weapon: Battle Axe {worn}
- add module loot and utility gear after the main import
- restock potions/rations with
Nx quantities
General Format
Name: KEY VALUE; KEY VALUE; KEY: VALUE; ...
- Fields are separated by semi-colons (
;).
- Each field is either
Key: Value (colon-separated) or Key Value (space-separated).
- The name is everything before the first colon (
:) on a single-line block.
- For multi-block import, separate statblocks with blank lines.
- The parser is case-insensitive for field keys.
- Trailing punctuation (
. ;) on values is stripped.
- Import dialog accepts drag-and-drop of plain text,
.txt/.md files, or journal content.
Multi-line bestiary / book paste (v14.3+)
Name on the first line; fields on following lines (no requirement for a single Name: … line):
Kobold
AC 7
HD 1/2
HP 3
MV 40
#AT 1
Dmg 1-4
ML 6
AL C
TT Nil
NA 4d4
Equivalent single-line form still works. First line may also be classic Name: AC 7; HD … with extra field lines below.
Minimal valid statblock
Goblin: AC 6; HD 1-1; HP 4; MV 20; #AT 1; Dmg 1-6; ML 7; SV NM; AL C
Supported Fields — Complete Reference
1. Name (Required)
Everything before the first colon. For monsters this is the creature name. For characters this is the character name. If missing, a warning is raised but parsing continues.
Mladen: AC 15; HD F1; ...
2. AC / AAC — Armor Class
Accepts both descending (classic B/X, lower = better) and ascending (modern, higher = better) AC.
| Syntax | Meaning |
|---|
AC 6 | Descending AC 6 (→ ascending 13) |
AC 15 | Ascending AC 15 (→ descending 4) |
AAC 15 | Explicit ascending AC 15 |
AC 10 | Ascending if ≥ 10, else descending (key-based heuristic) |
Heuristic: Plain AC values ≤ 10 are treated as descending B/X AC. Values > 10 are treated as ascending. Use AAC or AC + ascending/descending keyword to be explicit.
AC 6 — classic descending
AAC 13 — explicit ascending
AC 15 — auto-detected as ascending (> 10)
The parser computes both values internally. The tool will set both system.ac.value (descending) and system.aac.value (ascending) on the actor.
3. HD — Hit Dice
The most flexible field. Supports multiple formats:
| Format | Example | Meaning |
|---|
| Monster shorthand | 2D+1 | 2d8+2 (d8 implicit, per-die +1) |
| Monster shorthand no mod | 4D | 4d8 |
| Monster shorthand negative | 2D-2 | 2d8-4 |
| Explicit dice | 2d6 | 2d6 (no per-die bonus) |
| Explicit dice with total bonus | 2d6+1 | 2d6+1 (flat bonus, not per-die) |
| Class+Level (letter) | F3 | Fighter 3 (d8 HD) |
| Class+Level (letter) | MU2 | Magic-User 2 (d6 HD) |
| Class+Level (letter) | T1 | Thief 1 (d4 HD) |
| Class+Level (letter) | C4 | Cleric 4 (d8 HD) |
| Class+Level (letter) | D5 | Dwarf 5 (d8 HD) |
| Class+Level (letter) | E3 | Elf 3 (d6 HD) |
| Class+Level (letter) | H2 | Halfling 2 (d4 HD) |
| Fractional | 1/2 | 1d4 (½ HD creature) |
| Fractional | 1/4 | 1d4 (¼ HD creature) |
| Fractional | 3/2 | 2d8 (1½ HD creature) |
| Plain number | 3 | 3d8 (monster default) |
| Normal Man | Normal Man | 1d4 (NH) |
Class letter to die mapping:
| Letter | Class | Die |
|---|
F | Fighter | d8 |
M / MU | Magic-User | d6 |
T | Thief | d4 |
C | Cleric | d8 |
R | Ranger | d6 |
D | Dwarf | d8 |
E | Elf | d6 |
H | Halfling | d4 |
N | Normal Man | d4 |
Per-die bonus vs total bonus:
2D+1 → 2d8, each die gets +1 → total bonus +2 (per-die bonus)2d6+1 → 2d6, flat +1 bonus (total bonus, because die size is explicit)- The attack value for monster THAC0 is derived from
count + (bonus * 0.5).
4. HP — Hit Points
| Format | Example | Meaning |
|---|
| Parenthetical | (12 hp) | HP is 12 |
| Equals | =12 | HP is 12 |
| Last number | HD 1 (12 hp) | Picks 12 from context |
| Monster fallback | (omitted) | Auto-computed from average HD if HP field is selected |
HP 12
HP (12 hp)
HP = 12
If HP is omitted but selectedFields.hp is enabled, monster actors get HP auto-computed from ceil(count × avg(die) + bonus).
5. MV / Move / Movement — Movement Rate
Integer value. Feet per round in classic B/X terms.
MV 40 — 40' movement
Move 30 — 30' movement
Movement 120 — 120' (flying/swimming)
Only the first integer token is extracted.
6. ML / Morale — Morale
Integer, typically 2–12 in OSE. Warnings are raised for values outside 1–12 range.
ML 10
Morale 7
ML 12
7. AL / Alignment — Alignment
Free-text alignment. Trailing punctuation is stripped. Aliases normalize to short form L / N / C when recognized.
| Input | Stored |
|---|
L, Law, Lawful | L |
N, Neutral, Any | N |
C, Chaos, Chaotic | C |
| Other text | Kept as trimmed free text |
AL L
AL Lawful
AL Chaotic
Alignment: Neutral
When world setting Apply Token Defaults is enabled, disposition is derived from alignment (Lawful friendly, Neutral neutral, Chaotic hostile).
8. #AT / AT / Attacks — Number of Attacks
Integer count of attacks per round. Used with multi-part Dmg to create multiple Attack weapons (v14.3+).
#AT 1 — 1 attack
AT 2 — 2 attacks
Attacks 3 — 3 attacks
The # prefix is optional. Weapon count = max(#AT, number of Dmg segments).
9. Dmg / Damage — Damage Expression
The most expressive field. Supports:
| Format | Example | Parsed As |
|---|
| Range | 1-8 | 1d8 |
| Range with offset | 2-7 | 1d6+1 |
| Dice formula | 1d8 | 1d8 |
| Multi-dice | 2d6 | 2d6 |
| Dice with mod | 2d6+1 | 2d6+1 |
| Named parenthetical | 1-8 (axe) | 1d8, name ignored |
| Multi-attack slash/list | 1d6/1d8 | Two formulas → Attack + Attack 2 |
| Multi-attack comma | 1d6, 1d4 | Two formulas |
| Shared atk bonus | 1d6/1d8 +2 atk | Both segments get +2 |
| With attack bonus | +2 atk 1d8 | formula=1d8, bonus=+2 |
| With attack bonus | 1d8+2 atk | formula=1d8, bonus=+2 |
| Plain number | 6 | 1d6 |
Attack bonus notation: Append +N atk or -N atk on a segment (or trailing on the whole list) to set attack bonus on generated Attack items.
Dmg 1d8+2 atk — 1d8 damage, +2 attack bonus
Dmg +3 atk 2d6 — 2d6 damage, +3 attack bonus
Dmg 1d6/1d8 — two Attack weapons (with #AT 2 or more)
Dmg 1-8 — parsed as 1d8
If named Weapon: equipment is present, auto Attack items from Dmg are skipped (equipment wins).
Monster attack bonus fallback: If no explicit +N atk is provided, the tool derives attack bonus from HD using the B/X monster attack matrix (≤1HD → 0, 2HD → +1, 3HD → +2, etc.).
10. SV / Save / Saves — Saving Throw Class
One of the most important fields. It determines which save progression table to use.
Format: SV <CLASS_ABBREVIATION>[<LEVEL>]
SV F1 — Fighter 1
SV MU3 — Magic-User 3
SV T5 — Thief 5
SV C2 — Cleric 2
SV D4 — Dwarf 4
SV E1 — Elf 1
SV H2 — Halfling 2
SV NM — Normal Man (fixed saves 18/18/18/18/18)
SV NH — Normal Human (same as NM)
SV PAL3 — Paladin 3
SV BARB2 — Barbarian 2
SV RGR4 — Ranger 4
SV KNIGHT5 — Knight 5 (→ Fighter)
Complete SV class alias table:
| Input | Resolved Class Key | Display Name |
|---|
F, FTR, FIGHTER, K, KNT, KNIGHT, R, RGR, RANGER, RANG | fighter | Fighter |
T, THF, THIEF, ACROBAT, ACRO, ASSASSIN, ASS, BARD | thief | Thief |
C, CLR, CLERIC, DRU, DRUID | cleric_druid | Cleric |
M, MU, MAGE, MAGIC-USER, MAGICUSER, ILLUSIONIST, ILL | magic_user | Magic-User |
D, DWARF, DUERGAR | dwarf_halfling | Dwarf |
H, HALFLING | dwarf_halfling | Dwarf |
E, ELF | elf | Elf |
DROW | drow | Drow |
GNOME | gnome | Gnome |
HALF-ELF, HALFELF | half_elf | Half-Elf |
HALF-ORC, HALFORC | half_orc | Half-Orc |
PAL, PALADIN | paladin | Paladin |
BARB, BARBARIAN | barbarian | Barbarian |
SVIRF, SVIRFNEBLIN | svirfneblin | Svirfneblin |
NM, NH, NORMAL MAN, NORMAL-MAN, NORMALMAN, NORMAL HUMAN, NORMAL-HUMAN, NORMALHUMAN | normal_man | Normal Man |
If level is omitted, the parser tries to extract level from parsed HD count or from the existing actor's HD.
Save progression tables are built into the parser for all classes (thief, barbarian, cleric_druid, drow, dwarf_halfling, elf, fighter, gnome, half_elf, half_orc, magic_user, paladin, svirfneblin).
11. Qual / Quality / Qualities — Monster Qualities
Comma or slash separated list of monster qualities. These get appended to the auto-generated Attack item name and influence weapon flags.
Qual melee — Attack (melee)
Qualities undead, regenerating
Qual melee, poison — Attack (melee, poison)
Qualities containing melee or missile set the corresponding weapon system flag. Other qualities are appended to the default weapon name as Attack (quality1, quality2).
12. Notes — Freeform Notes
A catch-all field that triggers sub-parsing for equipment directives and traits.
Notes: armor leather+shield; weapon longsword; traits brave, loyal; role bodyguard
The parser extracts:
- Equipment:
weapon <items>, armor <items>, equipment <items>, gear <items>
- Traits:
traits <text> or traits: <text>
- Role: handled separately (see below)
13. Traits — Explicit Traits
Traits: brave, loyal, stubborn
Traits: undead, incorporeal, drains life
Traits direct, no-nonsense, blunt
Traits are written to system.details.notes as <strong>traits:</strong> <value>.
Features (Feat / Feature / Features) — Bracketed Named Features
Named feature blocks with description text. Each feature has a {Name} prefix followed by its description paragraph. Multiple features are separated by the next {Name} marker. The key accepts Feat, Feature, or Features (case-insensitive).
Feature: {Darkvision} 60 ft. range, sees in total darkness. {Regeneration} Regains 5 HP per round at the start of each turn unless damaged by fire or acid.
Behavior by actor type:
| Actor Type | Where features go |
|---|
| Monster | Appended to system.details.biography as <strong>Name</strong> Text, features separated by blank lines |
| Character | Created as embedded ability items with generic icon (systems/ose/assets/default/ability.png), with name = {Name} and system.description = {text} |
Duplicate handling: If an ability item with the same name already exists, it is updated with the new description text rather than duplicated.
Usage in statblock:
Feat: {Cleave} When you reduce a foe to 0 HP, you may make one additional melee attack. {Shield Wall} Adjacent shielded allies gain +1 AC.
Feature: {Breath Weapon} 60 ft. cone, 8d6 fire damage, save vs breath for half.
Features: {Undead Nature} Does not need to eat, breathe, or sleep.
Writing concise feature descriptions — source books often devote a full paragraph or page to a single ability. For the statblock importer, distill each feature into a single sentence covering only what the DM needs at the table:
- Damage: dice, type, area (e.g. "8d6 fire, 60 ft. cone" not "a great blast of searing flame erupts...")
- Save: save type and outcome (e.g. "save vs breath for half" or "save vs spell or paralyzed")
- Effect abbreviation: the mechanical result in minimal words (e.g. "-2 AC for 1d4 rounds" not "the target's armor class is reduced by 2 points for a duration of...")
- Duration: only if it's a combat-relevant number (e.g. "2d4 turns", "1 round")
- Omit: flavor text, lore, narrative, multiple synonyms, and any detail the DM can improvise
Good vs Bad examples:
| ❌ Too verbose | ✅ Concise & actionable |
|---|
{Dragon Fear} When the dragon takes to the air and lets out a terrifying roar that shakes the very foundations of the earth, all creatures who can see or hear the dragon within a 120 foot radius must make a saving throw against spells or become frightened, suffering a -2 penalty to all attack rolls and being unable to approach the dragon for as long as they remain in its presence. | {Dragon Fear} 120 ft. radius, save vs spell or frightened (-2 attack, cannot approach). |
{Vampiric Touch} The vampire reaches out with a deathly pale hand and upon a successful melee touch attack against a living target, the victim loses 2d6 hit points as their life force is drained away, which the vampire then adds to its own hit point total as it feeds upon their essence. | {Vampiric Touch} Melee touch, 2d6 necrotic, heals vampire equal damage. |
{Spellcasting} The lich is an accomplished spellcaster of immense power, having studied the arcane arts for centuries beyond counting, and can cast the following prepared spells using its Intelligence as its spellcasting ability, with a spell save DC of 20 and a +12 bonus to hit with spell attacks. | {Spellcasting} INT, DC 20, +12 atk. At will: detect magic, mage hand. 3/day: fireball, counterspell. 1/day: power word kill. |
14. Role — Combat Role
Role: bodyguard
Role: scout, trap-finder
Role straightforward escort
Stored in parsed.role. Descriptive text about the creature's combat function.
15. Weapon / Armor / Equipment / Gear — Equipment Directives
Explicit equipment fields that bypass notes parsing. Each accepts comma, slash, and, or + separated lists. Each segment may carry an inline quantity (Nx / xN).
Weapon: longsword, dagger
Armor: leather+shield
Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), rope
Gear: grappling hook, crowbar
Split rules for equipment lists:
- Commas:
longsword, dagger (commas inside parentheses stay part of the name, e.g. Rations (standard, 7 days))
- Slashes:
leather/shield
and: rope and torches+: leather + shield- Adjacent
+: leather+shield (but NOT axe+1 — magical notation is preserved)
Quantities / stack sizes (→ OSE system.quantity.value and .max, sheet shows N/N):
| Syntax | Example | Notes |
|---|
Nx Name | 10x Potion of Healing | Preferred when writing statblocks |
N x Name | 3 x Holy Water (vial) | spaces allowed |
Name xN | Potion of Healing x10 | suffix form |
Name x N | Torch x 6 | suffix with space |
N Name | 10 Arrows | bare count; name must start with a letter |
| Rich JSON | [Name::{"quantity":10}] | when description/metadata also needed |
Worn / equipped (→ OSE system.equipped = true — weapon in hand, armor worn):
| Syntax | Example | Effect |
|---|
Name {worn} | Sword +2 {worn} | Equipped / ready (preferred marker) |
{equipped} {held} {wielded} {ready} | Shield {held} | Same as {worn} |
{stowed} {carried} {unequipped} | Dagger {stowed} | Force not equipped |
| Defaults | Weapon: Sword / Armor: Chainmail | From Weapon: / Armor: fields, equipped by default even without marker |
| Gear list | Equipment: Cloak of Defence {worn} | Must mark {worn} — bag items stay unequipped otherwise |
Weapon: Sword +2 {worn}, Dagger {stowed}
Armor: Plate Mail {worn}, Shield {worn}
Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), Rope (50'), Holy Symbol
→ sword ready, dagger stowed, plate + shield worn, potions/rations in pack.
Combine with stacks: 2x Dagger {stowed}, Sword {worn}.
See Item stack quantities under Rich Inventory for agent writing rules.
Each directive feeds into the equipment container with structured requests (name + quantity):
parsed.equipment = {
weapons: [{ name, quantity, … }],
armors: […],
gear: [{ name: "Potion of Healing", quantity: 10 }, …],
coins: […]
}
16. Literacy — Literacy Status
Literacy: literate
Literacy: illiterate
Appended to notes as Literacy: <value>.
17. Spells / Spell / Spell List — Spell import (v14.3+)
Named spells are matched against loaded Item packs (type: spell) and created on the actor.
Spells: sleep, magic missile, shield
Spell: Charm Person
Slot-only shorthand is accepted but does not create spell items:
Spells: 2/1
Produces a warning; prefer named spells for Foundry. Optionally recorded as notes.
18. Languages / Lang — Spoken languages (v14.3+)
Comma-separated list written into actor notes as Languages: ….
Languages: Common, Elvish, Alignment tongue
Lang: Common, Dwarvish
19. TT / Treasure Type, NA / Number Appearing, SA / Special Attacks (v14.3+)
Bestiary book fields:
| Key | Example | Effect |
|---|
TT / Treasure Type | TT: E | Notes: Treasure Type |
NA / Number Appearing | NA: 4d4 | Notes: Number Appearing |
SA / Special Attacks | SA: breath weapon 30 ft | Feature {Special Attacks} text |
Kobold: AC 7; HD 1/2; ML 6; AL C; TT Nil; NA 4d4; SA pack tactics
20. Fields — Partial mode field list (v14.3+)
Used with Mode: Partial. Comma-separated field keys to apply:
Mode: Partial; Fields: hd, sv, spells, features
Recognized names include: name, ac, hd, hp, mv, ml, al, at, dmg, abilities, notes, qualities, equipment, features, spells, languages (and aliases like damage, gear, saves).
21. Mode / Apply To / Coins — Import control fields
| Key | Example | Effect |
|---|
Mode | Mode: Level-up | full (default), Inventory, Level-up / Levelup, Partial |
Apply To | Apply To: Mladen | Target existing actor by name (required when no sheet is open for inventory/level-up/partial) |
Coins | Coins: 5 gp, 8 sp | Creates coin item objects (gp/sp/cp/ep/pp) |
Also accepted as equipment-style keys: coins, loadout, inventory, treasure (feed the equipment/coins container). See Import Modes above.
22. Abilities — Ability Scores
Six standard B/X abilities. Can be parsed inline from any token that starts with an ability name, or extracted from the full body text.
Supported ability names:
Str / StrengthDex / DexterityCon / ConstitutionInt / IntelligenceWis / WisdomCha / Charisma
Format variants:
; Str 10 Dex 8 Con 6 Int 16 Wis 8 Cha 13
; Strength: 10 Dexterity: 8 Constitution: 6
; Str=10 Dex=8 Con=6 Int=16 Wis=8 Cha=13
The regex extracts ability_name [:=]? number patterns from anywhere in the body. Values can be negative.
Character vs Monster Statblocks
Monster Statblock (Minimal)
Kobold: AC 7; HD 1/2; MV 40; #AT 1; Dmg 1-4; ML 6; SV NM; AL C
Monster Statblock (Full Extended)
Great Wyrm: AC 18; HD 8D+4; HP 52; MV 30 fly 60; #AT 3; Dmg 2d8+3 atk / 1d6 / 1d6; ML 11; SV F8; AL C; Qual melee, fear; Notes: armor scale; Traits: breath weapon (60ft cone, 8d6 fire), fear aura (60ft, save vs spell); Role solo dragon
Character Statblock
Mladen: AAC 15; HD F1; HP 11; MV 20; #AT 1; Dmg +2 atk 1d8; ML 10; SV F1; AL N; Str 10 Dex 6 Con 6 Int 16 Wis 8 Cha 13; Weapon: Sword {worn}; Armor: Leather Armour {worn}, Shield {worn}; Traits: direct, no-nonsense, blunt; Role: bodyguard
Henchman / Classed NPC
Aelric: AAC 14; HD C3; HP 18; MV 30; #AT 1; Dmg 1d6; ML 8; SV C3; AL L; Str 12 Dex 9 Con 10 Int 13 Wis 16 Cha 11; Weapon: Mace {worn}; Armor: Chainmail {worn}; Traits: devout, healer; Role: support caster
Maximum Valid Monster Statblock (all monster-applicable fields)
Elder Lich: AC 20; HD 18D+4; HP 90; MV 30; #AT 2; Dmg 1d10+8 atk; ML 12; SV MU18; AL C; Qual undead, melee, magic; Notes: armor Bracers of Armour; weapon Wand of Paralysation, Dagger +1; equipment Cloak of Defence, Crystal Ball with ESP, Spell Scroll; traits paralyzing touch (save vs paralysis or paralyzed 2d4 turns), spellcasting (MU18), phylactery (cannot be destroyed until phylactery is found), immune to non-magical weapons, immune to cold and lightning, immune to charm and sleep; Feature: {Paralyzing Touch} Target must save vs paralysis or be paralyzed for 2d4 turns. {Spellcasting} Casts spells as an 18th-level Magic-User (5/5/5/5/4/4/3/3/2). {Phylactery} Cannot be permanently destroyed until its phylactery is located and destroyed. {Turn Resistance} +4 bonus to all saves against turning attempts; Role solo spellcaster
Maximum Valid Character Statblock (all character-applicable fields)
Ser Vex: AC 19; HD PAL6; HP 48; MV 20; #AT 2; Dmg 1d8+4 atk; ML 11; SV PAL6; AL L; Str 17 Dex 12 Con 15 Int 13 Wis 16 Cha 18; Notes: armor Plate Mail +2+Shield +1; weapon Sword +2; equipment Potion of Healing, Holy Symbol, Rations (standard 7 days), Rope (50'); traits devout, inspiring, fearless, tactical; Feature: {Cleave} When you reduce a foe to 0 HP, you may make one additional melee attack against another target within reach. {Shield Wall} While adjacent to an ally who also wields a shield, both of you gain +1 AC. {Battle Cry} Once per combat, all allies within 30 ft. gain +1 to attack rolls for 1 round; role front-line commander; Literacy literate
Multi-Block Import
Separate statblocks with one or more blank lines. Each block is parsed independently.
Mladen: AC 15; HD F1; HP 11; MV 20; #AT 1; Dmg 1d8+2 atk; ML 10; SV F1; AL N; Notes: armor leather+shield; weapon longsword
Kobold: AC 7; HD 1/2; MV 40; #AT 1; Dmg 1-4; ML 6; SV NM; AL C; Notes: small dog-faced humanoids, often with spears or slings
Aelric: AC 14; HD C3; HP 18; MV 30; #AT 1; Dmg 1d6; ML 8; SV C3; AL L; Str 12 Dex 9 Con 10 Int 13 Wis 16 Cha 11; Notes: armor chain; weapon mace
Targeting rules (v14.2+):
- Single block with an open actor sheet → applies to that actor.
- Multi-block → open actor is updated only when the parsed name matches the open actor; other blocks create new actors.
- Inventory / Level-up / Partial → always need an existing actor (
Apply To: or open sheet).
Optional world settings for new actors only:
- Import folder path (e.g.
Imported/Monsters)
- Name prefix / suffix
Export (Copy Statblock)
Use sheet header Copy Statblock or the actor directory context menu. Output is import-safe text for characters and monsters (core combat fields, equipment for PCs, multi-weapon Dmg for monsters when present).
Item stacks: gear/weapons/armor with quantity.value (or max) greater than 1 export as Nx Name (e.g. 10 potions → 10x Potion of Healing). Qty 1 stays a bare name.
Worn: equipped weapons/armor export with a trailing {worn} (e.g. Sword +2 {worn}, Plate Mail {worn}).
Round-trips cleanly with import.
Equipment Matching Logic
When equipment directives are present, the tool:
- Canonicalizes the name against
data/ose-equipment-stubs.json (a catalog of ~500+ OSE equipment items with normalized names across weapons, armor, shields, and gear)
- Searches all Item compendiums for the best match using a scoring algorithm
- Creates embedded items from compendium documents or as placeholder items depending on the
characterWeaponArmorImportMode setting
Matching algorithm:
- Exact normalized match: +300 score
- Starts-with / prefix match: +220
- Contains / substring match: +180
- Token overlap: +40 per matching word
- Magic bonus alignment penalties: non-magical requests penalize magical matches unless explicitly requested
- Minimum score threshold for acceptance: 80 for compendium items, 120 for name canonicalization
Explicit Magic Item Matching
To request a magical weapon, use +N notation:
Weapon: sword+2 — explicitly requests a +2 sword
Weapon: axe+1 — explicitly requests a +1 axe
Weapon: longsword — prefers non-magical longsword
Class Feature Auto-Import
For character actors (type="character"), the tool auto-imports class abilities from the ose-advancedfantasytome.abilities compendium when an SV class with a valid feature mapping is parsed.
How it works:
- The parser resolves
parsed.sv.class to a featureClass via FEATURE_CLASS_MAP
- Looks up that class key in
data/ose-advanced-tome-ability-class-map.json
- For each mapped ability, checks if the actor already has it (by compendium source UUID)
- If not present, imports the ability from the compendium
Feature class alias table (extended, used for class ability lookup):
| Input | Feature Class | Display |
|---|
FIGHTER, FTR, F | fighter | Fighter |
KNIGHT, KNT, K | knight | Knight |
RANGER, RGR, RANG | ranger | Ranger |
PALADIN, PAL | paladin | Paladin |
THIEF, THF, T | thief | Thief |
ACROBAT, ACRO | acrobat | Acrobat |
ASSASSIN, ASS | assassin | Assassin |
BARD | bard | Bard |
CLERIC, CLR, C | cleric | Cleric |
DRUID, DRU | druid | Druid |
MAGIC-USER, MAGICUSER, MU, M, MAGE | magic-user | Magic-User |
ILLUSIONIST, ILL | illusionist | Illusionist |
DWARF, DWF, D | dwarf | Dwarf |
DUERGAR | duergar | Duergar |
ELF, E | elf | Elf |
DROW, DRW | drow | Drow |
GNOME, G | gnome | Gnome |
HALF-ELF, HALFELF, HE | half-elf | Half-Elf |
HALF-ORC, HALFORC, HO | half-orc | Half-Orc |
HALFLING, HLF, H | halfling | Halfling |
SVIRFNEBLIN, SVIRFNEBLLIN, SVIRF | svirfneblin | Svirfneblin |
BARBARIAN, BARB | barbarian | Barbarian |
Note that the feature class resolution is more granular than SV class — for example, Knight and Ranger resolve to fighter for saves but to knight and ranger for feature import.
Avoiding Duplicate Class Feature Imports
The tool uses compendium source UUID tracking: each imported item gets a flags.core.sourceId set to Compendium.<compendiumId>.Item.<itemId>. Before importing, the tool checks if any existing item has that sourceId — if so, it skips.
Damage → Attack Item Generation
For monsters and placeholder-mode characters, when no Weapon: equipment is listed, the tool auto-generates Attack weapon item(s) from the damage field:
- Count:
max(#AT, number of slash/comma Dmg segments)
- Names:
Attack, Attack 2, … (plus quality suffix when present)
- Damage formula: each segment of the Dmg list
- Attack bonus: per-segment or shared
+N atk, else HD-derived for monsters
- Qualities:
melee/missile set corresponding weapon flags
- Updating: matching Attack names are updated rather than duplicated
Beast: AC 5; HD 4; #AT 2; Dmg 1d6/1d8; ML 8; AL N
Creates Attack (1d6) and Attack 2 (1d8).
HD → Attack Bonus (Monster THAC0)
When no explicit +N atk is provided, monster attack bonus is derived:
| HD Value | Attack Bonus |
|---|
| ≤ ½ | -1 |
| 1 | 0 |
| 2 | +1 |
| 3 | +2 |
| 4 | +3 |
| 5 | +4 |
| 6 | +5 |
| 7 | +6 |
| 8–9 | +7 |
| 10–11 | +8 |
| 12–13 | +9 |
| 14–15 | +10 |
| 16–17 | +11 |
| 18–19 | +12 |
| 20–21 | +13 |
| 22+ | +14 |
Token HP Reroll on Placement
Monsters with explicit HD but without a separate HP field get HP auto-computed. Additionally, when an unlinked monster token is placed on the canvas, the module can reroll HP from hit dice for that individual token (configurable via rerollMonsterHpOnPlacement setting).
Strict vs Lenient Mode
| Mode | Behavior |
|---|
| Strict | Unknown tokens become errors. AC and HP are required. All unknown field segments cause parse failure. |
| Lenient | Unknown tokens are reported as warnings. Missing AC/HP produce warnings only. Parsing continues with available data. |
Parse Confidence Scoring
The parser computes confidence scores internally, and the dialog surfaces live
warnings/errors while you type:
- ≥75% + zero errors → 🟢 Good
- 45–74% → 🟡 Warn
- <45% or any errors → 🔴 Error
Score is calculated as (parsed_fields / total_fields) × 100 - errors×20 - warnings×5 - unknown×4.
Complete Field Key Reference
Confidence / selection keys in FIELD_KEYS (v14.3+):
name — Actor nameac — Armor Classhd — Hit Dicehp — Hit Pointsmv — Movementml — Moraleal — Alignmentat — Number of Attacksdmg — Damage (incl. multi-segment lists)abilities — Ability Scoresnotes — Notes (traits, TT/NA/languages extras)qualities — Monster Qualitiesequipment — Equipment containerfeatures — Bracketed Feature: blocksspells — Named spell listlanguages — Language list
Additional parse-only / mode fields (not all scored the same way):
Mode, Apply To, Fields, TT, NA, SA, Literacy, Role, Weapon/Armor/Gear/Coins
Best Practices for Writing Statblocks
Do
- Always include a name (single-line before first colon, or multi-line first line)
- Use consistent separators — semi-colons between fields (or one field per line in multi-line form)
- Include SV class with level —
SV F3 not just SV F
- Use ascending AC for characters, descending for classic monsters
- Multi-attack: use
#AT n with Dmg a/b/c rather than one formula only
- Named spells for casters (
Spells: sleep, …) not only slot shorthand
- Level-up with
Mode: Level-up so gear is not wiped
- Include all six abilities for characters
- Keep traits comma-separated for clean notes output
- Use multi-block with blank lines for batch imports; match names when updating open actors
- Stack multiples with
Nx — write 10x Potion of Healing, never repeat the name ten times
- Use exact catalog item names with quantities:
2x Rations (standard, 7 days), 3x Holy Water (vial)
- Mark ready gear with
{worn} — Weapon: Sword {worn}; Armor: Plate Mail {worn}, Shield {worn} so weapons are in hand and armor applies
Don't
- Don't use
: in field values unless it's key: value format — it will split incorrectly
- Don't use
; inside field values — it's the field delimiter
- Don't put abilities in a separate block from the main statblock
- Don't rely on auto-detected AC without understanding the ≤10 heuristic
- Avoid
axe+1 next to shield in equipment — the + between letters triggers a split (leather+shield → ["leather", "shield"]) while axe+1 is preserved
- Don't invent stack syntax like
Potion of Healing (10) or Potion of Healing ×10 without x — use 10x Potion of Healing
- Don't list the same consumable ten times as ten comma segments
- Don't put
{worn} inside parentheses of catalog names — use a trailing marker: Shield (Steel) {worn} not Shield (Steel worn)
Advanced Examples
High-Level Character with Class Features
Seraphina: AC 18; HD PAL5; HP 45; MV 20; #AT 1; Dmg 1d8+3 atk; ML 10; SV PAL5; AL L; Str 16 Dex 10 Con 14 Int 12 Wis 15 Cha 17; Weapon: Sword +2 {worn}; Armor: Plate Mail {worn}, Shield {worn}; Traits: devout, inspiring, fearless; Role: front-line healer
Dragon (Full Monster)
Elder Red Dragon: AC 24; HD 11D; HP 66; MV 30 fly 90; #AT 3; Dmg 2d8+5 atk / 2d8+5 atk / 2d10+5 atk; ML 11; SV F11; AL C; Qual melee, fire, fear; Notes: traits breath weapon (90ft cone, 11d6 fire, save vs breath for half), fear aura (90ft, save vs spell), magic resistance 40%; Role solo dragon
Undead with Special Qualities
Wraith: AC 15; HD 4D; HP 20; MV 40 fly 60; #AT 1; Dmg 1d6+4 atk; ML 12; SV F4; AL C; Qual undead, incorporeal, energy drain; Notes: traits energy drain (1 level per hit, save vs death), immune to non-magical weapons, silver or magic to hit; Role ambush predator
Batch: NPC Party
Captain Varro: AC 16; HD F4; HP 28; MV 30; #AT 1; Dmg 1d8+1 atk; ML 9; SV F4; AL L; Str 15 Dex 12 Con 13 Int 10 Wis 11 Cha 14; Notes: armor chain+shield; weapon longsword+1; traits disciplined, tactical; role party leader
Scribe Tessa: AC 12; HD MU2; HP 8; MV 40; #AT 1; Dmg 1d4-1 atk; ML 6; SV MU2; AL N; Str 8 Dex 14 Con 9 Int 17 Wis 12 Cha 10; Notes: equipment spellbook, component pouch, ink and quill; traits curious, bookish; role knowledge expert
Brother Oren: AC 13; HD C3; HP 18; MV 30; #AT 1; Dmg 1d6; ML 8; SV C3; AL L; Str 11 Dex 8 Con 12 Int 13 Wis 16 Cha 12; Notes: armor leather; weapon mace; traits devout, healer, pacifist; role support healer
Classic B/X Monster (Minimal)
Orc: AC 6; HD 1; HP 5; MV 40; #AT 1; Dmg 1-8; ML 8; SV F1; AL C
Gelatinous Cube: AC 8; HD 4; HP 18; MV 20; #AT 1; Dmg 2-8; ML 12; SV F2; AL N; Qual undead, ooze, paralysis; Notes: traits transparent (surprise on 1-4), paralysis (2d4 turns, save vs paralysis), immune to cold and lightning; Role dungeon hazard
Extended Format with All Fields
Shadow Knight: AC 19; HD 6D+3; HP 33; MV 30; #AT 2; Dmg 1d10+4 atk; ML 11; SV F6; AL C; Str 17 Dex 14 Con 15 Int 13 Wis 12 Cha 16; Qual melee, necrotic; Notes: armor plate; weapon greatsword+2; equipment black cloak, unholy symbol; traits incorporeal step (phase through walls), death strike (crit on 19-20), immune to fear; role elite commander; Literacy literate
Multi-attack monster (slash Dmg)
Owlbear: AC 5; HD 5; HP 30; MV 40; #AT 3; Dmg 1d8/1d8/1d8; ML 9; SV F3; AL N; Qual melee
Caster with named spells (v14.3+)
Apprentice Voss: AAC 11; HD MU1; HP 4; MV 40; #AT 1; Dmg 1d4; ML 7; SV MU1; AL N; Str 8 Dex 12 Con 9 Int 16 Wis 11 Cha 10; Weapon: Dagger {worn}; Spells: sleep, charm person, read magic; Languages: Common, Alignment tongue; Traits: nervous, bookish; Role: apprentice
Multi-line bestiary paste (v14.3+)
Kobold
AC 7
HD 1/2
HP 3
MV 40
#AT 1
Dmg 1-4
ML 6
AL C
TT Nil
NA 4d4
SA pack tactics
Level-up existing PC (v14.3+)
Mladen: Mode: Level-up; HD F2; SV F2
(with the character sheet open, or Apply To: Mladen). Inventory and ability scores are kept; HP updates only if HP: is present; class features/homebrew re-apply from the new SV. Casters can add Spells: … on the same line.
Partial field reimport (v14.3+)
Mladen: Mode: Partial; Fields: hd, spells; HD F3; Spells: sleep, magic missile
Character with stacked consumables (Nx quantities)
Alchemist Mira: AAC 11; HD MU2; HP 6; MV 40; #AT 1; Dmg 1d4; ML 7; SV MU2; AL N; Str 8 Dex 13 Con 9 Int 16 Wis 12 Cha 11; Weapon: Dagger {worn}; Equipment: 10x Potion of Healing, 3x Potion of Fire Resistance, 2x Rations (standard, 7 days), 6x Torches (6), Rope (50'), Backpack; Coins: 12 gp, 5 sp; Spells: sleep, detect magic; Traits: careful, thrifty; Role: party alchemist
Inventory restock with stacks
Alchemist Mira: Mode: Inventory; Apply To: Alchemist Mira; Equipment: 5x Potion of Healing, 2x Holy Water (vial); Coins: 3 gp
Ready weapons and worn armor ({worn})
Ser Aldric: AAC 18; HD PAL5; HP 40; MV 20; #AT 1; Dmg 1d8+2 atk; ML 10; SV PAL5; AL L; Str 16 Dex 10 Con 14 Int 11 Wis 15 Cha 17; Weapon: Sword +2 {worn}, Dagger {stowed}; Armor: Plate Mail +1 {worn}, Shield {worn}; Equipment: Holy Symbol, 10x Potion of Healing, 2x Rations (standard, 7 days), Rope (50'); Traits: devout, inspiring; Role: front-line commander
Quick Reference Card
Single-line (core)
NAME: AC <n|AAC n>; HD <class+level|monsterHD>; HP <n>; MV <n>; #AT <n>; Dmg <dice|range|a/b/c>[+n atk]; ML <n>; SV <CLASS><LEVEL>; AL <L|N|C|Lawful|…>; [Str n Dex n …]; [Weapon: Name {worn}|Name {stowed}]; [Armor: Name {worn}]; [Equipment: Nx Name, …]; [Notes: …]; [Qual <q1, q2>]; [Feature: {Name} text.]; [Spells: name, name]; [Languages: …]; [TT/NA/SA …]; [Literacy <status>]; [Mode: …]; [Apply To: …]; [Fields: …]; [Coins: n gp]
Item stacks (multiples)
Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), Rope (50')
Weapon: 2x Dagger
Gear: 3x Holy Water (vial)
# also valid:
Equipment: Potion of Healing x10
Equipment: [Potion of Healing::{"type":"item","quantity":10}]
Worn / equipped
Weapon: Sword +2 {worn}, Dagger {stowed}
Armor: Plate Mail {worn}, Shield {worn}
Equipment: Holy Symbol, Cloak of Defence {worn}
Multi-line bestiary
NAME
AC n
HD …
…
TT …
NA …
Import modes
NAME: Mode: Inventory; Apply To: NAME; Weapon: …; Coins: …
NAME: Mode: Level-up; HD F2; SV F2
NAME: Mode: Partial; Fields: hd, spells; HD F3; Spells: sleep
Multi-attack / multi-block
NAME: #AT 2; Dmg 1d6/1d8; …
Block A: …
Block B: …
(blank line between blocks)
Parser Pipeline Summary
Input Text
→ splitBlocks() — blank-line separated multi-block paste
→ _prepare() — name + body:
• classic "Name: fields…" at first ":"
• multi-line bestiary: first line = name,
following lines joined with "; "
→ _tokenize() — split body by ";" → {key, value, raw} tokens
→ _consumeToken() — match each token (AC, HD, Dmg list, Mode,
Spells, TT/NA/SA, Languages, Fields, …)
→ _extractAbilities()— scan body for ability score pattern
→ _normalizeAndValidate() — import mode, alignment L/N/C, completeness
→ _computeConfidence() — score parse quality (FIELD_KEYS v14.3+)
→ applyToActor() — full / inventory / level-up / partial
Unknown tokens are collected and surfaced as live warnings in the dialog. In
strict mode, unknown tokens cause errors. In lenient mode, they generate
warnings. Multi-segment Dmg and #AT drive multi-weapon Attack creation
when no named Weapon: equipment is present.
OSE Equipment & Item Catalogs
CRITICAL: When writing statblocks with equipment directives (weapon:, armor:, equipment:, gear:), you MUST use exact names from these catalogs. The importer's matching algorithm scores against these canonical names. Using exact names guarantees perfect recognition. The normalized matching is forgiving, but exact matches score highest (300 points vs 120-220 for fuzzy).
How Equipment Matching Works
The importer performs a two-stage equipment resolution:
- Name Canonicalization: The requested name is normalized and matched against the
ose-equipment-stubs.json catalog below. The best-scoring canonical name replaces the input. Score >= 120 needed.
- Compendium Lookup: The canonicalized name is then searched across ALL loaded Item compendiums. Score >= 80 needed.
Scoring factors: exact match (300), prefix match (220), substring (180), word overlap (+40/word), magic bonus alignment (±80-140). Non-magical requests penalize magical matches unless +N is explicitly used.
WEAPON CATALOG (use exact names for weapon: directive)
Non-Magical Weapons
Arrows (quiver of 20), Battle Axe, Club, Crossbow, Crossbow bolts (case of 30),
Dagger, Halberd, Hammer (small), Hand axe, Javelin, Lance, Long bow, Mace,
Oil flask (burning), Polearm, Short bow, Short sword, Silver dagger,
Silver tipped arrow (1), Sling, Sling Stones, Spear, Staff, Sword,
Swords (generic), Torch, Two-handed sword, War hammer
Magical Weapons (append +N or use full name)
Arrows +1, Arrows +2, Arrow +1 Slaying, Arrow of Location,
Axe +1, Axe +2, Bow +1,
Crossbow +1 Distance, Crossbow +1 Speed, Crossbow +2 Accuracy,
Crossbow Bolts +1, Crossbow Bolts +2,
Dagger +1, Dagger +1 Buckle, Dagger +1 Throwing, Dagger +1 Venomous,
Dagger +2 +3 vs orcs goblins and kobolds, Dagger +2 Biter,
Mace +1, Mace +1 Disrupting, Mace +2, Mace +3,
Short Sword +2 Quickness,
Sling +1, Sling Bullet +1 Impact,
Spear +1, Spear +2, Spear +3, Spear -1 Backbiter (Cursed),
Sword +1, Sword +2, Sword +3,
Sword +1 +2 vs Lycanthropes, Sword +1 +2 vs Spell Users,
Sword +1 +3 vs Dragons, Sword +1 +3 vs Enchanted Creatures,
Sword +1 +3 vs Regenerating Creatures, Sword +1 +3 vs Reptiles,
Sword +1 +3 vs Shape Changers, Sword +1 +3 vs Undead,
Sword +1 Dragon Slayer, Sword +1 Energy Drain, Sword +1 Flaming,
Sword +1 Frost Brand, Sword +1 Giant Slayer, Sword +1 Light,
Sword +1 Locate Objects, Sword +1 Luck Blade, Sword +1 Sharpness,
Sword +1 Sun Blade, Sword +1 Wishes, Sword +1 Wounding,
Sword +2 Charm Person, Sword +2 Dancing, Sword +2 Nine Lives Stealer,
Sword +2 Venger, Sword +2 Vorpal, Sword +3 Defender, Sword +3 Holy Avenger,
Sword -1 Berserker (Cursed), Sword -1 Cursed, Sword -2 Cursed,
Trident +1 Fish Command, Trident +1 Submission, Trident +2 Warning,
Trident -2 Yearning (Cursed),
War Hammer +1, War Hammer +2, War Hammer +3 Dwarven Thrower,
War Hammer +3 Thunderbolts
Staves, Rods, and Wands (magical weapons)
Staff +1 Growing, Staff of Commanding, Staff of Dispelling, Staff of Healing,
Staff of Power, Staff of Snakes, Staff of Striking, Staff of Swarming Insects,
Staff of Withering, Staff of Wizardry, Staff of the Healer, Staff of the Woodlands,
Immovable Rod, Rod of Cancellation, Rod of Lordly Might, Rod of Parrying,
Rod of Striking,
Wand of Cold, Wand of Enemy Detection, Wand of Fear, Wand of Fire Balls,
Wand of Illusion, Wand of Lightning Bolts, Wand of Magic Detection,
Wand of Magic Missiles, Wand of Metal Detection, Wand of Negation,
Wand of Paralysation, Wand of Polymorph, Wand of Radiance,
Wand of Secret Door Detection, Wand of Summoning, Wand of Trap Detection
ARMOR CATALOG (use exact names for armor: directive)
Non-Magical Armor
Armour (generic), Chainmail, Dog armour, Horse barding, Leather Armour, Plate Mail
Magical Armor
Chainmail +1, Chainmail +2, Chainmail +3,
Leather Armour +1, Leather Armour +2, Leather Armour +3,
Plate Mail +1, Plate Mail +2, Plate Mail +3,
Bracers of Armour
Cursed Armor
Cursed Chainmail -1, Cursed Chainmail -2,
Cursed Leather Armour -1, Cursed Leather Armour -2,
Cursed Plate Mail -1, Cursed Plate Mail -2
Helms
Helm of Alignment Changing, Helm of Reading Languages and Magic,
Helm of Telepathy, Helm of Teleportation
SHIELD CATALOG (use exact names for armor: directive with shield)
Shield, Shield (Steel), Shield (Wood), Shield +1, Shield +2, Shield +3,
Cursed Shield -1, Cursed Shield -2, Brooch of Shielding
Note: When using armor leather+shield, the + splits into ["leather", "shield"]. The importer matches "shield" against the shield catalog. Use exact shield names like Shield (Steel) or Shield +1 for precise matching.
GEAR & ADVENTURING EQUIPMENT CATALOG (use for equipment: or gear: directives)
Standard Adventuring Gear
Backpack, Crowbar, Garlic, Grappling Hook, Holy Symbol, Holy Water (vial),
Iron Spikes (12), Lantern, Mirror (hand-sized steel), Oil (1 flask),
Pole (10' long wooden), Rations (iron, 7 days), Rations (standard, 7 days),
Rope (50'), Sack (large), Sack (small), Saddle and bridle, Saddle bags,
Stakes (3) and Mallet, Thieves' Tools, Tinder Box (flint & steel),
Torches (6), Waterskin, Wine (2 pints), Wolfsbane (1 bunch), GP
Poisons
Bloodstream Poison: I, Bloodstream Poison: II, Bloodstream Poison: III, Bloodstream Poison: IV,
Ingested Poison: I, Ingested Poison: II, Ingested Poison: III,
Ingested Poison: IV, Ingested Poison: V
Potions (use full names)
Potion of Clairaudience, Potion of Clairvoyance, Potion of Control,
Potion of Control Animal, Potion of Control Dragon, Potion of Control Giant,
Potion of Control Human, Potion of Control Plant, Potion of Control Undead,
Potion of Delusion, Potion of Diminution, Potion of ESP, Potion of Fire Resistance,
Potion of Flying, Potion of Gaseous Form, Potion of Giant Strength,
Potion of Growth, Potion of Healing, Potion of Heroism, Potion of Invisibility,
Potion of Invulnerability, Potion of Levitation, Potion of Longevity,
Potion of Poison, Potion of Polymorph Self, Potion of Speed,
Potion of Treasure Finding
Rings
Ring of Controlling Animals, Ring of Controlling Humans, Ring of Controlling Plants,
Ring of Delusion, Ring of Djinni Summoning, Ring of Fire Resistance,
Ring of Invisibility, Ring of Protection, Ring of Protection 5' Radius,
Ring of Regeneration, Ring of Spell Storing, Ring of Spell Turning,
Ring of Telekinesis, Ring of Water Walking, Ring of Weakness,
Ring of Wishes, Ring of X-Ray Vision
Scrolls
Cursed Scroll, Protection from Elementals Scroll, Protection from Lycanthropes Scroll,
Protection from Magic Scroll, Protection from Undead Scroll, Protection Scroll,
Spell Scroll, Treasure Map
Wondrous Items & Misc Magic
Alchemist's Beaker, Amulet of Protection Against Possession, Amulet of Protection Against Scrying,
Apparatus of the Crab, Bag of Devouring, Bag of Holding, Bag of Transformation,
Book of Foul Corruption, Book of Infinite Spells, Book of Sublime Holiness,
Boots of Dancing, Boots of Levitation, Boots of Speed, Boots of Travelling and Leaping,
Bracers of Defencelessness, Broom of Flying, Candle of Invocation,
Chime of Opening, Chime of Ravening,
Cloak of Defence, Cloak of Flight, Cloak of Poison, Cloak of the Manta Ray,
Crystal Ball, Crystal Ball with Clairaudience, Crystal Ball with ESP, Crystal Hypnosis Ball,
Cube of Force, Cube of Frost Resistance,
Decanter of Endless Water, Deck of Many Things, Displacer Cloak,
Drums of Panic, Drums of Thunder,
Dust of Appearance, Dust of Disappearance, Dust of Sneezing and Choking,
Efreeti Bottle,
Elemental Summoning Device (Air/Earth/Fire/Water),
Elven Cloak and Boots,
Eyes of Charming, Eyes of Minuscule Sight, Eyes of Petrification, Eyes of the Eagle,
Feather Token, Figurine of Wondrous Power, Flying Carpet, Folding Boat,
Gauntlets of Ogre Power,
Gem of Brightness, Gem of Monster Attraction, Gem of Pristine Faceting, Gem of Seeing,
Girdle of Giant Strength, Gloves of Dexterity, Gloves of Swimming and Climbing,
Horn of Blasting, Horn of Cave-Ins, Horn of Frothing, Horn of Valhalla, Horn of the Tritons,
Horseshoes of Speed, Horseshoes of a Zephyr,
Incense of Meditation, Incense of Obsession, Instant Fortress, Ioun Stones, Iron Flask,
Jug of Endless Liquids,
Libram of Arcane Power, Loadstone, Luckstone, Lyre of Building,
Marvellous Pigments,
Medallion of ESP 30', Medallion of ESP 90', Medallion of Thought Projection,
Mirror of Life Trapping, Mirror of Mental Prowess, Mirror of Opposition,
Necklace of Adaptation, Necklace of Fireballs, Necklace of Strangulation,
Net of Aquatic Snaring, Net of Snaring,
Oil of Insubstantiality, Oil of Slipperiness,
Pearl of Power, Pearl of Wisdom,
Periapt of Foul Rotting, Periapt of Health, Periapt of Proof Against Poison,
Periapt of Wound Closure,
Phylactery of Betrayal, Phylactery of Faithfulness, Phylactery of Longevity,
Pipes of the Sewers, Portable Hole, Purse of Plentiful Coin,
Restorative Ointment,
Robe of Blending, Robe of Eyes, Robe of Powerlessness,
Robe of Scintillating Colours, Robe of Useful Items, Robe of the Archmagi,
Rod of Absorption, Rod of Captivation, Rod of Resurrection,
Rope of Climbing, Rope of Entanglement, Rope of Strangulation, Rug of Suffocation,
Saw of Felling,
Scarab of Chaos, Scarab of Death, Scarab of Protection, Scarab of Rage,
Spade of Mighty Digging, Sphere of Annihilation, Sweet Water,
Talisman of the Sphere, Vacuous Grimoire
CLASS ABILITY CATALOG (auto-imported for characters via SV class)
When you write a character statblock with an SV class that maps to a feature class, the importer auto-imports ALL abilities listed for that class from the ose-advancedfantasytome.abilities compendium. Here are the available abilities per resolved feature class:
Acrobat (10 abilities)
After Reaching 9th Level, Climb sheer surfaces (CS), Combat, Evasion,
Falling (FA), Hide in shadows (HS), Jumping, Move Silently (MS),
Tightrope Walking (TW), Tumbling Attack
Assassin (10 abilities)
After Reaching 12th Level, Assassination (AS), Climb sheer surfaces (CS),
Combat, Disguise, Hear noise (HN), Hide in shadows (HS), Hirelings,
Move Silently (MS), Poison
Barbarian (12 abilities)
After Reaching 8th Level, Agile Fighting, Climb Sheer Surfaces (CS), Combat,
Cure Poison, Fear of Magic, Foraging, Foraging and Hunting,
Hide In Undergrowth (HD), Hunting, Move Silently (MS), Strike Invulnerable Monsters
Bard (7 abilities)
After Reaching 11th Level, Anti-Charm, Combat, Divine Magic, Enchantment,
Languages, Lore
Cleric (4 abilities)
After Reaching 9th Level, Combat, Divine Magic, Turn Undead
Drow (8 abilities)
After Reaching 9th Level, Combat, Detect Secret Doors, Divine Magic,
Immunity to Ghoul Paralysis, Light Sensitivity, Listening at Doors, Spider Affinity
Druid (10 abilities)
Charm Immunity, Combat, Divine Magic, Energy Resistance, Identification,
Pass Without Trace, Path-Finding, Reaching 12th Level and Above,
Shape Change, Sylvan Languages
Duergar (9 abilities)
After Reaching 9th Level, Combat, Detect Construction Tricks, Detect Room Traps,
Infravision, Light Sensitivity, Listening at Doors, Mental Powers, Stealth
Dwarf (6 abilities)
After Reaching 9th Level, Combat, Detect Construction Tricks, Detect Room Traps,
Infravision, Listening at Doors
Elf (7 abilities)
After Reaching 9th Level, Arcane Magic, Combat, Detect Secret Doors,
Immunity to Ghoul Paralysis, Infravision, Listening at Doors
Fighter (9 abilities)
After Reaching 9th Level, Chivalric Code, Combat, Flying Mounts, Horsemanship,
Hospitality, Mounted Combat, Strength Of Will, Stronghold
Gnome (11 abilities)
After Reaching 8th Level, Arcane Magic, Combat, Defensive Bonus,
Detect Construction Tricks, Hiding, Hiding In Dungeons,
Hiding in Woods/Undergrowth, Infravision, Listening at Doors,
Speak with Burrowing Mammals
Half-Elf (5 abilities)
After Reaching 9th Level, Arcane Magic, Combat, Detect Secret Doors, Infravision
Half-Orc (8 abilities)
After Reaching 8th Level, Back-stab, Combat, Hide in shadows (HS), Infravision,
Move Silently (MS), Pick pockets (PP), Retainers
Halfling (9 abilities)
Combat, Defensive Bonus, Hiding, Hiding In Dungeons, Hiding in Woods/Undergrowth,
Initiative Bonus (Optional Rule), Listening at Doors, Missile Attack Bonus, Stronghold
Illusionist (3 abilities)
After Reaching 11th Level, Arcane Magic, Combat
Knight (resolves to fighter for SV, separate feature class)
Knight uses Fighter abilities listed above.
Magic-User (3 abilities)
After Reaching 11th Level, Arcane Magic, Combat
Paladin (8 abilities)
After Reaching 9th Level, Combat, Divine Magic, Holy Resistance,
Laying On Hands, Turning Undead, Vow Of Humility, Warhorse
Ranger (11 abilities)
After Reaching 10th Level, Awareness, Combat, Divine Magic, Foraging,
Foraging and Hunting, Hunting, Limited Possessions, Pursuit, Stealth, Tracking
Svirfneblin (13 abilities)
After Reaching 8th Level, Blend into Stone, Blend into Stone (Gloomy),
Blend into Stone (Well-Lit), Combat, Defensive Bonus, Detect Construction Tricks,
Illusion Resistance, Infravision, Light Sensitivity, Speak with Earth Elementals,
Stone Murmurs, Using Magic Items
Thief (12 abilities)
After Reaching 9th Level, Back-stab, Climb sheer surfaces (CS), Combat,
Find/remove treasure traps (TR), Hear noise (HN), Hide In Shadows (HS),
Move silently (MS), Open Locks (OL), Pick Pockets (PP), Read Languages, Scroll Use
RACE ABILITY CATALOG (auto-imported for characters via race)
The importer can also match race-specific abilities using the race ability map. These are the race abilities available per race:
Drow (7 abilities)
Available Classes and Max Level, Detect Secret Doors, Immunity to Ghoul Paralysis,
Infravision, Innate Magic, Light Sensitivity, Listening at Doors
Duergar (9 abilities)
Available Classes and Max Level, Combat, Detect Construction Tricks, Detect Room Traps,
Infravision, Light Sensitivity, Listening at Doors, Resilience, Stealth
Dwarf (7 abilities)
Available Classes and Max Level, Combat, Detect Construction Tricks, Detect Room Traps,
Infravision, Listening at Doors, Resilience
Elf (5 abilities)
Available Classes and Max Level, Detect Secret Doors, Immunity to Ghoul Paralysis,
Infravision, Listening at Doors
Gnome (8 abilities)
Available Classes and Max Level, Combat, Defensive Bonus, Detect Construction Tricks,
Infravision, Listening at Doors, Magic Resistance, Speak with Burrowing Mammals
Half-Elf (3 abilities)
Available Classes and Max Level, Detect Secret Doors, Infravision
Half-Orc (2 abilities)
Available Classes and Max Level, Infravision
Halfling (7 abilities)
Available Classes and Max Level, Combat, Defensive Bonus,
Initiative Bonus (Optional Rule), Listening at Doors, Missile Attack Bonus, Resilience
Human (2 abilities)
Available Classes and Max Level, Racial Abilities (Optional Rule)
Svirfneblin (12 abilities)
Available Classes at Max Level, Blend into Stone, Blend into Stone (Gloomy),
Blend into Stone (Well-Lit), Combat, Defensive Bonus, Detect Construction Tricks,
Illusion Resistance, Infravision, Light Sensitivity, Listening at Doors,
Speak with Earth Elementals
COMPENDIUM OVERVIEW
The importer searches these compendium packs for item matching:
| Compendium | Type | Item Count |
|---|
ose-advancedfantasytome.abilities | Class Abilities | 93 |
ose-advancedfantasytome.race-abilities | Race Abilities | ~50 |
ose-advancedfantasytome.ose-equipment | Equipment | 71 |
ose-advancedfantasytome.ose-magic-items | Magic Items | 311 |
ose-advancedfantasytome.ose-monsters | Monsters | 428 |
ose-advancedfantasytome.ose-animals | Animals | 8 |
ose-advancedfantasytome.ose-macros | Macros | 5 |
ose-advancedfantasytome.ose-players-tome | Journal Entries | 14 |
STATBLOCK WRITING RULES WITH CATALOG KNOWLEDGE
When writing equipment in statblocks:
- Use exact canonical names from the catalogs above for perfect matching
- Weapons: use names from the WEAPON CATALOG. Prefer
Sword over longsword (the OSE catalog uses Sword). Use Battle Axe not battleaxe. Use Hand axe not handaxe.
- Armor: use
Leather Armour, Chainmail, Plate Mail (British spelling "Armour" is canonical). Use Shield for basic shield, Shield (Steel) or Shield (Wood) for specific.
- Magical items: append
+N for simple bonus, or use full magical name. Example: Sword +1, Leather Armour +1, Shield +1.
- Gear: use exact names like
Rope (50'), Torches (6), Rations (standard, 7 days), Tinder Box (flint & steel).
- Poisons: use the numbered format:
Bloodstream Poison: III, Ingested Poison: I.
- Multiples: prefix
Nx before the catalog name — 10x Potion of Healing, 2x Rations (standard, 7 days), 3x Holy Water (vial). Foundry shows stacks as value/max (10/10). Never repeat the same item name N times in a comma list.
- Worn: append
{worn} on ready weapons and worn armor/shields — Sword +1 {worn}, Plate Mail {worn}, Shield (Steel) {worn}. Use {stowed} for pack/backup weapons. Without this, armor may not count as worn and weapons may not show ready.
Equipment Examples Using Exact Names
; weapon Sword +1 {worn}, Dagger {stowed}; armor Chainmail {worn}, Shield (Steel) {worn}
; weapon Mace {worn}; armor Leather Armour {worn}, Shield (Wood) {worn}
; weapon Battle Axe {worn}; armor Plate Mail {worn}
; equipment Rope (50'), 6x Torches (6), 2x Rations (standard, 7 days), Tinder Box (flint & steel)
; equipment Thieves' Tools, Grappling Hook, Crowbar, Iron Spikes (12)
; equipment 10x Potion of Healing, 2x Potion of Fire Resistance, 3x Holy Water (vial)
; Equipment: 10x Potion of Healing, 2x Rations (standard, 7 days), Rope (50'), Backpack
; Weapon: Sword +2 {worn}; Armor: Plate Mail +1 {worn}, Shield {worn}; Equipment: Holy Symbol, 10x Potion of Healing
Class Feature Import Behavior
When you write SV F3, the importer:
- Sets save progression from the Fighter table for level 3
- Auto-imports ALL 9 fighter abilities from the compendium
- Sets
system.details.class to "Fighter"
When you write SV BARB2, the importer:
- Sets save progression from the Barbarian table for level 2
- Auto-imports ALL 12 barbarian abilities from the compendium
- Sets class display to "Barbarian"
When you write SV PAL5, the importer:
- Sets save progression from the Paladin table for level 5
- Auto-imports ALL 8 paladin abilities from the compendium
- Sets class display to "Paladin"
Duplicate prevention: If an ability already exists on the actor (tracked by compendium source UUID), it is never re-imported. You can safely re-import the same statblock without duplication.
