Implement auto-resubscription on room changes and combat start/end #300

New issue

Closed

opened 2026-03-16 01:59:24 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:59:24 +00:00

Owner

Metadata

Key	Value
Branch	`feature/m2-ui-resubscribe`
Commit Message	`feat: implement auto-resubscription on room changes and combat transitions`
Parent Epic	#298 — UI Event Subscription System

Background and Context

A player's context changes frequently during gameplay — moving between rooms, entering and leaving combat, changing areas. The UIEventSubscriber must automatically adjust its subscriptions when these transitions occur. Without auto-resubscription, a player who moves rooms would stop receiving events from the new room and continue receiving stale events from the old one.

Expected Behavior

When a player moves to a new room:

UIEventSubscriber unsubscribes from the old Room's events.
If the new room is in a different Area, unsubscribe from the old Area and subscribe to the new one.
Subscribe to the new Room's events.

When combat starts:

Subscribe to the new CombatInstance events.

When combat ends:

Unsubscribe from the CombatInstance.

These transitions are detected via lifecycle hooks on the Player object (e.g., on :room_changed, on :combat_started, on :combat_ended).

# Player moves from Room A (Area 1) to Room B (Area 2)
# Automatically:
#   - Unsubscribe from Room A
#   - Unsubscribe from Area 1
#   - Subscribe to Room B
#   - Subscribe to Area 2

Acceptance Criteria

Room change triggers unsubscribe from old room and subscribe to new room.
Area change (when moving to a room in a different area) triggers area resubscription.
Combat start triggers subscription to the new CombatInstance.
Combat end triggers unsubscription from the CombatInstance.
No duplicate subscriptions occur (e.g., subscribing to same room twice).
No orphaned subscriptions remain after transitions.
Lifecycle hooks on Player object are used for detection.

Subtasks

Code

Implement #on_room_changed(old_room, new_room) handler in UIEventSubscriber.
Implement area-change detection (compare old room's area to new room's area).
Implement #on_combat_started(combat_instance) handler.
Implement #on_combat_ended(combat_instance) handler.
Register lifecycle hooks on Player object for room_changed, combat_started, combat_ended.
Add guard against duplicate subscriptions.
Add cleanup verification (no orphaned listeners after transitions).

Quality

Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/ui_resubscribe.feature covering room change within same area, room change to different area, combat start subscription, combat end unsubscription, rapid room changes, no duplicate subscriptions, no orphaned subscriptions.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for auto-resubscription on room changes and combat transitions.
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 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 | Key | Value | |-----|-------| | **Branch** | `feature/m2-ui-resubscribe` | | **Commit Message** | `feat: implement auto-resubscription on room changes and combat transitions` | | **Parent Epic** | #298 — UI Event Subscription System | ## Background and Context A player's context changes frequently during gameplay — moving between rooms, entering and leaving combat, changing areas. The `UIEventSubscriber` must automatically adjust its subscriptions when these transitions occur. Without auto-resubscription, a player who moves rooms would stop receiving events from the new room and continue receiving stale events from the old one. ## Expected Behavior When a player moves to a new room: 1. `UIEventSubscriber` unsubscribes from the old Room's events. 2. If the new room is in a different Area, unsubscribe from the old Area and subscribe to the new one. 3. Subscribe to the new Room's events. When combat starts: 1. Subscribe to the new `CombatInstance` events. When combat ends: 1. Unsubscribe from the `CombatInstance`. These transitions are detected via lifecycle hooks on the Player object (e.g., `on :room_changed`, `on :combat_started`, `on :combat_ended`). ```ruby # Player moves from Room A (Area 1) to Room B (Area 2) # Automatically: # - Unsubscribe from Room A # - Unsubscribe from Area 1 # - Subscribe to Room B # - Subscribe to Area 2 ``` ## Acceptance Criteria - [ ] Room change triggers unsubscribe from old room and subscribe to new room. - [ ] Area change (when moving to a room in a different area) triggers area resubscription. - [ ] Combat start triggers subscription to the new `CombatInstance`. - [ ] Combat end triggers unsubscription from the `CombatInstance`. - [ ] No duplicate subscriptions occur (e.g., subscribing to same room twice). - [ ] No orphaned subscriptions remain after transitions. - [ ] Lifecycle hooks on Player object are used for detection. ## Subtasks ### Code - [ ] Implement `#on_room_changed(old_room, new_room)` handler in `UIEventSubscriber`. - [ ] Implement area-change detection (compare old room's area to new room's area). - [ ] Implement `#on_combat_started(combat_instance)` handler. - [ ] Implement `#on_combat_ended(combat_instance)` handler. - [ ] Register lifecycle hooks on Player object for room_changed, combat_started, combat_ended. - [ ] Add guard against duplicate subscriptions. - [ ] Add cleanup verification (no orphaned listeners after transitions). ### Quality - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/ui_resubscribe.feature` covering room change within same area, room change to different area, combat start subscription, combat end unsubscription, rapid room changes, no duplicate subscriptions, no orphaned subscriptions. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for auto-resubscription on room changes and combat transitions. - [ ] 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 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.