add-item

Imported from PJensen/jshack (.agents/skills/add-item/SKILL.md). Install upstream with npx skills add PJensen/jshack --skill add-item. Copyright stays with the author.

Add a new item with id $ARGUMENTS to the game.

Steps

1. Ask the user for the item concept if not obvious from the name — category (weapon/armor/consumable/tool/scroll/etc.), theme, special behavior, flavor.
2. Read the reference files listed below to understand existing patterns.
3. Define the item in src/rules/data/itemCatalog.js (ITEM_CATALOG object).
4. Add a palette entry in src/display/palette/base.js so it renders on screen.
5. Add to a loot table in src/rules/data/lootTables.js so it can drop.
6. Add any new hooks if the item has special behavior (use, drink, dip, throw).
7. Run tests: deno test --allow-read.

Reference files to read before writing:

• src/rules/data/itemCatalog.js — existing items, all patterns
• src/display/palette/base.js — existing glyph/color entries
• src/rules/data/lootTables.js — table structure and weights

Item Categories

Choose the right type and catalogKind for the item:

File 1: Item Catalog (src/rules/data/itemCatalog.js)

Add an entry to the ITEM_CATALOG object. Key = item id.

Required Fields (all items)

my_item: {
  id:           "my_item",          // must match key
  catalogKind:  "equipment",        // "equipment" | "magic" | "material" | "seed" | "food"
  name:         "My Item",          // display name
  type:         "equip",            // see type table above
  slot:         "weapon",           // see Slots section below
  material:     "steel",            // see Materials section below
  rarity:       1,                  // 1=common 2=magic 3=rare 4=epic 5=legendary
  rarityName:   "common",           // matching string label
  description:  "Flavor text.",
},

Equipment Fields (weapons & armor)

// Weapon-specific
damageDice:   "1d6",              // damage roll (e.g. "1d4", "2d6")
damageType:   "slash",            // "blunt" | "slash" | "pierce" | "fire" | "poison" etc.
staminaCost:  3,                  // stamina per attack
twoHanded:    false,              // true blocks offhand slot

// Stat bonuses (optional, mix-and-match)
bonuses: {
  attack:        2,               // hit chance bonus
  defense:       1,               // armor class bonus
  critChance:    0.05,            // 5% crit chance
  critMult:      0.5,             // 50% extra crit damage
  maxHp:         10,
  maxStamina:    5,
  staminaRegen:  1,
  maxMana:       10,
  manaRegen:     1,
  spellHit:      2,
  spellAvoid:    2,
  spellRadius:   1,
  fireResist:    0.25,            // 0.0-1.0
  poisonResist:  0.25,
  acidResist:    0.25,
  electricOhms:  50,
  bluntResist:   0.1,
  slashResist:   0.1,
  pierceResist:  0.1,
  kineticDR:     3,               // flat kinetic damage reduction
  luck:          1,
  visionRange:   1,
  dig:           1,               // mining effectiveness (pickaxes)
},

// Gem sockets (optional)
maxSockets:   2,                  // how many gems can be socketed

Consumable Fields (potions)

type: "potion",
slot: "bag",
potion: {
  route:    "oral",               // "oral" | "splash" | "dip" | "throw"
  doses:    1,
  channels: ["vitality"],         // ["vitality"] | ["stamina"] | ["mana"] | []
  effects:  [
    { key: "heal",  potency: 25, onset: 0, peak: 0, duration: 0, stack: 1, maxStacks: 1 },
    { key: "haste", potency: 1,  onset: 0, peak: 0, duration: 10, stack: 1, maxStacks: 1 },
  ],
  toxicity:  null,                // null | "poison" | "disease"
  beatitude: "uncursed",          // "blessed" | "uncursed" | "cursed"
  feel:      "You feel refreshed!",
},
hooks: { on_drink: myDrinkHook },  // if behavior beyond simple effects

Scroll Fields

type: "scroll",
slot: "bag",
hooks: {
  on_use: createCastSpellFromIdentityHook({
    identityPrefix: "scroll_",
    targetMode: "self",           // "self" | "intentTarget"
    consumeOnSuccess: true,
  }),
},

Spellbook Fields (teaches a spell)

// id MUST be "book_{spell_id}" — the hook strips the prefix to get spell id
type: "learn",
slot: "bag",
hooks: {
  on_use: createLearnSpellFromIdentityHook({
    identityPrefix: "book_",
    consumeOnSuccess: true,
  }),
},

