Crafting, Recipes & Item Graph

1. Summary

Crafting is multi-tier and deep: raw world materials refine through N levels into finished unique item instances (18) — tools, weapons, food, spells, stalls, and soul-bind consumables.

Every craftable is defined in an item construction graph (DAG): nodes = item templates; edges = recipes. Craft success mints a new instance_id with rolled quality and stats — never a generic stackable sword.

Enchantments extend instances further (17). NPC settlements use the same recipes via worker pools (18 §6).

2. Design principles

3. Material tiers (conceptual)

Tier 0 — RAW (world harvest)
  iron_ore, oak_log, wild_herb, raw_gem, animal_hide, ...

Tier 1 — PROCESSED
  iron_shard, lumber, cured_leather, herb_paste, cut_gem, ...

Tier 2 — REFINED
  iron_ingot, hardwood_plank, leather_strip, distilled_oil, ...

Tier 3+ — COMPONENTS
  iron_blade_blank, bow_stave, spell_ink, stew_base, ...

FINISHED — PRODUCTS
  longsword, hunting_bow, soul_bind_scroll, market_stall_kit, iron_stew, ...

Depth is not capped at 3 — a recipe chain can be 6+ hops (ore → ingot → blade → hilt → sword → enchant flame edge on instance via 17).

3.1 Food crafting & economy (decided)

Cooked meals are a primary player-driven commodity (10, 15):

Cooks, herbalists, and fishers supply adventurers and worker lodging pantries (13).

4. Recipe model

struct Recipe {
    id: RecipeId,
    output: ItemTemplateId,
    output_qty: u32,
    inputs: Vec<RecipeInput>,      // materials + qty
    required_tools: Vec<ToolReq>,    // items held or station nearby
    required_station: Option<StationKind>, // forge, kitchen, alchemy_table, ...
    skill: Option<SkillReq>,
    craft_time_ticks: u32,
    failure_chance: f32,             // skill modifies
    byproducts: Vec<RecipeInput>,    // optional
}

struct RecipeInput {
    item: ItemTemplateId,
    qty: u32,
    consumed: bool,                  // false = catalyst (e.g. reusable mold)
}

struct ToolReq {
    item: ItemTemplateId,            // e.g. smithing_hammer
    consumed: bool,
    min_durability: Option<f32>,
}

4.2 Craft failure & quality (decided)

4.3 Examples

Iron ingot

Iron stew (food)

Longsword

Each input item has its own upstream recipes — the graph resolves recursively for planning UIs (“what do I still need?”).

5. Item construction graph

5.1 Structure

Directed acyclic graph (detect cycles at content build time):

Node  = ItemTemplate
Edge  = Recipe (output → inputs)

soul_bind_scroll ──► blank_scroll, spirit_ink, bound_salt
spirit_ink       ──► ghost_mushroom, distilled_oil
distilled_oil    ──► wild_herb, glass_vial
glass_vial       ──► sand, furnace_fuel
...

5.2 Runtime services

5.3 Spells as craft outputs

Soul-bind scroll (and similar) are crafted consumables, not vendor buttons:

Recipe: soul_bind_scroll
  inputs: blank_scroll, spirit_ink, silver_dust
  station: inscription_table
  skill: arcane_inscription ≥ 20
  output: soul_bind_scroll × 1

Using the scroll on an eligible item triggers bind ritual (07 §4.3, §6).

6. Soul-binding process (decided)

6.1 Requirements

6.2 Flow

1. Player crafts soul_bind_scroll (crafting graph)
2. Player targets eligible item in inventory
3. Server validates: not already bound, scroll present, fees paid
4. Set item_instance.soul_bound = true
5. Audit log + bind timestamp; scroll consumed

Higher-tier binds (multi-slot gear) may require greater soul-bind elixir — deeper recipe chain.

6.3 Economy tie-in

Soul-bind consumables are tradeable until used — crafters supply bind services (10).

7. Tools & stations

7.1 Portable tools

Items in inventory/hands: hammer, cooking pot, knife, inscription stylus.
May have durability; craft recipes can wear them down.

7.2 World stations

Stations can be Area fixtures (town forge) or player-placed in building fixture anchors (20 §9.2).

7.3 Tool crafting

Tools are normal graph nodes — e.g. cooking_pot requires iron_ingot, clay, smelting + pottery skills.

8. Crafting execution (server)

1. Player submits CraftIntent { recipe_id, qty, station_id }
2. Region worker validates local station/tools
3. Central confirms inventory debit + mints unique instance(s) with quality/stat rolls (18)
4. Skill XP granted; failure rolls per recipe
5. Client receives inventory delta + craft result event

Batch queue for long crafts (food simmer, sword forge) — progress tick, interrupt rules.

8.1 Factory automation (workers)

Players automate multi-step production via hired workers, craft residences, devices, and job cycles — see 13-workers-and-automation.html. Workers execute the same recipes and stations as players; devices are the world anchor for worker craft steps.

9. TUI / agent

• flatland craft list --station forge
• flatland craft plan longsword → full BOM tree with missing nodes
• flatland craft start <recipe> --qty 1
• flatland soulbind use <scroll> <item>
• flatland enchant start <recipe> --item <instance> (17)

Agent JSON: recipe graph export for planning bots; enchant defs + margin planning.

10. Phasing

11. Open questions

Resolved (2026-07-06):

12. Content pipeline

assets/
  items/*.yaml          # templates, mass, volume, packable, can_soul_bind, enchantable
  recipes/*.yaml        # recipe definitions
  enchantments/*.yaml   # enchant defs (`17`)
  enchant_recipes/*.yaml
  stations/*.yaml       # station kinds per Area manifest
tools/
  validate-recipe-graph.mjs   # cycle detect, orphan check
  validate-enchant-graph.mjs

Economy, stalls, brokers: 10-economy-and-markets.html