diff options
Diffstat (limited to 'building_guide/items.md')
| -rw-r--r-- | building_guide/items.md | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/building_guide/items.md b/building_guide/items.md new file mode 100644 index 0000000..52bfa7d --- /dev/null +++ b/building_guide/items.md @@ -0,0 +1,190 @@ +## Items + +```yaml +id: bronze_pickaxe +name: bronze pickaxe +color: "178" # xterm-256 color index (0-255) +aliases: ["pick", "pickaxe"] +description: "A sturdy bronze pickaxe." +value: 10 +stackable: false +equip_slot: main_hand # optional — where it equips +weapon_type: melee # optional — melee, ranged, or science +attack_type: stab # stab/slash/crush/ranged/science — determines accuracy type +stats: # optional — per-type combat bonuses + stab_attack: 4 + slash_attack: -2 + crush_attack: 2 + strength_bonus: 3 +speed: 5 # ticks between attacks +tool_type: pickaxe # used by gather behaviors that require "tool: pickaxe" +tool_speed: 2 # reduces gather wait time +requirements: # optional — skill levels needed to equip + accuracy: 1 +``` + +### Equipment Stats (ItemStats) + +Weapons have per-type **attack bonuses** — these determine accuracy based on the weapon's `attack_type`: + +| Field | Description | +|---|---| +| `stab_attack` | Accuracy bonus for stab attacks | +| `slash_attack` | Accuracy bonus for slash attacks | +| `crush_attack` | Accuracy bonus for crush attacks | +| `science_attack` | Accuracy bonus for science attacks | +| `ranged_attack` | Accuracy bonus for ranged attacks | + +Armor has per-type **defense bonuses** — the mob's `attack_type` determines which defense is used: + +| Field | Description | +|---|---| +| `stab_defense` | Defense vs stab attacks | +| `slash_defense` | Defense vs slash attacks | +| `crush_defense` | Defense vs crush attacks | +| `science_defense` | Defense vs science attacks (negative on metal armor) | +| `ranged_defense` | Defense vs ranged attacks | + +Other damage/utility bonuses: + +| Field | Description | +|---|---| +| `strength_bonus` | Melee max hit bonus | +| `ranged_strength` | Ranged max hit bonus (on ammo) | +| `science_damage` | Science max hit bonus | +| `technology_bonus` | Reduces tech battery drain rate | + +### Attack Type + +Weapons should always set `attack_type`. Common mappings: + +| Category | attack_type | +|---|---| +| Swords | slash | +| Daggers | stab | +| Axes | slash | +| Pickaxes | stab | +| Bows | ranged | +| Unarmed | crush (default) | + +### Equipment Requirements + +Higher-tier equipment requires skill levels to equip: + +```yaml +requirements: + accuracy: 20 # melee weapons + defense: 20 # armor + ranged: 30 # ranged weapons/armor +``` + +Standard tiers: bronze/iron (none), steel (5), black (10), mithril (20), adamant (30), rune (40), dragon (60). + +### Ranged Ammo + +Arrows and bolts use `ranged_strength` for damage. Accuracy comes from the bow: + +```yaml +id: iron_arrow +name: iron arrow +stackable: true +equip_slot: ammo +stats: + ranged_strength: 10 +``` + +### Color + +The `color` field accepts xterm-256 palette indices (0-255) with optional modifiers: + +```yaml +color: "178" # bronze/gold +color: "75 bold" # bold steel blue +color: "g:196,208,226" # gradient red → orange → gold +``` + +In ANSI mode, extended colors (16-255) automatically downgrade to the nearest ANSI color. Use `colortable` in-game to see all 256 colors. + +Key item (quest token, not equippable): +```yaml +id: pass_stub +name: pass stub +description: "A crumpled slip of paper stamped with the guard's seal." +value: 0 +stackable: false +``` + +--- + +## Firemaking + +```yaml +id: logs +name: logs +fire_level: 1 # firemaking level required +fire_xp: 40 # XP for burning/stoking +burn_ticks: 24 # how long the fire burns +``` + +## Food / Healing + +```yaml +id: bread +name: bread +color: "222" +description: "A fresh loaf of bread, still warm from the oven." +value: 5 +heal_value: 5 # positive = heal, negative = damage +eat_message: "You eat the bread. Warm and satisfying." +``` + +## MadeFrom — Item Combinations + +Define what items combine to make this item. Used by the `use` command. Combinations run through the production system — players are prompted "How many?" and the action loops with a timer. + +```yaml +id: bread_dough +name: bread dough +color: "222" +ticks: 2 +made_from: + - items: [pot_of_flour] + quantity: 1 + byproducts: [empty_pot] + - items: [bucket_of_water, pitcher_of_water] + quantity: 1 + byproducts: [empty_bucket, empty_pitcher] +``` + +Each entry is an ingredient slot. Multiple `items` means any of them works. The first matching item found in inventory is consumed. + +`ticks` controls how many game ticks each production cycle takes (default 2). + +### Byproducts + +`byproducts` is a list matching the `items` list by index. When `bucket_of_water` (items[0]) is consumed, `empty_bucket` (byproducts[0]) is returned to inventory. When `pitcher_of_water` (items[1]) is consumed, `empty_pitcher` (byproducts[1]) is returned instead. + +Use `""` for items that produce no byproduct: + +```yaml +made_from: + - items: [pot_of_flour, loose_flour] + quantity: 1 + byproducts: [empty_pot, ""] # pot returns empty_pot, loose flour returns nothing + - items: [bucket_of_water] + quantity: 1 + byproducts: [empty_bucket] +``` + +Omit `byproducts` entirely if no items in that slot produce a byproduct: + +```yaml +made_from: + - items: [pot_of_flour] + quantity: 1 + byproducts: [empty_pot] # returns empty_pot + - items: [salt] + quantity: 1 # no byproducts field — salt is consumed entirely +``` + +See also `recipes.md` for station-based recipes. |