Flavor Book Fields

type: "book",
slot: "bag",
hooks: {
  on_use: createOpenFlavorBookHook("Title of Book", "Full text goes here. Can be long."),
},

Equipment Slots

weapon    — primary hand weapon
offhand   — shield or secondary 1H weapon (dual-wield)
armor     — body armor
head      — helm / hat / crown
neck      — amulet / pendant / necklace
belt      — waist belt
gloves    — gauntlets / gloves
ring1     — first ring slot (use "ring" and system assigns ring1/ring2)
ring2     — second ring slot
legs      — leggings / greaves (lower body)
feet      — boots / footwear
ammo      — ammunition
ranged    — bow / crossbow
bag       — inventory only (not equipped)

Materials

Common choices by item category:

Hook Patterns

Import hook creators from ./callbacks/items.js (or the relevant callbacks file — check existing imports at the top of itemCatalog.js).

Spell scroll

hooks: {
  on_use: createCastSpellFromIdentityHook({
    identityPrefix: "scroll_",
    targetMode: "self",
    consumeOnSuccess: true,
  }),
},

Spellbook

hooks: {
  on_use: createLearnSpellFromIdentityHook({
    identityPrefix: "book_",
    consumeOnSuccess: true,
  }),
},

Flavor book

hooks: {
  on_use: createOpenFlavorBookHook("My Title", "Page one text..."),
},

Poison coating (dippable poison)

hooks: {
  can_dip_target: (state) => state.targetInfo?.damageDice != null,
  on_dip: createPoisonCoatDipHook({
    chargesGranted: 5,
    coatingColor: "#84d26d",
    messageTemplate: "The blade is coated with poison.",
  }),
},

Thrown hazard

hooks: {
  on_throw: createTorchThrowHook({ turnsLeft: 30, radius: 1, tickDamage: 3 }),
},

Custom on_use (active item, special tool)

hooks: {
  on_use(ctx, state) {
    // ctx.world, ctx.helpers, state.actorId, state.itemId, state.itemInfo
    const { world } = ctx;
    // ... custom logic ...
    return { consumed: true };
  },
},

File 2: Palette Entry (src/display/palette/base.js)

Every item needs a palette entry to render on the ground or in UI. Add to the relevant section.

my_item: { glyph: "!", fg: "#66ff99", glow: "#44bb77" },

Fields

• glyph — single character or emoji shown on map/UI
• fg — foreground hex color
• glow — glow/shadow color (usually slightly darker)

Glyph Conventions by Type

Color Families by Theme

File 3: Loot Table (src/rules/data/lootTables.js)

Add to the appropriate sub-table. Common choices:

// Common equipment drop
{ type: "equip", weight: 20, pool: ["my_weapon"], affixChance: 0.2, affixCountMax: 1 },

// Magic item (potion, scroll, book)
{ type: "item",  weight: 25, itemId: "potion_my_potion" },

// Into sub:spellbooks
{ type: "item",  weight: 20, itemId: "book_my_spell" },

// Into a specific depth table (e.g. "drop:tier1", "drop:tier2")
{ type: "table", weight: 15, table: "sub:equip_magic" },

Weight guidance:

• Common drops: 25-35
• Magic items: 18-28
• Rare/epic gear: 10-20
• Legendary: 3-8
• Nothing (skip slot): 30-60

Table selection:

• Generic mob drops → find the tier table (e.g. "drop:tier0", "drop:tier1")
• Spellbooks → "sub:spellbooks"
• Common equipment → "sub:equip_common"
• Magic equipment → "sub:equip_magic"
• Rare equipment → "sub:equip_rare"

Balance Guidelines

Weapon Balance by Tier

Armor Balance by Slot

Consumable Balance

• Health potions: heal 15-60 HP depending on tier
• Mana potions: restore 10-40 mana
• Status potions: 5-15 turn duration
• Resist potions: 0.25-0.5 resist value, 20-40 turns

Rules

• JavaScript only — no TypeScript.
• Never use Math.random() in rules code. Potions and scrolls don't need RNG at definition time, but any hook that rolls RNG must use world.rand() or a deterministic seed.
• Item id must match the object key in ITEM_CATALOG.
• Always add a matching palette entry in src/display/palette/base.js.
• Always add the item to at least one loot table (or document why it is shop/quest-only).
• Run deno test --allow-read after all changes.