Implement basic trade commands with merchant NPCs #251

New issue

Open

opened 2026-03-16 01:41:48 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:41:48 +00:00

Owner

Metadata

Field	Value
Parent Epic	Epic: Storage & Trade (#212)
Legendary	Crafting & Resource Economy (#200)
Type	Feature
Priority	Medium
MoSCoW	Should Have
Points	8
Branch	`feature/m4-basic-trade-commands`
Commit Message	`Implement basic trade commands with merchant NPCs (#251)`

Background and Context

The trade system closes the economic loop in the crafting and resource economy. Players need the ability to sell their crafted goods and harvested resources to merchant NPCs, and to buy supplies and materials they need. Merchants serve as both a gold sink and a gold source, and their pricing is influenced by the player's reputation with them.

Reputation-based pricing creates a meaningful connection between the quality of goods a player sells and the deals they can get in the future. A player known for selling high-quality wares will enjoy better prices, while one who dumps low-quality goods will face worse terms.

Expected Behavior

sell <item> Command: Sells an item from the player's inventory to a merchant NPC in the same room. The sale price is calculated based on the item's base value, quality tier, and the player's reputation with the merchant.
- Sale price formula: base_value * quality_multiplier * reputation_modifier.
- The player receives gold equal to the sale price.
- The item is removed from the player's inventory.
buy <item> Command: Purchases an item from a merchant NPC's stock. The buy price is calculated similarly with a markup.
- Buy price formula: base_value * merchant_markup * (1 / reputation_modifier).
- Better reputation = lower buy prices.
- The player must have enough gold.
price <item> Command: Shows the buy and/or sell price for an item without committing to a transaction. Useful for price checking.
Reputation-Based Pricing:
- Reputation modifier ranges from 0.8 (hostile) to 1.3 (exalted).
- Default reputation modifier for a new player is 1.0 (neutral).
- Reputation is per-merchant or per-merchant-faction.
Merchant Stock: Merchants have a defined inventory of items for sale, loaded from configuration.

Acceptance Criteria

sell <item> correctly sells an item to a merchant in the same room.
Sale price correctly applies base value, quality multiplier, and reputation modifier.
The player receives the correct amount of gold on sale.
buy <item> correctly purchases an item from a merchant's stock.
Buy price correctly applies base value, merchant markup, and inverse reputation modifier.
buy fails with an appropriate message if the player lacks sufficient gold.
price <item> displays the buy and/or sell price without executing a transaction.
Reputation modifier correctly scales pricing between 0.8 and 1.3.
Merchants have configurable stock loaded from configuration files.
Commands only work when a merchant NPC is present in the same room.

Subtasks

Implement the sell <item> command handler with pricing calculation and inventory transfer.
Implement the buy <item> command handler with pricing, gold check, and inventory transfer.
Implement the price <item> command handler for price checking.
Implement the reputation-based pricing modifier (0.8 to 1.3 range).
Implement merchant stock configuration and loading.
Implement gold transaction handling (add/subtract gold from player).
Implement room-presence check for merchant NPC.
Implement descriptive feedback messages for all trade outcomes.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/basic_trade_commands.feature covering sell pricing, buy pricing, insufficient gold, price check, reputation modifier scaling, merchant presence check.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for end-to-end trade flow with reputation effects.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Field | Value | |---|---| | **Parent Epic** | Epic: Storage & Trade (#212) | | **Legendary** | Crafting & Resource Economy (#200) | | **Type** | Feature | | **Priority** | Medium | | **MoSCoW** | Should Have | | **Points** | 8 | | **Branch** | `feature/m4-basic-trade-commands` | | **Commit Message** | `Implement basic trade commands with merchant NPCs (#251)` | ## Background and Context The trade system closes the economic loop in the crafting and resource economy. Players need the ability to sell their crafted goods and harvested resources to merchant NPCs, and to buy supplies and materials they need. Merchants serve as both a gold sink and a gold source, and their pricing is influenced by the player's reputation with them. Reputation-based pricing creates a meaningful connection between the quality of goods a player sells and the deals they can get in the future. A player known for selling high-quality wares will enjoy better prices, while one who dumps low-quality goods will face worse terms. ## Expected Behavior 1. **`sell <item>` Command**: Sells an item from the player's inventory to a merchant NPC in the same room. The sale price is calculated based on the item's base value, quality tier, and the player's reputation with the merchant. - Sale price formula: `base_value * quality_multiplier * reputation_modifier`. - The player receives gold equal to the sale price. - The item is removed from the player's inventory. 2. **`buy <item>` Command**: Purchases an item from a merchant NPC's stock. The buy price is calculated similarly with a markup. - Buy price formula: `base_value * merchant_markup * (1 / reputation_modifier)`. - Better reputation = lower buy prices. - The player must have enough gold. 3. **`price <item>` Command**: Shows the buy and/or sell price for an item without committing to a transaction. Useful for price checking. 4. **Reputation-Based Pricing**: - Reputation modifier ranges from 0.8 (hostile) to 1.3 (exalted). - Default reputation modifier for a new player is 1.0 (neutral). - Reputation is per-merchant or per-merchant-faction. 5. **Merchant Stock**: Merchants have a defined inventory of items for sale, loaded from configuration. ## Acceptance Criteria - [ ] `sell <item>` correctly sells an item to a merchant in the same room. - [ ] Sale price correctly applies base value, quality multiplier, and reputation modifier. - [ ] The player receives the correct amount of gold on sale. - [ ] `buy <item>` correctly purchases an item from a merchant's stock. - [ ] Buy price correctly applies base value, merchant markup, and inverse reputation modifier. - [ ] `buy` fails with an appropriate message if the player lacks sufficient gold. - [ ] `price <item>` displays the buy and/or sell price without executing a transaction. - [ ] Reputation modifier correctly scales pricing between 0.8 and 1.3. - [ ] Merchants have configurable stock loaded from configuration files. - [ ] Commands only work when a merchant NPC is present in the same room. ## Subtasks - [ ] Implement the `sell <item>` command handler with pricing calculation and inventory transfer. - [ ] Implement the `buy <item>` command handler with pricing, gold check, and inventory transfer. - [ ] Implement the `price <item>` command handler for price checking. - [ ] Implement the reputation-based pricing modifier (0.8 to 1.3 range). - [ ] Implement merchant stock configuration and loading. - [ ] Implement gold transaction handling (add/subtract gold from player). - [ ] Implement room-presence check for merchant NPC. - [ ] Implement descriptive feedback messages for all trade outcomes. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/basic_trade_commands.feature` covering sell pricing, buy pricing, insufficient gold, price check, reputation modifier scaling, merchant presence check. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for end-to-end trade flow with reputation effects. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.