248 lines
5.2 KiB
Markdown
248 lines
5.2 KiB
Markdown
# 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
|