# Ashen Realms – Playable Slice 0.8.5

## Reputation-Gated Merchant Offers

**Status:** Implementation Specification  
**Depends on:** Slice 0.8  
**Purpose:** Make reputation visible and useful by locking selected merchant offers behind reputation or explicit unlock conditions instead of character levels.

---

## 1. Goal

The reputation system must change what the player can do.

A merchant should be able to communicate:

> "I don't know you well enough for that."

or:

> "Earn more trust in the Ashen Fields first."

The player sees desirable locked items, understands the requirement, and has a reason to continue hunting and trading.

---

## 2. No Level-Gated Merchant Progression

New merchant offers must not use character level as the primary progression gate.

Preferred gates:

- regional reputation
- World Renown
- NPC reputation, if already supported
- quest/unlock flag

The server is authoritative for all purchase requirements.

If `requiredLevel` still exists in an old item schema, it may remain for compatibility, but new Tier-1 merchant progression in these slices should not rely on it.

---

## 3. Offer Requirement Model

Merchant offers should support an optional requirement definition.

Conceptual examples:

```text
NONE
REGION_REPUTATION
WORLD_RENOWN
NPC_REPUTATION
QUEST_FLAG
```

An offer may later support multiple requirements, but do not overbuild a general rule engine unless the current code already has one.

A pragmatic structure is enough:

```text
requiredRegionReputation
requiredWorldRenown
requiredNpcReputation
requiredUnlockFlag
```

with nullable values.

---

## 4. Initial Locked Offers

At least two useful offers should demonstrate the system.

Recommended examples:

### Basic Hide Bag

- important progression item
- may be normally reputation-gated
- Slice 0.9 can temporarily bypass the gate through a quest referral

### Basic Trophy Pouch

- unlocked after the player has demonstrated some regional reputation

Optional additional offer:

### Bandit Blade or another Tier-1 gap filler

- available at a higher reputation threshold

Exact thresholds are balancing data.

---

## 5. Visible Locked Offers

Locked offers should usually remain visible.

Example:

```text
Basic Trophy Pouch
Capacity: 5 Raider Trophies
Price: 40 Silver
Requires: Ashen Fields Reputation 25
Current: 14
```

The Buy action is disabled.

This is preferable to hiding every locked item, because visible rewards create goals.

---

## 6. Server Validation

A malicious client must not bypass a disabled button.

Purchase flow:

```text
load character
load merchant offer
validate price
validate reputation requirement
validate quest/unlock flag
validate inventory/bag ownership rules
remove currency
grant item/bag
commit
```

If reputation is insufficient, return a stable domain error such as:

```text
MERCHANT_REPUTATION_TOO_LOW
```

with an English player-facing message.

---

## 7. Referral / Exception Support

Slice 0.9 needs a special tutorial moment:

The merchant normally would not give the player a useful bag yet, but a gate NPC sends the player with a referral.

Therefore the offer/unlock system must support one minimal exception:

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

or an equivalent quest reward/grant path.

Do not implement a complex faction favor engine.

The requirement is simply that the quest can legally allow one specific acquisition that reputation alone would not yet allow.

---

## 8. UI Requirements

Merchant cards/rows show:

- item/bag name
- icon
- Silver price
- relevant effect
- requirement
- player's current value
- locked/unlocked state

Use clear English copy.

Examples:

```text
Requires Ashen Fields Reputation 25
```

```text
Requires World Renown 3
```

```text
Unavailable – Borin does not know you well enough.
```

---

## 9. Feedback on Unlock

When a reputation increase makes an offer newly available, the player should receive lightweight feedback.

Example:

```text
New merchant offer unlocked: Basic Trophy Pouch
```

No large modal is required.

---

## 10. Tests

- offer with no requirement can be purchased
- insufficient regional reputation blocks purchase
- sufficient regional reputation allows purchase
- insufficient World Renown blocks purchase
- quest flag can unlock configured tutorial offer
- disabled client state is not trusted by backend
- price is still required even when reputation condition is met
- unlock state changes after a successful trade-in raises reputation

---

## 11. Acceptance Criteria

- [ ] Merchant offers can define reputation/unlock requirements.
- [ ] At least two offers visibly demonstrate locked states.
- [ ] Requirements are shown to the player in English.
- [ ] Server rejects purchases when requirements are not met.
- [ ] New progression offers do not depend on level gates.
- [ ] Quest/referral unlock support exists for Slice 0.9.
- [ ] Reputation increase can visibly unlock a previously locked offer.
- [ ] No generalized rules engine was added unnecessarily.

---

## 12. Out of Scope

Do not implement:

- dynamic merchant personalities
- haggling
- randomized daily shops
- faction wars
- reputation decay
- negative reputation systems
- multiple currencies per individual offer unless already required