Implement personal storage chest with store, retrieve, and storage commands #249

New issue

Open

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

freemo commented

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

Owner

Metadata

Field	Value
Parent Epic	Epic: Storage & Trade (#212)
Legendary	Crafting & Resource Economy (#200)
Type	Feature
Priority	Medium
MoSCoW	Must Have
Points	5
Branch	`feature/m4-personal-storage-chest`
Commit Message	`Implement personal storage chest with store, retrieve, and storage commands (#249)`

Background and Context

As the crafting and harvesting systems generate more items, players need a dedicated storage mechanism beyond their personal inventory. The personal storage chest is a container object that can be placed in the player's home or accessed at a bank location. It provides bulk storage for resources, crafted items, and other valuables.

The storage chest is also the target for the devotee auto-deposit feature — devotees assigned to harvest will deposit their gathered resources directly into the player's storage chest. This makes the storage chest a critical hub in the resource economy.

Expected Behavior

StorageChest Object: A new StorageChest game object that acts as a container. It is associated with a specific player (owner) and has a configurable capacity limit (number of item stacks).
store <item> Command: When a player is in the same room as their storage chest, they can store an item from their inventory into the chest. If the chest is full, an appropriate message is displayed.
retrieve <item> Command: The player can retrieve an item from the chest back to their inventory. If the item is not in the chest, an appropriate message is displayed.
storage Command: Lists all items currently in the player's storage chest with names, quantities, and quality tiers. Shows current capacity usage (e.g., "15/50 slots used").
Access Control: Only the chest's owner can store, retrieve, and view its contents.
Persistence: The chest's contents are persisted across server restarts.

Acceptance Criteria

StorageChest class exists as a game object with an owner, capacity limit, and item container.
store <item> moves an item from the player's inventory to the chest if capacity allows.
store <item> displays an error if the chest is full.
retrieve <item> moves an item from the chest to the player's inventory.
retrieve <item> displays an error if the item is not in the chest.
storage lists all items in the chest with names, quantities, quality tiers, and capacity usage.
Only the owner can interact with their storage chest.
Non-owners attempting to access the chest receive an appropriate denial message.
Chest contents are persisted across server restarts.
Capacity limit is configurable.

Subtasks

Create the StorageChest class extending the game object hierarchy with owner, capacity, and item storage.
Implement the store <item> command handler with capacity checking.
Implement the retrieve <item> command handler with item lookup.
Implement the storage command handler to list contents with details.
Implement access control: owner-only interaction.
Implement persistence for chest contents across server restarts.
Add configurable capacity limit (default and per-chest override).
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/personal_storage_chest.feature covering store, retrieve, storage list, capacity limit, owner access control, non-owner denial, persistence.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for storage chest creation, usage, and persistence.
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** | Must Have | | **Points** | 5 | | **Branch** | `feature/m4-personal-storage-chest` | | **Commit Message** | `Implement personal storage chest with store, retrieve, and storage commands (#249)` | ## Background and Context As the crafting and harvesting systems generate more items, players need a dedicated storage mechanism beyond their personal inventory. The personal storage chest is a container object that can be placed in the player's home or accessed at a bank location. It provides bulk storage for resources, crafted items, and other valuables. The storage chest is also the target for the devotee auto-deposit feature — devotees assigned to harvest will deposit their gathered resources directly into the player's storage chest. This makes the storage chest a critical hub in the resource economy. ## Expected Behavior 1. **StorageChest Object**: A new `StorageChest` game object that acts as a container. It is associated with a specific player (owner) and has a configurable capacity limit (number of item stacks). 2. **`store <item>` Command**: When a player is in the same room as their storage chest, they can store an item from their inventory into the chest. If the chest is full, an appropriate message is displayed. 3. **`retrieve <item>` Command**: The player can retrieve an item from the chest back to their inventory. If the item is not in the chest, an appropriate message is displayed. 4. **`storage` Command**: Lists all items currently in the player's storage chest with names, quantities, and quality tiers. Shows current capacity usage (e.g., "15/50 slots used"). 5. **Access Control**: Only the chest's owner can store, retrieve, and view its contents. 6. **Persistence**: The chest's contents are persisted across server restarts. ## Acceptance Criteria - [ ] `StorageChest` class exists as a game object with an owner, capacity limit, and item container. - [ ] `store <item>` moves an item from the player's inventory to the chest if capacity allows. - [ ] `store <item>` displays an error if the chest is full. - [ ] `retrieve <item>` moves an item from the chest to the player's inventory. - [ ] `retrieve <item>` displays an error if the item is not in the chest. - [ ] `storage` lists all items in the chest with names, quantities, quality tiers, and capacity usage. - [ ] Only the owner can interact with their storage chest. - [ ] Non-owners attempting to access the chest receive an appropriate denial message. - [ ] Chest contents are persisted across server restarts. - [ ] Capacity limit is configurable. ## Subtasks - [ ] Create the `StorageChest` class extending the game object hierarchy with owner, capacity, and item storage. - [ ] Implement the `store <item>` command handler with capacity checking. - [ ] Implement the `retrieve <item>` command handler with item lookup. - [ ] Implement the `storage` command handler to list contents with details. - [ ] Implement access control: owner-only interaction. - [ ] Implement persistence for chest contents across server restarts. - [ ] Add configurable capacity limit (default and per-chest override). - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/personal_storage_chest.feature` covering store, retrieve, storage list, capacity limit, owner access control, non-owner denial, persistence. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for storage chest creation, usage, and persistence. - [ ] 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.