Implement per-faction, per-settlement, and per-NPC reputation categories with entity type tagging #215

New issue

Open

opened 2026-03-16 01:37:15 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:37:15 +00:00

Owner

Metadata

Field	Value
Epic	#201 — Reputation Data Model & Storage
Legendary	#199 — Reputation & Social Standing
Type	Feature
Priority	High
Points	5
MoSCoW	Must Have
Branch	`feature/m4-reputation-entity-type-tagging`
Commit Message	`Implement per-faction, per-settlement, and per-NPC reputation categories with entity type tagging (#215)`

Background and Context

The reputation system tracks standing with many different kinds of entities — factions (e.g., the Merchant Guild), settlements (e.g., the town of Oakvale), and individual NPCs (e.g., Blacksmith Tormund). Each of these entity types behaves differently in the reputation system: factions propagate reputation to allies and rivals, settlements connect to parent regions, and NPCs contribute reputation to their affiliated faction.

To support this, the ReputationVector class needs to be extended with entity type metadata. Each entity in the reputation hash is tagged with a type (:faction, :settlement, or :npc), and convenience methods allow querying reputation entries filtered by type.

This categorization is essential for the reputation display commands (which group by type), the propagation system (which follows type-specific relationship paths), and the devotee system (which checks faction standing for recruitment).

Expected Behavior

When setting reputation for an entity, the entity type can be specified: set_reputation(entity, value, type: :faction).
Entity type is stored in a metadata hash at player.info["reputation_meta"] as {entity_id => {type: :faction}}.
factions() returns a hash of {entity_id => score} filtered to entities tagged as :faction.
settlements() returns a hash filtered to :settlement entities.
npcs() returns a hash filtered to :npc entities.
entity_type(entity) returns the type tag for a given entity.
Entities without an explicit type tag default to :faction.
Type tags persist across save/load cycles.

Acceptance Criteria

ReputationVector supports an optional type: keyword argument on set_reputation and modify_reputation.
Entity type metadata is stored in player.info["reputation_meta"].
factions() correctly filters and returns only faction-type entities.
settlements() correctly filters and returns only settlement-type entities.
npcs() correctly filters and returns only NPC-type entities.
entity_type(entity) returns the correct type or :faction as default.
Type metadata persists correctly through save/load.
Backward compatible with existing reputation data that has no type tags.

Subtasks

Extend ReputationVector to accept and store entity type metadata.
Implement player.info["reputation_meta"] storage structure.
Add type: keyword to set_reputation and modify_reputation.
Implement factions() filter method.
Implement settlements() filter method.
Implement npcs() filter method.
Implement entity_type(entity) lookup method.
Add backward compatibility for untagged entities.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/reputation_entity_types.feature covering type tagging, filtering by type, default type, backward compatibility, and persistence.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for entity type tagging across save/load and interaction with tier system.
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 | |-------|-------| | **Epic** | #201 — Reputation Data Model & Storage | | **Legendary** | #199 — Reputation & Social Standing | | **Type** | Feature | | **Priority** | High | | **Points** | 5 | | **MoSCoW** | Must Have | | **Branch** | `feature/m4-reputation-entity-type-tagging` | | **Commit Message** | `Implement per-faction, per-settlement, and per-NPC reputation categories with entity type tagging (#215)` | ## Background and Context The reputation system tracks standing with many different kinds of entities — factions (e.g., the Merchant Guild), settlements (e.g., the town of Oakvale), and individual NPCs (e.g., Blacksmith Tormund). Each of these entity types behaves differently in the reputation system: factions propagate reputation to allies and rivals, settlements connect to parent regions, and NPCs contribute reputation to their affiliated faction. To support this, the `ReputationVector` class needs to be extended with entity type metadata. Each entity in the reputation hash is tagged with a type (`:faction`, `:settlement`, or `:npc`), and convenience methods allow querying reputation entries filtered by type. This categorization is essential for the reputation display commands (which group by type), the propagation system (which follows type-specific relationship paths), and the devotee system (which checks faction standing for recruitment). ## Expected Behavior 1. When setting reputation for an entity, the entity type can be specified: `set_reputation(entity, value, type: :faction)`. 2. Entity type is stored in a metadata hash at `player.info["reputation_meta"]` as `{entity_id => {type: :faction}}`. 3. `factions()` returns a hash of `{entity_id => score}` filtered to entities tagged as `:faction`. 4. `settlements()` returns a hash filtered to `:settlement` entities. 5. `npcs()` returns a hash filtered to `:npc` entities. 6. `entity_type(entity)` returns the type tag for a given entity. 7. Entities without an explicit type tag default to `:faction`. 8. Type tags persist across save/load cycles. ## Acceptance Criteria - [ ] `ReputationVector` supports an optional `type:` keyword argument on `set_reputation` and `modify_reputation`. - [ ] Entity type metadata is stored in `player.info["reputation_meta"]`. - [ ] `factions()` correctly filters and returns only faction-type entities. - [ ] `settlements()` correctly filters and returns only settlement-type entities. - [ ] `npcs()` correctly filters and returns only NPC-type entities. - [ ] `entity_type(entity)` returns the correct type or `:faction` as default. - [ ] Type metadata persists correctly through save/load. - [ ] Backward compatible with existing reputation data that has no type tags. ## Subtasks - [ ] Extend `ReputationVector` to accept and store entity type metadata. - [ ] Implement `player.info["reputation_meta"]` storage structure. - [ ] Add `type:` keyword to `set_reputation` and `modify_reputation`. - [ ] Implement `factions()` filter method. - [ ] Implement `settlements()` filter method. - [ ] Implement `npcs()` filter method. - [ ] Implement `entity_type(entity)` lookup method. - [ ] Add backward compatibility for untagged entities. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/reputation_entity_types.feature` covering type tagging, filtering by type, default type, backward compatibility, and persistence. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for entity type tagging across save/load and interaction with tier system. - [ ] 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.