ashen-realms/docs/playable-slices/0.9-First-Quest-and-Bag-Tutorial.md

# Ashen Realms – Playable Slice 0.9

## First Quest & Loot-Bag Tutorial

**Status:** Implementation Specification  
**Depends on:** Slice 0.8.5  
**Purpose:** Introduce quests, NPC-directed progression, bag capacity and the merchant loop through one small coherent tutorial chain.

---

## 1. Goal

This slice should teach several systems without a conventional tutorial popup sequence.

The player learns naturally that:

- NPCs provide direction
- monster goods must be carried
- carrying capacity matters
- merchants can help
- reputation affects relationships/offers
- hunting goods can later be exchanged for progression

The quest should feel like world interaction, not a checklist tutorial.

---

## 2. Quest Concept

Working quest title:

**Trouble Beyond the Gate**

Quest-giver:

**South Gate Warden**

Use an existing named gate NPC if one has already been implemented. Do not create a duplicate NPC merely because this document uses a generic title.

Merchant:

**Borin, Quartermaster** or the existing Graufurt merchant.

---

## 3. Narrative Flow

### Step 1 – Speak with the South Gate Warden

The warden is concerned about increasingly aggressive scavengers and raiders beyond the gate.

Player-facing English example:

> "The road has gone bad. Start small. Bring me five Ashen Pelts from the rats beyond the gate. I want to know what the ash is doing to them."

Objective:

```text
Collect 5 Ashen Pelts
```

---

## 4. Capacity Problem

The player currently has no Hide Bag.

Default HIDE capacity is 1.

After collecting the first Ashen Pelt:

```text
Ashen Pelts 1 / 1
Hide capacity reached.
```

The quest remains at `1 / 5`.

The game should now provide a clear next action rather than leaving the player confused.

Suggested quest update:

```text
You cannot carry enough pelts. Return to the South Gate Warden.
```

Do not secretly increase capacity for the quest.

---

## 5. Referral to the Merchant

On returning, the warden acknowledges the problem and refers the player to Borin.

Example:

> "Right. You're not equipped for hauling spoils yet. Go see Borin in Graufurt. Tell him I sent you. He'll complain, but he'll give you something useful."

Set a persisted unlock/referral flag, for example:

```text
referred-by-south-gate-warden
```

New objective:

```text
Speak with Borin in Graufurt
```

---

## 6. Merchant Interaction

Borin normally would not provide the bag at the player's current reputation.

His dialogue should make the relationship system visible.

Example:

> "I don't know you, and I don't hand out gear to every wanderer who walks in here."

Then after recognizing the referral:

> "But the South Gate Warden sent you. Fine. Take this. Bring it back full and make it worth my trouble."

Grant:

**Basic Hide Bag**

```text
Category: HIDE
Capacity: 5
```

The grant should use the quest/referral exception supported by Slice 0.8.5.

---

## 7. Continue the Hunt

The player can now carry five HIDE-category goods.

Objective returns to:

```text
Collect 5 Ashen Pelts
```

Important:

- an already-owned first pelt still counts
- the player should need four more, not five more
- the bag capacity view changes immediately to `1 / 5`

---

## 8. Quest Turn-In

The player returns to the South Gate Warden with five Ashen Pelts.

The quest consumes the required five pelts.

The warden explains the normal long-term loop:

> "Good. That's enough for me. From now on, take hides and trophies to Borin. He'll pay for useful spoils, and word gets around when you keep the roads clear."

This line connects:

- monster loot
- merchant exchange
- Silver
- regional reputation
- World Renown

without needing a separate tutorial screen.

---

## 9. Quest Rewards

The main reward of this quest is the **Basic Hide Bag** and system knowledge.

Optional one-time rewards may include:

- small regional reputation increase
- small World Renown milestone increase
- quest completion flag

Avoid a large Silver reward that undermines the merchant trade loop.

No XP reward.

---

## 10. Minimal Quest System Requirements

The system must support at least:

- quest definition
- quest acceptance
- ordered objectives
- item collection progress
- NPC interaction objective
- persisted completion
- quest flags/unlock flags
- item consumption on turn-in
- one-time rewards

Do not build a full branching narrative engine.

A simple step-based quest state machine is sufficient.

---

## 11. Quest State Safety

The flow must not softlock when:

- player already owns one or more Ashen Pelts before accepting
- player sells/trades pelts while quest is active
- player disconnects during a quest step
- bag was already obtained through development data
- player tries to receive the referral bag twice

Define deterministic behavior.

Recommended:

- objectives derive progress from current owned quantity where appropriate
- quest item consumption validates quantity at turn-in
- bag grant is idempotent
- referral flag persists

---

## 12. UI Requirements

At minimum:

### NPC / Local View

- quest available marker
- quest in progress marker
- quest turn-in marker
- Talk interaction

### Quest UI

Show:

- title
- short description
- current objective
- progress

Example:

```text
Trouble Beyond the Gate
Collect Ashen Pelts 1 / 5

You cannot carry enough pelts. Return to the South Gate Warden.
```

### Bag UI

When the bag is granted:

```text
New Loot Bag
Basic Hide Bag
Hide Capacity: 5
```

---

## 13. Tests

- quest can be accepted only once in active state
- first pelt updates objective to 1/5
- no bag blocks carrying second HIDE item
- return step activates correctly
- referral flag is set
- merchant grants Basic Hide Bag once
- capacity becomes 5
- previously owned pelt remains counted
- five pelts allow turn-in
- turn-in consumes five pelts
- quest completes and cannot reward bag repeatedly

---

## 14. Acceptance Criteria

- [ ] One complete NPC quest chain is playable.
- [ ] The quest intentionally exposes the default 1-item carrying limit.
- [ ] The player is directed back instead of softlocked.
- [ ] A persisted merchant referral is created.
- [ ] Merchant grants Basic Hide Bag because of the referral.
- [ ] Hide capacity becomes 5.
- [ ] Player can collect five Ashen Pelts.
- [ ] Turn-in consumes the pelts and completes the quest.
- [ ] NPC explains that future goods should be traded to the merchant.
- [ ] Quest grants no XP.
- [ ] All dialogue/UI text is English.

---

## 15. Out of Scope

Do not implement:

- branching quest choices
- voice acting
- cinematic dialogue
- daily quests
- repeatable bounty framework
- quest sharing
- party quest progress
- large quest journal taxonomy