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.

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

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.

<pre style="background: #1e1e1e; color: #d4d4d4; padding: 0.75em 1em; overflow-x: auto; border-radius: 4px;">{ "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 }] }] }</pre>

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.

<pre style="background: #1e1e1e; color: #d4d4d4; padding: 0.75em 1em; overflow-x: auto; border-radius: 4px;">[ { "code": "gardening", "color": "#4F7F3C", "trainings": [{ "code": "gardener", "levels": [{ "level": 1, "xp": 100, "title": "Gardener", "trait": "green-thumb" }] }] } ]</pre>

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.

<pre style="background: #1e1e1e; color: #d4d4d4; padding: 0.75em 1em; overflow-x: auto; border-radius: 4px;">[ { "type": "craft", "training": "gardener", "recipe": "mymod:flowerpot-", "xp": 5 }, { "type": "book", "training": "gardener", "item": "mymod:trainingbook-gardener", "xp": 100 } ]</pre>

---

🔒 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 &mdash; one ungated with extra ingredients (so untrained players can still build it the hard way), one trait-gated with a simpler ingredient list.

<pre style="background: #1e1e1e; color: #d4d4d4; padding: 0.75em 1em; overflow-x: auto; border-radius: 4px;">[ { "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 } }, {