Implement personal harvesting mechanics #240

New issue

Open

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

freemo commented

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

Owner

Metadata

Field	Value
Parent Epic	Epic: Harvesting System (#209)
Legendary	Crafting & Resource Economy (#200)
Type	Feature
Priority	High
MoSCoW	Must Have
Points	8
Branch	`feature/m4-personal-harvesting-mechanics`
Commit Message	`Implement personal harvesting mechanics (#240)`

Background and Context

With the HarvestNode data model in place, players need the ability to interact with harvest nodes directly. Personal harvesting is the primary way players gather resources — it involves a skill check against the node's difficulty, a quality formula that rewards higher skill levels, XP gain for the relevant harvesting skill, depletion tracking on the node, and a cooldown between harvests.

The quality formula is: base_quality * (1 + skill_level/100) * focus_bonus, where:

base_quality is a random value within the node's quality_range.
skill_level is the player's level in the relevant harvesting skill.
focus_bonus is a multiplier (default 1.0) that can be increased by concentration abilities or items.

This mechanic should feel rewarding — higher-skilled players produce noticeably better resources, incentivizing skill investment.

Expected Behavior

When a player issues a harvest command targeting a HarvestNode:

Skill Check: The system checks the player's skill level against the node's difficulty and skill_required. If the player's skill is too low, the harvest fails with an informative message.
Quality Calculation: On success, the quality of the harvested resource is calculated using: base_quality * (1 + skill_level/100) * focus_bonus. The result is clamped to 1-100.
Resource Yield: A resource item is created with the calculated quality and added to the player's inventory. The yield is selected from the node's yields array based on drop chance.
XP Gain: The player gains XP in the relevant harvesting skill. XP amount scales with node difficulty.
Depletion Tracking: The node's current_depletion is incremented. If the node becomes fully depleted, the respawn timer is set.
Cooldown: A per-player cooldown prevents harvesting the same node again for a configurable duration (e.g., 5 seconds).
Feedback: The player receives descriptive text about what they harvested and its quality.

Acceptance Criteria

A harvest command is available to players when they are in a room containing a HarvestNode.
The skill check correctly gates harvesting based on the player's skill level vs. node difficulty.
The quality formula base_quality * (1 + skill_level/100) * focus_bonus is correctly implemented and the result is clamped to 1-100.
Harvested resources are added to the player's inventory with the calculated quality.
The player gains XP in the relevant harvesting skill proportional to node difficulty.
Node depletion is tracked correctly; depleted nodes cannot be harvested until respawned.
A per-player cooldown prevents rapid re-harvesting of the same node.
Descriptive feedback is shown to the player on successful harvest, failed skill check, depleted node, and cooldown.

Subtasks

Implement the harvest command handler that targets HarvestNode objects.
Implement the skill check logic comparing player skill level to node difficulty.
Implement the quality formula: base_quality * (1 + skill_level/100) * focus_bonus with clamping.
Implement resource yield selection from the node's yields array based on drop chance.
Implement XP gain for the relevant harvesting skill scaled by difficulty.
Implement depletion tracking integration with HarvestNode#harvest!.
Implement per-player cooldown tracking for harvest nodes.
Write descriptive feedback messages for all harvest outcomes.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/personal_harvesting.feature covering skill check pass/fail, quality formula calculation, XP gain, depletion tracking, cooldown enforcement.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for end-to-end harvesting flow.
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: Harvesting System (#209) | | **Legendary** | Crafting & Resource Economy (#200) | | **Type** | Feature | | **Priority** | High | | **MoSCoW** | Must Have | | **Points** | 8 | | **Branch** | `feature/m4-personal-harvesting-mechanics` | | **Commit Message** | `Implement personal harvesting mechanics (#240)` | ## Background and Context With the `HarvestNode` data model in place, players need the ability to interact with harvest nodes directly. Personal harvesting is the primary way players gather resources — it involves a skill check against the node's difficulty, a quality formula that rewards higher skill levels, XP gain for the relevant harvesting skill, depletion tracking on the node, and a cooldown between harvests. The quality formula is: `base_quality * (1 + skill_level/100) * focus_bonus`, where: - `base_quality` is a random value within the node's `quality_range`. - `skill_level` is the player's level in the relevant harvesting skill. - `focus_bonus` is a multiplier (default 1.0) that can be increased by concentration abilities or items. This mechanic should feel rewarding — higher-skilled players produce noticeably better resources, incentivizing skill investment. ## Expected Behavior When a player issues a `harvest` command targeting a `HarvestNode`: 1. **Skill Check**: The system checks the player's skill level against the node's `difficulty` and `skill_required`. If the player's skill is too low, the harvest fails with an informative message. 2. **Quality Calculation**: On success, the quality of the harvested resource is calculated using: `base_quality * (1 + skill_level/100) * focus_bonus`. The result is clamped to 1-100. 3. **Resource Yield**: A resource item is created with the calculated quality and added to the player's inventory. The yield is selected from the node's `yields` array based on drop chance. 4. **XP Gain**: The player gains XP in the relevant harvesting skill. XP amount scales with node difficulty. 5. **Depletion Tracking**: The node's `current_depletion` is incremented. If the node becomes fully depleted, the respawn timer is set. 6. **Cooldown**: A per-player cooldown prevents harvesting the same node again for a configurable duration (e.g., 5 seconds). 7. **Feedback**: The player receives descriptive text about what they harvested and its quality. ## Acceptance Criteria - [ ] A `harvest` command is available to players when they are in a room containing a `HarvestNode`. - [ ] The skill check correctly gates harvesting based on the player's skill level vs. node difficulty. - [ ] The quality formula `base_quality * (1 + skill_level/100) * focus_bonus` is correctly implemented and the result is clamped to 1-100. - [ ] Harvested resources are added to the player's inventory with the calculated quality. - [ ] The player gains XP in the relevant harvesting skill proportional to node difficulty. - [ ] Node depletion is tracked correctly; depleted nodes cannot be harvested until respawned. - [ ] A per-player cooldown prevents rapid re-harvesting of the same node. - [ ] Descriptive feedback is shown to the player on successful harvest, failed skill check, depleted node, and cooldown. ## Subtasks - [ ] Implement the `harvest` command handler that targets `HarvestNode` objects. - [ ] Implement the skill check logic comparing player skill level to node difficulty. - [ ] Implement the quality formula: `base_quality * (1 + skill_level/100) * focus_bonus` with clamping. - [ ] Implement resource yield selection from the node's `yields` array based on drop chance. - [ ] Implement XP gain for the relevant harvesting skill scaled by difficulty. - [ ] Implement depletion tracking integration with `HarvestNode#harvest!`. - [ ] Implement per-player cooldown tracking for harvest nodes. - [ ] Write descriptive feedback messages for all harvest outcomes. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/personal_harvesting.feature` covering skill check pass/fail, quality formula calculation, XP gain, depletion tracking, cooldown enforcement. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for end-to-end harvesting flow. - [ ] 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.