Progression Framework

Quests, training, and evolving traders for Vintage Story modders.

Progression Framework is a content-empty mod that provides three reusable systems for other mods to build on: a quest engine, a training/profession engine, and an evolving-trader engine. Drop JSON into your mod's asset folders and the framework discovers it at load time.

---

✨ For Players

This mod adds nothing on its own it was built for the Seafarer mod to provide quests, training, and unlocks.

What it gives you in-game

• Training Ledger (L) — A tabbed dialog showing your training progress and active quests.
• Quest log — Quests track automatically as you talk to NPCs and turn in items.
• Evolving traders — NPC stock and dialogue change as you complete work for them.

---

🧩 For Modders — Overview

The framework scans every loaded mod domain for content at AssetsFinalize. Drop JSON into the conventional paths below and you have working content.

Subsystem	Path	Notes
Quests	<yourmod>:config/quests/*.json	First-loaded wins on collisions.
Training	<yourmod>:config/training/*.json	Recognised filenames: professions.json, xp.json, config.json.
Tradelists	<yourmod>:config/tradelists/*.json	Looked up by stem from EntityEvolvingTrader JSONs.
Dialogue	base-game NPC conversation system	Quests subscribe to dialogue triggers.

Registered identifiers

These names are stable for cross-mod use: entity class EntityEvolvingTrader, item class ItemTrainingBook, hotkey progressionframeworkledger, network channel progressionframework:questsync, Harmony id progressionframework.

---

📋 Adding a Quest

Save a JSON file under your mod's config/quests/. The code is its identifier; npc is the entity code that gives it. delivery objectives count items the player turns in to that NPC; rewards fire when the threshold is hit.

{
  "code": "harvest-help",
  "npc": "mymod:trader-farmer",
  "scope": "server",
  "autoEnable": true,
  "objectives": [{
    "code": "deliver-wheat",
    "type": "delivery",
    "items": [{ "item": "game:grain-spelt", "quantity": 1 }],
    "required": 32,
    "rewards": [{ "type": "addSellingItem", "itemCode": "game:scythe-copper", "itemType": "item", "stacksize": 1, "stockAvg": 1, "stockVar": 0, "priceAvg": 8, "priceVar": 1 }]
  }]
}

Quest titles, descriptions, and group names go through your mod's lang/en.json using the titleLangKey, descriptionLangKey, and groupLangKey fields.

---

🎓 Adding Training

A profession contains one or more trainings; each training has levels; each level grants a trait. Save the list at config/training/professions.json.

[
  {
    "code": "gardening",
    "color": "#4F7F3C",
    "trainings": [{
      "code": "gardener",
      "levels": [{ "level": 1, "xp": 100, "title": "Gardener", "trait": "green-thumb" }]
    }]
  }
]

XP sources go in config/training/xp.json. The craft kind grants XP whenever a matching grid recipe completes; book when an ItemTrainingBook is read; dialogue when a registered dialogue trigger fires.

[
  { "type": "craft", "training": "gardener", "recipe": "mymod:flowerpot-*", "xp": 5 },
  { "type": "book",  "training": "gardener", "item": "mymod:trainingbook-gardener", "xp": 100 }
]

---

🔒 Gating a Recipe with a Crafting Trait

Once a training level grants a trait (green-thumb in the example above), any grid recipe variant with requiresTrait: "green-thumb" only matches when the player has earned that trait. A common pattern is to ship two variants — one ungated with extra ingredients (so untrained players can still build it the hard way), one trait-gated with a simpler ingredient list.

[
  {
    "ingredientPattern": "S,F,R",
    "ingredients": {
      "S": { "type": "item", "code": "mymod:schematic-greenhouse" },
      "F": { "type": "item", "code": "game:firewood",   "quantity": 5 },
      "R": { "type": "item", "code": "game:rope",       "quantity": 4 }
    },
    "width": 1, "height": 3, "shapeless": true,
    "output": { "type": "block", "code": "mymod:greenhouse-frame", "quantity": 1 }
  },
  {
    "requiresTrait": "green-thumb",
    "ingredientPattern": "F,R",
    "ingredients": {
      "F": { "type": "item", "code": "game:firewood", "quantity": 5 },
      "R": { "type": "item", "code": "game:rope",     "quantity": 4 }
    },
    "width": 1, "height": 2, "shapeless": true,
    "output": { "type": "block", "code": "mymod:greenhouse-frame", "quantity": 1 }
  }
]

requiresTrait is a base-game GridRecipe field, not a Progression Framework one — the framework's contribution is granting the trait via training so the recipe gate fires.

---

🛠 Built-in Handlers

• Quest objective types — delivery, kill.
• Quest reward types — addSellingItem, giveItem, awardTrainingXP, incrementEntityVariable.
• XP source kinds — craft, dialogue, book.

Need something custom? Register your own handler from C# in your mod's Start(): questSystem.RegisterObjectiveType("fetch", new MyFetchHandler());. Implement IQuestObjectiveHandler, IQuestRewardHandler, or IXpSourceHandler.

---

🔧 Compatibility & Requirements

Required: Vintage Story 1.22.0-rc.7 or newer.

Known incompatibilities: none reported.